El SDK de Singular está disponible como complemento para Cordova. Las siguientes instrucciones le muestran cómo integrar Singular en su aplicación Cordova.

Requisitos previos

• En este artículo se asume que dispone de una aplicación Cordova funcional.
• Para inicializar el SDK, necesita la clave y el secreto del SDK de Singular. Puede obtenerlas en la plataforma Singular en"Developer Tools > SDK Integration > SDK Keys".

Añadir el plugin de Singular

Para añadir el plugin Singular a tu proyecto Cordova, ejecuta lo siguiente:

cordova plugin add singular_cordova_sdk

Ionic

Si utiliza Ionic:

1. Instale el plugin Singular SDK:

   $ ionic cordova plugin add singular_cordova_sdk

2. En su archivo ts principal, declare una variable de ventana:

   declare var cordova;

3. Ahora puede utilizar el plugin de Singular directamente desde 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
   
   
   
   }); 
   }}
   

Inicialización del SDK (obligatorio)

El código de inicialización de Singular SDK debe invocarse cada vez que se abra la aplicación. Es un requisito previo para toda la funcionalidad de atribución de Singular. También envía una nueva sesión de usuario a Singular (las sesiones se utilizan para calcular la retención de usuarios).

Para inicializar el SDK de Singular

1. Cree un objeto SingularConfig. El objeto contiene la clave y el secreto de Singular SDK.
2. Configure los parámetros opcionales si desea que su aplicación admita enlaces profundos y/o SKAdNetwork (consulte Añadir compatibilidad con enlaces profundos y Añadir compatibilidad con SKAdNetwork más abajo).
3. META Instalar soporte de atribución de referencia

   Configuración SDK necesaria para activar la atribución "Meta Install Referrer":

   1. Proporcione su Id de aplicación de Facebook en el objeto de configuración Singular.
      

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

   Dónde puedo encontrar el Facebook App ID de una aplicación?
4. Inicializa el SDK utilizando el objeto SingularConfig.

Ejemplo de código (con ajustes opcionales comentados):

// 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);
*/

/*
// To enable META Install Referrer


singularConfig.withFacebookAppId("INSERT YOUR FACEBOOK APP ID HERE");
*/

/*
// Optional: Enable SKAdNetwork (in Managed Mode, see guide for more options)


singularConfig.withSkAdNetworkEnabled(true);
*/

// Initialize Singular


cordova.plugins.SingularCordovaSdk.init(singularConfig);

Envío del ID de usuario a Singular (opcional)

Puede enviar su ID de usuario interno a Singular utilizando un método del SDK de Singular.

• El ID de usuario puede ser cualquier identificador y no debe exponer PII (Personally Identifiable Information). Por ejemplo, no debe utilizar la dirección de correo electrónico, el nombre de usuario o el número de teléfono del usuario. Singular recomienda utilizar un valor hash único sólo para sus datos de origen.
• El valor de ID de usuario que se pasa a Singular también debe ser el mismo ID de usuario interno que se captura en todas las plataformas (Web/Móvil/PC/Consola/Offline).
• Singular incluirá el ID de usuario en las exportaciones a nivel de usuario, ETL y devoluciones internas de BI (si está configurado). El ID de usuario es un dato de origen y Singular no lo comparte con terceros.
• El valor del ID de usuario, cuando se establece con el método Singular SDK, persistirá hasta que se desactive utilizando el método unsetCustomUserId o hasta que se desinstale la aplicación. Cerrar o reiniciar la aplicación no anula el ID de usuario.

Para establecer el ID de usuario, utilice el método setCustomUserId. Para desactivarlo (por ejemplo, si el usuario "cierra sesión" en la cuenta), llame a unsetCustomUserId.

Si ya conoce el ID de usuario cuando se abre la aplicación, llame a setCustomUserId antes de inicializar Singular SDK. De esta forma, Singular puede tener el ID de usuario desde la primera sesión. Sin embargo, el ID de usuario no suele estar disponible hasta que el usuario se registra o realiza un inicio de sesión. En ese caso, llame a setCustomUserId una vez finalizado el flujo de registro.

SingularCordovaSdk.setCustomUserId('CustomUserId');

SingularCordovaSdk.unsetCustomUserId();

SingularCordovaSdk.setDeviceCustomUserId('CustomUserId');

Seguimiento de eventos (sin ingresos)

Además de enviar sesiones de usuario a Singular (mediante la inicialización del SDK), también puede enviar eventos de usuario. Los datos sobre eventos in-app ayudan a Singular a analizar el rendimiento de sus campañas de adquisición de usuarios y a medir los KPI.

Por ejemplo, es posible que su organización desee recopilar datos sobre inicios de sesión de usuarios, registros, finalización de tutoriales o subidas de nivel en una aplicación de juegos.

Para enviar eventos a Singular, utilice el método eventWithArgs . Asigne un nombre al evento y añada los atributos que desee controlar.

// Example: Report an event called View Product with event attributes


cordova.plugins.SingularCordovaSdk.eventWithArgs(
  'ViewProduct', // Event name


  {
    // Event attributes


    productID:"123",
    productCategory:"Outerwear"
  }
)

Seguimiento de ingresos

Para que Singular pueda realizar un seguimiento de los ingresos de su aplicación procedentes de las compras dentro de la aplicación, notifique los eventos IAP a Singular.

Recomendamos utilizar el método eventWithArgs y pasar el objeto IAP como atributo del evento. Singular utiliza el objeto IAP para validar la compra y detectar compras fraudulentas para que no distorsionen sus métricas de ingresos (consulte las preguntas frecuentes sobre validación de compras dentro de la aplicación).

Si utiliza la biblioteca https://github.com/j3k0/cordova-plugin-purchase, puede utilizar el siguiente 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


);

Seguimiento de eventos híbridos (Avanzado)

Singular recomienda enviar todos los eventos e ingresos a través del SDK de Singular integrado en su aplicación. Sin embargo, Singular puede recopilar eventos e ingresos de otras fuentes.

Cualquier evento NO enviado desde el SDK de Singular debe cumplir con los requisitos de documentación de eventos de servidor a servidor de Singular y proporcionar el identificador de dispositivo correspondiente para atribuir correctamente un evento.

Guías de seguimiento de eventos híbridos

Seguimiento de la atribución de ingresos publicitarios

Añadir soporte para enlaces profundos

Los enlaces profundos son enlaces que abren la aplicación en el teléfono del usuario y lo envían directamente a una página o experiencia de usuario específica en lugar de al widget principal de la aplicación.

Los enlaces profundos se utilizan normalmente en campañas de retargeting, dirigidas a usuarios que ya tienen la aplicación en su teléfono pero que no la han utilizado durante un tiempo.

Singular admite enlaces profundos a través de Singular Links (consulte las preguntas frecuentes sobre Singular Links).

Para utilizar Singular Links en su aplicación

1. Siga las instrucciones de Singular Links Prerequisites.

2. Para Android, añada este código a la actividad 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, añada este código a su 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 Singular SDK en su código, añada .withSingularLink al objeto Singular config y especifique su función de gestión de enlaces:

   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);
   

Añadir compatibilidad con SKAdNetwork

El plugin de Singular es compatible con el framework SKAdNetwork. Puede activar el seguimiento de SKAdNetwork para su aplicación utilizando las opciones de configuración que se indican a continuación.

Modo gestionado (recomendado)

En el modo gestionado, Singular gestiona el valor de conversión de SKAdNetwork por usted automáticamente, basándose en un modelo de conversión de su elección que puede configurar en la plataforma Singular.

Para obtener más información, consulte Comprender la gestión del valor de conversión de Singular y las Preguntas frecuentes sobre la configuración del modelo de SKAdNetwork. Para obtener una guía paso a paso sobre el uso de SKAdNetwork con Singular, consulte Cómo empezar con SKAdNetwork.

Para habilitar SKAdNetwork en modo gestionado, utilice el siguiente código:

var singularConfig = new
  cordova.plugins.SingularCordovaSdk.SingularConfig("", "");

// Enable SKAdNetwork (in managed mode by default)


singularConfig.withSkAdNetworkEnabled(true);

cordova.plugins.SingularCordovaSdk.init(singularConfig);

Modo manual

Si ya dispone de su propia estrategia y herramientas para gestionar el valor de conversión de SKAdNetwork, puede utilizar SKAdNetwork en modo manual.

Para activar SKAdNetwork en modo manual, utilice el siguiente código:

var singularConfig = new
  cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");

// Enable SKAdNetwork


singularConfig.withSkAdNetworkEnabled(true);

// Select SKAdNetwork manual mode


singularConfig.withManualSkanConversionManagement();

// Optional: define handler to track changes to the conversion value


var conversionHandler = function(updatedConversionValue){
  // Do something with updatedConversionValue


}

singularConfig.withConversionValueUpdatedHandler(conversionHandler);

// Initialize the Singular SDK


cordova.plugins.SingularCordovaSdk.init(singularConfig);

Para actualizar el valor de conversión utilice el siguiente código:

cordova.plugins.SingularCordovaSdk.skanUpdateConversionValue(
  newConversionValue,
  function(isSuccess){
    // isSuccess == true if the update was successful


  }
)

Para recuperar el valor de conversión actual, utilice el siguiente código:

cordova.plugins.SingularCordovaSdk.skanGetConversionValue(
  function(conversionValue){
    // Do something with conversionValue


  }
)

Otras opciones

Seguimiento de desinstalaciones

Para permitir que Singular rastree las desinstalaciones de aplicaciones, envíe el token APNS/FCM a Singular utilizando el siguiente código:

Android:

cordova.plugins.SingularCordovaSdk.setUninstallToken(fcmToken)

iOS:

cordova.plugins.SingularCordovaSdk.setUninstallToken(apnsToken)

Creación de enlaces cortos

Utilice enlaces cortos para transformar enlaces Singular largos y llenos de parámetros en enlaces más cortos y seguros que sean convenientes para compartir.

Normalmente, querrá crear enlaces cortos de forma dinámica para que los usuarios de su aplicación puedan compartirlos con sus amigos para invitarles a utilizar la aplicación.

Para crear un enlace corto, necesitas

• Un Enlace Singular que lleve a la descarga de tu app (consulta las Preguntas Frecuentes sobre Enlaces Singulares).
• Cualquier parámetro que desee añadir al enlace de forma dinámica (consulte Parámetros del enlace de seguimiento para ver la lista de opciones).
• El nombre y el ID del usuario que remite, si desea poder rastrear las nuevas instalaciones de la aplicación hasta el usuario que compartió el enlace.

Para crear enlaces cortos utilice el siguiente 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


        }
    }
)

Cumplimiento de las leyes de privacidad de datos

Singular proporciona funciones de protección de la privacidad para ayudarle a cooperar con cualquier socio que pueda estar cumpliendo con las leyes de privacidad del consumidor, como GDPR y CCPA(Ley de Privacidad del Consumidor de California). Estos socios quieren ser notificados si el usuario final ha dado su consentimiento para compartir su información privada.

Si ha implementado una forma de solicitar a los usuarios su consentimiento para compartir su información, utilice el método limitDataSharing para notificar a Singular la elección del usuario:

Utilice SingularCordovaSdk.limitDataSharing(false) para indicar que el usuario ha consentido (optado) en compartir su información.

Utilice SingularCordovaSdk.limitDataSharing(true) si el usuario no dio su consentimiento.

Singular utiliza LimitDataSharing en los"Postbacks de privacidad del usuario", así como para transmitir esta información a los socios que la requieren para cumplir la normativa pertinente. Consulte"Privacidad del usuario y Limitar el uso compartido de datos" para obtener más información.

// User has opted into sharing data


cordova.plugins.SingularCordovaSdk.limitDataSharing(false);

Métodos adicionales para el cumplimiento del GDPR

Singular SDK proporciona varios métodos para ayudarle a cumplir con las políticas GDPR y permitir que Singular conozca el consentimiento o no consentimiento del usuario para el seguimiento.

cordova.plugins.SingularCordovaSdk.trackingOptIn();

cordova.plugins.SingularCordovaSdk.stopAllTracking();

cordova.plugins.SingularCordovaSdk.resumeAllTracking();

cordova.plugins.SingularCordovaSdk.isAllTrackingStopped();