Requisitos previos
Complete estos pasos de requisitos previos antes de instalar el SDK de Singular Unity para garantizar un proceso de integración sin problemas.
Requisitos previos obligatorios:
- Complete los pasos de planificación: Siga la guía de Integración de Singular SDK: Planificación y requisitos previos. Estos pasos son obligatorios para cualquier integración de Singular SDK.
- Compruebe 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ás migrando del paquete anterior
.unitypackageal nuevoUPM, lee las instrucciones de actualización antes de continuar.
Instalación
Instalación a través de Unity Package Manager (UPM)
El SDK de Singular Unity se instala a través de Unity Package Manager utilizando URLs Git. Siga estos pasos para añadir el SDK a su proyecto.
Pasos de Instalación
- Abra el Package Manager: En Unity, navegue a Window > Package Manager.
- Añadir paquete desde Git: Haga clic en el botón [+]en la esquina superior izquierda y seleccione "Añadir paquete desde URL git".
-
Introduzca la URL de Git:
-
Para Standard SDK: Introduzca
https://github.com/singular-labs/Singular-Unity-SDK.git -
Para Kids SDK: Introduzca
https://github.com/singular-labs/Singular-Unity-SDK.git#kids
-
Para Standard SDK: Introduzca
- Complete la instalación: Haz clic en "Añadir"para instalar el paquete SDK.
¿No utiliza Google EDM4U? Si su proyecto no utiliza el Gestor de dependencias externas, deberá descargar y añadir manualmente las dependencias nativas.
Instalación manual de dependencias
-
Descarga de dependencias: Descarga el archivo
Plugins.zipapropiado desde el bucket S3 de Singular:-
SDK estándar (v5.6.0):
Descargue los plugins del SDK estándar -
SDK para niños (v5.6.0):
Descargar plugins del SDK para niños
-
SDK estándar (v5.6.0):
- Extraer a Activos: Extrae los archivos descargados y muévelos a Assets > Plugins en tu proyecto Unity.
-
Configura el framework iOS: Ve a Activos > Plugins > iOS y selecciona
Singular.xcframework. - Incrustar binario: En el panel Inspector, marque la opción "Añadir a binarios incrustados".
Consejos de configuración de Android
Configure los ajustes de compilación de Android para garantizar la funcionalidad adecuada del SDK. Unity proporciona varias formas de personalizar los manifiestos de Android y los archivos Gradle.
Usted puede modificar el AndroidManifest usando uno de dos métodos:
Método 1: Manifiesto personalizado de Unity
- Vaya a Archivo > Configuración de compilación > Configuración del reproductor > Configuración de publicación.
- Habilite "Custom Main Manifest" en la sección Publishing Settings.
-
Unity genera un archivo
AndroidManifest.xmlpor defecto en Assets/Plugins/Android/AndroidManifest.xml. - Edite este archivo para añadir los permisos y configuraciones requeridos.
Fuente: Documentación de Unity Android Manifest
Método 2: Android Studio
- Exporte su proyecto desde Unity usando Archivo > Configuración de compilación > Exportar proyecto.
- Abra el proyecto exportado en Android Studio.
-
Edite el archivo
AndroidManifest.xmldirectamente en Android Studio.
Método 1: Plantilla personalizada de Unity
- Vaya a Archivo > Configuración de compilación > Configuración del reproductor > Configuración de publicación.
- Habilite "Custom Gradle Template" bajo la sección Publishing Settings.
-
Unity genera un archivo
mainTemplate.gradleen Assets/Plugins/Android/mainTemplate.gradle. - Añada sus configuraciones Gradle personalizadas a este archivo.
Fuente: Documentación general de Unity Gradle
Método 2: Android Studio
- Exporte su proyecto desde Unity.
- Abre el proyecto en Android Studio.
-
Edita directamente el archivo
build.gradlede la aplicación.
Cuando construya aplicaciones Android en Unity, usted puede encontrar errores de "Duplicate class" causados por múltiples SDKs incluyendo las mismas dependencias transitivas. Esto ocurre comúnmente con la biblioteca Android Vending Licensing cuando se utiliza tanto AppLovin SDK como Singular SDK.
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.10.0.aar -> jetified-singular_sdk-12.10.0-runtime (com.singular.sdk:singular_sdk:12.10.0)
Solución 1: Uso del Gestor de Dependencias Externo (EDM4U)
Si su proyecto utiliza External Dependency Manager para Unity (recomendado), añada reglas de exclusión a su archivo XML de dependencias.
-
Localice su archivo
*Dependencies.xmlen su proyecto Unity (típicamente enAssets/Editoro una ubicación similar). - Añada 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.10.0" />
</androidPackages>
</dependencies>
Nota: Este enfoque es más persistente que modificar las plantillas Gradle, ya que Android Resolver puede sobrescribir los cambios de la plantilla personalizada durante la resolución.
Solución 2: Uso de plantillas Gradle personalizadas
Si no está utilizando EDM4U, aplique 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.
- Habilite "Custom Main Gradle Template"o "Custom Launcher Gradle Template".
-
Abra
Assets/Plugins/Android/mainTemplate.gradle(olauncherTemplate.gradle). - Añada la regla de exclusión a su 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.10.0'
}
Alternativa: Aplique una exclusión global añadiendo esto después de su bloque de dependencias:
configurations.all {
exclude group: 'com.android.vending', module: 'licensing'
}
Verificar resolución
- Después de aplicar la exclusión, limpie su proyecto borrando las carpetas Library/Bee y Temp.
- Reconstruya su proyecto Android en Unity.
- Comprueba que el error de clase duplicada ya no aparece en la salida de compilación.
Por qué funciona: Ambos SDKs incluyen la misma librería de licencias de Android como dependencia transitiva. La exclusión le dice a Gradle que use sólo una copia, resolviendo el conflicto.
Si su proyecto utiliza ProGuard para la ofuscación de código, añada las siguientes reglas keep a su archivo proguard-unity.txt para evitar que se elimine el SDK Singular:
-keep class com.singular.sdk.** { *; }
-keep public class com.android.installreferrer.** { *; }
-keep public class com.singular.unitybridge.** { *; }
Consejos para la configuración de iOS
Configure los ajustes específicos de iOS para permitir la atribución adecuada, la vinculación profunda y la funcionalidad de prueba.
Después de construir su proyecto Unity para iOS y antes de construir en Xcode, actualice sus dependencias CocoaPods para asegurarse de que tiene las últimas versiones del SDK.
cd /path/to/your/ios/project
pod repo update
pod update
Para probar su integración, registre el IDFV (Identifier for Vendor) para añadir rápidamente su dispositivo de prueba en la consola de Singular SDK.
Añadir registro IDFV
- Abra su proyecto Xcode después de construir desde Unity.
- Navegue a Classes > UnityAppController.mm.
-
Busque el método
applicationDidBecomeActive. - Añada el siguiente código para registrar el IDFV:
// Log IDFV for testing
NSLog(@"Singular === IDFV: %@", [[[UIDevice currentDevice] identifierForVendor] UUIDString]);
- Construya y ejecute su aplicación en Xcode.
- Compruebe los registros de la consola de Xcode para la salida IDFV.
- Copie el IDFV y añádalo como dispositivo de prueba en la consola de Singular SDK.
Habilite Universal Links para deep linking configurando Associated Domains en su proyecto Xcode.
Pasos de configuración de enlaces profundos
- Añadir dominio asociado: En Xcode, vaya a la pestaña Signing & Capabilities (Firma y capacidades) de la aplicación de destino.
- Habilite la capacidad: Haz clic en [+] Capacidad y añade "Dominios asociados".
-
Añadir dominio: Añade tu dominio de seguimiento Singular en el formato:
applinks:yourdomain.sng.link - Configurar ID de equipo: En el panel de control de Singular, vaya a la configuración de su aplicación y añada su ID de equipo de Apple. Esto permite a Singular generar y alojar el archivo Apple App Site Association (AASA) necesario para Universal Links.
Importante: Si no se configuran correctamente los dominios asociados y el ID de equipo, los enlaces universales no funcionarán y los usuarios no podrán abrir su aplicación desde los enlaces de seguimiento de Singular.
Integrar el SDK
Cree el GameObject de SingularSDK
Singular SDK requiere un GameObject en su jerarquía de escena Unity para funcionar. Puede añadir este GameObject utilizando el prefab proporcionado o creándolo manualmente.
Añadir Prefab a la Escena
- En el panel Proyecto, vaya a Paquetes > Singular > SingularSDK > Prefabs.
- Arrastre el prefab SingularSDKObject a su panel de jerarquía.
- El prefab está ahora listo para configurar en el Inspector.
Creación Manual del GameObject
- En el panel de Jerarquía, haga clic derecho y seleccione Crear Vacío.
-
Nombre el GameObject
SingularSDKObject(se requiere el nombre exacto). - Con el GameObject seleccionado, navegue al panel Inspector.
- Haga click en Add Component.
- Busque "Singular" y seleccione el componente de script Singular SDK.
Crítico: El GameObject debe llamarse exactamente SingularSDKObject para que el SDK funcione correctamente.
Configure los ajustes del SDK
Configure sus credenciales SDK y ajustes de inicialización a través del Inspector de Unity. Su API Key y Secret son necesarios para que el SDK se comunique con los servidores de Singular.
Añadir credenciales API
- Seleccione SingularSDKObject: Haga clic en el SingularSDKObject en su Jerarquía.
- Localice las credenciales: Inicie sesión en su cuenta de Singulary navegue hasta Herramientas de desarrollador > Integración SDK > Claves SDK.
- Copie las claves: Copie su SDK Key y SDK Secret.
- Péguelas en el Inspector: En el panel Inspector de Unity, pegue las credenciales en los campos Clave de API de Singular y Secreto de API de Singular.
Crítico: NO utilice la Clave de API de informes de Singular. Utilice únicamente la Clave de API y el Secreto específicos del SDK de la página Integración del SDK. El uso de credenciales incorrectas impedirá el envío de datos a Singular.
Verifique su integración: Después de la configuración, pruebe su implementación utilizando la consola del SDK de Singularpara asegurarse de que los eventos se están rastreando correctamente.
Configuración predeterminada del inspector
El SingularSDKObject viene con valores predeterminados sensibles. Comprender estos ajustes le ayudará a personalizar el comportamiento del SDK para los requisitos de su aplicación.
- Initialize On Awake: Habilitado por defecto. El SDK se inicializa automáticamente cuando el GameObject se despierta. Deshabilite esto si necesita retrasar la inicialización para el consentimiento de privacidad u otros requisitos.
- SKAN Activado: Habilitado por defecto (sólo iOS). Habilita la atribución SKAdNetwork en modo gestionado, donde Singular actualiza automáticamente los valores de conversión en función del modelo de conversión configurado.
- Esperar autorización de seguimiento: Establecer en 0 (desactivado). Si su aplicación muestra el mensaje de transparencia de seguimiento de aplicaciones de iOS (ATT), ajústelo a 300 segundos. Esto retrasa la sesión SDK hasta que el usuario responde a la solicitud ATT, asegurando que el IDFA puede ser capturado 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. Debería estar deshabilitado en versiones de producción. Funciona con el parámetro Nivel de registro (véase más abajo).
-
Nivel de registro: El valor predeterminado es 3 (Información). Controla el nivel de detalle de los registros. 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 DDL Seg: Establecido en 0 (utiliza 60 segundos por defecto). Determina cuánto tiempo espera el SDK los datos de enlaces profundos diferidos del servidor. El servidor deja de buscar después de este tiempo de espera si no se encuentra ningún enlace profundo diferido.
- Tiempo de espera de sesión Sec: Establecer en 0 (utiliza 60 segundos por defecto). Define el tiempo que la aplicación puede estar en segundo plano antes de que el SDK cree una nueva sesión al volver al primer plano.
- Shortlink Resolve Timeout: Establecer en 0 (utiliza 10 segundos por defecto). Protege la experiencia del usuario evitando largas esperas si no se puede resolver un enlace corto.
Opciones de configuración adicionales
A partir del 18 de junio de 2025: Advanced Mobile Measurement (AMM)de Meta elimina la necesidad de implementar Meta Install Referrer. Si los informes de AMM están activados, no es necesario configurar Meta Install Referrer.
Si necesitas admitir el método de atribución de Meta Install Referrer heredado, añade el ID de tu aplicación de Facebook a la configuración de SingularSDKObject.
Pasos de configuración
- Seleccione el SingularSDKObject en su jerarquía de escena.
- En el panel Inspector, localice el campo "Facebook App ID".
- Introduce tu ID de aplicación de Facebook (encuéntralo en tu Facebook Developer Console).
Recursos adicionales:
Inicializar el SDK
Cumplimiento de la privacidad: Al implementar Singular SDK, cumple con las leyes de privacidad de las regiones en las que operas, incluidas GDPR, CCPA, COPPA y otras. Para obtener orientación, consulte Prácticas de inclusión y exclusión voluntaria del SDK.
Inicialice Singular SDK cada vez que inicie su aplicación. 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
Por defecto, el script SingularSDK.cs inicializa automáticamente el SDK cuando su escena se carga a través del método Awake() de Unity. No se requiere código adicional si Initialize On Awakeestá habilitado en el Inspector.
Inicialización Manual
Si usted necesita inicializar el SDK en un momento específico (por ejemplo, después de obtener el consentimiento del usuario), deshabilite la inicialización automática y llame al método de inicialización manualmente.
Configuración de la Inicialización Manual
- Seleccione el SingularSDKObject en su jerarquía de escenas.
- En el panel Inspector, desmarque Inicializar al despertar.
-
Llame a
SingularSDK.InitializeSingularSDK()en su código cuando esté 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 hilos: Llame siempre a los métodos del SDK de Singular Unity desde el mismo hilo utilizado para otras llamadas a la API de Unity. El SDK no es seguro para múltiples subprocesos.
Configuración Avanzada
Configurar el tiempo de espera de la sesión
Personalice el tiempo que su 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 por defecto es de 60 segundos. Para cambiar este valor
- Seleccione el SingularSDKObject en su jerarquía de escena.
- En el panel Inspector, localice el campo Session Timeout Sec.
- Introduzca el valor de tiempo de espera deseado en segundos (por ejemplo, 120 para 2 minutos).
- Déjelo en 0 para utilizar el tiempo de espera por defecto de 60 segundos.
Práctica recomendada: Tenga en cuenta los patrones de uso típicos de su aplicación a la hora de configurar el tiempo de espera de la sesión. Los juegos con sesiones cortas 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 .unitypackage al enfoque moderno de Unity Package Manager (UPM), siga estos pasos críticos de actualización.
Crítico: Debe eliminar manualmente todos los archivos existentes de Singular SDK antes de instalar el paquete UPM. De lo contrario, se producirán conflictos y errores de compilación.
Procedimiento de actualización
Complete estos pasos en orden antes de instalar el SDK a través de Unity Package Manager:
1. Eliminar Archivos de Código
Navegue hasta la carpeta /Codede su proyecto (normalmente Assets/Singular/Code) y elimine todos los scripts C# relacionados con Singular.
2. Elimine las dependencias de Android
Vaya a /Plugins/Androidy elimine 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. Eliminar las dependencias de iOS
Vaya a /Plugins/iOS y elimine los siguientes archivos Singular:
-
Todos los archivos de cabecera
.h(por ejemplo,SingularSDK.h) -
Todos los archivos de implementación de
.m(por ejemplo,SingularUnityBridge.m) -
Singular.xcframeworkCarpeta
Importante: Elimine únicamente los archivos específicos de Singular. Tenga cuidado de no eliminar otros archivos de plugin de los que pueda depender su proyecto.
4. Verifique el estado limpio
- Después de eliminar los archivos, cierre Unity completamente.
- Borre la carpeta Library en el directorio de su proyecto para forzar a Unity a reimportar assets.
- Reabra su proyecto Unity.
- Espere a que Unity termine de reimportar los assets.
- Verifique que no hay errores de compilación antes de proceder con la instalación de UPM.
5. Instale el paquete UPM
Ahora está listo para instalar el Singular SDK a través del Unity Package Manager. Siga las instrucciones de instalación de UPMen la parte superior de esta guía.