O SDK do Singular está disponível como um plug-in para o Cordova. As instruções abaixo mostram como integrar o Singular na sua aplicação Cordova.

Pré-requisitos

• Este artigo assume que você tem um aplicativo Cordova funcional.
• Para inicializar o SDK, você precisa da Chave do SDK Singular e do Segredo do SDK. Você pode obtê-los na plataforma Singular em"Ferramentas do desenvolvedor > Integração do SDK > Chaves do SDK".

Adicionando o plugin do Singular

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

cordova plugin add singular_cordova_sdk

Ionic

Se você estiver usando o Ionic:

1. Instale o plug-in Singular SDK:

   $ ionic cordova plugin add singular_cordova_sdk

2. No 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:

   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(() => {
   
       // Add code to initialize the Singular SDK here
   
   
   }); 
   }}
   

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

Para inicializar o SDK do 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 Adicionando suporte a deep links e Adicionando suporte a SKAdNetwork abaixo).
3. Suporte à atribuição de referenciador da instalação META
   Apartir de 18 de junho de 2025, o Advanced Mobile Measurement Reporting (AMM) do Meta eliminou a necessidade de implementar o Meta Install Referrer. Não é recomendável implementar o Referenciador de instalação do Meta se o relatório AMM estiver ativado.
   Configuração necessária do SDK para ativar a atribuição do "Meta Install Referrer":
   1. Forneça seu ID do aplicativo do Facebook no objeto de configuração Singular.
      

      // To enable META Install Referrer
      singularConfig.withFacebookAppId("INSERT YOUR FACEBOOK APP ID HERE");

   Onde posso encontrar a ID de aplicativo do Facebook de um aplicativo?
4. Inicialize o SDK usando o objeto SingularConfig.

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

// Create the configuration object
var singularConfig = new
cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");

/*
// Optional: Enable deep linking (requires additional setup steps, see guide)
var linkHandler = function(data){
   var deeplink = data.deeplink;
   var passthrough = data.passthrough;
   var isDeferred = data.isDeferred;
   // Add link handling logic here
}
singularConfig.withSingularLink(linkHandler);
*/

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

Eventos de rastreamento (não receita)

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

// Example: Report an event called View Product with event attributes
cordova.plugins.SingularCordovaSdk.eventWithArgs(
  'ViewProduct', // Event name

  {
    // Event attributes
    productID:"123",
    productCategory:"Outerwear"
  }
)

Rastreamento de receita

Para permitir que o Singular rastreie a receita que seu aplicativo gera com compras no aplicativo, relate eventos de IAP ao 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 detetar 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 estiver a utilizar a biblioteca https://github.com/j3k0/cordova-plugin-purchase, pode utilizar 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)
}

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

Rastreamento de evento híbrido (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 do 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

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

Adicionando suporte a Deep Linking

As ligações profundas são ligações que abrem a aplicação no telemóvel do utilizador e o enviam diretamente para uma página ou experiência de utilizador específica, em vez de apenas para o widget principal da aplicação.

As ligações profundas são normalmente utilizadas em campanhas de retargeting, destinadas a utilizadores que já têm a aplicação no seu telemóvel, mas que podem não ter interagido com ela durante algum tempo.

O Singular suporta links profundos 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:

   Java Kotlin

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

   import singular_cordova_sdk.SingularCordovaSdk
   
   override fun onNewIntent(intent: Intent) {
       SingularCordovaSdk.handleNewIntent(intent)
   }
   

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

   Swift Objective-C

   import UIKit
   import SingularCordovaSdk
   
   class AppDelegate: UIResponder, UIApplicationDelegate {
       
       var window: UIWindow?
       var viewController: MainViewController?
       
       func application(
           _ application: UIApplication,
           didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
       ) -> Bool {
           // Initialize window
           window = UIWindow(frame: UIScreen.main.bounds)
           
           // Configure view controller
           viewController = MainViewController()
           window?.rootViewController = viewController
           
           // Initialize Singular SDK
           SingularCordovaSdk.setLaunchOptions(launchOptions)
           
           // Make window visible
           window?.makeKeyAndVisible()
           
           return true
       }
       
       func application(
           _ application: UIApplication,
           continue userActivity: NSUserActivity,
           restorationHandler: @escaping ([Any]?) -> Void
       ) -> Bool {
           return SingularCordovaSdk.startSession(with: userActivity)
       }
   }
   

   #import "SingularCordovaSdk.h"
   #import "MainViewController.h"
   
   - (BOOL)application:(UIApplication *)application 
   didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
       // Initialize window
       self.window = [[UIWindow alloc] initWithFrame:[UIScreen mainScreen].bounds];
       
       // Configure view controller
       self.viewController = [[MainViewController alloc] init];
       self.window.rootViewController = self.viewController;
       
       // Initialize Singular SDK
       [SingularCordovaSdk setLaunchOptions:launchOptions];
       
       // Make window visible
       [self.window makeKeyAndVisible];
       
       return YES;
   }
   
   - (BOOL)application:(UIApplication *)application
   continueUserActivity:(NSUserActivity *)userActivity
   restorationHandler:(void (^)(NSArray<id> *))restorationHandler {
       return [SingularCordovaSdk startSessionWithUserActivity:userActivity];
   }
   

3. Antes de inicializar o SDK do Singular em seu código, adicione .withSingularLink ao objeto de configuração do Singular e especifique sua função de manipulador de link:

   JavaScript

   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;
     // Add link handling logic here
   
   }
   
   singularConfig.withSingularLink(linkHandler);
   
   cordova.plugins.SingularCordovaSdk.init(singularConfig);
   

Outras opções

Rastreamento de desinstalações

Para permitir que o Singular rastreie desinstalações de aplicativos, envie o token APNS/FCM para o Singular usando o seguinte código:

Android:

cordova.plugins.SingularCordovaSdk.setUninstallToken(fcmToken)

iOS:

cordova.plugins.SingularCordovaSdk.setUninstallToken(apnsToken)

Criando links de referência curtos

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

Normalmente, pretende criar links curtos de forma dinâmica para que os utilizadores da sua aplicação possam partilhá-los com amigos e convidá-los a utilizar a aplicação.

Para criar um link curto, você precisa de:

• Um link singular que leva ao download do seu aplicativo (consulte as Perguntas frequentes sobre links singulares).
• Quaisquer parâmetros que queira adicionar ao link dinamicamente (consulte Parâmetros de link de rastreamento para obter a lista de opções).
• O nome e a ID do utilizador de referência, se pretender acompanhar as novas instalações da aplicação até ao utilizador que partilhou o link.

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

cordova.plugins.SingularCordovaSdk.createReferrerShortLink(
    longLinkURL, 
    referrerName,
    referrerID,
    {
        // Tracking link parameters to add to the short link, e.g. "channel":"sms"

        param1: value1,
        param2: value2,
        ...
    },
    {
        onSuccess: function (shortLinkURL) {
        // Do something with shortLinkURL

        },
        onError: function (error) {
        // Handle error

        }
    }
)

Conformidade com as leis de privacidade de dados

A Singular fornece uma funcionalidade de proteção da privacidade para o ajudar a cooperar com quaisquer parceiros que possam estar em conformidade com as leis de privacidade do consumidor, como o GDPR e o CCPA(California Consumer Privacy Act). Estes parceiros querem ser notificados se o utilizador final consentiu em partilhar as suas informações privadas.

Se tiver implementado uma forma de pedir o consentimento dos utilizadores para partilharem as suas informações, utilize o método limitDataSharing para notificar a Singular da escolha do utilizador:

Utilize SingularCordovaSdk.limitDataSharing(false) para indicar que o utilizador consentiu (opted in) em partilhar as suas informações.

Utilize SingularCordovaSdk.limitDataSharing(true) se o utilizador não tiver dado o seu consentimento.

A Singular utiliza LimitDataSharing em"User Privacy Postbacks", bem como transmite esta informação a parceiros que a requerem para cumprir os regulamentos relevantes. Consulte"Privacidade do utilizador e Limitar partilha de dados" para obter mais informações.

// User has opted into sharing data
cordova.plugins.SingularCordovaSdk.limitDataSharing(false);

Métodos adicionais para conformidade com o GDPR

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

cordova.plugins.SingularCordovaSdk.trackingOptIn();

cordova.plugins.SingularCordovaSdk.stopAllTracking();

cordova.plugins.SingularCordovaSdk.resumeAllTracking();

cordova.plugins.SingularCordovaSdk.isAllTrackingStopped();