Descargar SDK de Android versión 12.14.0

Video guía disponible

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

Requisitos previos

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

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

Instalación

Métodos de instalación

Nota: Android Studio ahora usa 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 administració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 declararlos 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 aplicación.

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

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

Resolución de problemas: clases duplicadas

Es posible que encuentres errores de clases duplicadas cuando múltiples dependencias incluyen la misma librería. Esto suele ocurrir 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 las dependencias en conflicto

Para resolver los problemas de clases duplicadas, excluye la dependencia transitiva en conflicto del SDK de Singular o de las demás dependencias que causen el conflicto.

dependencies {
    // Exclude specific Google Play Services modules from Singular SDK
    implementation("com.singular.sdk:singular_sdk:12.14.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.14.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 globales de exclusión

Si el conflicto de clases duplicadas afecta a varias dependencias en tu proyecto, puedes aplicar una regla global de exclusión.

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

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

./gradlew app:dependencies --configuration debugRuntimeClasspath

Este comando muestra el árbol completo de dependencias de tu aplicación, 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 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 has desactivado las dependencias transitivas para el SDK de Singular, agrega manualmente estas librerías obligatorias a las dependencias del módulo de tu aplicación.

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 aplicación 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.

Descarga el SDK: Descarga el SDK desde el enlace que aparece en la parte superior de esta página
Extrae y agrega a libs: Descomprime el paquete del SDK y agrega Singular.aar al directorio libs de tu proyecto de 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 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.14.0</version>
</dependency>

Método 4: instalación con Eclipse

Instalación con Eclipse

Integra el SDK usando Eclipse siguiendo estos pasos.

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

Si no quieres usar el plugin, sigue estos pasos:

Descomprime el AAR: Descomprime singular_sdk-12.14.0.aar
Renombra el archivo JAR: Renombra classes.jar a singular_sdk-12.14.0.jar (este es el jar principal del SDK)
Agrega el install referrer: Agrega la librería com.android.installreferrer:installreferrer:2.2 a tu proyecto
Copia los permisos: Copia el permiso BIND_GET_INSTALL_REFERRER_SERVICE desde el AndroidManifest.xml contenido en el AAR a tu AndroidManifest.xml
Copia el permiso de licencia: Copia el permiso CHECK_LICENSE desde el 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 dentro de la etiqueta <manifest> de 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 SDK para Kids .

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, incluidas 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 declaración de importación

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 seguimiento de sesiones y la atribución, inicializa el SDK de Singular cada vez que se inicie tu aplicación creando un método privado e invocándolo desde el método onCreate() de tu MainActivity.

Sigue estos pasos:

Agrega la función: Coloca el método de inicialización dentro de la clase MainActivity (o cualquier Activity que sea punto de entrada)
Inserta las credenciales: Reemplaza SDK KEY y SDK SECRET con la SDK key y el SDK secret de Singular de tu dashboard
Actualiza SingularConfig: Antes de inicializar el SDK, crea un objeto SingularConfig y define cualquier preferencia del SDK (consulta las opciones de configuración a continuación)
Llama a la función: Invoca initSingularSDK() en onCreate() después de configurar 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 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)
}

Pautas de implementación

Sigue estas pautas 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 garantizar un seguimiento de sesiones adecuado
Manejo de errores: El bloque try-catch registra los errores de inicialización (por ejemplo, credenciales no válidas) sin que la aplicación se bloquee
Deep linking: Para gestionar deep links (URL que abren tu aplicación), consulta Soporte para deep links para conocer la configuración ampliada
META Install Referrer: Agrega config.withFacebookAppId("FacebookAppID") para habilitar la atribución mediante 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 el reporte AMM está habilitado.

Consejo profesional: Si tu aplicación admite múltiples 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 mediante métodos de configuración encadenables. Consulta la tabla a continuación para conocer todas las opciones disponibles.

Método	Descripción
`.withFacebookAppId(String facebookAppID)`	Configura el Facebook App ID. Requerido para la atribución mediante Meta Install Referrer . Consulta ¿Dónde puedo encontrar el Facebook App ID de una aplicación? 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 el reporte AMM está habilitado.
`.withCustomUserId(String customId)`	Envía el ID de 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 tiempo de espera de 10 segundos para la resolución de enlaces cortos. Para anularlo, usa la sobrecarga de tres argumentos. Esta llamada también gestiona los deferred deep links, por lo que ya no se requiere una configuración separada de `withDDLHandler` / `withDDLTimeoutInSec` .
`.withOpenURI(URI openURI)`	Obtiene la URI a partir del intent (para procesar deep links si la aplicación se abre a través de un enlace que no proviene de Singular)
`.withGlobalProperty(String key, String value, boolean overrideExisting)`	Establece una propiedad global con un valor determinado. La clave y el valor se enviarán a Singular junto con cualquier evento/sesión que envíe la aplicación
`.withSessionTimeoutInSec(long timeout)`	Define el tiempo de espera de la sesión
`.withFCMDeviceToken(String token)`	Establece el token de FCM que se enviará en la primera sesión
`.withLoggingEnabled()`	Habilita el registro (logging)
`.withLogLevel(int level)`	Define el nivel de registro (el valor por defecto es Log.ERROR)