Documento

Descargar SDK de Android Versión 12.10.0

Sample App (Java)
Revise una integración completa

Video Guía Disponible

Vea este vídeo para un recorrido detallado del proceso de integración. Utilice tanto el vídeo como la guía escrita a continuación para obtener los mejores resultados.

Requisitos previos

Complete los pasos en Integración de un SDK Singular: Planificación y requisitos previos antes de proceder con esta integración.

Importante: Estos pasos previos son necesarios para cualquier integración de Singular SDK.

Instalación

Métodos de instalación

Nota: Android Studio ahora utiliza de forma predeterminada Kotlin DSL (build.gradle.kts) para los nuevos proyectos. Todos los ejemplos de código que aparecen a continuación muestran los formatos Kotlin DSL (recomendado ) y Groovy DSL.

Método 1: Gradle (Recomendado)

Añadir repositorio SDK

Configura el repositorio Singular Maven en la gestión de dependencias de tu proyecto.

Nota: A partir de Gradle 7, Android recomienda utilizar declaraciones de repositorio centralizadas en settings.gradle o settings.gradle.ktsen lugar de declaraciones a nivel de proyecto o módulo build.gradle.

Configuración de Gradle 7

Añade el repositorio Singular SDK a tu archivo de configuración:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://maven.singular.net/")
        }
    }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url 'https://maven.singular.net/'
        }
    }
}

Versiones anteriores de Gradle

Para versiones anteriores de Gradle, añada el repositorio a su archivo de compilación a nivel de proyecto:

repositories {
    mavenCentral()
    maven {
        url = uri("https://maven.singular.net/")
    }
}

repositories {
    mavenCentral()
    maven {
        url 'https://maven.singular.net/'
    }
}

Añadir dependencia de la biblioteca Singular

Añada la biblioteca Singular a las dependencias del módulo de su aplicación.

dependencies {
    implementation("com.singular.sdk:singular_sdk:12.10.0")
}

dependencies {
    implementation 'com.singular.sdk:singular_sdk:12.10.0'
}

Solución de problemas: Problemas de clases duplicadas

Puedes encontrarte con errores de clases duplicadas cuando varias dependencias incluyen la misma biblioteca. Esto suele ocurrir con las bibliotecas de Google Play Services cuando se utilizan versiones anteriores.

Ejemplo de error común:

Duplicate class com.google.android.gms.common.api.ResultCallback found in modules play-services-6.5.87.aar and play-services-basement-17.6.0.aar

Resolución: Excluir dependencias en conflicto

Para resolver los problemas de clases duplicadas, excluye la dependencia transitiva conflictiva de Singular SDK u otras dependencias que causen el conflicto.

dependencies {
    // Exclude specific Google Play Services modules from Singular SDK
    implementation("com.singular.sdk:singular_sdk:12.10.0") {
        exclude(group = "com.google.android.gms", module = "play-services")
    }

    // Add the specific Google Play Services libraries your app needs
    implementation("com.google.android.gms:play-services-ads-identifier:17.0.0")
    implementation("com.google.android.gms:play-services-appset:16.0.2")
}

dependencies {
    // Exclude specific Google Play Services modules from Singular SDK
    implementation('com.singular.sdk:singular_sdk:12.10.0') {
        exclude group: 'com.google.android.gms', module: 'play-services'
    }

    // Add the specific Google Play Services libraries your app needs
    implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0'
    implementation 'com.google.android.gms:play-services-appset:16.0.2'
}

Reglas de exclusión global

Si el conflicto de clase duplicada afecta a varias dependencias del proyecto, puede aplicar una regla de exclusión global.

configurations.all {
    exclude(group = "com.google.android.gms", module = "play-services")
}

configurations.all {
    exclude group: 'com.google.android.gms', module: 'play-services'
}

Verificación de la resolución de dependencias

Una vez aplicadas las reglas de exclusión, comprueba el árbol de dependencias para asegurarte de que se han resuelto los conflictos.

./gradlew app:dependencies --configuration debugRuntimeClasspath

Este comando muestra el árbol de dependencias completo de tu aplicación, mostrando qué bibliotecas están incluidas y cuáles han sido excluidas.

Compatibilidad con Samsung Galaxy Store

Añade la dependencia de referencia de instalación de Samsung Galaxy Store si tu aplicación se distribuye a través de Samsung Galaxy Store.

dependencies {
    implementation("store.galaxy.samsung.installreferrer:samsung_galaxystore_install_referrer:4.0.0")
}

dependencies {
    implementation 'store.galaxy.samsung.installreferrer:samsung_galaxystore_install_referrer:4.0.0'
}

Dependencias transitivas

Si ha desactivado las dependencias transitivas para Singular SDK, añada manualmente estas bibliotecas necesarias a las dependencias del módulo de su aplicación.

dependencies {
    implementation("com.android.installreferrer:installreferrer:2.2")
    implementation("com.google.android.gms:play-services-appset:16.0.0")
}

dependencies {
    implementation 'com.android.installreferrer:installreferrer:2.2'
    implementation 'com.google.android.gms:play-services-appset:16.0.0'
}

Dependencia de Google Play Services

Si tu aplicación no implementa Google Play Services API 17.0.0 o superior, añade la siguiente dependencia.

dependencies {
    implementation("com.google.android.gms:play-services-ads-identifier:17.0.0")
}

dependencies {
    implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0+'
}

Método 2: Instalación manual

Métodos de instalación alternativos

Descarga manual

Descargue e integre manualmente el archivo AAR del SDK en su proyecto.

Descargue el SDK: Descarga el SDK desde el enlace en la parte superior de esta página
Extraer y añadir a libs: Descomprima el paquete SDK y añada Singular.aar al directorio libs de su proyecto Android.
Crea el directorio libs: Si no existe, crea un directorio llamado libs en la carpeta de tu proyecto (normalmente en <project>/app/libs)

Método 3: Instalación Maven

Instalación Maven

Añade el repositorio de Singular Maven al archivo pom.xmlde tu proyecto.

<project ...>
    <repositories>
        <repository>
            <id>singular.net</id>
            <url>http://maven.singular.net/</url>
        </repository>
    </repositories>
</project>

Añade la dependencia:

<dependency>
    <groupId>com.singular.sdk</groupId>
    <artifactId>singular_sdk</artifactId>
    <version>12.10.0</version>
</dependency>

Método 4: Instalación en Eclipse

Instalación en Eclipse

Integra el SDK usando Eclipse siguiendo estos pasos.

Puede utilizar el plugin de Eclipse AAR: gradle-eclipse-aar-plugin

Si no quieres usar el plugin, sigue estos pasos:

Descomprime el AAR: Descomprimir singular_sdk-12.10.0.aar
Renombra el archivo JAR: Cambia el nombre de classes.jara singular_sdk-12.10.0.jar (este es el jar principal del SDK)
Añade el referrer de instalación: Añade la librería com.android.installreferrer:installreferrer:2.2a tu proyecto
Copie los permisos: Copie el permiso BIND_GET_INSTALL_REFERRER_SERVICE del AndroidManifest.xml contenido en el AAR a su AndroidManifest.xml
Copiar permiso de licencia: Copie el permiso CHECK_LICENSE del AndroidManifest.xml contenido en el AAR a su AndroidManifest.xml

Configuración de ProGuard

Reglas de ProGuard

Añada las siguientes reglas a su archivo proguard.config para evitar problemas de ofuscación de código.

-keep class com.singular.sdk.** { *; }
-keep public class com.android.installreferrer.** { *; }
# Uncomment this line in case your are calling the 'revenue' function using the Google billing library
#-keep public class com.android.billingclient.** { *; }

Permisos requeridos

Configuración de AndroidManifest

Añade estos permisos bajo la etiqueta <manifest> en tu archivo AndroidManifest.xml.

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="BIND_GET_INSTALL_REFERRER_SERVICE" />
<uses-permission android:name="com.android.vending.CHECK_LICENSE" />
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

Excluya el permiso com.google.android.gms.permission.AD_ID si está integrando el SDK Kids.

Consultas de Samsung Galaxy Store

Para admitir el referenciador de instalación de Samsung Galaxy Store, añada lo siguiente a su archivo AndroidManifest.xml.

<queries>
    <package android:name="com.sec.android.app.samsungapps" />
</queries>

Integración SDK

Cumplimiento de la privacidad: Siga cumpliendo con las leyes de privacidad promulgadas en las regiones en las que hace negocios, incluidas GDPR, CCPA y COPPA, al implementar los SDK de Singular. Consulte Prácticas de Opt-In y Opt-Outde SDK para obtener orientación.

Importar Singular SDK

Añadir declaración de importación

Importe la biblioteca Singular en su archivo MainActivity.

import com.singular.sdk.*

import com.singular.sdk.*;

Inicializar el SDK

Crear función de inicialización

Para habilitar el seguimiento y la atribución de sesiones, inicialice el SDK de Singular cada vez que inicie su aplicación creando un método privado y llamándolo desde el método onCreate() de su MainActivity.

Siga estos pasos:

Añada la función: Coloque el método de inicialización dentro de su clase MainActivity (o cualquier actividad de punto de entrada).
Inserte las Credenciales: Reemplace SDK KEYy SDK SECRET con su clave y secreto de Singular SDK desde su panel de control.
Actualice SingularConfig: Antes de inicializar el SDK, cree un objeto SingularConfig y establezca las preferencias del SDK (vea Opciones de Configuración más abajo).
Llame a la función: Invoque initSingularSDK() en onCreate() después de configurar la interfaz de usuario pero antes de registrar los eventos.

Implementación básica

Cree el método de inicialización con la configuración básica.

private fun initSingularSDK() {
    // Configure Singular with SDK key and secret
    val config = SingularConfig("SDK KEY", "SDK SECRET")

    try {
        Singular.init(applicationContext, config)
        Log.d("Singular", "SDK initialized successfully")
    } catch (e: Exception) {
        Log.e("Singular", "SDK initialization failed: ${e.message}")
    }
}

private void initSingularSDK() {
    // Configure Singular with SDK key and secret
    SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET");

    try {
        Singular.init(getApplicationContext(), config);
        Log.d("Singular", "SDK initialized successfully");
    } catch (Exception e) {
        Log.e("Singular", "SDK initialization failed: " + e.getMessage());
    }
}

Llamada desde MainActivity onCreate

Invoca el método de inicialización en el método onCreate() de tu MainActivity.

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    // Initialize Singular SDK
    initSingularSDK()

    // Proceed with your app setup (e.g., UI initialization)
}

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    // Initialize Singular SDK
    initSingularSDK();

    // Proceed with your app setup (e.g., UI initialization)
}

Directrices de implementación

Siga estas directrices clave cuando implemente la inicialización del SDK.

Colocación: Añada el método de inicialización en su MainActivity, no en la clase Application, para asegurar el correcto seguimiento de la sesión.
Gestión de errores: El bloque try-catch registra los errores de inicialización (p. ej., credenciales no válidas) sin bloquear la aplicación.
Enlaces profundos: Para manejar enlaces profundos (URLs que lanzan tu aplicación), ver Supporting Deep Linkspara una configuración extendida.
META Install Referrer: Añada config.withFacebookAppId("FacebookAppID") para habilitar la atribución de Meta Install Referrer

A partir del 18 de junio de 2025, Meta Advanced Mobile Measurement Reporting (AMM)elimina la necesidad de implementar Meta Install Referrer. No se recomienda implementar Meta Install Referrer si los informes AMM están habilitados.

Consejo profesional: Si su aplicación admite varios puntos de entrada (por ejemplo, enlaces profundos), asegúrese de que initSingularSDK() se llama en cada actividad relevante de onCreate() para garantizar un comportamiento coherente.

Opciones de configuración

Métodos SingularConfig

El objeto SingularConfig le permite personalizar el comportamiento del SDK utilizando métodos de configuración encadenables. Consulte la siguiente tabla para conocer todas las opciones disponibles.

Método	Descripción
`.withFacebookAppId(String facebookAppID)`	Configure el ID de la aplicación de Facebook. Requerido para la atribución de Meta Install Referrer. Ver ¿Dónde puedo encontrar el Facebook App ID de una aplicación? A partir del 18 de junio de 2025, los informes de medición móvil avanzada (AMM )de Meta eliminan la necesidad de implementar Meta Install Referrer. No se recomienda implementar Meta Install Referrer si los informes AMM están activados.
`.withCustomUserId(String customId)`	Enviar el ID de usuario a Singular
`.withSingularLink(getIntent(), SingularLinkHandler handler)`	Habilitar enlaces profundos con Singular Links
`.withDDLTimeoutInSec(long timeout)`	Establezca el tiempo que Singular busca un enlace profundo diferido cuando se abre la aplicación por primera vez.
`.withOpenURI(URI openURI)`	Obtener el URI de la intención (para procesar enlaces profundos si la aplicación se abre a través de un enlace que no se origina en Singular).
`.withGlobalProperty(String key, String value, boolean overrideExisting)`	Establecer una propiedad global con un valor determinado. La clave y el valor se enviarán a Singular con cualquier evento/sesión enviado desde la aplicación.
`.withSessionTimeoutInSec(long timeout)`	Establece el tiempo de espera de la sesión
`.withFCMDeviceToken(String token)`	Establece el token FCM que se enviará en la primera sesión
`.withLoggingEnabled()`	Activar el registro
`.withLogLevel(int level)`	Configura el nivel de registro (por defecto es Log.ERROR)