Pré-requisitos

Conclua estes passos pré-requisitos antes de instalar o Singular SDK do React Native para garantir um processo de integração sem problemas.

Instalação

Instalação do pacote SDK

Adicione o SDK Singular React Native ao seu projeto utilizando o npm. O SDK fornece ligações JavaScript aos SDKs nativos da Singular para iOS e Android.

Instalar via NPM

1. Abra o terminal: Navegue até ao diretório raiz do seu projeto.
2. Instalar o pacote: Execute o seguinte comando para adicionar o SDK ao seu projeto:
   bash

   npm install singular-react-native --save

Ligar os módulos nativos

A forma como liga o SDK depende da sua versão do React Native e se está a utilizar o Expo.

• React Native 0.60+: O SDK vincula-se automaticamente. Não são necessárias etapas adicionais.
• React Native 0.59 ou anterior: Vincule manualmente o código da ponte nativa:
  bash

  react-native link singular-react-native

• Projetos Expo: Após instalar o SDK, adicione-o à sua configuração de plugins:
  app.json

  {
    "expo": {
      "plugins": ["singular-react-native"]
    }
  }

  Em seguida, recompile a sua aplicação utilizando o guia de personalização de código nativo do Expo.

Configuração da plataforma

Configuração do iOS

Conclua a configuração específica do iOS para ativar as dependências do CocoaPods e garantir o funcionamento adequado do SDK.

Instalar as dependências do CocoaPods

Execute o seguinte comando a partir do diretório raiz do seu projeto para instalar as dependências iOS necessárias:

cd ios && pod install

Configuração do Android

Configure os seus ficheiros de compilação do Android para adicionar o repositório Singular Maven, as permissões necessárias e as dependências.

Adicionar repositório Maven

Adicione o repositório Maven da Singular ao ficheiro build.gradle do seu projeto para ativar a resolução de dependências do SDK.

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

Adicionar permissões necessárias

Adicione estas permissões ao seu ficheiro AndroidManifest.xml sob a tag <manifest> para ativar a funcionalidade principal do SDK.

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="BIND_GET_INSTALL_REFERRER_SERVICE" />
<uses-permission android:name="com.android.vending.CHECK_LICENSE" />
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

Suporte da Samsung Galaxy Store

Para ativar o rastreamento de referência de instalação da Samsung Galaxy Store, adicione o seguinte ao seu AndroidManifest.xml:

<queries>
   <package android:name="com.sec.android.app.samsungapps" />
</queries>

Dependências transitivas

Se desativou as dependências transitivas para o Singular SDK na sua configuração do Gradle, adicione manualmente estas dependências necessárias:

dependencies {
    // Required for install referrer tracking
    implementation("com.android.installreferrer:installreferrer:2.2")

    // Required for App Set ID
    implementation("com.google.android.gms:play-services-appset:16.0.0")
}

Configuração do ProGuard

Ao compilar APKs de lançamento, o ProGuard (ou R8) pode remover ou ofuscar classes do SDK . Adicione estas regras de retenção para preservar a funcionalidade do Singular.

1. Localize o ficheiro do ProGuard: Navegue até android/app/proguard-rules.pro no seu projeto.
2. Adicione regras de preservação: acrescente as seguintes regras ao ficheiro:
   proguard-rules.pro

   # Preserve Singular SDK classes
   -keep class com.singular.sdk.** { *; }
   
   # Preserve Android Install Referrer library
   -keep public class com.android.installreferrer.** { *; }
   
   # Uncomment if using Singular revenue tracking with Google Play Billing Library
   #-keep public class com.android.billingclient.** { *; }

Integração do SDK

Importar classes do SDK

Importe as classes do SDK da Singular no início do seu ficheiro principal da aplicação (normalmente App.tsx ou App.js).

// Direct TurboModule API initialization (React Native 0.76+)

// Import Native API and EventEmitter
import NativeSingular from 'singular-react-native/js/NativeSingular';
import { NativeEventEmitter } from 'react-native';

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

Inicializar o SDK

Inicialização básica

1. Obter credenciais: Inicie sessão na sua con ta Singular e navegue até Ferramentas do Desenvolvedor > Integração do SDK > Chaves do SDK para encontrar a sua Chave e Segredo do SDK.
2. Criar configuração: Instancie um objeto SingularConfig, ou um objeto simples para a API do TurboModule, com as suas credenciais.
3. Adicione a configuração: Opcionalmente, encadeie métodos de configuração (legado) ou adicione propriedades diretamente no objeto de configuração (TurboModule).
4. Inicializar SDK: Chame Singular.init() ou NativeSingular.init() para iniciar o SDK.

Exemplo de inicialização

Inicialize o SDK no ponto de entrada da sua aplicação, normalmente dentro de um gancho useEffect para garantir que é executado uma vez no arranque da aplicação.

// TurboModule direct API (React Native 0.76+ New Architecture)
import React, { useEffect } from 'react';
import NativeSingular from 'singular-react-native/js/NativeSingular';

export default function App() {
  useEffect(() => {
    const config: SingularConfig = {
      apikey: 'YOUR_SDK_KEY',
      secret: 'YOUR_SDK_SECRET',
      enableLogging: true,
      logLevel: 3,
    };

    NativeSingular.init(config);

  }, []);
  
  return (
    // Your app components
  );
}

import React, { useEffect } from 'react';
import Singular, { SingularConfig } from 'singular-react-native';

export default function App() {
  useEffect(() => {
    const config = new SingularConfig('YOUR_SDK_KEY', 'YOUR_SDK_SECRET')
      .withLoggingEnabled()
      .withLogLevel(3);
    
    Singular.init(config);
  }, []);
  
  return (
    // Your app components
  );
}
      

Exemplo de configuração avançada

Configure várias funcionalidades do SDK durante a inicialização, encadeando métodos de configuração antes de chamar init().

// TurboModule direct API (React Native 0.76+ New Architecture)
import React, { useEffect } from 'react';
import NativeSingular from 'singular-react-native/js/NativeSingular';
import { NativeEventEmitter } from 'react-native';

export default function App() {
  useEffect(() => {
    const config: SingularConfig = {
      apikey: 'YOUR_SDK_KEY',
      secret: 'YOUR_SDK_SECRET',
      customUserId: 'user_123456',
      limitDataSharing: false,
      waitForTrackingAuthorizationWithTimeoutInterval: 300
    };

    NativeSingular.init(config);

    // Register event listener
    const emitter = new NativeEventEmitter(NativeSingular);
    emitter.addListener('SingularLinkHandler', (params) => {
      console.log('Singular: Deep link:', params.deeplink);
      console.log('Singular: Passthrough:', params.passthrough);
      console.log('Singular: Is deferred:', params.isDeferred);
      console.log('Singular: urlParameters:', params.urlParameters);
    });

  }, []);
  
  return (
    // Your app components
  );
}

import React, { useEffect } from 'react';
import { Singular, SingularConfig } from 'singular-react-native';

export default function App() {
  useEffect(() => {
    const config = new SingularConfig(
      'YOUR_SDK_KEY',
      'YOUR_SDK_SECRET'
    )
      // User identification
      .withCustomUserId('user_123456')

      // Privacy settings
      .withLimitDataSharing(false)

      // Deep linking
      .withSingularLink((params: SingularLinkParams) => {
        console.log('Singular: Deep link:', params.deeplink);
        console.log('Singular: Passthrough:', params.passthrough);
        console.log('Singular: Is deferred:', params.isDeferred);
        console.log('Singular: urlParameters:', params.urlParameters);
      })

      // iOS-specific
      .withWaitForTrackingAuthorizationWithTimeoutInterval(300)

      // Debugging
      .withLoggingEnabled()
      .withLogLevel(3);

    Singular.init(config);
  }, []);

  return (
    // Your app components
  );
}

Configuração avançada

Necessário para a medição de conversão integrada do Google Ads no iOS

Se a sua aplicação executa campanhas do Google Ads direcionadas a utilizadores do iOS 14.5+, são necessárias etapas adicionais de configuração do SDK para suportar a Medição de Conversão Integrada do iOS (ICM). Isto inclui:

• Integrar o SDK de Medição no Dispositivo (ODM) do Google
• Atualização para o SDK do Singular para iOS v12.8.1+ (ou v5.5.0+ para Unity, v1.8.0+ para Flutter/Cordova, v3.9.0+ para React Native)
• Adicionar o sinalizador do ligador « -ObjC » e ativar « enableOdmWithTimeoutInterval » em SingularConfig

Nota: A ativação de enableOdmWithTimeoutInterval atrasa a inicialização do SDK e pode adiar os callbacks de deep links. Conclua esta configuração durante a implementação inicial do SDK para evitar trabalho adicional.

Consulte os requisitos técnicos completos do iOS ICM