Requisitos previos
Completa estos pasos previos antes de instalar el SDK de Singular para Unity para garantizar un proceso de integración fluido.
Requisitos previos necesarios:
- Completa los pasos de planificación: sigue la guía de Integración de un SDK de Singular: Planificación y requisitos previos. Estos pasos son obligatorios para cualquier integración del SDK de Singular.
- Comprueba el gestor de dependencias: verifica si tu proyecto utiliza Google EDM4U (External Dependency Manager for Unity). Más información sobre Google EDM4U.
-
¿Actualizando desde .unitypackage? Si está migrando del paquete heredado
.unitypackageal nuevo paqueteUPM, lea las instrucciones de actualización antes de continuar.
Instalación
Instalación a través del Gestor de paquetes de Unity (UPM)
El SDK de Singular para Unity se instala a través del Gestor de paquetes de Unity utilizando URL de Git . Sigue estos pasos para añadir el SDK a tu proyecto.
Pasos de instalación
- Abre el Gestor de paquetes: en Unity, ve a Ventana > Gestor de paquetes.
- Añadir paquete desde Git: Haz clic en el botón [+] de la esquina superior izquierda y selecciona «Añadir paquete desde URL de Git».
-
Introduce la URL de Git:
-
Para el SDK estándar: Introduce
https://github.com/singular-labs/Singular-Unity-SDK.git -
Para el SDK para niños: Introduce
https://github.com/singular-labs/Singular-Unity-SDK.git#kids
-
Para el SDK estándar: Introduce
- Finaliza la instalación: haz clic en «Añadir» para instalar el paquete del SDK.
¿No utiliza Google EDM4U? Si su proyecto no utiliza el Gestor de dependencias externas, debe descargar y añadir manualmente las dependencias nativas.
Instalación manual de dependencias
-
Descargar dependencias: Descarga el archivo
Plugins.zipadecuado del bucket S3 de Singular:-
SDK estándar (v5.7.0):
Descargar complementos del SDK estándar -
SDK para niños (v5.6.0):
Descargar complementos del SDK para niños
-
SDK estándar (v5.7.0):
- Extraer a Assets: Extrae los archivos descargados y muévelos a Assets > Plugins en tu proyecto de Unity .
-
Configurar el marco de trabajo de iOS: Ve a
Recursos > Complementos > iOS y selecciona
Singular.xcframework. - Incrustar binario: En el panel Inspector, marca la opción «Añadir a binarios incrustados».
Consejos de configuración para Android
Configura los ajustes de compilación de Android para garantizar el correcto funcionamiento del SDK. Unity ofrece múltiples formas de personalizar los manifiestos de Android y los archivos Gradle .
Puedes modificar AndroidManifest utilizando uno de estos dos métodos:
Método 1: Manifiesto personalizado de Unity
- Ve a Archivo > Ajustes de compilación > Ajustes del reproductor > Ajustes de publicación.
- Habilita «Manifiesto principal personalizado» en la sección Configuración de publicación.
-
Unity genera un archivo
AndroidManifest.xmlpredeterminado en Assets/Plugins/Android/AndroidManifest.xml. - Edita este archivo para añadir los permisos y configuraciones necesarios.
Fuente: Documentación del manifiesto de Android de Unity
Método 2: Android Studio
- Exporta tu proyecto desde Unity mediante Archivo > Configuración de compilación > Exportar proyecto.
- Abre el proyecto exportado en Android Studio.
-
Edita el archivo `
AndroidManifest.xml` directamente en Android Studio.
Método 1: Plantilla personalizada de Unity
- Ve a Archivo > Configuración de compilación > Configuración del reproductor > Configuración de publicación.
- Habilita «Plantilla Gradle personalizada» en la sección Ajustes de publicación.
-
Unity genera un archivo `
mainTemplate.gradle` en ` Assets/Plugins/Android/mainTemplate.gradle`. - Añade tus configuraciones personalizadas de Gradle a este archivo.
Fuente: Documentación de introducción a Gradle de Unity
Método 2: Android Studio
- Exporta tu proyecto desde Unity.
- Abre el proyecto en Android Studio.
-
Edita directamente el archivo `
build.gradle` de la aplicación.
Al compilar aplicaciones de Android en Unity, es posible que te encuentres con errores de «clase duplicada» causados por varSDK de iOS que incluyen las mismas dependencias transitivas. Esto suele ocurrir con la biblioteca Android Vending Licensing cuando se utilizan 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: Uso del gestor de dependencias externo (EDM4U)
Si tu proyecto utiliza External Dependency Manager para Unity (recomendado), añade reglas de exclusión a tu archivo XML de dependencias.
-
Localice el archivo «
*Dependencies.xml» en su proyecto de Unity (normalmente en «Assets/Editor» o 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 en las plantillas personalizadas durante la resolución.
Solución 2: Uso de plantillas Gradle personalizadas
Si no utiliza EDM4U, aplique las reglas de exclusión directamente en sus archivos de configuración de Gradle.
- Vaya a Archivo > Configuración de compilación > Configuración del reproductor > Configuración de publicación.
- Habilita «Plantilla Gradle principal personalizada» o «Plantilla Gradle de lanzador personalizada».
-
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 .
- Recompila tu proyecto de Android en Unity.
- Comprueba que el error de clase duplicada ya no aparece en el resultado de la compilación.
Por qué funciona: Ambos SDK incluyen la misma biblioteca de licencias de Android como dependencia transitiva. La exclusión indica a Gradle que utilice solo una copia, resolviendo el conflicto.
Si tu proyecto utiliza 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 se elimine el SDK de Singular:
-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 correctamente la atribución, los enlaces profundos y la funcionalidad de pruebas.
Después de compilar tu proyecto de Unity para iOS y antes de compilarlo en Xcode, actualiza tus dependencias de CocoaPods para asegurarte de que dispones de las últimas versiones del SDK.
cd /path/to/your/ios/project
pod repo update
pod update
Para probar tu integración, registra el IDFV (Identificador de proveedor) para añadir rápidamente tu dispositivo de prueba en la consola del SDK de Singular.
Añadir 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 aplicación en Xcode.
- Comprueba 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 enlaces universales para los enlaces profundos configurando los dominios asociados en tu proyecto de Xcode.
Pasos para la configuración de enlaces profundos
- Añadir dominio asociado: En Xcode, ve a la pestaña «Firma ycapacidades» del destino de tu aplicación.
- Habilita la capacidad: haz clic en [+] Capacidad y añade «Dominios asociados».
-
Añadir dominio: Añade tu dominio de seguimiento de Singular
en el formato:
applinks:yourdomain.sng.link - Configurar el ID de equipo: En el panel de control de Singular, ve a la configuración de tu aplicación y añade tu ID de equipo de Apple . Esto permite a Singular generar y alojar el archivo de Asociación de Sitios de Aplicaciones de Apple (AASA) necesario para los enlaces universales.
Importante: Sin los dominios asociados y el ID de equipo correctamente configurados, los enlaces universales no funcionarán y los usuarios no podrán abrir tu aplicación desde los enlaces de seguimiento de Singular .
Si utilizas otros SDK que registran el UnityAppController (como Firebase, Adjust o AppsFlyer), es posible que se produzcan 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 comprueba que la siguiente línea no esté comentada:IMPL_APP_CONTROLLER_SUBCLASS(SingularAppDelegate)
Esto permite que Singular funcione junto con otros SDK mediante el uso de el método swizzling en lugar de crear una subclase de 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 utilizando el prefab proporcionado o creándolo manualmente.
Añadir prefab a la escena
- En el panel Proyecto, ve a Paquetes > Singular > SingularSDK > Prefabs.
- Arrastra el prefab SingularSDKObject a tu panel Hierarchy.
- El prefab ya está listo para configurarlo en el Inspector.
Creación manual de GameObject
- En el panel Jerarquía, haz clic con el botón derecho y selecciona Crear vacío.
-
Asigna al GameObject el nombre «
SingularSDKObject» (se requiere el nombre exacto). - Con el GameObject seleccionado, ve al panel Inspector.
- Haz clic en «Añadir componente».
- Busca «Singular» y selecciona el componente de script Singular SDK.
Importante: El GameObject debe llamarse
exactamente
SingularSDKObject para que el SDK funcione
correctamente.
Configurar los ajustes del SDK
Configura tus credenciales del SDK y los ajustes de inicialización a través del Inspector de Unity. Tu clave API y tu secreto son necesarios para que el SDK se comunique con los servidores de Singular.
Añadir credenciales de API
- Selecciona SingularSDKObject: haz clic en SingularSDKObject en tu jerarquía.
- Busca las credenciales: Inicia sesión en tu cuenta de Singular y ve a Herramientas de desarrollador > Integración del SDK > Claves del SDK.
- Copiar claves: Copia tu clave SDK y tu secreto SDK.
- Pegar en el Inspector: En el panel Inspector de Unity, pega las credenciales en los campos Clave API de Singular y Secreto API de Singular.
Importante: NO utilices la clave de la API de informes de Singular . Utiliza únicamente la clave y el secreto de la API específicos del SDK que se encuentran en la página de integración del SDK . El uso de credenciales incorrectas impedirá que los datos se envíen a Singular.
Verifica tu integración: Tras la configuración, prueba tu implementación utilizando la Consola del SDK de Singular para asegurarte de que los eventos se registran correctamente.
Configuración predeterminada del inspector
SingularSDKObject incluye ajustes predeterminados razonables. Comprender estos ajustes te ayudará a personalizar el comportamiento del SDK según los requisitos de tu aplicación.
- Inicializar al despertar: habilitado por defecto. El SDK se inicializa automáticamente cuando el GameObject se activa. Desactive esta opción si necesita retrasar la inicialización por motivos de consentimiento de privacidad u otros requisitos.
- SKAN habilitado: Habilitado por defecto (solo iOS ). Habilita la atribución de SKAdNetwork en modo gestionado, donde Singular actualiza automáticamente los valores de conversión basándose en su modelo de conversión configurado.
- Esperar autorización de seguimiento: Establezca en 0 (desactivado). Si su aplicación muestra el aviso de Transparencia en el seguimiento de aplicaciones de iOS (ATT), establezca este valor en 300 segundos. Esto retrasa la sesión del SDK hasta que el usuario responda al aviso de ATT, lo que garantiza que se pueda capturar el IDFA si se concede el consentimiento. Déjelo en 0 si no utiliza ATT.
- Habilitar registro: Habilitado por defecto. Genera 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 la configuración del nivel de registro (véase más abajo).
-
Nivel de registro: Establecido en 3 (Información) 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.
- Tiempo de espera de DDL (segundos): Establecido en 0 (utiliza el valor predeterminado de 60 segundos). Determina cuánto tiempo espera el SDK a recibir los datos de enlaces profundos diferidos del servidor. El servidor deja de buscar tras este tiempo de espera si no se encuentra ningún enlace profundo diferido.
- Tiempo de espera de sesión (segundos): Establecer en 0 (utiliza el valor predeterminado de 60 segundos). Define cuánto tiempo puede permanecer la aplicación en segundo plano antes de que el SDK cree una nueva sesión al volver al primer plano.
- Tiempo de espera de resolución de enlaces cortos: Establecer en 0 (utiliza el valor predeterminado de 10 segundos). Tiempo máximo de espera para la resolución de enlaces cortos . Protege la experiencia del usuario evitando largas esperas si un enlace corto no se puede resolver.
Opciones de configuración adicionales
A partir del 18 de junio de 2025: la Medición móvil avanzada (AMM)de Meta elimina la necesidad de implementar el Referente de instalación de Meta. Si los informes de AMM están habilitados, no es necesario configurar el Referente de instalación de Meta.
Si necesita admitir el método de atribución heredado de Meta Install Referrer, añada su ID de aplicación de Facebook a la configuración de SingularSDKObject.
Pasos de configuración
- Seleccione SingularSDKObject en su jerarquía de escenas .
- En el panel Inspector, localiza el campo «Facebook App ID» .
- Introduzca su ID de aplicación de Facebook (lo encontrará en su Consola de desarrolladores de Facebook).
Recursos adicionales:
Inicializar el SDK
Cumplimiento de la normativa de privacidad: al implementar el SDK de Singular, cumpla con las leyes de privacidad de las regiones en las que opera, incluyendo el RGPD, la CCPA, la COPPA y otras. Para obtener orientación, consulte las prácticas de inclusión y exclusión voluntaria del SDK.
Inicialice el SDK de Singular cada vez que se inicie su aplicación. La inicialización del SDK es esencial para todas las funciones 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 la escena mediante el método Awake() de Unity.
No se requiere código adicional si la opción «Initialize OnAwake»
está habilitada 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), desactiva la inicialización automática y llama al método de inicialización manualmente.
Configuración de la inicialización manual
- Selecciona 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
Utilice este método para inicializar manualmente el SDK cuando la inicialización automática esté desactivada.
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 utilizado para otras llamadas a la API de Unity. El SDK no es seguro para múltiples subprocesos.
Configuración avanzada
Requisitos para la medición de conversiones integrada de Google Ads en iOS
Si su aplicación ejecuta campañas de Google Ads dirigidas a usuarios de iOS 14.5 o superior, se requieren pasos de configuración adicionales del SDK para admitir la medición de conversiones integrada (ICM) de iOS. Esto incluye:
- Integrar el SDK de medición en el dispositivo (ODM) de Google
- Actualización 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 indicador del enlazador «
-ObjC» y habilitar «enableOdmWithTimeoutInterval» enSingularConfig
Nota: Habilitar enableOdmWithTimeoutInterval retrasa la inicialización del SDK y puede aplazar las devoluciones de llamada de enlaces profundos. Realice esta configuración durante la implementación inicial del SDK para evitar tener que volver a trabajar en ello.
Consulte los requisitos técnicos completos de iOS ICM
Configurar el tiempo de espera de la sesión
Personaliza el tiempo que tu aplicación puede permanecer en segundo plano antes de que el SDK cree una nueva sesión cuando la aplicación vuelva al primer plano.
Configuración del tiempo de espera de la sesión
El tiempo de espera de sesión predeterminado es de 60 segundos. Para cambiar este valor:
- Selecciona 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 deseado en segundos (por ejemplo, 120 para 2 minutos).
- Déjalo en 0 para utilizar el tiempo de espera predeterminado de 60 segundos.
Práctica recomendada: Ten en cuenta los patrones de uso habituales de tu aplicación al configurar el tiempo de espera de la sesión. Los juegos con sesiones cortas y frecuentes pueden beneficiarse de un tiempo de espera más corto, mientras que las aplicaciones de productividad pueden necesitar tiempos de espera más largos.
Actualización de .unitypackage a UPM
Si está migrando del método de instalación heredado de « .unitypackage »
al enfoque moderno de Unity Package Manager (UPM), siga 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. Si no lo haces, se producirán conflictos y errores de compilación. .
Procedimiento de actualización
Sigue estos pasos en orden antes de instalar el SDK a través de Unity Package Manager:
1. Eliminar archivos de código
Ve a la carpeta /Code
de tu proyecto (normalmente Assets/Singular/Code)
y elimina todos los scripts C# relacionados con Singular.
2. Eliminar las dependencias de Android
Ve a /Plugins/Android y elimina los siguientes archivos de Singular:
-
Todos los archivos
.aarque contengan «singular» en el nombre -
Todos los archivos de
.jarque contengan «singular» en el nombre -
singular-sdk.aar -
install-referrer-*.aar -
singular-unitybridge.aar
3. Eliminar las dependencias de iOS
Ve a /Plugins/iOS y elimina los siguientes archivos de Singular:
-
Todos los archivos de encabezado de
.h(por ejemplo,SingularSDK.h) -
Todos los archivos de implementación de
.m(p. ej.,SingularUnityBridge.m) -
Singular.xcframeworkcarpeta
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. Comprueba que todo está limpio
- Después de eliminar los archivos, cierra Unity por completo.
- Elimina la carpeta Library del directorio de tu proyecto para obligar a Unity a volver a importar los activos.
- Vuelve a abrir tu proyecto de Unity.
- Espera a que Unity termine de reimportar los activos.
- Comprueba que no haya errores de compilación antes de proceder con la instalación de UPM.
5. Instala el paquete UPM
Ahora ya estás listo para instalar el SDK de Singular a través del Gestor de paquetes de Unity. Sigue las instrucciones de instalación de UPM que se indican al principio de esta guía.