Pré-requisitos

Conclua estas etapas de pré-requisitos antes de instalar o Singular SDK do Cordova para garantir um processo de integração tranquilo.

Instalação do plug-in

Instalando o plug-in do Singular

Adicione o plugin do Singular ao seu projeto Cordova usando a CLI do Cordova. O plugin fornece ligações JavaScript para os SDKs nativos do Singular para iOS e Android.

Instalar via CLI do Cordova

1. Abra o terminal: Navegue até o diretório raiz do seu projeto Cordova.
2. Adicionar plugin: Execute o seguinte comando para instalar o plugin Singular SDK:
   bash

   cordova plugin add singular_cordova_sdk

3. Verificar a instalação: Confirme se o plug-in foi adicionado verificando o arquivo config.xml para a entrada do plug-in ou executando:
   bash

   cordova plugin list

Integração do Ionic Framework

Se estiver a criar a sua aplicação Cordova com o Ionic Framework, siga estes passos adicionais para integrar corretamente o SDK Singular.

Instalar o plug-in para o Ionic

1. Instalar via Ionic CLI: use o comando Ionic Cordova para adicionar o plug-in:
   bash

   ionic cordova plugin add singular_cordova_sdk

2. Declare a variável Cordova: No seu arquivo TypeScript principal (normalmente app.component.ts ou home.page.ts), declare a variável Cordova na parte superior:
   TypeScript

   declare var cordova;

3. Inicializar na plataforma pronta: Use o evento de plataforma pronta para garantir que os plug-ins nativos sejam carregados antes da inicialização do SDK:
   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(() => {
         // Initialize Singular SDK here (see SDK Integration section)
   
       });
     }
   }

Configuração da plataforma

Configuração do Android

Configure as permissões e definições específicas do Android para ativar a funcionalidade principal do SDK e o rastreamento de atribuição.

Adicionar permissões necessárias

Adicione as permissões necessárias do Android ao seu arquivo Cordova config.xml para habilitar a atribuição, o acesso à rede e instalar o rastreamento de referenciador.

1. Abra config.xml: Navegue até a raiz do seu projeto Cordova e abra o arquivo config.xml.
2. Adicionar permissões: Na secção <platform name="android">, adicione a seguinte permissão:
   config.xml

   <platform name="android">
       <!-- Required for GAID collection and attribution -->
       <edit-config file="app/src/main/AndroidManifest.xml" mode="merge" target="/manifest">
           <uses-permission android:name="com.google.android.gms.permission.AD_ID" />
       </edit-config>
   </platform>

Permissões adicionais (adicionadas automaticamente)

As seguintes permissões são adicionadas automaticamente pelo plug-in Singular Cordova e não requerem configuração manual:

• android.permission.INTERNET - Acesso à rede para transmissão de dados
• android.permission.ACCESS_NETWORK_STATE - Monitorização do estado da rede
• BIND_GET_INSTALL_REFERRER_SERVICE - Instalar rastreamento de referenciador

Configuração do iOS

A configuração do iOS é tratada automaticamente pelo plug-in Cordova. Não são necessários passos adicionais de configuração manual para projectos iOS.

Integração do SDK

Inicialize o SDK Singular sempre que seu aplicativo for iniciado. A inicialização do SDK é essencial para todas as funcionalidades de atribuição do Singular e cria uma nova sessão para calcular as métricas de retenção de usuários.

Inicialização básica do SDK

Crie um objeto SingularConfig com suas credenciais do SDK e inicialize o SDK usando o método init(). Isso deve ser feito o mais cedo possível no ciclo de vida do seu aplicativo.

Exemplo de inicialização

1. Obter credenciais: Faça login na sua conta Singulare navegue até Ferramentas do desenvolvedor > Integração do SDK > Chaves do SDKpara encontrar sua chave e segredo do SDK.
2. Criar configuração: Instanciar um objeto SingularConfig com suas credenciais.
3. Inicializar o SDK: Chame init() para iniciar o SDK.

// Create the Singular configuration object
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  "YOUR_SDK_KEY",
  "YOUR_SDK_SECRET"
);

// Initialize the Singular SDK
cordova.plugins.SingularCordovaSdk.init(singularConfig);

Configuração avançada

Configure recursos adicionais do SDK encadeando métodos de configuração antes de chamar init(). Este exemplo demonstra opções de configuração comuns, incluindo deep linking, registo e tempo limite da sessão.

// Create configuration with credentials
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  "YOUR_SDK_KEY",
  "YOUR_SDK_SECRET"
);

// Enable debug logging (disable in production)
singularConfig.withLoggingEnabled();

// Set custom session timeout (default is 60 seconds)
singularConfig.withSessionTimeoutInSec(120);

// Configure deep linking handler
var linkHandler = function(data) {
  var deeplink = data.deeplink;
  var passthrough = data.passthrough;
  var isDeferred = data.isDeferred;

  console.log("Received deep link:", deeplink);
  console.log("Is deferred:", isDeferred);

  // Handle navigation based on deep link
  if (deeplink) {
    // Navigate to appropriate screen
  }
};
singularConfig.withSingularLink(linkHandler);

// Set custom user ID (if user is logged in)
singularConfig.withCustomUserId("user_12345");

// Initialize Singular
cordova.plugins.SingularCordovaSdk.init(singularConfig);

Atribuição do referenciador de instalação do Meta

Configure a atribuição do Referenciador de Instalação do Meta (Facebook) para rastrear instalações de campanhas de anúncios do Facebook e do Instagram.

Ativar o Meta Install Referrer

Se o AMM não estiver ativado ou se você precisar do Meta Install Referrer para rastreamento legado, adicione sua ID do aplicativo do Facebook à configuração do SDK.

1. Localizar ID de aplicativo do Facebook: Faça login na sua conta de desenvolvedor do Facebooke navegue até o painel do seu aplicativo para localizar a ID do aplicativo.
2. Adicionar à configuração: Use o método withFacebookAppId() para ativar o Meta Install Referrer:
   JavaScript

   // Create configuration
   var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
     "YOUR_SDK_KEY",
     "YOUR_SDK_SECRET"
   );
   
   // Enable Meta Install Referrer
   singularConfig.withFacebookAppId("YOUR_FACEBOOK_APP_ID");
   
   // Initialize SDK
   cordova.plugins.SingularCordovaSdk.init(singularConfig);