SDK de Unity - Integración básica

Requisitos previos

Completa estos pasos previos antes de instalar el SDK de Singular para Unity para garantizar un proceso de integración sin problemas.

Requisitos previos obligatorios:


Instalación

Instalación mediante Unity Package Manager (UPM)

El SDK de Singular para Unity se instala a través de Unity Package Manager usando URLs de Git. Sigue estos pasos para añadir el SDK a tu proyecto.

Pasos de instalación

  1. Abre Package Manager: En Unity, ve a Window > Package Manager .
  2. Añade el paquete desde Git: Haz clic en el botón [+] en la esquina superior izquierda y selecciona "Add package from git URL" .
  3. Introduce la URL de Git:
    • Para el SDK estándar: Introduce https://github.com/singular-labs/Singular-Unity-SDK.git
    • Para el SDK de Kids: Introduce https://github.com/singular-labs/Singular-Unity-SDK.git#kids
  4. Completa la instalación: Haz clic en "Add" para instalar el paquete del SDK.

¿No usas Google EDM4U? Si tu proyecto no usa el External Dependency Manager, debes descargar y añadir manualmente las dependencias nativas.

Instalación manual de dependencias

  1. Descarga las dependencias: Descarga el archivo Plugins.zip correspondiente desde el bucket de S3 de Singular:
  2. Extrae en Assets: Extrae los archivos descargados y muévelos a Assets > Plugins en tu proyecto de Unity.
  3. Configura el framework de iOS: Ve a Assets > Plugins > iOS y selecciona Singular.xcframework .
  4. Incorpora el binario: En el panel Inspector, marca la opción "Add to Embedded Binaries" .

Consejos de configuración para Android

Configura los ajustes de compilación de Android para garantizar el correcto funcionamiento del SDK. Unity ofrece varias formas de personalizar los manifiestos de Android y los archivos Gradle.

Cómo actualizar AndroidManifest.xml

Puedes modificar el AndroidManifest usando uno de dos métodos:

Método 1: Manifiesto personalizado de Unity

  1. Ve a File > Build Settings > Player Settings > Publishing Settings .
  2. Habilita "Custom Main Manifest" en la sección Publishing Settings.
  3. Unity genera un archivo AndroidManifest.xml predeterminado en Assets/Plugins/Android/AndroidManifest.xml .
  4. Edita este archivo para añadir los permisos y las configuraciones necesarios.

Fuente: Documentación del Android Manifest de Unity

Método 2: Android Studio

  1. Exporta tu proyecto desde Unity usando File > Build Settings > Export Project .
  2. Abre el proyecto exportado en Android Studio.
  3. Edita el archivo AndroidManifest.xml directamente en Android Studio.
Cómo actualizar los archivos de compilación de Gradle

Método 1: Plantilla personalizada de Unity

  1. Ve a File > Build Settings > Player Settings > Publishing Settings .
  2. Habilita "Custom Gradle Template" en la sección Publishing Settings.
  3. Unity genera un archivo mainTemplate.gradle en Assets/Plugins/Android/mainTemplate.gradle .
  4. Añade tus configuraciones personalizadas de Gradle a este archivo.

Fuente: Documentación general de Gradle de Unity

Método 2: Android Studio

  1. Exporta tu proyecto desde Unity.
  2. Abre el proyecto en Android Studio.
  3. Edita el archivo build.gradle de la app directamente.
Resolución de errores de clase duplicada

Al compilar apps de Android en Unity, es posible que encuentres errores de "Duplicate class" causados por varSDK de iOS que incluyen las mismas dependencias transitivas. Esto ocurre comúnmente con la biblioteca Android Vending Licensing al usar tanto el SDK de AppLovin como el SDK de Singular.

Ejemplo de error:

Duplicate class com.android.vending.licensing.ILicensingService found in modules
applovin-sdk-13.5.0.aar -> jetified-applovin-sdk-13.5.0-runtime (com.applovin:applovin-sdk:13.5.0)
and singular_sdk-12.11.0.aar -> jetified-singular_sdk-12.11.0-runtime (com.singular.sdk:singular_sdk:12.11.0)

Solución 1: Usar External Dependency Manager (EDM4U)

Si tu proyecto usa External Dependency Manager for Unity (recomendado), añade reglas de exclusión a tu archivo Dependencies XML.

  1. Localiza tu archivo *Dependencies.xml en tu proyecto de Unity (normalmente en Assets/Editor o una ubicación similar).
  2. Añade una regla de exclusión a una de las dependencias del SDK:
XML
<dependencies>
  <androidPackages>
    <androidPackage spec="com.applovin:applovin-sdk:13.5.0">
      <androidSdkPackageIds>
        <exclude group="com.android.vending" module="licensing"/>
      </androidSdkPackageIds>
    </androidPackage>
    <androidPackage spec="com.singular.sdk:singular_sdk:12.11.0" />
  </androidPackages>
</dependencies>

Nota: Este enfoque es más persistente que modificar las plantillas de Gradle, ya que Android Resolver puede sobrescribir los cambios de plantilla personalizados durante la resolución.

Solución 2: Usar plantillas personalizadas de Gradle

Si no usas EDM4U, aplica las reglas de exclusión directamente en tus archivos de configuración de Gradle.

  1. Ve a File > Build Settings > Player Settings > Publishing Settings .
  2. Habilita "Custom Main Gradle Template" o "Custom Launcher Gradle Template" .
  3. Abre Assets/Plugins/Android/mainTemplate.gradle (o launcherTemplate.gradle ).
  4. Añade la regla de exclusión a tu bloque de dependencias:
Gradle
dependencies {
    implementation('com.applovin:applovin-sdk:13.5.0') {
        exclude group: 'com.android.vending', module: 'licensing'
    }
    implementation 'com.singular.sdk:singular_sdk:12.11.0'
}

Alternativa: Aplica una exclusión global añadiendo esto después de tu bloque de dependencias:

Gradle
configurations.all {
    exclude group: 'com.android.vending', module: 'licensing'
}

Verifica la resolución

  1. Después de aplicar la exclusión, limpia tu proyecto eliminando las carpetas Library/Bee y Temp .
  2. Vuelve a compilar tu proyecto de Android en Unity.
  3. Verifica que el error de clase duplicada ya no aparezca en la salida de compilación.

Por qué funciona: Ambos SDK incluyen la misma biblioteca de licencias de Android como dependencia transitiva. La exclusión le indica a Gradle que use solo una copia, resolviendo el conflicto.

Configuración de ProGuard

Si tu proyecto usa ProGuard para la ofuscación de código, añade las siguientes reglas de retención a tu archivo proguard-unity.txt para evitar que el SDK de Singular sea eliminado:

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

Consejos de configuración para iOS

Configura los ajustes específicos de iOS para habilitar la atribución, el deep linking y las funciones de prueba correctamente.

Actualiza las dependencias de CocoaPods

Después de compilar tu proyecto de Unity para iOS y antes de compilar en Xcode, actualiza tus dependencias de CocoaPods para asegurarte de tener las últimas versiones del SDK.

Terminal
cd /path/to/your/ios/project
pod repo update
pod update
Registra el IDFV para pruebas

Para probar tu integración, registra el IDFV (Identifier for Vendor) para añadir rápidamente tu dispositivo de prueba en la consola del SDK de Singular.

Añade el registro del IDFV

  1. Abre tu proyecto de Xcode después de compilarlo desde Unity.
  2. Ve a Classes > UnityAppController.mm .
  3. Busca el método applicationDidBecomeActive .
  4. Añade el siguiente código para registrar el IDFV:
Objective-C
// Log IDFV for testing
NSLog(@"Singular === IDFV: %@", [[[UIDevice currentDevice] identifierForVendor] UUIDString]);
  1. Compila y ejecuta tu app en Xcode.
  2. Revisa los registros de la consola de Xcode para ver la salida del IDFV.
  3. Copia el IDFV y añádelo como dispositivo de prueba en la consola del SDK de Singular .
Configura la compatibilidad con deep links

Habilita los Universal Links para deep linking configurando los Associated Domains en tu proyecto de Xcode.

  1. Añade un Associated Domain: En Xcode, ve a la pestaña Signing & Capabilities del target de tu app.
  2. Habilita la capability: Haz clic en [+] Capability y añade "Associated Domains" .
  3. Añade el dominio: Añade tu dominio de tracking de Singular con el formato: applinks:yourdomain.sng.link
  4. Configura el Team ID: En el panel de Singular, ve a la configuración de tu app y añade tu Apple Team ID. Esto permite que Singular genere y aloje el archivo Apple App Site Association (AASA) necesario para los Universal Links.

Importante: Sin los Associated Domains y el Team ID configurados correctamente, los Universal Links no funcionarán y los usuarios no podrán abrir tu app desde los enlaces de tracking de Singular.

⚠️ Importante: resolución de conflictos de UnityAppController

Si usas otros SDK que registran el UnityAppController (como Firebase, Adjust o AppsFlyer), es posible que encuentres conflictos que impidan que Singular se inicialice correctamente. En Unity, solo una clase puede registrarse como UnityAppController a la vez.

Para resolver este conflicto:

  1. Abre el archivo SingularSwizzledAppController.m en tu proyecto de Xcode.
  2. Descomenta todo el código de este archivo.
  3. Abre SingularAppDelegate.m y valida que la siguiente línea no esté comentada:
    IMPL_APP_CONTROLLER_SUBCLASS(SingularAppDelegate)

Esto permite que Singular funcione junto con otros SDK usando method swizzling en lugar de crear una subclase del UnityAppController.


Integra el SDK

Crea el GameObject SingularSDK

El SDK de Singular requiere un GameObject en la jerarquía de tu escena de Unity para funcionar. Puedes añadir este GameObject usando el prefab proporcionado o creándolo manualmente.

Método 1: Usar el prefab de Singular (recomendado)

Añade el prefab a la escena

  1. En el panel Project , ve a Packages > Singular > SingularSDK > Prefabs .
  2. Arrastra el prefab SingularSDKObject a tu panel Hierarchy .
  3. El prefab ya está listo para configurarse en el Inspector.
Método 2: Crear el GameObject manualmente

Creación manual del GameObject

  1. En el panel Hierarchy , haz clic derecho y selecciona Create Empty .
  2. Nombra el GameObject SingularSDKObject (se requiere el nombre exacto).
  3. Con el GameObject seleccionado, ve al Inspector .
  4. Haz clic en Add Component .
  5. Busca "Singular" y selecciona el componente de script Singular SDK .

Importante: El GameObject debe llamarse exactamente SingularSDKObject para que el SDK funcione correctamente.

Configura los ajustes del SDK

Configura las credenciales del SDK y los ajustes de inicialización a través del Inspector de Unity. Tu API Key y Secret son obligatorios para que el SDK se comunique con los servidores de Singular.

Añade las credenciales de la API

  1. Selecciona SingularSDKObject: Haz clic en el SingularSDKObject en tu Hierarchy.
  2. Localiza las credenciales: Inicia sesión en tu cuenta de Singular y ve a Developer Tools > SDK Integration > SDK Keys .
  3. Copia las claves: Copia tu SDK Key y SDK Secret .
  4. Pégalas en el Inspector: En el panel Inspector de Unity, pega las credenciales en los campos Singular API Key y Singular API Secret .

Importante: NO uses la API Key de Singular Reporting. Usa únicamente la API Key y el Secret específicos del SDK de la página SDK Integration. Usar credenciales incorrectas impedirá que los datos se envíen a Singular.

Verifica tu integración: Después de la configuración, prueba tu implementación usando la consola del SDK de Singular para asegurarte de que los eventos se rastreen correctamente.

Ajustes predeterminados del Inspector

El SingularSDKObject viene con valores predeterminados razonables. Entender estos ajustes te ayuda a personalizar el comportamiento del SDK según los requisitos de tu app.

Opciones de configuración predeterminadas
  • Initialize On Awake: Habilitado de forma predeterminada. El SDK se inicializa automáticamente cuando el GameObject se activa (awake). Deshabilítalo si necesitas retrasar la inicialización por consentimiento de privacidad u otros requisitos.
  • SKAN Enabled: Habilitado de forma predeterminada (solo en iOS). Habilita la atribución de SKAdNetwork en Managed Mode, donde Singular actualiza automáticamente los conversion values según tu modelo de conversión configurado.
  • Wait For Tracking Authorization: Establecido en 0 (deshabilitado). Si tu app muestra el aviso de iOS App Tracking Transparency (ATT), establece este valor en 300 segundos. Esto retrasa la sesión del SDK hasta que el usuario responda al aviso de ATT, asegurando que el IDFA pueda capturarse si se otorga el consentimiento. Déjalo en 0 si no usas ATT.
  • Enable Logging: Habilitado de forma predeterminada. Genera los registros de depuración del SDK para ayudar con la integración y la resolución de problemas. Debe deshabilitarse en las compilaciones de producción. Funciona con el ajuste Log Level (ver más abajo).
  • Log Level: Establecido en 3 (Info) de forma predeterminada. Controla el nivel de detalle del registro. Los números más bajos producen registros más detallados:
    C#
    // Based on Android Logger log levels
    public enum LogLevel {
       Verbose = 2,  // Most verbose
       Debug   = 3,
       Info    = 4,  // Default
       Warn    = 5,
       Error   = 6,
       Assert  = 7   // Least verbose
    }

    Nota: Los registros detallados están disponibles principalmente en Android.

  • DDL Timeout Sec: Establecido en 0 (usa el valor predeterminado de 60 segundos). Determina cuánto tiempo espera el SDK los datos del deferred deep link del servidor. El servidor deja de buscar después de este tiempo de espera si no se encuentra ningún deferred deep link.
  • Session Timeout Sec: Establecido en 0 (usa el valor predeterminado de 60 segundos). Define cuánto tiempo puede estar la app en segundo plano antes de que el SDK cree una nueva sesión al volver al primer plano.
  • Shortlink Resolve Timeout: Establecido en 0 (usa el valor predeterminado de 10 segundos). Tiempo máximo de espera para la resolución del short link. Protege la experiencia del usuario evitando esperas largas si un short link no puede resolverse.

Opciones de configuración adicionales

Configuración del Install Referrer de Facebook (Meta)

A partir del 18 de junio de 2025: el Advanced Mobile Measurement (AMM) de Meta elimina la necesidad de implementar el Meta Install Referrer. Si el reporte de AMM está habilitado, no necesitas configurar el Meta Install Referrer.

Si necesitas admitir el antiguo método de atribución del Meta Install Referrer, añade tu Facebook App ID a la configuración del SingularSDKObject.

Pasos de configuración

  1. Selecciona el SingularSDKObject en la jerarquía de tu escena.
  2. En el panel Inspector, localiza el campo "Facebook App ID" .
  3. Introduce tu Facebook App ID (lo encuentras en tu Facebook Developer Console).

Recursos adicionales:


Inicializa el SDK

Cumplimiento de privacidad: Al implementar el SDK de Singular, cumple con las leyes de privacidad de las regiones en las que operas, incluidas GDPR, CCPA, COPPA y otras. Para más orientación, consulta Prácticas de opt-in y opt-out del SDK .

Inicializa el SDK de Singular cada vez que se inicie tu app. La inicialización del SDK es esencial para toda la funcionalidad de atribución de Singular y crea una nueva sesión para calcular las métricas de retención de usuarios.

Inicialización automática

De forma predeterminada, el script SingularSDK.cs inicializa automáticamente el SDK cuando se carga tu escena a través del método Awake() de Unity. No se requiere código adicional si Initialize On Awake está habilitado en el Inspector.

Inicialización manual

Si necesitas inicializar el SDK en un momento específico (por ejemplo, después de obtener el consentimiento del usuario), deshabilita la inicialización automática y llama al método de inicialización manualmente.

Configuración de la inicialización manual

  1. Selecciona el SingularSDKObject en la jerarquía de tu escena.
  2. En el panel Inspector, desmarca Initialize On Awake .
  3. Llama a SingularSDK.InitializeSingularSDK() en tu código cuando estés listo para inicializar.

Método InitializeSingularSDK

Usa este método para inicializar el SDK manualmente cuando la inicialización automática está deshabilitada.

C#
using UnityEngine;
using Singular;

public class GameInitializer : MonoBehaviour
{
    void Start()
    {
        // Perform any required setup (e.g., consent management)
        CheckUserConsent();

        // Initialize Singular SDK after consent is obtained
        // SDK Key and Secret are configured on the SingularSDKObject
        SingularSDK.InitializeSingularSDK();
    }

    void CheckUserConsent()
    {
        // Your consent logic here
    }
}

Seguridad de subprocesos: Llama siempre a los métodos del SDK de Singular para Unity desde el mismo subproceso usado para otras llamadas a la API de Unity. El SDK no es seguro para subprocesos en múltiples subprocesos.


Configuración avanzada

Requerido para la medición de conversiones integradas de Google Ads en iOS

Si tu app ejecuta campañas de Google Ads dirigidas a usuarios de iOS 14.5+, se requieren pasos de configuración adicionales del SDK para admitir la iOS Integrated Conversion Measurement (ICM). Esto incluye:

  • Integrar el SDK On-Device Measurement (ODM) de Google
  • Actualizar al SDK de Singular para iOS v12.8.1+ (o v5.5.0+ para Unity, v1.8.0+ para Flutter/Cordova, v3.9.0+ para React Native)
  • Añadir el flag de linker -ObjC y habilitar enableOdmWithTimeoutInterval en SingularConfig

Nota: Habilitar enableOdmWithTimeoutInterval retrasa la inicialización del SDK y puede aplazar los callbacks de deep link. Completa esta configuración durante la implementación inicial del SDK para evitar tener que rehacer el trabajo.

Ver los requisitos técnicos completos del ICM de iOS


Configura el tiempo de espera de sesión

Personaliza cuánto tiempo puede permanecer tu app en segundo plano antes de que el SDK cree una nueva sesión cuando la app vuelve al primer plano.

Configuración del tiempo de espera de sesión

El tiempo de espera de sesión predeterminado es de 60 segundos. Para cambiar este valor:

  1. Selecciona el SingularSDKObject en la jerarquía de tu escena.
  2. En el panel Inspector, localiza el campo Session Timeout Sec .
  3. Introduce el valor de tiempo de espera que desees en segundos (p. ej., 120 para 2 minutos).
  4. Déjalo en 0 para usar el tiempo de espera predeterminado de 60 segundos.

Buena práctica: Ten en cuenta los patrones de uso habituales de tu app al configurar el tiempo de espera de sesión. Los juegos con sesiones cortas y frecuentes pueden beneficiarse de un tiempo de espera más corto, mientras que las apps de productividad pueden necesitar tiempos de espera más largos.


Actualización de .unitypackage a UPM

Si estás migrando del antiguo método de instalación .unitypackage al enfoque moderno de Unity Package Manager (UPM), sigue estos pasos de actualización críticos.

Instrucciones de migración: de .unitypackage a UPM

Importante: Debes eliminar manualmente todos los archivos existentes del SDK de Singular antes de instalar el paquete UPM. No hacerlo provocará conflictos y errores de compilación.

Procedimiento de actualización

Completa estos pasos en orden antes de instalar el SDK a través de Unity Package Manager:

Eliminación de archivos paso a paso

1. Elimina los archivos de código

Ve a la carpeta /Code de tu proyecto (normalmente Assets/Singular/Code ) y elimina todos los scripts de C# relacionados con Singular.

2. Elimina las dependencias de Android

Ve a /Plugins/Android y elimina los siguientes archivos de Singular:

  • Todos los archivos .aar con "singular" en el nombre
  • Todos los archivos .jar con "singular" en el nombre
  • singular-sdk.aar
  • install-referrer-*.aar
  • singular-unitybridge.aar

3. Elimina las dependencias de iOS

Ve a /Plugins/iOS y elimina los siguientes archivos de Singular:

  • Todos los archivos de encabezado .h (p. ej., SingularSDK.h )
  • Todos los archivos de implementación .m (p. ej., SingularUnityBridge.m )
  • la carpeta Singular.xcframework

Importante: Elimina únicamente los archivos específicos de Singular. Ten cuidado de no borrar otros archivos de plugins de los que pueda depender tu proyecto.

4. Verifica el estado limpio

  1. Después de eliminar los archivos, cierra Unity por completo.
  2. Elimina la carpeta Library del directorio de tu proyecto para forzar a Unity a reimportar los assets.
  3. Vuelve a abrir tu proyecto de Unity.
  4. Espera a que Unity termine de reimportar los assets.
  5. Verifica que no haya errores de compilación antes de continuar con la instalación de UPM.

5. Instala el paquete UPM

Ahora estás listo para instalar el SDK de Singular a través de Unity Package Manager. Sigue las instrucciones de instalación de UPM al principio de esta guía.