Integración SDK singular para Cordova

 

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

Prerequisites

  • Este artículo asume que usted tiene una aplicación Cordova funcional.
  • Para inicializar el SDK, necesita su Clave SDK de Singular y su Secreto SDK. Puede obtenerlas en la plataforma Singular en "Developer Tools > SDK Integration > SDK Keys".

Añadir el plugin de Singular

Para añadir el plugin de Singular a su proyecto Cordova, ejecute lo siguiente:

cordova plugin add singular_cordova_sdk

Ionic

Si utiliza Ionic:

  1. Instala 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:

    import {Component} from '@angular/core';
      import {Platform} from '@ionic/angular';
      declare var cordova;
      ...
      
      export class HomePage {
      constructor(public platform: Platform) {
      this.platform.ready().then(() => {
      
          // Agregue código para inicializar el SDK de Singular aquí
      
      }); 
      }}

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 Install Atribución de referencias

    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.
      // Para habilitar META Install Referrer
      singularConfig.withFacebookAppId("INSERTE AQUÍ EL ID DE SU APLICACIÓN DE FACEBOOK");
    Dónde puedo encontrar el Facebook App ID de una aplicación?
  4. Inicialice el SDK utilizando el objeto SingularConfig.

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

// Crear el objeto de configuración
  var singularConfig = new
  cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");
  
  /*
  // Opcional: habilite los enlaces profundos (requiere pasos de configuración adicionales, consulte la guía)
  var linkHandler = function(data){
  var deeplink = data.deeplink;
  var passthrough = data.passthrough;
  var isDeferred = data.isDeferred;
  // Agregue lógica de manejo de enlaces aquí
  }
  singularConfig.withSingularLink(linkHandler);
  */
  
/*
// Para habilitar META Install Referrer
singularConfig.withFacebookAppId("INSERTE AQUÍ EL ID DE SU APLICACIÓN DE FACEBOOK");
*/
/* // Opcional: habilite SKAdNetwork (en modo administrado, consulte la guía para obtener más opciones) singularConfig.withSkAdNetworkEnabled(true); */ // Inicializar 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 de Singular SDK.

Nota: Si utiliza la solución multidispositivo de Singular, debe recopilar el ID de usuario en todas las plataformas.

  • 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 de un 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 desestablecerlo (por ejemplo, si el usuario "cierra sesión" en la cuenta), llame a unsetCustomUserId.

Nota: Si varios usuarios utilizan un único dispositivo, recomendamos implementar un flujo de cierre de sesión para establecer y desestablecer el ID de usuario para cada inicio y cierre de sesión.

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 después de que el flujo de registro se haya completado.

Método SingularCordovaSdk.setCustomUserID
Descripción Envía el ID de usuario a Singular.
Firma SingularCordovaSdk.setCustomUserId(String customUserId)
Ejemplo de uso
SingularCordovaSdk.setCustomUserId('CustomUserId');
SingularCordovaSdk.unsetCustomUserIDMétodo
Descripción Anula el ID de usuario que se ha enviado a Singular.
Firma SingularCordovaSdk.unsetCustomUserId()
Ejemplode uso
SingularCordovaSdk.unsetCustomUserId();

Opcional: Asignación de dispositivos de ID de usuario personalizados

Importante: Esta función Enterprise avanzada sólo está disponible en casos excepcionales. Por favor, consulte con uno de los Ingenieros de Soluciones de Singular antes de implementarla.

Singular puede recibir datos adicionales de seguimiento de eventos móviles a través de una integración de servidor a servidor. Para utilizar esta función, debe asignar el ID de usuario al identificador de seguimiento de dispositivos móviles de Singular.

Nota: Llame a este método tan pronto como sea posible después de inicializar el SDK Singular o una vez que tenga el ID de usuario.

Método SingularCordovaSdk.setDeviceCustomUserId
Descripción Establece el Id. de usuario personalizado igual que el inicio de sesión y lo asigna al identificador de seguimiento de Singular.
Firma SingularCordovaSdk.setDeviceCustomUserId(String customUserId)
Ejemplo de uso
SingularCordovaSdk.setDeviceCustomUserId('CustomUserId');

Seguimiento de eventos (no ingresos)

Además de enviar sesiones de usuario a Singular (inicializando el SDK), también puede enviar eventos de usuario. Los datos sobre eventos dentro de la aplicación ayudan a Singular a analizar el rendimiento de sus campañas de captació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.

// Ejemplo: informar un evento llamado Ver producto con atributos de evento
  cordova.plugins.SingularCordovaSdk.eventWithArgs(
    'ViewProduct', // Nombre del evento
    {
      // Atributos del evento
      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)
  }

Envío de ingresos personalizados

Si no puede enviar el objeto IAP a Singular, una alternativa es utilizar el método customRevenue, que acepta un nombre de evento, un código de moneda y el importe de la compra.

Ejemplo:

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

Nota: pase la divisa como un código de divisa ISO 4217 de tres letras, por ejemplo, "USD", "EUR", "INR".

Seguimiento de Eventos Híbrido (Avanzado)

Singular recomienda enviar todos los eventos e ingresos a través del SDK de Singular integrado en su app. Sin embargo, Singular puede recoger 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.

Importante:

Se producirán discrepancias si los identificadores de dispositivo utilizados en las solicitudes de eventos de servidor a servidor no tienen un identificador de dispositivo coincidente en Singular. Tenga en cuenta las siguientes posibilidades:

  • Si se recibe una solicitud de evento "antes" de que Singular SDK haya registrado el identificador de dispositivo, desde una App Session, entonces la solicitud de evento se considerará la "primera sesión" para el dispositivo desconocido, y Singular atribuirá el dispositivo como una atribución orgánica.
  • Si Singular SDK registró un identificador de dispositivo, pero el identificador de Singular SDK difiere del identificador de dispositivo especificado en la solicitud de evento de servidor a servidor, entonces el evento se atribuirá incorrectamente.

Guías de seguimiento de eventos híbridos

Envío de eventos desde un servidor interno

Singular puede recopilar datos sobre los ingresos de su Servidor para ayudar a analizar el rendimiento y el ROI de sus campañas.

Requisitos:

  • Desde un Evento de Registro o Inicio de Sesión in-app, capture y pase los identificadores de dispositivo y almacene estos datos con el ID de Usuario en su servidor. Dado que los identificadores de dispositivo pueden cambiar para un usuario, asegúrese de actualizar los identificadores cuando un usuario genere una sesión de aplicación. Esto garantiza que el evento del lado del servidor se atribuya al dispositivo correcto.
  • Los eventos del lado del servidor son específicos de cada plataforma y sólo deben enviarse con el identificador de dispositivo que coincida con la plataforma del dispositivo (por ejemplo, IDFA o IDFV para dispositivos iOS).
  • Puede utilizar el mecanismo de postback de Singular Internal BI para enviar un evento en tiempo real a su endpoint interno para que pueda actualizar el conjunto de datos en el lado del servidor. Consulte las Preguntas Frecuentes sobre Postback de BI Interno.
  • Revise la sección "Seguimiento de Ingresos" en la guía de Integración Servidor-a-Servidor para más detalles.
Envío de Eventos desde un Proveedor de Ingresos
Proveedores de terceros como RevenueCat o adapty pueden proporcionar Ingresos por Compras y Suscripciones a Singular.

Siga los siguientes enlaces para obtener más información sobre cómo habilitar a estos socios.

Envío de Eventos desde Segmento

Para que Segment pueda enviar eventos a Singular, en paralelo con el SDK de Singular, debe añadir un Destino "Cloud-Mode" en Segment. Siga nuestra guía AQUÍ.

Seguimiento de la atribución de ingresos publicitarios

Puede utilizar el complemento Singular para configurar la atribución de ingresos publicitarios (consulte las preguntas frecuentes sobre atribución de ingresos publicitarios).

Para configurar la atribución de ingresos publicitarios:

  1. Añada el fragmento de código apropiado para obtener información sobre ingresos publicitarios de la plataforma de mediación que utiliza para los datos de ingresos publicitarios. Consulte los fragmentos de código en nuestra documentación del SDK de Android.

Nota: pase la divisa como un código de divisa ISO 4217 de tres letras, por ejemplo, "USD", "EUR", "INR".

Notifique los eventos de ingresos publicitarios a Singular utilizando el siguiente código
  1. Inicialice el objeto SingularAdData con los datos pertinentes.
  2. Comunique los datos a Singular
Javascript
const adData = new cordova.plugins.SingularCordovaSdk.SingularAdData(
   mediationPlatform,
   currencyCode, // e.g., "USD"
   revenueAmount)

cordova.plugins.SingularCordovaSdk.adRevenue(adData);

Añadir soporte para enlaces profundos

Los enlaces profundos son enlaces que abren la aplicación en el teléfono del usuario y le 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 suelen utilizar 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:

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

    Para iOS, añada este código a su AppDelegate:

    #import "SingularCordovaSdk.h"
      
        - (BOOL)application:(UIApplication*)application
        didFinishLaunchingWithOptions:(NSDictionary*)launchOptions
        {
           self.viewController = [[MainViewController alloc] init];
           [SingularCordovaSdk setLaunchOptions: launchOptions];
           return [super
        application:application didFinishLaunchingWithOptions:launchOptions];
        }
      
        - (BOOL)application:(UIApplication *)application
        continueUserActivity:(NSUserActivity *)userActivity
        restorationHandler:(void (^)(NSArray<id> * _Nullable))restorationHandler{
         [SingularCordovaSdk startSessionWithUserActivity:userActivity];
         return
        YES;
        }
  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:

    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;
        // Agregue lógica de manejo de enlaces aquí
      }
      
      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 modo gestionado, Singular gestiona automáticamente el valor de conversión de SKAdNetwork por usted, 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 lagestió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("<SDK KEY>", "<SDK SECRET>");
  
  // Habilite SKAdNetwork (en modo administrado de forma predeterminada)
  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>");
  
  // Habilitar SKAdNetwork
  singularConfig.withSkAdNetworkEnabled(true);
  
  // Seleccione el modo manual SKAdNetwork
  singularConfig.withManualSkanConversionManagement();
  
  // Opcional: defina el controlador para realizar un seguimiento de los cambios en el valor de conversión
  var conversionHandler = function(updatedConversionValue){
    // Hacer algo con el valor de conversión actualizado
  }
  
  singularConfig.withConversionValueUpdatedHandler(conversionHandler);
  
  // Inicializar el SDK de Singular
  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 == verdadero si la actualización fue exitosa
    }
  )

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

cordova.plugins.SingularCordovaSdk.skanGetConversionValue(
    function(conversionValue){
      // Hacer algo con el valor de conversión
    }
  )

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 enlacede 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,
      {
          // Parámetros del enlace de seguimiento para agregar al enlace corto, p. "channel":"sms"
          param1: value1,
          param2: value2,
          ...
      },
      {
          onSuccess: function (shortLinkURL) {
          // Haz algo con shortLinkURL
          },
          onError: function (error) {
          // Manejar error
          }
      }
  )

Cumplimiento de las leyes de privacidad de datos

Singular proporciona una funcionalidad 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(California Consumer Privacy Act). 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.

Nota: El uso del método es opcional, pero puede haber información de atribución que el socio compartirá con Singular sólo si se notifica específicamente que el usuario ha optado por ello.

Método SingularCordovaSdk.limitDataSharing
Firma SingularCordovaSdk.limitDataSharing(booleanshouldLimitDataSharing)
Descripción Notifica a Singular el consentimiento del usuario (opt-in) para compartir datos privados.
Ejemplo de uso
// El usuario ha optado por compartir datos
cordova.plugins.SingularCordovaSdk.limitDataSharing(false);

Métodos adicionales para el cumplimiento de 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.

Método SingularCordovaSdk.trackingOptIn
Descripción Notifica a Singular el consentimiento del usuario (opt-in) para el seguimiento.
Ejemplo de uso
cordova.plugins.SingularCordovaSdk.trackingOptIn();
Método SingularCordovaSdk .stopAllTracking
Descripción

Detiene todas las actividades de seguimiento de este usuario en esta aplicación.

Nota: si se llama a este método, se desactiva el SDK, incluso después de reiniciar la aplicación (el estado es persistente). La única forma de volver a activar el seguimiento es llamando a resumeAllTracking().
Ejemplo de uso
cordova.plugins.SingularCordovaSdk.stopAllTracking();
SingularCordovaSdk.resumeAllTracking Método
Descripción Reanuda el seguimiento para este usuario en esta aplicación.
Ejemplo de uso
cordova.plugins.SingularCordovaSdk.resumeAllTracking();
SingularCordovaSdk.isAllTrackingStoppedMétodo
Descripción Comprueba el estado del seguimiento de este usuario en esta aplicación. Devuelve true si el seguimiento se ha detenido mediante StopAllTracking() y no se ha reanudado.
Ejemplo de uso
cordova.plugins.SingularCordovaSdk.isAllTrackingStopped();