Descargar SDK de Android versión 12.13.0

Guía en video disponible

Mira este video para obtener un recorrido detallado del proceso de integración. Usa tanto el video como la guía escrita a continuación para obtener mejores resultados.

Requisitos previos

Completa los pasos en Integración de un SDK de Singular: planificación y requisitos previos antes de continuar con esta integración.

Importante: Estos pasos de requisitos previos son obligatorios para cualquier integración del SDK de Singular.

Instalación

Métodos de instalación

Nota: Android Studio ahora utiliza por defecto Kotlin DSL (build.gradle.kts) para los nuevos proyectos. Todos los ejemplos de código a continuación muestran tanto el formato Kotlin DSL (recomendado) como Groovy DSL .

Método 1: Gradle (recomendado)

Agregar el repositorio del SDK

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

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

Configuración para Gradle 7+

Agrega el repositorio del SDK de Singular a tu archivo de settings:

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, agrega el repositorio a tu 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/'
    }
}

Agregar la dependencia de la librería de Singular

Agrega la librería de Singular a las dependencias del módulo de tu app.

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

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

Resolución de problemas: clases duplicadas

Puede que te encuentres con errores de clases duplicadas cuando varias dependencias incluyen la misma librería. Esto ocurre comúnmente con las librerías de Google Play Services al usar 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

Solución: excluir dependencias en conflicto

Para resolver los problemas de clases duplicadas, excluye la dependencia transitiva (transitive dependency) en conflicto del SDK de Singular u otras dependencias que estén causando el conflicto.

dependencies {
    // Exclude specific Google Play Services modules from Singular SDK
    implementation("com.singular.sdk:singular_sdk:12.13.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.13.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 globales

Si el conflicto de clases duplicadas afecta a múltiples dependencias a través de tu proyecto, puedes 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'
}

Verificar la resolución de dependencias

Después de aplicar las reglas de exclusión, verifica el árbol de dependencias de tu proyecto para asegurarte de que los conflictos se hayan resuelto.

./gradlew app:dependencies --configuration debugRuntimeClasspath

Este comando muestra el árbol completo de dependencias de tu app, indicando qué librerías están incluidas y cuáles han sido excluidas.

Soporte para Samsung Galaxy Store

Agrega la dependencia del install referrer de Samsung Galaxy Store si tu app 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 (Transitive Dependencies)

Si has deshabilitado las dependencias transitivas para el SDK de Singular, agrega manualmente estas librerías requeridas a las dependencias del módulo de tu app.

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

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

Dependencia de Google Play Services

Si tu app no implementa Google Play Services API 17.0.0 o superior, agrega 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

Descarga e integra manualmente el archivo AAR del SDK en tu proyecto.

Descargar el SDK: Descarga el SDK desde el enlace en la parte superior de esta página
Extraer y agregar a libs: Descomprime el paquete del SDK y agrega Singular.aar al directorio libs de tu proyecto de Android
Crear 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 con Maven

Instalación con Maven

Agrega el repositorio Maven de Singular al archivo pom.xml de tu proyecto.

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

Agrega la dependencia:

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

Método 4: instalación con Eclipse

Instalación con Eclipse

Integra el SDK usando Eclipse siguiendo estos pasos.

Puedes utilizar el plugin Eclipse AAR: gradle-eclipse-aar-plugin

Si no deseas utilizar el plugin, sigue estos pasos:

Descomprimir el AAR: Descomprime singular_sdk-12.13.0.aar
Renombrar el archivo JAR: Renombra classes.jar como singular_sdk-12.13.0.jar (este es el jar principal del SDK)
Agregar el install referrer: Agrega la librería com.android.installreferrer:installreferrer:2.2 a tu proyecto
Copiar los permisos: Copia el permiso BIND_GET_INSTALL_REFERRER_SERVICE del AndroidManifest.xml contenido en el AAR a tu AndroidManifest.xml
Copiar el permiso de licencia: Copia el permiso CHECK_LICENSE del AndroidManifest.xml contenido en el AAR a tu AndroidManifest.xml

Configuración de ProGuard

Reglas de ProGuard

Agrega las siguientes reglas a tu 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 del AndroidManifest

Agrega 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" />

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

Consultas para Samsung Galaxy Store

Para admitir el install referrer de Samsung Galaxy Store, agrega lo siguiente a tu AndroidManifest.xml .

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

Integración del SDK

Cumplimiento de privacidad: Cumple con las leyes de privacidad vigentes en las regiones donde operas, incluyendo GDPR, CCPA y COPPA, al implementar los SDK de Singular. Consulta Prácticas de opt-in y opt-out del SDK para obtener orientación.

Importar el SDK de Singular

Agregar la sentencia de Import

Importa la librería de Singular en tu archivo MainActivity.

import com.singular.sdk.*

import com.singular.sdk.*;

Inicializar el SDK

Crear la función de inicialización

Para habilitar el tracking de sesiones y la atribución, inicializa el SDK de Singular cada vez que se inicie tu app creando un método privado y llamándolo desde el método onCreate() de tu MainActivity.

Sigue estos pasos:

Agregar la función: Coloca el método de inicialización dentro de tu clase MainActivity (o cualquier Activity de punto de entrada)
Insertar las credenciales: Reemplaza SDK KEY y SDK SECRET con la SDK key y el secret de Singular de tu dashboard
Actualizar SingularConfig: Antes de inicializar el SDK, crea un objeto SingularConfig y establece las preferencias del SDK (ver las opciones de configuración a continuación)
Llamar a la función: Invoca initSingularSDK() en onCreate() después de la configuración de la UI pero antes de registrar eventos

Implementación básica

Crea 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());
    }
}

Invocar desde onCreate de MainActivity

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)
}

Lineamientos de implementación

Sigue estos lineamientos clave al implementar la inicialización del SDK.

Ubicación: Agrega el método de inicialización en tu MainActivity, no en la clase Application, para asegurar el correcto tracking de sesiones
Manejo de errores: El bloque try-catch registra los errores de inicialización (por ejemplo, credenciales no válidas) sin que la app falle
Deep linking: Para manejar los deep links (URLs que abren tu app), consulta Cómo dar soporte a los deep links para la configuración extendida
META Install Referrer: Agrega config.withFacebookAppId("FacebookAppID") para habilitar Atribución de Meta Install Referrer

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

Pro Tip: Si tu app admite varios puntos de entrada (por ejemplo, deep links), asegúrate de que initSingularSDK() se llame en el onCreate() de cada Activity relevante para garantizar un comportamiento consistente.

Opciones de configuración

Métodos de SingularConfig

El objeto SingularConfig te permite personalizar el comportamiento del SDK usando métodos de configuración encadenables. Consulta la tabla a continuación para todas las opciones disponibles.

Método	Descripción
`.withFacebookAppId(String facebookAppID)`	Configura el Facebook App ID. Obligatorio para la atribución de Meta Install Referrer . Consulta ¿Dónde puedo encontrar el Facebook App ID de una app? A partir del 18 de junio de 2025 , el Advanced Mobile Measurement Reporting (AMM) de Meta elimina la necesidad de implementar Meta Install Referrer. No se recomienda implementar Meta Install Referrer si los reportes de AMM están habilitados.
`.withCustomUserId(String customId)`	Envía el ID del usuario a Singular
`.withSingularLink(Intent intent, SingularLinkHandler handler)` `.withSingularLink(Intent intent, SingularLinkHandler handler, long shortlinkTimeoutSec)`	Habilita el deep linking con Singular Links. La sobrecarga de un argumento usa por defecto un timeout de resolución de short link de 10 segundos; usa la sobrecarga de tres argumentos para sobrescribirlo. Esta llamada también maneja los deferred deep links, por lo que ya no es necesaria una configuración separada de `withDDLHandler` / `withDDLTimeoutInSec` .
`.withOpenURI(URI openURI)`	Obtiene el URI desde el intent (para procesar deep links si la app se abre a través de un enlace que no se origina en Singular)
`.withGlobalProperty(String key, String value, boolean overrideExisting)`	Establece una propiedad global con un valor determinado. La key y el value se enviarán a Singular junto con cualquier evento/sesión que se envíe desde la app
`.withSessionTimeoutInSec(long timeout)`	Establece el timeout de la sesión
`.withFCMDeviceToken(String token)`	Define el token de FCM que se enviará en la primera sesión
`.withLoggingEnabled()`	Habilita el logging
`.withLogLevel(int level)`	Configura el nivel de logging (por defecto es Log.ERROR)