Antes de empezar: Requisitos previos del SDK

• Siga los pasos indicados en Integración de un SDK Singular:Planificación y requisitos previos.
  Estos pasos son requisitos previos para cualquier integración de Singular SDK.
• Compruebe si utiliza Google EDM4U, el gestor de dependencias externas de Google para Unity.
  ¿Qué es Google EDM4U? Más información [AQUÍ].
  

1. Instalando el SDK

1.1. Descarga e importación del paquete SDK

1.2. Configuración para Android

-keep class com.singular.sdk.** { *; }
-keep public class com.android.installreferrer.** { *; }
-keep public class com.singular.unitybridge.** { *; }

1.3. Consejos para iOS

pod repo update
pod update

// Impresión del identificador de vendedor (IDFV) en la consola de Xcode para su uso en la consola de Singular SDK
NSLog(@"Singular === IDFV: %@", [[[UIDevice currentDevice] identifierForVendor] UUIDString]);

2. Integración SDK

2.1. Cree el SingularSDKObject

Añadir el SingularSDKObject a la Jerarquía

Configure los ajustes de SingularSDKObject

1. En el panel Inspección para el SingularSDKObject, pegue su Clave SDK Singular y Secreto SDK en los campos respectivos. Para recuperar la clave y el secreto del SDK, inicie sesión en su cuenta de Singular y vaya a"Developer Tools > SDK Integration > SDK Keys").
   
   
   
   IMPORTANTE: NO UTILICE la clave API de Singular Reporting o no recibirá sus datos SDK. Siga las instrucciones anteriores para recuperar la clave y el secreto adecuados.
   
   
   

   Si la clave y el secreto de Singular SDK se aplican incorrectamente, los datos no se enviarán a Singular.
   Pruebe su implementación utilizando la consola de Singular SDK para verificar el comportamiento correcto.

Otras opciones del panel de inspección:

2.2. Uso de SKAdNetwork

A partir de Unity SDK versión 4.0.17, SKAdNetwork está habilitado por defecto. Está habilitado en el modo gestionado (en el que Singular actualiza el valor de conversión de SKAN por usted utilizando un modelo de conversión que usted elige en el panel de control de Singular).

Para utilizar SKAdNetwork, no es necesario configurar nada más ni añadir ningún código, siempre y cuando esté utilizando el SDK más reciente.

Información adicional

// Se celebró un acto de inscripción
Singular.Event("SignUp");

// Actualiza el valor de conversión a 7
SingularSDK.SkanUpdateConversionValue(7);

int? value = SingularSDK.SkanGetConversionValue();

public class Main : MonoBehaviour, SingularConversionValueUpdatedHandler {
  void Awake() {
    SingularSDK.SetConversionValueUpdatedHandler(this);
  }

  void OnConversionValueUpdated(int value) {
    // Utilizar el valor de conversión
  }
}

2.3. Manejar el consentimiento de App Tracking Transparency(ATT) de iOS

¿Está mostrando el aviso App Tracking Transparency(ATT)?

A partir de iOS 14.5, las aplicaciones deben solicitar el consentimiento del usuario (mediante el marco App Tracking Transparency) antes de poder acceder y compartir algunos datos del usuario, incluido el IDFA del dispositivo, que es útil para fines de seguimiento.

Singular y las redes publicitarias se benefician enormemente de disponer del IDFA para identificar dispositivos y realizar la atribución de instalaciones (aunque hay formas de hacerlo sin el IDFA). Recomendamos encarecidamente solicitar el consentimiento del usuario para obtener el IDFA.

Se recomienda retrasar la inicialización de Singular SDK hasta que el usuario responda a la solicitud de ATT.

Por defecto, Singular SDK envía una sesión de usuario cuando se inicializa. Cuando se envía una sesión desde un nuevo dispositivo, se activa inmediatamente el proceso de atribución de Singular, que se realiza basándose únicamente en los datos de que dispone Singular en ese momento. Por lo tanto, solicitar el consentimiento y recuperar el IDFA antes de que el SDK de Singular envíe la primera sesión es esencial.

Para configurar el waitForTrackingAuthorizationWithTimeoutInterval ajuste la opción de configuración en el panel de Inspección de SingularSDKObject . Esto establece el tiempo máximo (en segundos) para que el Singular SDK espere a que el Usuario autorice/deniegue el Consentimiento de AppTrackingTransparency antes de registrar eventos en los servidores de Singular.

2.4. Manejo de enlaces profundos

Los enlaces profundos son URLs que dirigen a los usuarios a contenidos específicos dentro de una aplicación. Cuando un usuario hace clic en un enlace profundo en un dispositivo con la aplicación ya instalada, la aplicación se abre y muestra un producto o experiencia en particular.

Los enlaces de seguimiento singulares pueden incorporar tanto enlaces profundos como enlaces profundos diferidos. Para más detalles, puede consultar nuestras Preguntas frecuentes sobre enlaces profundos y las Preguntas frecuentes sobre enlaces singulares.

Amplíe las secciones a continuación para obtener más detalles sobre la compatibilidad de plataformas y el código del controlador:

using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using Singular;

public class SingularMain : MonoBehaviour, SingularLinkHandler
{
    // Start se llama antes de la actualización del primer fotograma
    void Start()
    {
        
    }
    
    void Awake () {
        Debug.Log("Singular === Awake");
        /* Registra la clase como gestor de Singular Link. Puede llamar a este método en cualquier momento de la ejecución de la aplicación. Obtendrá los detalles del enlace de seguimiento y llamará a OnSingularLnkResolved. */
        SingularSDK.SetSingularLinkHandler(this);
    }
    
    public void OnSingularLinkResolved(SingularLinkParams linkParams) {
        Debug.Log("Singular === OnSingularLinkResolved");
        
        // El destino del enlace profundo, configurado en la página Gestionar enlaces
        string deeplink = linkParams.Deeplink;

        // Los parámetros de paso añadidos al enlace, si los hay.
        string passthrough = linkParams.Passthrough;

        // Si el enlace está configurado como enlace profundo diferido.
        bool isLinkDeferred = linkParams.IsDeferred;

        // Añadir código aquí para procesar el enlace profundo
        Debug.Log("Singular === deeplink: "+deeplink);
        Debug.Log("Singular === passthrough: "+passthrough);
        Debug.Log("Singular === isLinkDeferred: "+isLinkDeferred);      
    }
}

public void SetSingularLinkHandler(SingularLinkHandler 
handler)

public class Main : MonoBehaviour, SingularLinkHandler {
    void Awake () {
        SingularSDK.SetSingularLinkHandler(this)
    }
}

public void OnSingularLinkResolved(SingularLinkParams
linkParams)

public void OnSingularLinkResolved(SingularLinkParams
linkParams){
    // Lea los detalles del enlace de seguimiento y regístrelos
    Debug.Log("deeplink: " + linkParams.Deeplink);
    Debug.Log("passthrough: " + linkParams.Passthrough);
    Debug.Log("is_deferred: " + linkParams.IsDeferred);
}

public class Main : SingularDeferredDeepLinkHandler {
              
// ...
                
void Awake () {
    // Registra la clase como gestor de enlaces profundos. 
    // Puedes llamar a este método en cualquier momento de la ejecución de la app.
    SingularSDK.SetDeferredDeepLinkHandler(this);
}
                
public void OnDeferredDeepLink(string deeplink) {
    // El código para manejar el enlace profundo va aquí. 
    // En este ejemplo, el enlace profundo sólo se registra.
    Debug.Log ("Deep link received:" + deeplink);
}
                
// ...

2.5. Inicialización del SDK

El código de inicialización del SDK debe ejecutarse cada vez que se abra la aplicación. Es un requisito previo para toda la funcionalidad de atribución de Singular y envía una nueva sesión a Singular, que se utiliza para calcular la retención de usuarios.

Por defecto, SingularSDK.cs inicializa el SDK automáticamente cuando se crea la escena a través del método Awake.

Inicialización manual

Si prefiere inicializar el SDK manualmente en un momento posterior de la ejecución de la aplicación, haga lo siguiente:

1. Desactive la opción Initialize on Awake en el panel de inspección del objeto SingularSDK.
2. Utilice el método estático SingularSDK.InitializeSingularSDK para inicializar el SDK:

public void InitializeSingularSDK()

// SDK Key y SDK Secret se establecen en el
// objeto de juego asociado a SingularSDK 
SingularSDK.InitializeSingularSDK();

2.6. Configuración del tiempo de espera de la sesión (opcional)

Por defecto, si la aplicación se ejecuta en segundo plano durante 60 segundos o más antes de volver al primer plano, Singular SDK registra una nueva sesión. Puede cambiar el valor predeterminado del tiempo de espera modificando la propiedad Session Timeout Sec de su SingularSDKObject.

2.7. 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.

• 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.
• Cuando se establece con el método Singular SDK, el valor del ID de usuario persiste hasta que se desestablece utilizando el método UnsetCustomUserId o hasta que se desinstala 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 este modo, Singular puede obtener 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.

SingularSDK.SetCustomUserId("custom_user_id");

SingularSDK.UnsetCustomUserId();

SingularSDK.SetDeviceCustomUserId('CustomUserId');

3. Seguimiento de eventos e ingresos

3.1. Seguimiento de eventos (no ingresos)

Singular puede recopilar datos sobre eventos dentro de la aplicación para ayudar a analizar el rendimiento de sus campañas y 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.

Singular admite una variedad de eventos estándar. Las redes publicitarias suelen admitir estos eventos de uso común para la elaboración de informes y la optimización. Otra ventaja es que cuando utiliza nombres de eventos estándar, Singular los reconoce automáticamente y los añade a la lista de eventos sin que tenga que definirlos manualmente. Recomendamos utilizar eventos estándar siempre que sea posible.

La lista de eventos enviados a Singular (con los atributos que los acompañan) debe ser compilada por el equipo de UA/marketing/negocio basándose en los KPI de marketing de su organización. El equipo comercial puede seguir Cómo realizar el seguimiento de eventos en la aplicación: Guía para clientes de Singular Attribution.

Con cada evento que rastree, puede pasar varios atributos. Consulte los atributos estándar recomendados por evento.

Envíe eventos estándar a Singular utilizando los métodos event o eventWithArgs en su código.

SingularSDK.Event(Events.sngLogin);

public static void Event(string name)

public static void Event(string name, params object[] args)

public static void Event(Dictionary<string, object> args,
string name)

// 1) Enviar el evento estándar Iniciar sesión
SingularSDK.Event(Events.sngLogin);

// 2) Un ejemplo de evento personalizado que pasa dos pares clave-valor
SingularSDK.Event("myEventName", "Key1", "Value1", "Key2", 1234);

// 3) Ejemplo de evento JSON que pasa un diccionario
// Crear un diccionario de atributos
Dictionary<string, object> attributes = new Dictionary<string, object>();

// Añadir atributos
attributes["key1"] = "value1";
attributes["key2"] = "value2";
attributes["key3"] = "value3";
// Añadir más atributos según sea necesario

SingularSDK.Event(attributes, "myEventName");

3.2. Seguimiento de ingresos

Singular puede recopilar datos sobre los ingresos obtenidos a través de la aplicación para ayudar a analizar el rendimiento y el ROI de sus campañas. Singular hará que los datos estén disponibles en informes, exportación de registros y postbacks.

Puede realizar un seguimiento de los eventos de ingresos utilizando el objeto IAP (In-App Purchases) integrado de Unity. De esta manera, Singular obtiene toda la información disponible sobre la compra para obtener informes más completos. Singular también obtiene el recibo de compra, que Singular utiliza en el back-end para validar la compra y descartar el fraude de atribución.

public static void InAppPurchase(Product product,
Dictionary<string, object> attributes, bool isRestored = false)

public static void InAppPurchase(string eventName,
Product product, Dictionary<string, object> attributes, 
bool isRestored = false)

public static void InAppPurchase(IEnumerable<Product> products,
Dictionary<string, object> attributes, bool isRestored = false)

public static void InAppPurchase(string eventName,
IEnumerable<Product> products, Dictionary<string, object> 
attributes, bool isRestored = false)

// IAP con un único producto y sin atributos adicionales
SingularSDK.InAppPurchase(myProduct, null);

// PAI con un único producto y atributos
var attr = new Dictionary<string, object>() {
["my_first_attribute"] = "value1",
["my_second_attribute"] = "value2"};
 
SingularSDK.InAppPurchase(myProduct, attr);

// IAP con un solo producto, sin atributos adicionales y un nombre de evento personalizado

SingularSDK.InAppPurchase("MyCustomProduct",
myProduct, null);

// IAP con lista de productos, sin atributos adicionales
SingularSDK.InAppPurchase(myProductList, null);

// IAP con una lista de productos, sin atributos adicionales y un nombre de evento personalizado

SingularSDK.InAppPurchase("MyCustomProducts",
myProductList, null);

public static void Revenue(string currency, double amount)

public static void Revenue(string currency, double amount, string productSKU, string productName, string productCategory, int productQuantity, double productPrice)

public static void Revenue(string currency, double amount, Dictionary<string, object> attributes)

// Enviar un evento de ingresos sin detalles del producto
SingularSDK.Revenue("USD", 1.99);

// Enviar un evento de ingresos con detalles del producto
SingularSDK.Revenue("USD", 4.99, "coin_package_abc123", "Coin Pack 5", "Bundles", 1, 4.99);

// Enviar un evento de ingresos con un diccionario JSON para los atributos
Dictionary<string, object> attributes = new Dictionary<string, object>();

// Añadir atributos
attributes["productSKU"] = "coin_package_abc123";
attributes["productName"] = "Coin Pack 5";
attributes["productCategory"] = "Bundles";
attributes["productQuantity"] = 2;
attributes["productPrice"] = 4.99;

SingularSDK.Revenue("USD", 9.98, attributes);

public static void CustomRevenue(string eventName, string currency, double amount)

public static void CustomRevenue(string eventName, string currency, double amount, string productSKU, string productName, string productCategory, int productQuantity, double productPrice)

public static void CustomRevenue(string eventName, string currency, double amount, Dictionary<string, object> attributes)

// Enviar un evento de ingresos con un nombre personalizado
SingularSDK.CustomRevenue("MyCustomRevenue", "USD", 9.99);

// Enviar un evento de ingresos con un nombre personalizado + detalles del producto
SingularSDK.CustomRevenue("MyCustomRevenue", "USD", 50.50, "abc123", "myProductName", "myProductCategory", 2, 25.50);

// Enviar un evento de ingresos con un nombre personalizado + diccionario JSON para atributos
// Crear un diccionario de atributos
Dictionary<string, object> attributes = new Dictionary<string, object>();

// Añadir atributos
attributes["productSKU"] = "coin_package_abc123";
attributes["productName"] = "Coin Pack 5";
attributes["productCategory"] = "Bundles";
attributes["productQuantity"] = 2;
attributes["productPrice"] = 4.99;
// Añadir más atributos según sea necesario

SingularSDK.CustomRevenue("MyCustomRevenue", "USD", 9.98, attributes);

3.3. Seguimiento de eventos híbrido (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

4. Opciones Avanzadas

4.1. Creación de Enlaces de Referencia Cortos

Utilice los enlaces cortos para transformar enlaces singulares 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).
• Puede añadir los parámetros que desee al enlace de forma dinámica (consulte Parámetros del enlace de seguimiento para ver la lista de opciones).
• Si desea realizar un seguimiento de las nuevas instalaciones de la aplicación hasta el usuario que compartió el enlace, debe proporcionar el Nombre de remitente y el ID de remitente del usuario remitente.

Utilice el método createReferrerShortLink para crear un enlace corto, como en el ejemplo siguiente.

void callback(string shortLinkURL, string error){
    // Añade aquí tu lógica de compartición si shortLinkURL no es null 
    // Si hubo un error, añade lógica para reintentar/abortar/modificar los params
    // pasados a la función, basándose en la causa del error
}

SingularSDK.createReferrerShortLink(
    "https://sample.sng.link/B4tbm/v8fp?_dl=https%3A%2F%2Fabc.com",
    "John Doe", // Nombre del remitente
    "342", // ID de remitente
    new Dictionary<string, string>() { 
        // un objeto Diccionario que contenga los parámetros que desee añadir
        {"channel", "sms"}
    },
    callback 
);

4.2. Añadir soporte de atribución de ingresos publicitarios

4.3. Seguimiento de desinstalaciones

Seguimiento de desinstalaciones en Android

Para habilitar el seguimiento de desinstalaciones para su aplicación Android, primero configure la aplicación en la plataforma Singular como se detalla en Configuración del seguimiento de desinstalaciones. A continuación, siga las siguientes instrucciones.

Habilitación del seguimiento de desinstalaciones mediante Firebase Cloud Messaging (FCM):

1. Integrarse con FCM:

Para realizar un seguimiento de las desinstalaciones, puedes utilizar los servicios de la plataforma Firebase Cloud Messaging (FCM). Si aún no utiliza FCM, siga las instrucciones de Google sobre cómo configurar una aplicación cliente de Firebase Cloud Messaging en Android.

2. Actualice el archivo AndroidManifest.xml:

Actualiza tu archivo AndroidManifest.xml para añadir el filtro de intent necesario para tu app (sustituye MyFirebaseMessagingService por tu clase que implemente el servicio Firebase):

<service android:name=".java.MyFirebaseMessagingService" android:exported="false">
  <intent-filter>
    <action android:name="com.google.firebase.MESSAGING_EVENT" />
  </intent-filter> 
</service>

3. Registrar y enviar el token de dispositivo FCM:

Después de recuperar el token FCM, pásalo como parámetro al método 'RegisterTokenForUninstall':

SingularSDK.RegisterTokenForUninstall(String fcmDeviceToken);

El método 'RegisterTokenForUninstall' debe llamarse antes que elmétodo 'SingularSDK.InitializeSingularSDK()'.

Seguimiento de desinstalaciones en iOS

El seguimiento de la desinstalación en iOS se basa en la tecnología de notificaciones push de Apple. Si su aplicación no es compatible con las notificaciones push, consulte la guía de Apple. Si su aplicación ya admite notificaciones push, debe pasar el token de dispositivo devuelto por APNS mediante el método RegisterTokenForUninstall una vez inicializado el SDK.

public static void RegisterTokenForUninstall
(string APNSToken)

// pasar el token APNS como una cadena hexadecimal
  SingularSDK.RegisterTokenForUninstall("ba85ab31a7c7
f5c2f012587f29fb0e596d4b67e7b7b2838fa1a8582c1f7dbdee");

4.4. Añadir propiedades globales

Con cada sesión y evento enviado desde la aplicación, el SDK de Singular le permite definir propiedades adicionales personalizadas para enviar a los servidores de Singular. Estas propiedades pueden representar cualquier información que desee sobre el usuario, el modo de la aplicación, el estado o cualquier otra cosa. Una vez definidas estas propiedades, estarán disponibles como dimensiones en sus informes, y podrá utilizarlas para desglosar sus datos.

Por ejemplo, si tienes una aplicación de juegos, puedes definir una propiedad llamada "Nivel" y establecerla inicialmente en "0". Cualquier sesión y evento enviado desde la app se enviará con "Nivel": "0". Una vez que el usuario sube de nivel, restableces la propiedad a "1" y así sucesivamente. A continuación, puede obtener sus informes, incluyendo sesiones, recuentos de eventos y datos de ingresos, desglosados por nivel de usuario.

Configuración de propiedades globales antes de la inicialización

Puede utilizar el método SetGlobalProperty para establecer propiedades globales a través de SingularSDK antes de inicializar el SDK. Si desea que sus propiedades globales se incluyan en la sesión, desactive el indicador 'Initialize On awake'.

Dado que las propiedades globales y sus valores persisten entre las ejecuciones de la aplicación, es posible que la propiedad que está configurando ya tenga un valor diferente. Utilice el parámetro overrideExisting para indicar al SDK si debe anular una propiedad existente con el nuevo valor.

Configuración de propiedades globales tras la inicialización

Puede utilizar los siguientes métodos para establecer, desestablecer y recuperar propiedades globales en cualquier momento durante la ejecución de la aplicación.

bool result = SingularSDK.SetGlobalProperty("key", "value", false);

Dictionary<string, string> props = SingularSDK.GetGlobalProperties();

SingularSDK.UnsetGlobalProperty(“test_key”);

SingularSDK.clearGlobalProperties();

4.5. Recopilación de la referencia de instalación en dispositivos Android antiguos

En Android, la referencia de instalación es la herramienta más precisa de Singular para determinar la atribución y ayudar a Singular a detectar y analizar los intentos de fraude. Se trata de un identificador proporcionado por Google Play Store que apunta al anuncio en el que el usuario hizo clic antes de instalar la aplicación.

En dispositivos con la última versión de Google Play Store, el SDK de Singular recopila automáticamente el valor de referencia de instalación (ya que Singular está integrado con la última API de referencia de Google Play).

Para recopilar el referrer de instalación en dispositivos más antiguos, siga las instrucciones de la guía Android SDK.

5. Cumplimiento de las leyes de privacidad de datos

5.1. LimitDataSharing

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.

Limitar el uso compartido de datos

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 limitDataSharing:NO para indicar que el usuario ha dado su consentimiento (optado) para compartir su información.
• Utilice limitDataSharing:YES si el usuario no dio su consentimiento.

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

// El usuario ha aceptado compartir sus datos
SingularSDK.LimitDataSharing(false);

5.2. Métodos adicionales para el cumplimiento del GDPR

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

SingularSDK.TrackingOptIn();

SingularSDK.StopAllTracking();

SingularSDK.ResumeAllTracking();

SingularSDK.IsAllTrackingStopped();