Como adicionar o SDK ao seu projeto

Para adicionar o Singular React SDK ao seu projeto:

1. Abra o terminal no diretório raiz de seu projeto.

2. Faça o download do pacote SDK para seu projeto com o seguinte comando:

   npm install singular-react-native --save

3. Se você estiver usando o React Native 0.60+, o pacote Singular será vinculado automaticamente ao seu projeto.

   Se estiver usando o React Native versão 0.59 ou anterior, execute o seguinte para vincular o código de ponte nativo do pacote Singular ao seu projeto:

   react-native link singular-react-native

Configuração de pré-requisitos

Pré-requisitos do iOS

No diretório raiz do projeto, execute o seguinte comando:

cd ios; pod install

Pré-requisitos do Android

No arquivo build.gradle dentro da seção allprojects, adicione o seguinte aos repositórios Maven do seu aplicativo:

allprojects {
  repositories {
    maven { url 'https://maven.singular.net/' }
  }
}

Adicione as seguintes permissões ao arquivo AndroidManifest.xml do aplicativo:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!--  Essa permissão é necessária para recuperar os dados do Google Play Referrer -->
<uses-permission android:name="com.google.android.finsky.permission.BIND_GET_INSTALL_REFERRER_SERVICE" />

<!--  Essa permissão é necessária para recuperar dados da API de licenciamento do Google  -->
<uses-permission android:name="com.android.vending.CHECK_LICENSE" />

Se a compilação do seu aplicativo tiver como alvo o Android 12/API nível 31 ou superior, adicione permissões para acessar o ID de publicidade do Google:

<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

Se você desativou as dependências transitivas para o Singular SDK, adicione o seguinte ao arquivo build.gradle.

implementation 'com.android.installreferrer:installreferrer:2.2'
implementation 'com.google.android.gms:play-services-appset:16.0.0'

Inicialização do SDK

O código de inicialização do SDK deve ser chamado sempre que seu aplicativo for aberto. Ele é um pré-requisito para todas as funcionalidades de atribuição da Singular e 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.

Importação das classes necessárias

Em seu arquivo App.js, adicione o seguinte código para importar as classes Singular e SingularConfigs.

import {Singular, SingularConfig, Events, Attributes} from 'singular-react-native';

Configuração e inicialização do SDK

1. Antes de inicializar o Singular SDK, você precisa criar um objeto SingularConfig. O objeto contém sua chave SDK e seu segredo SDK (você pode obtê-los fazendo login em sua conta Singular e acessando "Developer Tools > SDK Integration > SDK Keys").
2. Opcionalmente, você pode adicionar configurações para ativar vários recursos do SDK.
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
      config.withFacebookAppId("INSIRA SEU ID DO APLICATIVO DO FACEBOOK AQUI");

   Onde posso encontrar o Facebook App ID de um aplicativo?
4. Em seguida, use o método init para inicializar o SDK, passando o objeto SingularConfig

Por exemplo:

const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');
  
 // Configurações opcionais:
 // Defina o ID do usuário se for conhecido no momento da inicialização
 config.withCustomUserId("274e9db5c836093499df921be5b7f32001d49c50"); 
  
 // Para ativar a META Install Referrer
 config.withFacebookAppId("INSERT YOUR FACEBOOK APP ID HERE");
  
 // Permite a criação de links diretos
 config.withSingularLinks(callBackFunction); 
  
 Singular.init(config);

Singular.init(config);

Envio do 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.

• 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. O fechamento ou a reinicialização do aplicativo não desinstala a ID de usuário.

Para definir a ID de usuário, use o método setCustomUserId. Para cancelar a definição (por exemplo, se o usuário fizer "logout" da conta), ligue para unsetCustomUserId.

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, chame setCustomUserId depois que o fluxo de registro for concluído.

Singular.setCustomUserId("custom_user_id");

Singular.unsetCustomUserId();

Singular.setDeviceCustomUserId("CustomUserId");

Como lidar com o consentimento do AppTrackingTransparency

A partir do iOS 14.5, é necessário solicitar o consentimento do usuário (usando o ATTrackingManager) antes de poder acessar o IDFA do dispositivo para rastreamento.

Se quiser inicializar o Singular SDK antes de solicitar o consentimento do usuário, você pode atrasar o disparo de eventos do SDK sem IDFA por um intervalo de tempo especificado, a fim de aguardar o consentimento do usuário.

Para isso, inicialize o Singular SDK com a opção waitForTrackingAuthorizationWithTimeoutInterval, como no exemplo a seguir:

const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');
  
// Ativar a SKAdNetwork
config.withSkAdNetworkEnabled(true);
  
// Aguarde 5 minutos pela autorização de rastreamento antes de enviar qualquer evento
config.withWaitForTrackingAuthorizationWithTimeoutInterval(300);
  
Singular.init(config);

Rastreamento de eventos (não receita)

A Singular pode coletar dados sobre eventos in-app para ajudar a analisar o desempenho de suas campanhas 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.

A Singular oferece suporte a uma variedade de eventos padrão, que são comumente usados pelas redes de anúncios para geração de relatórios e otimização. Outra vantagem é que, quando você usa nomes de eventos padrão, o Singular os reconhece automaticamente e os adiciona à lista de eventos sem que você precise defini-los manualmente. Recomendamos o uso de eventos padrão sempre que possível.

A lista de eventos enviados à Singular (com os atributos que os acompanham) deve ser compilada pela equipe de UA/marketing/negócios com base nos KPIs de marketing da sua organização. A equipe de negócios pode seguir o guia em How to Track In-App Events: Guide For Singular Attribution Customers (Guia para clientes de atribuição singular) .

Com cada evento que você rastreia, é possível passar vários atributos. Veja os atributos padrão recomendados por evento.

Em seu código, envie eventos para a Singular usando os métodos event ou eventWithArgs.

/* Enviar o login de evento padrão */
Singular.event(sngLogin);

/* Envie o Standard Event Content View com os atributos recomendados */
Singular.eventWithArgs(sngContentView, { 
  sngAttrContentType: 'PrivacyController',
  sngAttrContentId: '130',
  sngAttrContent: 'GDPR Opt-Out Options'
});

Rastreamento de receita

A Singular pode coletar dados sobre a receita obtida por meio do aplicativo para ajudar a analisar o desempenho e o ROI de suas campanhas. A Singular disponibilizará os dados para você em relatórios, exportação de registros e postbacks.

Ao relatar eventos de receita para a Singular, recomendamos passar o objeto de compra conforme retornado do processo de compra no aplicativo (IAP ) do Android ou do iOS. Dessa forma, a Singular obtém todos os detalhes da transação, o que enriquece seus relatórios da Singular com dados. Além disso, a Singular obtém o recibo da transação do Google, que pode ser usado para validar a transação no contexto do combate à fraude no aplicativo.

Passando o objeto de compra no React Native

// Adicionar as importações das classes do Singular Purchase
import {
   Singular,
   SingularConfig,
   SingularIOSPurchase,
   SingularAndroidPurchase,
  } from 'singular-react-native';
  
  let singularPurchase = null;
  
  if (Platform.OS === 'ios') {
   singularPurchase = new SingularIOSPurchase(
     product.revenue,
     product.currency,
     purchase.productId,
     purchase.transactionId,
     purchase.transactionReceipt,
   );
  } else if (Platform.OS === 'android'){
   singularPurchase = new SingularAndroidPurchase(
     product.revenue,
     product.currency,
     purchase.transactionReceipt,
     purchase.signatureAndroid,
   );
  }
  
  Singular.inAppPurchase('report iap', singularPurchase);

Passagem do objeto Purchase usando código nativo

iOS

// informar os detalhes da transação à Singular
[Singular iapComplete:transaction];
  
// informar os detalhes da transação à Singular com um nome personalizado
[Singular iapComplete:transaction withName:@"MyCustomRevenue"];

Android

Para tirar proveito da funcionalidade IAP do Android, primeiro adicione o seguinte ao arquivo build.gradle do seu aplicativo:

implementation 'com.singular.sdk:singular_sdk:9.+

Singular.revenue("USD", 5.50, purchase);

Singular.customRevenue("MyCustomRevenue", 
    "USD", 5.50, purchase);

Relatório de eventos de receita sem o objeto de compra

Embora seja altamente recomendável relatar eventos de receita da maneira descrita acima, você também pode enviar eventos de receita para a Singular apenas passando a moeda e o valor da transação. Observe que, dessa forma, a Singular não obtém o recibo de compra e não pode validar a transação.

Singular.revenue("USD", 5.50);

Singular.customRevenue("MyCustomRevenue", "USD", 5.50);

Adição de suporte à atribuição de receita de anúncios (avançado)

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.

Guias de rastreamento de eventos híbridos

Adição de suporte a Deep Linking

Deep links são links que levam a um conteúdo específico dentro de um aplicativo. Quando um usuário clica em um link profundo em um dispositivo que tem o aplicativo instalado, o aplicativo é aberto e mostra um produto ou uma experiência específica.

Os links de rastreamento singulares podem incluir links diretos, bem como links diretos diferidos(consulte nossas Perguntas frequentes sobre links diretos e as Perguntas frequentes sobre links singulares para obter mais informações).

As instruções abaixo mostrarão a você como:

1. Acessar o link de rastreamento que levou à abertura do seu aplicativo,
2. Ler o destino do deep link e
3. Mostrar o conteúdo apropriado.

Ativação de Singular Links

Para ativar o Singular Links no iOS e no Android, consulte Pré-requisitos do Singular Links.

Manipulação de Singular Links

O SDK da Singular fornece um mecanismo de manipulador para ler os detalhes do link de rastreamento que levou à abertura do aplicativo.

Para usar o manipulador:

1. Chame withSingularLinks quando você criar o objeto SingularConfig, como no exemplo abaixo. Isso registra um manipulador de Singular Links.
2. Dentro do manipulador, chame ou defina uma função de retorno de chamada que receba um objeto SingularLinksParams, como no exemplo abaixo. O objeto SingularLinksParams contém os seguintes campos:
   • deeplink - o endereço do deep link fornecido no parâmetro de consulta. _dl Isso é o que você precisa analisar para mostrar aos usuários o produto ou a experiência correta.
   • passthrough - todos os parâmetros incluídos no parâmetro de consulta _p parâmetro de consulta do Singular Link.
   • isDeferred - True se esse for um deep link diferido.
   • urlParameters - todos os parâmetros de string de consulta do Singular Tracking Link.
     • Você deve anexar o par _forward_params=1 ao Singular Tracking Link para que todos os parâmetros de string de consulta estejam disponíveis no SDK.

const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');
  config.withSingularLink(singularLinksParams => {
      const deeplink = singularLinksParams.deeplink;
      const passthrough = singularLinksParams.passthrough;
      const isDeferred = singularLinksParams.isDeferred;
      const urlParameters = singularLinksParams.urlParameters;
      
      // Adicione seu código aqui para lidar com o deep link
  });
  //...
  Singular.init(config);

Configuração dos pré-requisitos

Pré-requisitos do iOS

Na seção AppDelegate.m do projeto, adicione o seguinte:

// Parte superior do AppDelegate.m
  #import <Singular-React-Native/SingularBridge.h>
  
  - (BOOL)application:(UIApplication *)application 
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
      // Adicionar dentro de didFinishLaunchingWithOptions
      [SingularBridge startSessionWithLaunchOptions:launchOptions];
    return YES;
  }
  
  // Adicione este método ao delegado do aplicativo
  - (BOOL)application:(UIApplication *)application 
    continueUserActivity:(NSUserActivity *)userActivity 
      restorationHandler:(void (^)(NSArray<id> * _Nullable))restorationHandler{
        [SingularBridge startSessionWithUserActivity:userActivity];
        return YES;
  }

Pré-requisitos do Android

Na seção MainActivity.java do projeto, adicione o seguinte:

// Adicione como parte das importações na parte superior da classe
import android.content.Intent;
import net.singular.react_native.SingularBridgeModule;
  
// Adicionar à classe MainActivity
  @Override
  public void onNewIntent(Intent intent) {
    if(intent.getData() != null) {
      setIntent(intent);
      super.onNewIntent(intent);
      SingularBridgeModule.onNewIntent(intent);
    }
  }

Introdução: SKAdNetwork e SKAN

SKAdNetwork é a nova estrutura da Apple para atribuir instalações móveis sem comprometer a privacidade do usuário final. A nova versão do SDK do iOS da Singular ajuda você a implementar a SKAdNetwork sem problemas e com o mínimo de esforço de engenharia. Essa implementação da SKAdNetwork é baseada no SKAN - um padrão desenvolvido pela Singular para uma implementação tranquila da SKAdNetwork.

Para obter um guia completo sobre a implementação de SKAdNetwork da Singular, consulte o guia de implementação de SKAdNetwork do SDK do iOS.

Ativação do rastreamento de SKAdNetwork

Para ativar o rastreamento de SKAdNetwork para seu aplicativo, ative a opção de configuração skAdNetworkEnabled antes de inicializar o Singular:

const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');

// Ativar a SKAdNetwork
config.withSkAdNetworkEnabled(true);

// Registre-se em um retorno de chamada para quando o valor de conversão for atualizado
config.conversionValueUpdatedHandler(value => {
	console.log(`Updated conversion value: ${value}`);
  });

Singular.init(config);

Manipulação de atualizações de valores de conversão

Modo gerenciado

Por padrão, a implementação da SKAdNetwork gerencia o valor de conversão diretamente do lado do servidor Singular.

Isso permite o máximo de flexibilidade, pois você pode definir e alterar seus valores de conversão por meio da plataforma Singular, sem modificar o código do lado do cliente.

Esse modo gerenciado no lado do servidor também o ajuda a lidar com os temporizadores da SKAdNetwork. A SKAdNetwork permite que você atualize o valor de conversão dentro de 24 horas a partir do momento do registro na SKAdNetwork. Qualquer chamada para atualizar o valor de conversão estende o cronômetro por mais 24 horas. Portanto, ao escolher seus eventos de conversão, você terá que se certificar de que os eventos ocorram dentro dessa janela de atualização. No modo gerenciado, você pode alterar a configuração do evento de conversão a qualquer momento, sem lançar uma nova versão do seu aplicativo.

Modo manual

Se você quiser atualizar o valor de conversão por conta própria no código do aplicativo, chame withManualSkanConversionManagement ao inicializar o SDK:

const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');
// Ativar a SKAdNetwork
config.withSkAdNetworkEnabled(true);

// Habilitar atualizações manuais do valor de conversão
config.withManualSkanConversionManagement();

Singular.init(config);

Em seguida, para atualizar o valor de conversão, use o método skanUpdateConversionValue sempre que necessário no ciclo de vida do aplicativo:

// evento de registro aconteceu
Singular.event("SignUp");

// atualizar o valor de conversão para 7
Singular.skanUpdateConversionValue(7);

Recuperação do valor de conversão

Para obter o valor de conversão atual, use o método skanGetConversionValue. Esse método funciona tanto no modo gerenciado quanto no manual.

const conversionValue = Singular.skanGetConversionValue();

Criação de links de referência curtos

Use links curtos para transformar Singular Links longos e cheios de parâmetros 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 rastreamento para 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.

Use o método createReferrerShortLink para criar um link curto, como no exemplo abaixo.

Singular.createReferrerShortLink (
    "https://sample.sng.link/B4tbm/v8fp?_dl=https%3A%2F%2Fabc.com",
    "John Doe", // Nome do referenciador
    "aq239897", // ID do referenciador
    {"channel": "sms"}, // Any parameters you want to add to the link
    (shortLinkURL,error) => {
      /* Adicione sua lógica de compartilhamento aqui se shortLinkURL não for nulo. Se houver um erro, adicione a lógica para tentar novamente/abortar/modificar os parâmetros passados para a função, com base na causa do erro. */
    }
)

Rastreamento de desinstalações

Para permitir que o Singular rastreie as desinstalações de seu aplicativo:

1. Primeiro, configure o aplicativo na plataforma Singular, conforme detalhado em Configuração do rastreamento de desinstalação [Android][iOS].
2. Use seu método preferido para recuperar os tokens APNS/FCM no React Native.
3. Chame o método setUninstallToken, passando o token APNS/FCM como no exemplo abaixo. Certifique-se de passar o token correto com base na plataforma do dispositivo.

if (Platform.OS === 'ios') {
  Singular.setUninstallToken(apnsToken);
} else if (Platform.OS === 'android'){
  Singular.setUninstallToken(fcmToken);
}

Modificação do tempo limite da sessão

O Singular SDK gerencia as sessões de usuário automaticamente, portanto, não é necessário adicionar nenhum código para lidar com as sessões. No entanto, você pode modificar o valor do tempo limite da sessão, se desejar.

Por padrão, se o aplicativo for executado em segundo plano por 60 segundos ou mais antes de retornar ao primeiro plano, o SDK registrará uma nova sessão.

Para alterar o valor do tempo limite, use .withSessionTimeoutInSec ao criar o objeto SingularConfig. Por exemplo:

const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>')
    .withSessionTimeoutInSec(120); // Defina o tempo limite para 120 segundos
Singular.init(config);

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.

Limite o compartilhamento de dados

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 limitDataSharing:NO para indicar que o usuário consentiu (optou por participar) em compartilhar suas informações.
• Use limitDataSharing:YES 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.

// O usuário optou por compartilhar dados
Singular.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.

Singular.trackingOptIn();

Singular.stopAllTracking();

Singular.resumeAllTracking();

Singular.isAllTrackingStopped();