Pré-requisitos

Conclua estas etapas de pré-requisito antes de instalar o SDK do Singular para Cordova para garantir uma integração tranquila.

Instalação

Instalação do plugin Singular

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

Instalação através da CLI do Cordova

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

   cordova plugin add singular_cordova_sdk

3. Verifique a instalação: Confirme que o plugin foi adicionado verificando se existe uma entrada para o plugin no seu ficheiro ` config.xml ` ou executando:
   bash

   cordova plugin list

Integração com o Ionic Framework

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

Instalar o plugin para o Ionic

1. Instale através da CLI do Ionic: Use o comando Ionic Cordova para adicionar o plugin:
   bash

   ionic cordova plugin add singular_cordova_sdk

2. Declare a variável Cordova: No seu ficheiro TypeScript principal (normalmente app.component.ts ou home.page.ts ), declare a variável Cordova no início:
   TypeScript

   declare var cordova;

3. Inicialize no evento platform ready: Use o evento platform ready para garantir que os plugins 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 Android necessárias ao seu ficheiro Cordova config.xml para ativar a atribuição, o acesso à rede e o rastreamento de referência de instalação.

1. Abrir o config.xml: Navegue até à raiz do seu projeto Cordova e abra o ficheiro config.xml.
2. Adicione 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 plugin 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 - Rastreamento de referência de instalação

Configuração do iOS

A configuração do iOS é tratada automaticamente pelo plugin Cordova. Não são necessárias etapas adicionais de configuração manual para projetos iOS.

Integração do SDK

Inicialize o SDK da Singular sempre que a sua aplicação for iniciada. A inicialização do SDK é essencial para todas as funcionalidades de atribuição da Singular e cria uma nova sessão para calcular as métricas de retenção de utilizadores.

Sobre o SDID

O Singular Device ID (SDID) é um identificador em nível de dispositivo que a Singular gera e gerencia. Em uma integração híbrida, em que este SDK é executado no seu app e o seu servidor também envia eventos pela API Server-to-Server (S2S), enviar o mesmo SDID nesses eventos do lado do servidor os vincula ao mesmo dispositivo que o SDK está rastreando. Isso permite que a Singular atribua a atividade do SDK e do S2S a um único dispositivo sem depender de identificadores de publicidade específicos da plataforma.

Inicialização básica do SDK

Crie um objeto ` SingularConfig ` com as suas credenciais do SDK e inicialize o SDK utilizando o método ` init() `. Isto deve ser feito o mais cedo possível no ciclo de vida da sua aplicação.

Exemplo de inicialização

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 com as 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"
);

// Log the SDID once the SDK receives it (SDID is enabled by default for new accounts)
singularConfig.sdidReceivedCallback = function(sdid) {
  console.log("Singular SDID received:", sdid);
};

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

Configuração avançada

Configure funcionalidades adicionais do SDK encadeando métodos de configuração antes de chamar init(). Este exemplo demonstra opções de configuração comuns, incluindo ligações profundas, 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 de Referência de Instalação Meta

Configure a atribuição de Referenciador de Instalação da Meta (Facebook) para rastrear instalações provenientes de campanhas publicitárias no Facebook e no Instagram.

Ativar o Meta Install Referrer

Se o AMM não estiver ativado ou se precisar do Meta Install Referrer para rastreamento legado, adicione o seu ID de aplicação do Facebook à configuração do SDK.

1. Encontrar o ID da aplicação do Facebook: Inicie sessão na sua conta de programador do Facebook e aceda ao painel de controlo da sua aplicação para localizar o ID da aplicação.
2. Adicionar à configuração: utilize 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);

Configuração avançada

Necessário para a medição de conversões integrada do Google Ads para 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 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 link. Conclua esta configuração durante a implementação inicial do SDK para evitar trabalho adicional.

Consulte os requisitos técnicos completos do iOS ICM