O SDK do Singular está disponível como um plug-in para o Cordova. As instruções abaixo mostram como integrar o Singular na sua aplicação Cordova.

Pré-requisitos

• Este artigo assume que você tem um aplicativo Cordova funcional.
• Para inicializar o SDK, você precisa da Chave do SDK Singular e do Segredo do SDK. Você pode obtê-los na plataforma Singular em"Ferramentas do desenvolvedor > Integração do SDK > Chaves do SDK".

Adicionando o plugin do Singular

Para adicionar o plug-in Singular ao seu projeto Cordova, execute o seguinte:

cordova plugin add singular_cordova_sdk

Ionic

Se você estiver usando o Ionic:

1. Instale o plug-in Singular SDK:

   $ ionic cordova plugin add singular_cordova_sdk

2. No seu arquivo ts principal, declare uma variável de janela:

   declare var cordova;

3. Agora você pode usar o plug-in Singular diretamente do Cordova:

   TypeScript

   import {Component} from '@angular/core';
   import {Platform} from '@ionic/angular';
   declare var cordova;
   ...
   
   export class HomePage {
   constructor(public platform: Platform) {
   this.platform.ready().then(() => {
   
       // Add code to initialize the Singular SDK here
   
   
   
   }); 
   }}
   

Inicializando o SDK (obrigatório)

O código de inicialização do Singular SDK deve ser chamado toda vez que seu aplicativo for aberto. Ele é um pré-requisito para todas as funcionalidades de atribuição do Singular. Ele também envia uma nova sessão de usuário para o Singular (as sessões são usadas para calcular a retenção de usuários).

Para inicializar o SDK do Singular:

1. Crie um objeto SingularConfig. O objeto contém sua chave e segredo do Singular SDK.
2. Defina configurações opcionais se quiser que seu aplicativo ofereça suporte a deep links e/ou SKAdNetwork (consulte Adicionando suporte a deep links e Adicionando suporte a SKAdNetwork abaixo).
3. META Instalar suporte à atribuição de referenciador

   Configuração necessária do SDK para ativar a atribuição do "Meta Install Referrer":

   1. Forneça seu ID do aplicativo do Facebook no objeto de configuração Singular.
      

      // To enable META Install Referrer
      
      
      singularConfig.withFacebookAppId("INSERT YOUR FACEBOOK APP ID HERE");

   Onde posso encontrar a ID de aplicativo do Facebook de um aplicativo?
4. Inicialize o SDK usando o objeto SingularConfig.

Exemplo de código (com configurações opcionais comentadas):

// Create the configuration object


var singularConfig = new
cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");

/*
// Optional: Enable deep linking (requires additional setup steps, see guide)


var linkHandler = function(data){
var deeplink = data.deeplink;
var passthrough = data.passthrough;
var isDeferred = data.isDeferred;
// Add link handling logic here


}
singularConfig.withSingularLink(linkHandler);
*/

/*
// To enable META Install Referrer


singularConfig.withFacebookAppId("INSERT YOUR FACEBOOK APP ID HERE");
*/

/*
// Optional: Enable SKAdNetwork (in Managed Mode, see guide for more options)


singularConfig.withSkAdNetworkEnabled(true);
*/

// Initialize Singular


cordova.plugins.SingularCordovaSdk.init(singularConfig);

Enviando o ID de usuário para a Singular (opcional)

Você pode enviar sua ID de usuário interna para a Singular usando um método do SDK da Singular.

• A ID de usuário pode ser qualquer identificador e não deve expor PII (Informações de identificação pessoal). Por exemplo, não deve utilizar o endereço de correio eletrónico, o nome de utilizador ou o número de telefone de um utilizador. A Singular recomenda o uso de um valor com hash exclusivo apenas para seus dados primários.
• O valor da ID de usuário passado para a Singular também deve ser a mesma ID de usuário interna que você captura em todas as plataformas (Web/Mobile/PC/Console/Offline).
• A Singular incluirá o ID de utilizador nas exportações ao nível do utilizador, ETL e postbacks do BI interno (se configurado). O ID do usuário é um dado primário e a Singular não o compartilha com outras partes.
• O valor da ID de usuário, quando definido com o método Singular SDK, persistirá até que seja desmarcado usando o método unsetCustomUserId ou até que o aplicativo seja desinstalado. Fechar ou reiniciar a aplicação não anula a definição do ID de utilizador.

Para definir o ID de utilizador, utilize o método setCustomUserId. Para a anular (por exemplo, se o Utilizador "sair" da conta), ligue para unsetCustomUserId.

Se você já sabe a ID de usuário quando o aplicativo é aberto, chame setCustomUserId antes de inicializar o SDK do Singular. Dessa forma, o Singular pode ter a ID de usuário desde a primeira sessão. No entanto, a ID de usuário normalmente não está disponível até que o usuário se registre ou faça um login. Nesse caso, chame setCustomUserId após a conclusão do fluxo de registo.

SingularCordovaSdk.setCustomUserId('CustomUserId');

SingularCordovaSdk.unsetCustomUserId();

SingularCordovaSdk.setDeviceCustomUserId('CustomUserId');

Eventos de rastreamento (sem receita)

Além de enviar sessões de usuário para a Singular (através da inicialização do SDK), você também pode enviar eventos de usuário. Os dados sobre eventos in-app ajudam a Singular a analisar o desempenho de suas campanhas de aquisição de usuários e medir KPIs.

Por exemplo, sua organização pode querer coletar dados sobre logins de usuários, registros, conclusões de tutoriais ou subida de nível em um aplicativo de jogos.

Para enviar eventos para o Singular, use o método eventWithArgs . Dê um nome ao evento e adicione os atributos que deseja rastrear.

// Example: Report an event called View Product with event attributes


cordova.plugins.SingularCordovaSdk.eventWithArgs(
  'ViewProduct', // Event name


  {
    // Event attributes


    productID:"123",
    productCategory:"Outerwear"
  }
)

Rastreamento de receita

Para permitir que o Singular rastreie a receita que seu aplicativo gera com compras no aplicativo, relate eventos de IAP ao Singular.

Recomendamos usar o método eventWithArgs e passar o objeto IAP como um atributo de evento. A Singular usa o objeto IAP para validar a compra e detetar compras fraudulentas para que elas não distorçam suas métricas de receita (consulte as Perguntas frequentes sobre validação de compras no aplicativo).

Se estiver a utilizar a biblioteca https://github.com/j3k0/cordova-plugin-purchase, pode utilizar o seguinte código:

store.when('product123 verified', onProductVerified);
product.verify();

function onProductVerified(product){
  const iap = new cordova.plugins.SingularCordovaSdk.SingularIAP(product);
  cordova.plugins.SingularCordovaSdk.eventWithArgs('IAP_EVENT', iap)
}

cordova.plugins.SingularCordovaSdk.customRevenue(
  customEventName, // E.g. "purchase"


  currencyCode, // E.g. "USD"


  purchaseAmount // E.g. 3.2


);

Rastreamento de evento híbrido (avançado)

A Singular recomenda o envio de todos os eventos e receitas por meio do SDK da Singular integrado ao seu aplicativo. No entanto, a Singular pode coletar eventos e receitas de outras fontes.

Qualquer evento NÃO enviado do SDK da Singular deve estar em conformidade com os requisitos de documentação de eventos de servidor para servidor da Singular e fornecer o identificador de dispositivo correspondente para atribuir corretamente um evento.

Guias de rastreamento de eventos híbridos

Acompanhamento da atribuição de receita de anúncios

Adicionando suporte a Deep Linking

As ligações profundas são ligações que abrem a aplicação no telemóvel do utilizador e o enviam diretamente para uma página ou experiência de utilizador específica, em vez de apenas para o widget principal da aplicação.

As ligações profundas são normalmente utilizadas em campanhas de retargeting, destinadas a utilizadores que já têm a aplicação no seu telemóvel, mas que podem não ter interagido com ela durante algum tempo.

O Singular suporta links profundos por meio de Singular Links (consulte as Perguntas frequentes sobre Singular Links).

Para usar o Singular Links em seu aplicativo:

1. Siga as instruções em Pré-requisitos do Singular Links.

2. Para Android, adicione este código à atividade principal:

   Java Kotlin

   import singular_cordova_sdk.SingularCordovaSdk;
   
   @Override
   public void onNewIntent(Intent intent) {
     SingularCordovaSdk.handleNewIntent(intent);
   }
   

   import singular_cordova_sdk.SingularCordovaSdk
   
   override fun onNewIntent(intent: Intent) {
       SingularCordovaSdk.handleNewIntent(intent)
   }
   

   Para iOS, adicione este código ao seu AppDelegate:

   Swift Objective-C

   import UIKit
   import SingularCordovaSdk
   
   class AppDelegate: UIResponder, UIApplicationDelegate {
       
       var window: UIWindow?
       var viewController: MainViewController?
       
       func application(
           _ application: UIApplication,
           didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
       ) -> Bool {
           // Initialize window
   
           window = UIWindow(frame: UIScreen.main.bounds)
           
           // Configure view controller
   
           viewController = MainViewController()
           window?.rootViewController = viewController
           
           // Initialize Singular SDK
   
           SingularCordovaSdk.setLaunchOptions(launchOptions)
           
           // Make window visible
   
           window?.makeKeyAndVisible()
           
           return true
       }
       
       func application(
           _ application: UIApplication,
           continue userActivity: NSUserActivity,
           restorationHandler: @escaping ([Any]?) -> Void
       ) -> Bool {
           return SingularCordovaSdk.startSession(with: userActivity)
       }
   }
   

   #import "SingularCordovaSdk.h"
   #import "MainViewController.h"
   
   - (BOOL)application:(UIApplication *)application 
   didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
       // Initialize window
   
       self.window = [[UIWindow alloc] initWithFrame:[UIScreen mainScreen].bounds];
       
       // Configure view controller
   
       self.viewController = [[MainViewController alloc] init];
       self.window.rootViewController = self.viewController;
       
       // Initialize Singular SDK
   
       [SingularCordovaSdk setLaunchOptions:launchOptions];
       
       // Make window visible
   
       [self.window makeKeyAndVisible];
       
       return YES;
   }
   
   - (BOOL)application:(UIApplication *)application
   continueUserActivity:(NSUserActivity *)userActivity
   restorationHandler:(void (^)(NSArray<id> *))restorationHandler {
       return [SingularCordovaSdk startSessionWithUserActivity:userActivity];
   }
   

3. Antes de inicializar o SDK Singular em seu código, adicione .withSingularLink ao objeto de configuração Singular e especifique sua função de manipulador de link:

   JavaScript

   var singularConfig = new
     cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");
   
   var linkHandler = function(data){
     var deeplink = data.deeplink;
     var passthrough = data.passthrough;
     var isDeferred = data.isDeferred;
     // Add link handling logic here
   
   
   }
   
   singularConfig.withSingularLink(linkHandler);
   
   cordova.plugins.SingularCordovaSdk.init(singularConfig);
   

Adicionando suporte a SKAdNetwork

O plug-in Singular oferece suporte à estrutura SKAdNetwork. Você pode ativar o rastreamento de SKAdNetwork para seu aplicativo usando as opções de configuração abaixo.

Modo gerenciado (recomendado)

No modo gerenciado, o Singular gerencia automaticamente o valor de conversão de SKAdNetwork para você, com base em um modelo de conversão de sua escolha que pode ser configurado na plataforma Singular.

Para saber mais, consulte Entendendo o gerenciamento de valores de conversão da Singular e as Perguntas frequentes sobre a configuração do modelo SKAdNetwork. Para obter um guia passo a passo sobre como usar a SKAdNetwork com a Singular, consulte Como começar a usar a SKAdNetwork.

Para ativar a SKAdNetwork no modo gerido, utilize o seguinte código:

var singularConfig = new
  cordova.plugins.SingularCordovaSdk.SingularConfig("", "");

// Enable SKAdNetwork (in managed mode by default)


singularConfig.withSkAdNetworkEnabled(true);

cordova.plugins.SingularCordovaSdk.init(singularConfig);

Modo manual

Se já tiver a sua própria estratégia e ferramentas para gerir o valor de conversão de SKAdNetwork, pode utilizar SKAdNetwork em modo manual.

Para ativar a SKAdNetwork em modo manual, utilize o seguinte código:

var singularConfig = new
  cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");

// Enable SKAdNetwork


singularConfig.withSkAdNetworkEnabled(true);

// Select SKAdNetwork manual mode


singularConfig.withManualSkanConversionManagement();

// Optional: define handler to track changes to the conversion value


var conversionHandler = function(updatedConversionValue){
  // Do something with updatedConversionValue


}

singularConfig.withConversionValueUpdatedHandler(conversionHandler);

// Initialize the Singular SDK


cordova.plugins.SingularCordovaSdk.init(singularConfig);

Para atualizar o valor de conversão, utilize o seguinte código:

cordova.plugins.SingularCordovaSdk.skanUpdateConversionValue(
  newConversionValue,
  function(isSuccess){
    // isSuccess == true if the update was successful


  }
)

Para recuperar o valor de conversão atual, utilize o seguinte código:

cordova.plugins.SingularCordovaSdk.skanGetConversionValue(
  function(conversionValue){
    // Do something with conversionValue


  }
)

Outras opções

Acompanhamento de desinstalações

Para permitir que a Singular rastreie desinstalações de aplicativos, envie o token APNS/FCM para a Singular usando o seguinte código:

Android:

cordova.plugins.SingularCordovaSdk.setUninstallToken(fcmToken)

iOS:

cordova.plugins.SingularCordovaSdk.setUninstallToken(apnsToken)

Criando links de referência curtos

Use links curtos para transformar links Singular longos e cheios de parâmetros em links mais curtos e mais seguros que são convenientes para compartilhamento.

Normalmente, pretende criar links curtos de forma dinâmica para que os utilizadores da sua aplicação possam partilhá-los com amigos para os convidar a utilizar a aplicação.

Para criar um link curto, você precisa de:

• Um link singular que leva ao download do seu aplicativo (consulte as Perguntas frequentes sobre links singulares).
• Quaisquer parâmetros que queira adicionar ao link dinamicamente (consulte Parâmetros de link de rastreamento para obter a lista de opções).
• O nome e a ID do utilizador de referência, se pretender acompanhar as novas instalações da aplicação até ao utilizador que partilhou o link.

Para criar links curtos, use o seguinte código:

cordova.plugins.SingularCordovaSdk.createReferrerShortLink(
    longLinkURL, 
    referrerName,
    referrerID,
    {
        // Tracking link parameters to add to the short link, e.g. "channel":"sms"


        param1: value1,
        param2: value2,
        ...
    },
    {
        onSuccess: function (shortLinkURL) {
        // Do something with shortLinkURL


        },
        onError: function (error) {
        // Handle error


        }
    }
)

Conformidade com as leis de privacidade de dados

A Singular fornece uma funcionalidade de proteção da privacidade para o ajudar a cooperar com quaisquer parceiros que possam estar em conformidade com as leis de privacidade do consumidor, como o GDPR e o CCPA(California Consumer Privacy Act). Estes parceiros querem ser notificados se o utilizador final consentiu em partilhar as suas informações privadas.

Se tiver implementado uma forma de pedir o consentimento dos utilizadores para partilharem as suas informações, utilize o método limitDataSharing para notificar a Singular da escolha do utilizador:

Utilize SingularCordovaSdk.limitDataSharing(false) para indicar que o utilizador consentiu (opted in) em partilhar as suas informações.

Utilize SingularCordovaSdk.limitDataSharing(true) se o utilizador não tiver dado o seu consentimento.

A Singular utiliza LimitDataSharing em"User Privacy Postbacks", bem como transmite esta informação a parceiros que a requerem para cumprir os regulamentos relevantes. Consulte"Privacidade do utilizador e Limitar partilha de dados" para obter mais informações.

// User has opted into sharing data


cordova.plugins.SingularCordovaSdk.limitDataSharing(false);

Métodos adicionais para conformidade com o GDPR

O Singular SDK fornece vários métodos para ajudá-lo a cumprir as políticas do GDPR e informar ao Singular sobre o consentimento ou não consentimento do usuário para rastreamento.

cordova.plugins.SingularCordovaSdk.trackingOptIn();

cordova.plugins.SingularCordovaSdk.stopAllTracking();

cordova.plugins.SingularCordovaSdk.resumeAllTracking();

cordova.plugins.SingularCordovaSdk.isAllTrackingStopped();