Vea este vídeo para obtener una visión detallada del proceso de integración. Le recomendamos que utilice tanto el vídeo como la guía escrita que figura a continuación.
Antes de empezar: Requisitos previos del SDK
Siga los pasos indicados en Integración de un SDK Singular:Planificación y requisitos previos.
Estos pasos son requisitos previos para cualquier integración de Singular SDK.
Instale el SDK
Añadir el SDK utilizando Gradle
Nota: A partir de Gradle 7, Android sugiere utilizar declaraciones de repositorio centralizadas en settings.gradle en lugar de declaracionesbuild.gradle a nivel de proyecto o módulo .
-
Añada el repositorio Singular SDK al archivo settings.grad le:
dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() maven{ url = uri("https://maven.singular.net/") } } }
O, en versiones anteriores de Gradle, añade el repositorio de Singular SDK al archivo project/build.gradle:
repositories { mavenCentral() maven { url 'https://maven.singular.net/' } }
-
Añada la biblioteca Singular a la lista de dependencias en app/build.gradle:
dependencies { ... implementation 'com.google.android.gms:play-services:6.5.87' implementation 'com.singular.sdk:singular_sdk:12.7.1' ... }
Además, añade lo siguiente para admitir el referente 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' ... }
-
Si has desactivado las dependencias transitivas para Singular SDK, añade lo siguiente a tu app/build.gradle:
dependencies { ... implementation 'com.android.installreferrer:installreferrer:2.2' implementation 'com.google.android.gms:play-services-appset:16.0.0' ... }
-
Si tu app no implementa Google Play Services API 17.0.0 o superior, añade la siguiente dependencia al archivo app/build. gradle:
dependencies { ... implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0+' ... }
Nota: los usuarios de Gradle 1.x-2.x deben utilizar "compile" en lugar de "implementation" para añadir dependencias.
Añadir el SDK sin Gradle
- Descargue el SDK desde el enlace en la parte superior de la página.
- Descomprime el paquete SDK y añade Singular.aar al directorio libs de tu proyecto Android. Si no existe, crea un directorio llamado libs en la carpeta de tu proyecto (normalmente en <project>/app/libs).
Añade nuestro repositorio maven al pom.xml de 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.7.1</version>
</dependency>
Puedes usar el plugin Eclipse AAR: gradle-eclipse-aar-plugin
Si no desea utilizar el plugin, siga estos pasos:
- Descomprime singular_sdk-12.7.1.aar.
- Renombra classes.jar a singular_sdk-12.7.1.jar (este es el jar principal del SDK).
- Añade la librería 'com.android.installreferrer:installreferrer:2.2' a tu proyecto de la forma que prefieras.
- Copia el permiso BIND_GET_INSTALL_REFERRER_SERVICE del AndroidManifest.xml contenido en el AAR a tu AndroidManifest.xml
- copia los permisos CHECK_LICENSE del AndroidManifest.xml contenido en el AAR a tu AndroidManifest.xml
Requisitos si utiliza Proguard
Añada las siguientes líneas de código a su archivo proguard.config:
-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.** { *; }
Añadir permisos requeridos
Añada estos permisos bajo la etiqueta <manifest> en su 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" />
Para admitir el referente de instalación de Samsung Galaxy Store, añada lo siguiente:
<queries>
<package android:name="com.sec.android.app.samsungapps" />
</queries>
Integrar el SDK
Nota: Recuerde que debe cumplir las distintas leyes de privacidad promulgadas en las regiones en las que opera, incluidas GDPR, CCPA y COPPA, cuando implemente los SDK de Singular. Para obtener más información, consulte Prácticas de inclusión y exclusión de SDK.
Importación de la biblioteca de Singular
Para importar la biblioteca Singular, añada la siguiente importación a su archivo MainActivity:
import com.singular.sdk.*;
import com.singular.sdk.*
Inicialización del SDK de Singular
Inicialización de Singular SDK con una función privada
Para permitir el seguimiento y la atribución de sesiones, el SDK de Singular debe inicializarse cada vez que se inicie la aplicación. Se recomienda crear un método privado, initSingularSDK(), y llamarlo desde el método onCreate() de MainActivity.
Siga estos pasos:
- Añada la función: Coloque el siguiente método dentro de su clase MainActivity (o cualquier punto de entrada Activity).
- Inserte las credenciales: Sustituya "SDK KEY" y "SDK SECRET" por la clave y el secreto de Singular SDK de su panel de control de Singular.
-
Actualice el objeto SingularConfig: Antes de inicializar el SDK, debe crear un objeto SingularConfig. Opcionalmente, cualquier preferencia del SDK que desee establecer debe establecerse aquí. Utilice la referencia del método SingularConfig que aparece a continuación para ver las opciones:
Referencia del método SingularConfig: Ver todas las opciones ".with" disponiblesLa siguiente tabla enumera todos los métodos ".with" disponibles para el objeto SingularConfig para añadir opciones y funciones a su aplicación.
Encontrará información detallada sobre cada función en las secciones siguientes o en Opciones avanzadas.
Método
Descripción
.withFacebookAppId(Cadena facebookAppID)
Configura el ID de la aplicación de Facebook. Necesario para la atribución "Meta Install Referrer".
Consulta"¿Dónde puedo encontrar el Facebook App ID de una aplicación?".
.withCustomUserId(cadena customId)
Envía el ID de usuario a Singular.
.withSingularLink(getIntent(), SingularLinkHandler handler)
Habilita el enlace profundo con Singular Links.
.withDDLTimeoutInSec (long timeout)
Establece el tiempo que Singular busca un enlace profundo diferido cuando se abre la aplicación por primera vez.
.withOpenURI (URI openURI)
Obtiene el URI de la intención (para procesar los enlaces profundos si la aplicación se abre a través de un enlace que no procede de Singular).
.withGlobalProperty(String key, String value, boolean overrideExisting)
Establece una propiedad global a un valor dado. 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 ()
Habilita el registro.
.withLogLevel (int nivel)
Configura el nivel de registro (por defecto es Log.ERROR).
- Llamar a la función: Invoca initSingularSDK() en onCreate() después de configurar la interfaz de usuario pero antes de registrar los eventos.
Esta es la implementación básica:
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());
}
}
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}")
}
}
Ejemplo de uso en MainActivity
@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)
}
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
// Initialize Singular SDK
initSingularSDK()
}
Detalles de la clave
- Colocación: Añada este método 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 (por ejemplo, credenciales no válidas) sin bloquear la aplicación.
- Enlaces profundos (opcional): Para manejar enlaces profundos (por ejemplo, URLs que lanzan tu aplicación), consulta nuestro artículo Supporting Deep Links para la configuración extendida.
- Soporte de META Install Referrer Attribution: Añada la opción de configuración config.withFacebookAppId("FacebookAppID") para activar la atribución "Meta Install Referrer".
Consejo profesional: Si su aplicación admite varios puntos de entrada (por ejemplo, enlaces profundos), asegúrese de que initSingularSDK() se llama en cada actividadrelevante de onCreate() para garantizar un comportamiento coherente.