Integração SDK singular para Cordova

 

O SDK da Singular está disponível como um plug-in para o Cordova. As instruções abaixo mostram como integrar o Singular em seu aplicativo Cordova.

Pré-requisitos

  • Este artigo pressupõe que você tenha um aplicativo Cordova funcional.
  • Para inicializar o SDK, você precisa da chave do SDK da Singular e do segredo do SDK. Você pode obtê-los na plataforma Singular em "Developer Tools > SDK Integration > SDK Keys".

Como adicionar o plug-in da Singular

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

cordova plugin add singular_cordova_sdk

Ionic

Se estiver usando o Ionic:

  1. Instale o plug-in Singular SDK:

    $ ionic cordova plugin add singular_cordova_sdk
  2. Em 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:

    import {Component} from '@angular/core';
      import {Platform} from '@ionic/angular';
      declare var cordova;
      ...
      
      export class HomePage {
      constructor(public platform: Platform) {
      this.platform.ready().then(() => {
      
          // Adicione o código para inicializar o SDK Singular aqui
      
      }); 
      }}

Inicialização do 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 a Singular (as sessões são usadas para calcular a retenção de usuários).

Para inicializar o SDK da 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 Adicionar suporte a deep links e Adicionar suporte a SKAdNetwork abaixo).
  3. Suporte à atribuição de referenciador da instalação META

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

    1. Forneça seu Facebook App Id no objeto de configuração Singular.
      // Para ativar o referenciador de instalação META
      singularConfig.withFacebookAppId("INSIRA SEU ID DO APLICATIVO DO FACEBOOK AQUI");
    Onde posso encontrar o Facebook App ID de um aplicativo?
  4. Inicialize o SDK usando o objeto SingularConfig.

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

// Crie o objeto de configuração
  var singularConfig = new
  cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");
  
  /*
  // Opcional: ative links diretos (requer etapas de configuração adicionais, consulte o guia)
  var linkHandler = function(data){
  var deeplink = data.deeplink;
  var passthrough = data.passthrough;
  var isDeferred = data.isDeferred;
  // Adicione lógica de manipulação de link aqui
  }
  singularConfig.withSingularLink(linkHandler);
  */
  
/*
// Para ativar o referenciador de instalação META
singularConfig.withFacebookAppId("INSIRA SEU ID DO APLICATIVO DO FACEBOOK AQUI");
*/
/* // Opcional: habilite SKAdNetwork (no modo gerenciado, consulte o guia para mais opções) singularConfig.withSkAdNetworkEnabled(true); */ // Inicializar Singular cordova.plugins.SingularCordovaSdk.init(singularConfig);

Envio da ID de usuário para a Singular (opcional)

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

Observação: Se você usar a solução Cross-Device da Singular, deverá coletar o ID do usuário em todas as plataformas.

  • O ID do usuário pode ser qualquer identificador e não deve expor PII (Informações Pessoais Identificáveis). Por exemplo, você não deve usar o endereço de e-mail, nome de usuário ou número de telefone de um usuário. A Singular recomenda o uso de um valor hash exclusivo apenas para seus dados primários.
  • O valor do ID de usuário passado para a Singular também deve ser o mesmo ID de usuário interno que você captura em todas as plataformas (Web/Mobile/PC/Console/Offline).
  • A Singular incluirá o ID de usuário nas exportações em nível de usuário, ETL e postbacks de BI interno (se configurado). O ID do usuário é um dado primário, e a Singular não o compartilha com terceiros.
  • O valor da ID de usuário, quando definido com o método Singular SDK, persistirá até que seja desfeito usando o método unsetCustomUserId ou até que o aplicativo seja desinstalado. Fechar ou reiniciar o aplicativo não desativa a ID do usuário.

Para definir a ID de usuário, use o método setCustomUserId. Para desmarcá-la (por exemplo, se o usuário fizer "logout" da conta), chame unsetCustomUserId.

Observação: se vários usuários usarem um único dispositivo, recomendamos a implementação de um fluxo de logout para definir e cancelar a definição da ID de usuário para cada login e logout.

Se você já souber a ID do usuário quando o aplicativo for aberto, ligue para setCustomUserId antes de inicializar o SDK da Singular. Dessa forma, a 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, ligue para setCustomUserId depois que o fluxo de registro for concluído.

Método SingularCordovaSdk.setCustomUserID
Descrição Envia o ID do usuário para o Singular.
Assinatura SingularCordovaSdk.setCustomUserId(String customUserId)
Exemplo de uso
SingularCordovaSdk.setCustomUserId('CustomUserId');
Método SingularCordovaSdk.unsetCustomUserID
Descrição Desfaz a definição do ID de usuário que foi enviado para a Singular.
Assinatura SingularCordovaSdk.unsetCustomUserId()
Exemplode uso
SingularCordovaSdk.unsetCustomUserId();

Opcional: Mapeamento de dispositivo de ID de usuário personalizado

Importante: Esse recurso avançado da Enterprise só está disponível em casos excepcionais. Consulte um dos engenheiros de soluções da Singular antes de implementá-lo.

A Singular pode receber dados adicionais de rastreamento de eventos móveis por meio de uma integração de servidor para servidor. Para utilizar esse recurso, você deve mapear o ID do usuário para o identificador de rastreamento de dispositivos móveis da Singular.

Observação: chame esse método o mais rápido possível após a inicialização do SDK da Singular ou assim que tiver o ID do usuário.

Método SingularCordovaSdk.setDeviceCustomUserId
Descrição Define o ID de usuário personalizado igual ao login e o mapeia para o identificador de rastreamento da Singular.
Assinatura SingularCordovaSdk.setDeviceCustomUserId(String customUserId)
Exemplo de uso
SingularCordovaSdk.setDeviceCustomUserId('CustomUserId');

Rastreamento de eventos (não receita)

Além de enviar sessões de usuário para a Singular (por meio 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 a Singular, use o método eventWithArgs . Dê um nome ao evento e adicione os atributos que deseja rastrear.

// Exemplo: Relatar um evento chamado Visualizar Produto com atributos de evento
  cordova.plugins.SingularCordovaSdk.eventWithArgs(
    'ViewProduct', // Nome do evento
    {
      // Atributos de evento
      productID:"123",
      productCategory:"Outerwear"
    }
  )

Rastreamento de receita

Para permitir que a Singular rastreie a receita que seu aplicativo obtém com compras no aplicativo, informe eventos IAP à 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 detectar 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 você estiver usando a biblioteca https://github.com/j3k0/cordova-plugin-purchase, poderá usar 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)
  }

Envio de receita personalizada

Se você não puder enviar o objeto IAP para a Singular, uma alternativa é usar o método customRevenue, que aceita um nome de evento, um código de moeda e o valor da compra.

Exemplo:

cordova.plugins.SingularCordovaSdk.customRevenue(
    customEventName, // Exemplo "purchase"
    currencyCode, // Exemplo "USD"
    purchaseAmount // Exemplo 3.2
  );

Observação: passe a moeda como um código de moeda ISO 4217 de três letras, por exemplo, "USD", "EUR", "INR".

Rastreamento híbrido de eventos (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 pelo 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.

Importante:

Ocorrerão discrepâncias se os identificadores de dispositivo usados nas solicitações de eventos Server-to-Server não tiverem um identificador de dispositivo correspondente no Singular. Esteja ciente das seguintes possibilidades:

  • Se uma solicitação de evento for recebida "antes" de o SDK do Singular ter registrado o identificador do dispositivo, a partir de uma sessão de aplicativo, a solicitação de evento será considerada a "primeira sessão" do dispositivo desconhecido, e o Singular atribuirá o dispositivo como uma atribuição orgânica.
  • Se o Singular SDK tiver registrado um identificador de dispositivo, mas o identificador do Singular SDK for diferente do identificador de dispositivo especificado na solicitação de evento de servidor para servidor, o evento será atribuído incorretamente.

Guias de rastreamento de eventos híbridos

Envio de eventos de um servidor interno

A Singular pode coletar dados sobre a receita de seu servidor para ajudar a analisar o desempenho e o ROI de suas campanhas.

Requisitos:

  • A partir de um evento de registro ou login no aplicativo, capture e passe os identificadores de dispositivo e armazene esses dados com o ID do usuário no seu servidor. Como os identificadores de dispositivo podem mudar para um usuário, certifique-se de atualizar os identificadores quando um usuário gerar uma sessão de aplicativo. Isso garante que o evento no lado do servidor será atribuído ao dispositivo correto.
  • Os eventos do lado do servidor são específicos da plataforma e só devem ser enviados com o identificador de dispositivo correspondente à plataforma do dispositivo (por exemplo, IDFA ou IDFV para dispositivos iOS).
  • Você pode usar o mecanismo de postback do Singular Internal BI para enviar um evento em tempo real para seu endpoint interno, de modo que possa atualizar o conjunto de dados no lado do servidor. Consulte as Perguntas frequentes sobre postback do BI interno.
  • Consulte a seção "Rastreamento de receita" no guia Integração servidor a servidor para obter detalhes.
Envio de eventos de um provedor de receita
Provedores de terceiros, como RevenueCat ou adapty, podem fornecer receita de compra e assinatura para a Singular.

Siga os links abaixo para obter detalhes sobre como habilitar esses parceiros.

Envio de eventos do segmento

Para permitir que o Segment envie eventos para a Singular, em paralelo com o SDK da Singular, você deve adicionar um destino "Cloud-Mode" no Segment. Siga nosso guia AQUI.

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

Você pode usar o plug-in Singular para configurar a atribuição de receita de anúncios (consulte as Perguntas frequentes sobre atribuição de receita de anúncios).

Para configurar a atribuição de receita de anúncios:

  1. Adicione o trecho de código apropriado para obter informações de receita de anúncios da plataforma de mediação que você usa para dados de receita de anúncios. Consulte os trechos de código em nossa documentação do Android SDK.

Observação: passe a moeda como um código de moeda ISO 4217 de três letras, por exemplo, "USD", "EUR", "INR".

Informe os eventos de receita de anúncios à Singular usando o seguinte código
  1. Inicialize o objeto SingularAdData com os dados relevantes
  2. Informar os dados à Singular
Javascript
const adData = new cordova.plugins.SingularCordovaSdk.SingularAdData(
   mediationPlatform,
   currencyCode, // e.g., "USD"
   revenueAmount)

cordova.plugins.SingularCordovaSdk.adRevenue(adData);

Adição de suporte a Deep Linking

Deep links são links que abrem o aplicativo no telefone do usuário e o enviam diretamente para uma página ou experiência de usuário específica, em vez de apenas para o widget principal do aplicativo.

Os links profundos geralmente são usados em campanhas de retargeting, destinadas a usuários que já têm o aplicativo em seus telefones, mas que talvez não tenham se envolvido com ele por algum tempo.

A Singular suporta deep linking 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:

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

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

    #import "SingularCordovaSdk.h"
      
        - (BOOL)application:(UIApplication*)application
        didFinishLaunchingWithOptions:(NSDictionary*)launchOptions
        {
           self.viewController = [[MainViewController alloc] init];
           [SingularCordovaSdk setLaunchOptions: launchOptions];
           return [super
        application:application didFinishLaunchingWithOptions:launchOptions];
        }
      
        - (BOOL)application:(UIApplication *)application
        continueUserActivity:(NSUserActivity *)userActivity
        restorationHandler:(void (^)(NSArray<id> * _Nullable))restorationHandler{
         [SingularCordovaSdk startSessionWithUserActivity:userActivity];
         return
        YES;
        }
  3. Antes de inicializar o Singular SDK em seu código, adicione .withSingularLink ao objeto de configuração do Singular e especifique sua função de manipulador de links:

    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;
        // Adicione lógica de manipulação de link aqui
      }
      
      singularConfig.withSingularLink(linkHandler);
      
      cordova.plugins.SingularCordovaSdk.init(singularConfig);

Adição de suporte a SKAdNetwork

O plug-in Singular é compatível com a 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, a Singular gerencia automaticamente o valor de conversão da 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 do valor de conversão da Singulare 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 gerenciado, use o seguinte código:

var singularConfig = new
    cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");
  
  // Habilitar SKAdNetwork (no modo gerenciado por padrão)
  singularConfig.withSkAdNetworkEnabled(true);
  
  cordova.plugins.SingularCordovaSdk.init(singularConfig);

Modo manual

Se você já tiver sua própria estratégia e ferramentas para gerenciar o valor de conversão da SKAdNetwork, poderá usar a SKAdNetwork no modo manual.

Para ativar a SKAdNetwork no modo manual, use o código a seguir:

var singularConfig = new
    cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");
  
  // Ativar SKAdNetwork
  singularConfig.withSkAdNetworkEnabled(true);
  
  // Selecione o modo manual SKAdNetwork
  singularConfig.withManualSkanConversionManagement();
  
  // Opcional: defina o gerenciador para rastrear alterações no valor de conversão
  var conversionHandler = function(updatedConversionValue){
    // Faça algo com updateConversionValue
  }
  
  singularConfig.withConversionValueUpdatedHandler(conversionHandler);
  
  // Inicialize o SDK Singular
  cordova.plugins.SingularCordovaSdk.init(singularConfig);

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

cordova.plugins.SingularCordovaSdk.skanUpdateConversionValue(
    newConversionValue,
    function(isSuccess){
      // isSuccess == true se a atualização foi bem-sucedida
    }
  )

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

cordova.plugins.SingularCordovaSdk.skanGetConversionValue(
    function(conversionValue){
      // Faça algo com ConversionValue
    }
  )

Outras opções

Rastreamento 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)

Criação de links de referência curtos

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

Normalmente, você desejará criar links curtos dinamicamente para que os usuários do seu aplicativo possam compartilhá-los com amigos e convidá-los a usar o aplicativo.

Para criar um link curto, você precisa de:

  • Um Singular Link que leve ao download do aplicativo (consulte as Perguntas frequentes sobre Singular Links).
  • Quaisquer parâmetros que você queira adicionar ao link dinamicamente (consulte Parâmetros do link de rastreamentopara obter a lista de opções).
  • O nome e o ID do usuário de referência, se você quiser rastrear as novas instalações do aplicativo até o usuário que compartilhou o link.

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

cordova.plugins.SingularCordovaSdk.createReferrerShortLink(
      longLinkURL, 
      referrerName,
      referrerID,
      {
          // Parâmetros de link de rastreamento para adicionar ao link curto, por exemplo. "channel":"sms"
          param1: value1,
          param2: value2,
          ...
      },
      {
          onSuccess: function (shortLinkURL) {
          // Faça algo com shortLinkURL
          },
          onError: function (error) {
          // Lidar com erro
          }
      }
  )

Conformidade com as leis de privacidade de dados

A Singular fornece a funcionalidade de proteção da privacidade para ajudá-lo a cooperar com quaisquer parceiros que possam estar em conformidade com as leis de privacidade do consumidor, como GDPR e CCPA(California Consumer Privacy Act). Esses parceiros querem ser notificados se o usuário final consentiu em compartilhar suas informações privadas.

Se você tiver implementado uma forma de solicitar o consentimento dos usuários para compartilhar suas informações, use o método limitDataSharing para notificar a Singular sobre a escolha do usuário:

Use SingularCordovaSdk.limitDataSharing(false) para indicar que o usuário consentiu (optou por participar) em compartilhar suas informações.

Use SingularCordovaSdk.limitDataSharing(true)se o usuário não consentiu.

A Singular usa LimitDataSharing em "Postbacks de privacidade do usuário", bem como repassa essas informações a parceiros que as exigem para cumprir os regulamentos relevantes. Consulte "Privacidade do usuário e Limite de compartilhamento de dados" para obter mais informações.

Observação: O uso do método é opcional, mas pode haver informações de atribuição que o parceiro compartilhará com a Singular somente se for especificamente notificado de que o usuário optou por participar.

Método SingularCordovaSdk.limitDataSharing
Assinatura SingularCordovaSdk.limitDataSharing(booleanshouldLimitDataSharing)
Descrição Notifica a Singular sobre o consentimento do usuário (opt-in) para compartilhar dados privados.
Exemplo de uso
// O usuário optou por compartilhar dados
cordova.plugins.SingularCordovaSdk.limitDataSharing(false);

Métodos adicionais para conformidade com o GDPR

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

Método SingularCordovaSdk.trackingOptIn
Descrição Notifica a Singular sobre o consentimento do usuário (opt-in) para rastreamento.
Exemplo de uso
cordova.plugins.SingularCordovaSdk.trackingOptIn();
Método SingularCordovaSdk.stopAllTracking
Descrição

Interrompe todas as atividades de rastreamento para este usuário neste aplicativo.

Observação: a chamada desse método desativa efetivamente o SDK, mesmo após a reinicialização do aplicativo (o estado é persistente)! A única maneira de reativar o rastreamento é chamar resumeAllTracking().
Exemplo de uso
cordova.plugins.SingularCordovaSdk.stopAllTracking();
Método SingularCordovaSdk.resumeAllTracking
Descrição Retoma o rastreamento para esse usuário nesse aplicativo.
Exemplo de uso
cordova.plugins.SingularCordovaSdk.resumeAllTracking();
Método SingularCordovaSdk.isAllTrackingStopped
Descrição Verifica o status de rastreamento desse usuário neste aplicativo. Retorna true se o rastreamento tiver sido interrompido usando StopAllTracking() e não tiver sido retomado.
Exemplo de uso
cordova.plugins.SingularCordovaSdk.isAllTrackingStopped();