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:
- Completa los pasos de planificación: Sigue la guía en Integración de un SDK de Singular: planificación y requisitos previos . Estos pasos son obligatorios para cualquier integración de un SDK de Singular.
- Verifica el gestor de dependencias: Comprueba si tu proyecto usa Google EDM4U (External Dependency Manager for Unity). Más información sobre Google EDM4U .
-
¿Actualizas desde .unitypackage?
Si estás migrando del antiguo
.unitypackageal nuevo paqueteUPM, lee las instrucciones de actualización antes de continuar.
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
- Abre Package Manager: En Unity, ve a Window > Package Manager .
- Añade el paquete desde Git: Haz clic en el botón [+] en la esquina superior izquierda y selecciona "Add package from git URL" .
-
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
-
Para el SDK estándar:
Introduce
- 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
-
Descarga las dependencias:
Descarga el archivo
Plugins.zipcorrespondiente desde el bucket de S3 de Singular:-
SDK estándar (v5.8.0):
Descargar los plugins del SDK estándar -
SDK de Kids (v5.6.0):
Descargar los plugins del SDK de Kids
-
SDK estándar (v5.8.0):
- Extrae en Assets: Extrae los archivos descargados y muévelos a Assets > Plugins en tu proyecto de Unity.
-
Configura el framework de iOS:
Ve a
Assets > Plugins > iOS
y selecciona
Singular.xcframework. - 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.
Puedes modificar el AndroidManifest usando uno de dos métodos:
Método 1: Manifiesto personalizado de Unity
- Ve a File > Build Settings > Player Settings > Publishing Settings .
- Habilita "Custom Main Manifest" en la sección Publishing Settings.
-
Unity genera un archivo
AndroidManifest.xmlpredeterminado en Assets/Plugins/Android/AndroidManifest.xml . - 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
- Exporta tu proyecto desde Unity usando File > Build Settings > Export Project .
- Abre el proyecto exportado en Android Studio.
-
Edita el archivo
AndroidManifest.xmldirectamente en Android Studio.
Método 1: Plantilla personalizada de Unity
- Ve a File > Build Settings > Player Settings > Publishing Settings .
- Habilita "Custom Gradle Template" en la sección Publishing Settings.
-
Unity genera un archivo
mainTemplate.gradleen Assets/Plugins/Android/mainTemplate.gradle . - Añade tus configuraciones personalizadas de Gradle a este archivo.
Fuente: Documentación general de Gradle de Unity
Método 2: Android Studio
- Exporta tu proyecto desde Unity.
- Abre el proyecto en Android Studio.
-
Edita el archivo
build.gradlede la app directamente.
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.
-
Localiza tu archivo
*Dependencies.xmlen tu proyecto de Unity (normalmente enAssets/Editoro una ubicación similar). - Añade una regla de exclusión a una de las dependencias del SDK:
<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.
- Ve a File > Build Settings > Player Settings > Publishing Settings .
- Habilita "Custom Main Gradle Template" o "Custom Launcher Gradle Template" .
-
Abre
Assets/Plugins/Android/mainTemplate.gradle(olauncherTemplate.gradle). - Añade la regla de exclusión a tu bloque de dependencias:
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:
configurations.all {
exclude group: 'com.android.vending', module: 'licensing'
}
Verifica la resolución
- Después de aplicar la exclusión, limpia tu proyecto eliminando las carpetas Library/Bee y Temp .
- Vuelve a compilar tu proyecto de Android en Unity.
- 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.
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:
-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.
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.
cd /path/to/your/ios/project
pod repo update
pod update
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
- Abre tu proyecto de Xcode después de compilarlo desde Unity.
- Ve a Classes > UnityAppController.mm .
-
Busca el método
applicationDidBecomeActive. - Añade el siguiente código para registrar el IDFV:
// Log IDFV for testing
NSLog(@"Singular === IDFV: %@", [[[UIDevice currentDevice] identifierForVendor] UUIDString]);
- Compila y ejecuta tu app en Xcode.
- Revisa los registros de la consola de Xcode para ver la salida del IDFV.
- Copia el IDFV y añádelo como dispositivo de prueba en la consola del SDK de Singular .
Habilita los Universal Links para deep linking configurando los Associated Domains en tu proyecto de Xcode.
Pasos para configurar deep links
- Añade un Associated Domain: En Xcode, ve a la pestaña Signing & Capabilities del target de tu app.
- Habilita la capability: Haz clic en [+] Capability y añade "Associated Domains" .
-
Añade el dominio:
Añade tu dominio de tracking
de Singular
con el formato:
applinks:yourdomain.sng.link - 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.
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:
-
Abre
el archivo
SingularSwizzledAppController.men tu proyecto de Xcode. - Descomenta todo el código de este archivo.
-
Abre
SingularAppDelegate.my 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.
Añade el prefab a la escena
- En el panel Project , ve a Packages > Singular > SingularSDK > Prefabs .
- Arrastra el prefab SingularSDKObject a tu panel Hierarchy .
- El prefab ya está listo para configurarse en el Inspector.
Creación manual del GameObject
- En el panel Hierarchy , haz clic derecho y selecciona Create Empty .
-
Nombra el GameObject
SingularSDKObject(se requiere el nombre exacto). - Con el GameObject seleccionado, ve al Inspector .
- Haz clic en Add Component .
- 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
- Selecciona SingularSDKObject: Haz clic en el SingularSDKObject en tu Hierarchy.
- Localiza las credenciales: Inicia sesión en tu cuenta de Singular y ve a Developer Tools > SDK Integration > SDK Keys .
- Copia las claves: Copia tu SDK Key y SDK Secret .
- 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.
- 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:
// 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
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
- Selecciona el SingularSDKObject en la jerarquía de tu escena.
- En el panel Inspector, localiza el campo "Facebook App ID" .
- 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
- Selecciona el SingularSDKObject en la jerarquía de tu escena.
- En el panel Inspector, desmarca Initialize On Awake .
-
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.
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
-ObjCy habilitarenableOdmWithTimeoutIntervalenSingularConfig
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:
- Selecciona el SingularSDKObject en la jerarquía de tu escena.
- En el panel Inspector, localiza el campo Session Timeout Sec .
- Introduce el valor de tiempo de espera que desees en segundos (p. ej., 120 para 2 minutos).
- 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.
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:
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
.aarcon "singular" en el nombre -
Todos los archivos
.jarcon "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
- Después de eliminar los archivos, cierra Unity por completo.
- Elimina la carpeta Library del directorio de tu proyecto para forzar a Unity a reimportar los assets.
- Vuelve a abrir tu proyecto de Unity.
- Espera a que Unity termine de reimportar los assets.
- 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.