Nuevo Guía en vídeo
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 encontrará 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.
1. Añadir el SDK a su proyecto
1.1 Añadir el SDK usando Gradle
Nota: A partir de Gradle 7, Android sugiere utilizar declaraciones de repositorios centralizados en settings.gradle a nivel de proyecto o módulo build.gradle declaraciones.
-
Añada el repositorio Singular SDK al archivo settings.gradle:
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
maven { url '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ñade la librería Singular a la lista de dependencias en app/build.gradle:
dependencies { implementation 'com.google.android.gms:play-services:6.5.87' implementation fileTree(dir: 'libs', include: ['*.jar']) ... implementation 'com.singular.sdk:singular_sdk:12.6.0' ... }
Además, añada lo siguiente para admitir la referencia de instalación de Samsung Galaxy Store si su 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 ha desactivado las dependencias transitivas para el SDK de Singular, añada lo siguiente a su 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.
1.2. 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 en la carpeta libs del 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.0.2</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.6.0.aar.
- Renombra classes.jar a singular_sdk-12.6.0.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
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.** { *; }
# Descomenta esta línea en caso de que estés llamando a la función 'revenue' usando la librería de facturación de Google
#-keep public class com.android.billingclient.** { *; }
1.3. Añadir permisos requeridos
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" />
Nota: si tu aplicación está diseñada para Android 12/API nivel 31 o superior, añade permisos para acceder al ID de publicidad de Google:
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />
No añada este permiso si está integrando el SDK para niños.
Además, añade lo siguiente para admitir la referencia de instalación de Samsung Galaxy Store si tu aplicación se distribuye a través de Samsung Galaxy Store y está orientada a Android 11 o superior:
<queries>
<package android:name="com.sec.android.app.samsungapps" />
</queries>
2. Configuración de una integración básica del 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 SDK Opt-In y Opt-Out Practices.
2.1. 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.*
2.2. Construcción de un objeto de configuración
Antes de inicializar el SDK, debe crear un objeto SingularConfig. Este objeto contendrá lo siguiente
- SDK Keys y SDK Secrets (para obtenerlos, inicie sesión en su cuenta de Singular y vaya a "HERRAMIENTAS DEL DESARROLLADOR > Integración SDK > SDK Keys").
- Opcionalmente, las preferencias del SDK que desee establecer.
- META Install Atribución de referencias
Configuración SDK necesaria para activar la atribución "Meta Install Referrer":
- Proporcione su Id de aplicación de Facebook en el objeto de configuración singular.
// Para habilitar META Install Referrer config.withFacebookAppId("INSERTE AQUÍ EL ID DE SU APLICACIÓN DE FACEBOOK");
- Proporcione su Id de aplicación de Facebook en el objeto de configuración singular.
El siguiente ejemplo de código crea un objeto de configuración y establece las opciones de configuración comunes antes de inicializar Singular SDK.
En las secciones siguientes se ofrecen más detalles sobre estas opciones y sobre cómo personalizarlas.
@Override
protected void onCreate(Bundle savedInstanceState) {
...
// Crear un objeto de configuración
SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET");
// Configurar un gestor de enlaces profundos
config.withSingularLink(
getIntent(),
new SingularLinkHandler() {
@Override
public void onResolved(SingularLinkParams params) {
String deeplink = params.getDeeplink();
String passthrough = params.getPassthrough();
boolean isDeferred = params.isDeferred();
// Añada aquí el código de gestión de enlaces profundos
}
}
);
Singular.init(context, config);
...
}
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// Crear un objeto de configuración
val config = SingularConfig("SDK KEY", "SDK SECRET")
// Configurar un gestor de enlaces profundos
config.withSingularLink(
intent
) { params ->
val deeplink = params.deeplink
val passthrough = params.passthrough
val isDeferred = params.isDeferred
// Añada aquí el código de gestión de enlaces profundos
}
Singular.init(this, config)
...
}
La 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(String 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(String 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. |
.withDDLHandler (DeferredDeepLinkHandler handler) |
Habilita el enlace profundo con enlaces de seguimiento heredados (en lugar de los nuevos enlaces de Singular). |
.withOpenURI (URI openURI) |
Obtiene el URI de la intent (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 level) |
Configura el nivel de registro (por defecto es Log.ERROR). |
2.3. Añadir soporte para enlaces profundos
Los enlaces profundos son enlaces que llevan a contenidos específicos dentro de una aplicación. Cuando un usuario hace clic en un enlace profundo en un dispositivo con la aplicación instalada, la aplicación se abre y muestra un producto o experiencia específicos. Los enlaces de seguimiento singulares pueden incluir enlaces profundos, así como enlaces profundos diferidos(consulte nuestras Preguntas frecuentes sobre enlaces profundos y las Preguntas frecuentes sobre enlaces singulares para obtener más información).
Activación de enlaces profundos mediante enlaces singulares
Para habilitar enlaces profundos para su aplicación, consulte Requisitos previos de Singular Links.
Cómo añadir un filtro de intenciones de enlaces profundos
Añada un filtro de intención como el siguiente a su AndroidManifest.xml para habilitar el soporte de enlaces profundos en una actividad. Si tiene más de una actividad que debe abrirse a través de un enlace profundo, haga esto para cada actividad.
Nota: El Intent NO debe ser configurado con un valor 'android:host'. Si se debe utilizar un valor 'android:host': asegúrese de incluir el valor del host en la configuración de la página de Singular Apps para el esquema de la aplicación, y utilice el mismo valor 'scheme://host' para todos los enlaces profundos de Singular.
<activity>
<intent-filter>
<data android:scheme="singular-example" />
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
</intent-filter>
</activity>
Gestión de enlaces profundos
Singular SDK proporciona un mecanismo de control para leer los detalles del enlace de seguimiento que ha llevado a la apertura de la aplicación. Más arriba, en el código de ejemplo de Construcción de un objeto de configuración, se incluye un manejador de ejemplo.
Nota: el controlador SingularLinkHandler sólo se activa si la aplicación se abrió a través de un enlace singular (consulte las preguntas frecuentes sobre enlaces singulares). Otros tipos de enlaces de aplicaciones sólo se activarán si el dominio está incluido en supportedDomains al crear el objeto Singular Config. Consulte"Gestión de enlaces profundos no singulares" para obtener más información.
Modificación del tiempo de espera de los enlaces profundos diferidos
De forma predeterminada, cuando una aplicación envía la primera sesión a Singular desde un dispositivo determinado, el servidor de Singular busca en sus registros si existe un enlace profundo diferido que coincida con ese dispositivo (consulte ¿Qué son los enlaces profundos diferidos?). Si se encuentra un enlace profundo diferido, se devuelve a la aplicación para que lo procese. Pero si no se encuentra ningún enlace profundo diferido en 60 segundos, el servidor deja de buscar.
Puede modificar el valor del tiempo de espera llamando a withDDLTimeoutInSec al crear el objeto SingularConfig. El ejemplo siguiente cambia el tiempo de espera a 30 segundos:
SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET");
...
config.withDDLTimeoutInSec(30);
...
Singular.init(context, config);
Gestión de enlaces profundos no singulares
Singular SDK admite enlaces profundos no servidos por Singular. Esto es necesario para medir la atribución para socios como Google Ads.
A partir de la versión 12.1.1 del SDK para Android, los enlaces universales no servidos por Singular son compatibles por defecto. No es necesaria ninguna acción por su parte para admitir enlaces de terceros si dispone de la nueva versión del SDK.
Para admitir estos enlaces profundos, proporcione una lista de enlaces de aplicaciones Android admitidos en supportedDomains cuando cree su objeto SingularConfig:
SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET");
// supportedDomains
List<String> supportedDomains = Arrays.asList("subdomain.mywebsite.com", "subdomain.myotherwebsite.com");
config.withSingularLink(
getIntent(),
new SingularLinkHandler() {
@Override
public void onResolved(SingularLinkParams params) {
// manejar la devolución de llamada
}
},
supportedDomains
);
2.4. Inicialización de Singular
El SDK de Singular debe inicializarse cada vez que se abre la aplicación. Es un requisito previo para todas las funciones de atribución de Singular y también envía una nueva sesión de usuario a Singular (las sesiones se utilizan para calcular la retención de usuarios).
Para inicializar Singular, utilice el siguiente código:
Singular.init(context, config);
Parámetro | Descripción |
Context context | Desde la clase de aplicación, puede pasar esto o getApplicationContext () como contexto. Para obtener el contexto de la aplicación desde una actividad, llame a currentActivity.getApplicationContext(). |
SingularConfig config | El objeto SingularConfig creado en los pasos anteriores. |
El método init puede ser llamado en cualquier punto de la aplicación pero debe ser llamado antes de que cualquier evento sea reportado. Recomendamos llamar init en el onCreate de la actividad principal así como en cualquier actividad que vaya a ser abierta directamente por un deep link.
Nota: Debe inicializar Singular dentro de cualquier actividad que vaya a abrirse mediante un enlace profundo (consulte Implementación de enlaces profundos). Por lo tanto, no recomendamos inicializar Singular en el onCreate de la aplicación. Si Singular se inicializa en el nivel de la aplicación y luego de nuevo dentro de una actividad, provocará sesiones duplicadas en la base de datos de Singular.
2.5. Envío del ID de usuario a Singular (opcional)
Puede enviar su ID de usuario interno a Singular utilizando un método del SDK de Singular.
Nota: Si utiliza la solución multidispositivo de Singular, debe recopilar el ID de usuario en todas las plataformas.
- El ID de usuario puede ser cualquier identificador y no debe exponer PII (Personally Identifiable Information). Por ejemplo, no debe utilizar la dirección de correo electrónico, el nombre de usuario o el número de teléfono de un usuario. Singular recomienda utilizar un valor hash único sólo para sus datos de origen.
- El valor de ID de usuario que se pasa a Singular también debe ser el mismo ID de usuario interno que se captura en todas las plataformas (Web/Móvil/PC/Consola/Offline).
- Singular incluirá el ID de usuario en las exportaciones a nivel de usuario, ETL y devoluciones internas de BI (si está configurado). El ID de usuario es un dato de origen y Singular no lo comparte con terceros.
- El valor del ID de usuario, cuando se establece con el método Singular SDK, persistirá hasta que se desactive utilizando el método unsetCustomUserId o hasta que se desinstale la aplicación. Cerrar o reiniciar la aplicación no anula el ID de usuario.
Para establecer el ID de usuario, utilice el método setCustomUserId. Para desactivarlo (por ejemplo, si el usuario "cierra sesión" en la cuenta), llame a unsetCustomUserId.
Nota: Si varios usuarios utilizan un único dispositivo, recomendamos implementar un flujo de cierre de sesión para establecer y desestablecer el ID de usuario para cada inicio y cierre de sesión.
Si ya conoce el ID de usuario cuando se abre la aplicación, llame a setCustomUserId antes de inicializar Singular SDK. De esta forma, Singular puede tener el ID de usuario desde la primera sesión. Sin embargo, el ID de usuario no suele estar disponible hasta que el usuario se registra o realiza un inicio de sesión. En ese caso, llame a setCustomUserId una vez finalizado el flujo de registro.
Método Singular.setCustomUserID | |
---|---|
Descripción | Envía el ID de usuario a Singular. |
Firma | public void setCustomUserId(cadena customUserId) |
Ejemplo de uso |
|
Método Singular.unsetCustomUserID | |
Descripción | Anula la configuración del ID de usuario que se ha enviado a Singular. |
Firma | public void unsetCustomUserId() |
Ejemplo de uso |
|
Importante: Esta función Enterprise avanzada sólo está disponible en casos excepcionales. Por favor, consulte con uno de los Ingenieros de Soluciones de Singular antes de implementarla.
Singular puede recibir datos adicionales de seguimiento de eventos móviles a través de una integración de servidor a servidor. Para utilizar esta función, debe asignar el ID de usuario al identificador de seguimiento de dispositivos móviles de Singular.
Nota: Llame a este método tan pronto como sea posible después de inicializar el SDK de Singular o una vez que tenga el ID de usuario.
Método Singular.setDeviceCustomUserId | |
---|---|
Descripción | Establece el Id. de usuario personalizado igual que el inicio de sesión y lo asigna al identificador de seguimiento de Singular. |
Firma | public void setDeviceCustomUserId(string customUserId) |
Ejemplo de uso |
|
2.6. Implementación de propiedades globales (opcional)
Singular SDK permite definir propiedades personalizadas adicionales para enviarlas a los servidores de Singular con cada sesión y evento enviados desde la aplicación. Estas propiedades pueden representar cualquier información que desee sobre el usuario, el modo o el estado de la aplicación, o cualquier otra cosa. Una vez definidas estas propiedades, estarán disponibles como dimensiones en sus informes y podrá utilizarlas para desglosar sus datos.
Por ejemplo, si tienes una aplicación de juegos, puedes definir una propiedad llamada "Nivel" y establecerla inicialmente en "0". Cualquier sesión y evento enviado desde la app se enviará con "Nivel": "0". Una vez que el usuario sube de nivel, restableces la propiedad a "1" y así sucesivamente. A continuación, puede obtener sus informes, incluyendo sesiones, recuento de eventos y datos de ingresos, desglosados por nivel de usuario.
- Puedes definir hasta 5 propiedades globales.
- Persisten entre las ejecuciones de la aplicación (con el último valor que les hayas dado) hasta que las desestablezcas o el usuario desinstale la aplicación.
- El nombre y el valor de cada propiedad pueden tener un máximo de 200 caracteres. Si pasas un nombre o valor de propiedad más largo, se truncará a 200 caracteres.
- Las propiedades globales son accesibles y están disponibles en las exportaciones a nivel de usuario y en los postbacks. En el futuro, se añadirá soporte para informes agregados. Si tiene alguna pregunta o está interesado en las actualizaciones de las propiedades globales, póngase en contacto con su gestor de atención al cliente de Singular.
Configuración de propiedades globales a través de SingularConfig
Puede utilizar el método withGlobalProperty para establecer propiedades globales a través de SingularConfig antes de inicializar el SDK.
Tenga en cuenta que, dado que las propiedades globales y sus valores persisten entre ejecuciones de la aplicación, es posible que la propiedad que está estableciendo ya tenga un valor diferente. Utilice el parámetro overrideExisting para indicar al SDK si debe anular una propiedad existente con el nuevo valor o no.
Método withGlobalProperty | |
---|---|
Descripción | Establece una propiedad global. |
Firma | withGlobalProperty(String key, String value, boolean overrideExisting) |
Ejemplo de uso |
|
Establecimiento de propiedades globales tras la inicialización
Utilice los siguientes métodos para establecer, desestablecer y recuperar propiedades globales en cualquier momento de la ejecución de la aplicación.
Singular.setGlobalProperty Método | |
---|---|
Descripción |
Establece una propiedad global a un valor dado. Notas:
|
Firma | public static bool setGlobalProperty(String key, String value, boolean overrideExisting) |
Ejemplo de uso |
|
Método singular.getGlobalProperties | |
Descripción | Recupera todas las propiedades globales y sus valores actuales como un mapa. |
Firma | public static Map<String, String> getGlobalProperties() |
Ejemplo de uso |
|
Método Singular.unsetGlobalProperty | |
Descripción | Elimina una propiedad global. |
Firma | public static void unsetGlobalProperty(String key) |
Ejemplo de uso |
|
Método singular.clearGlobalProperties | |
Descripción | Elimina todas las propiedades globales. |
Firma | public static void clearGlobalProperties() |
Ejemplo de uso |
|
3. Seguimiento de eventos e ingresos
3.1. Seguimiento de eventos (no ingresos)
Singular puede recopilar datos sobre eventos dentro de la aplicación para ayudar a analizar el rendimiento de sus campañas y medir los KPI.Por ejemplo, es posible que su organización desee recopilar datos sobre inicios de sesión de usuarios, registros, finalización de tutoriales o subidas de nivel en una aplicación de juegos.
¿Qué son los eventos y atributos estándar?
Singular soporta una variedad de eventos estándar.Las redes publicitarias suelen admitir estos eventos de uso común para la generación de informes y la optimización. Otra ventaja es que cuando se utilizan nombres de eventos estándar, Singular los reconoce automáticamente y los añade a la lista de eventos sin que tenga que definirlos manualmente. Recomendamos utilizar eventos estándar siempre que sea posible.
La lista de eventos enviados a Singular (con los atributos que los acompañan) debe ser compilada por el equipo de UA/marketing/negocio basándose en los KPI de marketing de su organización. El equipo comercial puede seguir la guía Cómo realizar el seguimiento de los eventos In-App: Guía para clientes de Singular Attribution.
Con cada evento que rastree, puede pasar varios atributos. Consulte los atributos estándar recomendados por evento.
Envío de eventos
En su código, envíe eventos a Singular utilizando los métodos eventJSON o event (recomendamos eventJSON para facilitar la lectura).
- Para los eventos estándar, utilice el nombre Android del evento tal y como aparece en la lista de eventos y atributos estándar del SDK de Android, por ejemplo, sngTutorialComplete. Consulte los siguientes ejemplos de código.
- Si envía eventos personalizados (eventos que su organización desea medir y que no coinciden con ninguno de los eventos estándar de Singular), utilice cualquier cadena que desee y que cumpla con las limitaciones.
Método Singular.eventJSON | |
---|---|
Descripción | Envía un evento de usuario a Singular con información adicional en formato JSONObject. |
Firma |
Singular.eventJSON(String name, JSONObject args)
Nota: 'args' es un JSONObject que contiene uno o varios pares clave-valor. La clave es una cadena y el valor puede ser cualquier tipo permitido como valor JSONObject.
|
Ejemplo de uso |
|
Método Singular.event | |
Descripción | Notifica un evento de usuario a Singular con o sin información adicional. |
Firma |
Singular.event(String eventName) Nota: 'args' es uno o varios pares clave-valor (véase el ejemplo siguiente). La clave es una cadena y el valor puede ser cualquier tipo permitido como valor JSONObject (es decir, JSONObject, JSONArray, String, Boolean, Integer, Long, Double o NULL). La lista 'args' debe contener un número par de elementos o el evento será rechazado por Singular. |
Ejemplo de uso |
|
Notas:
- Recomendamos encarecidamente pasar los nombres y atributos de los eventos en inglés para garantizar la compatibilidad con socios y soluciones de análisis de terceros si tiene previsto utilizarlos.
- Los nombres de eventos están limitados a 32 caracteres ASCII. Las cadenas en caracteres no ASCII deben tener menos de 32 bytes una vez convertidas a UTF-8.
- Los atributos y valores están limitados a 500 caracteres ASCII.
3.2. Seguimiento de ingresos
Singular puede recopilar datos sobre los ingresos obtenidos a través de la aplicación para ayudar a analizar el rendimiento y el ROI de sus campañas.Singular pondrá los datos a su disposición en informes, exportación de registros y postbacks.
Seguimiento de ingresos mediante el objeto de compra
Al informar de eventos de ingresos a Singular, recomendamos pasar el objeto de compra recibido de la biblioteca de facturación. Esto tiene dos ventajas:
- Singular obtiene todos los detalles de la transacción, lo que enriquece sus informes de Singular.
- Singular obtiene el recibo de la transacción de Google, que se puede utilizar para validar la transacción en el contexto de la lucha contra el fraude in-app.
RECORDATORIO:
- A partir del 2 de agosto de 2023, todas las aplicaciones nuevas deberán utilizar la versión 5 o posterior de Billing Library. A partir del 1 de noviembre de 2023, todas las actualizaciones de las aplicaciones existentes deberán utilizar la versión 5 o posterior de Billing Library. Más información.
- Si su aplicación está orientada a Android 14 o superior, debe actualizar a PBL 5.2.1 o PBL 6.0.1 o superior.
Utiliza los métodos revenue y customRevenue para reportar eventos. CustomRevenue te permite pasar un nombre de evento personalizado para que puedas ver los ingresos en los informes de Singular desglosados por los distintos tipos de eventos de ingresos.
Nota: cualquier ingreso notificado en una divisa diferente se convertirá automáticamente a la divisa preferida de su organización, según lo establecido en su cuenta de Singular.
Singular.revenue Método | |
---|---|
Descripción | Envía un evento de ingresos a Singular con información adicional opcional. |
Firma |
Singular.revenue(String currency, double amount, Object purchase) Nota:
|
Ejemplo de uso |
|
Singular.customRevenue Método | |
Descripción | Envía un evento de ingresos a Singular con un nombre de evento e información adicional opcional. |
Firma |
Singular.customRevenue(String eventName, String currency, double amount, Object purchase) Nota:
|
Ejemplo de uso |
|
Notificación de ingresos sin el objeto de compra
Aunque recomendamos encarecidamente informar de los eventos de ingresos de la forma descrita anteriormente, también puede utilizar ingresos y customRevenue sin pasar el objeto de compra. En su lugar, puede pasar la divisa y el importe de la transacción, así como detalles opcionales del producto.
Tenga en cuenta que al informar de eventos de ingresos de esta forma, Singular no obtiene el recibo de compra y no puede validar la transacción.
Método Singular.revenue (sinobjeto de compra) | |
---|---|
Descripción |
Envía un evento de ingresos a Singular con información adicional opcional. |
Firma |
Singular.revenue(String currency, double amount, String productSKU, String productName, String productCategory, int productQuantity, double productPrice) Singular.revenue(String currency, double amount) Nota: pase la divisa como un código de divisa ISO 4217 de tres letras, como "USD", "EUR" o "INR". |
Ejemplo de uso |
|
Método Singular.customRevenue (sin objeto de compra) | |
Descripción | Envía un evento de ingresos a Singular con un nombre de evento e información adicional opcional. |
Firma |
Singular.customRevenue(String eventName, String currency, double amount, String productSKU, String productName, String productCategory, int productQuantity, double productPrice) Nota: pase la divisa como un código de divisa ISO 4217 de tres letras, como "USD", "EUR" o "INR". |
Ejemplo de uso |
|
3.3. Seguimiento de Eventos Híbrido (Avanzado)
Singular recomienda enviar todos los eventos e ingresos a través del SDK de Singular integrado en su app. Sin embargo, Singular puede recoger eventos e ingresos de otras fuentes.
Cualquier evento NO enviado desde el SDK de Singular debe cumplir con los requisitos de documentación de eventos de servidor a servidor de Singular y proporcionar el identificador de dispositivo correspondiente para atribuir correctamente un evento.
Importante:
Se producirán discrepancias si los identificadores de dispositivo utilizados en las solicitudes de eventos de servidor a servidor no tienen un identificador de dispositivo coincidente en Singular. Tenga en cuenta las siguientes posibilidades:
- Si se recibe una solicitud de evento "antes" de que Singular SDK haya registrado el identificador de dispositivo, desde una App Session, entonces la solicitud de evento se considerará la "primera sesión" para el dispositivo desconocido, y Singular atribuirá el dispositivo como una atribución orgánica.
- Si Singular SDK registró un identificador de dispositivo, pero el identificador de Singular SDK difiere del identificador de dispositivo especificado en la solicitud de evento de servidor a servidor, entonces el evento se atribuirá incorrectamente.
Guías de seguimiento de eventos híbridos
Singular puede recopilar datos sobre los ingresos de su Servidor para ayudar a analizar el rendimiento y el ROI de sus campañas.
Requisitos:
- Desde un Evento de Registro o Inicio de Sesión in-app, capture y pase los identificadores de dispositivo y almacene estos datos con el ID de Usuario en su servidor. Dado que los identificadores de dispositivo pueden cambiar para un usuario, asegúrese de actualizar los identificadores cuando un usuario genere una sesión de aplicación. Esto garantiza que el evento del lado del servidor se atribuya al dispositivo correcto.
- Los eventos del lado del servidor son específicos de cada plataforma y sólo deben enviarse con el identificador de dispositivo que coincida con la plataforma del dispositivo (por ejemplo, IDFA o IDFV para dispositivos iOS).
- Puede utilizar el mecanismo de postback de Singular Internal BI para enviar un evento en tiempo real a su endpoint interno para que pueda actualizar el conjunto de datos en el lado del servidor. Consulte las Preguntas Frecuentes sobre Postback de BI Interno.
- Revise la sección "Seguimiento de Ingresos" en la guía de Integración Servidor-a-Servidor para más detalles.
Siga los siguientes enlaces para obtener más información sobre cómo habilitar a estos socios.
4. Opciones avanzadas
4.1. Creación de enlaces de referencia cortos
Nota: Esta funcionalidad está disponible en la versión 12.1.1+ del SDK. Una vez creados, los enlaces cortos permanecen activos durante 30 días.
Utilice los enlaces cortos para transformar enlaces singulares largos y llenos de parámetros en enlaces más cortos y seguros que sean convenientes para compartir.
Normalmente, querrá crear enlaces cortos de forma dinámica para que los usuarios de su aplicación puedan compartirlos con sus amigos para invitarles a utilizar la aplicación.
Para crear un enlace corto, necesitas
- Un Enlace Singular que lleve a la descarga de tu app (consulta las Preguntas Frecuentes sobre Enlaces Singulares).
- Cualquier parámetro que desee añadir al enlace de forma dinámica (consulte Parámetros del enlace de seguimiento para ver la lista de opciones).
- El nombre y el ID del usuario remitente, si desea realizar un seguimiento de las nuevas instalaciones de la aplicación hasta el usuario que compartió el enlace.
Utilice el método createReferrerShortLink para crear un enlace corto como en el ejemplo siguiente.
// Crear un objeto JSON para añadir parámetros al Singular Link (si aún no existen en la URL del enlace).
JSONObject params = new JSONObject();
try {
params.put("channel","sms");
params.put("another parameter","parameter value");
} catch (JSONException e) {
e.printStackTrace();
}
Singular.createReferrerShortLink (
"https://sample.sng.link/D52wc/cuvk?pcn=test", // URL original de Singular Link
"Referrer Name",
"Referrer ID",
params,
new ShortLinkHandler() {
@Override
public void onSuccess(final String shortLinkURL) {
view.post(new Runnable() {
@Override
public void run() {
// Añada aquí su lógica de participación
}
});
}
@Override
public void onError(final String error) {
view.post(new Runnable() {
@Override
public void run() {
// Lógica para reintentar/abortar/modificar los parámetros pasados a la función, basándose en la causa del error.
}
});
}
});
// Crear un objeto JSON para añadir parámetros al Singular Link (si aún no existen en la URL del enlace).
val params = JSONObject()
try {
params.put("channel", "sms")
params.put("another parameter", "parameter value")
} catch (e: JSONException) {
e.printStackTrace()
}
Singular.createReferrerShortLink(
"https://sample.sng.link/D52wc/cuvk?pcn=test", // URL original de Singular Link
"Referrer Name",
"Referrer ID",
params,
object : ShortLinkHandler {
override fun onSuccess(shortLinkURL: String) {
view.post(Runnable {
// Añada aquí su lógica de participación
})
}
override fun onError(error: String) {
view.post(Runnable {
// Lógica para reintentar/abortar/modificar los parámetros pasados a la función, basándose en la causa del error.
})
}
})
4.2. Añadir soporte de atribución de ingresos publicitarios
Singular está integrado con plataformas de mediación como Google AdMob, AppLovin, Unity LevelPlay (IronSource) y TradPlus para la atribución de ingresos publicitarios. Singular también es compatible con otras plataformas de mediación a través de nuestra integración genérica de SDK de ingresos publicitarios.
Puede obtener datos de atribución de ingresos publicitarios de su plataforma de mediación añadiendo un fragmento de código a su integración Singular SDK. Esto también le permite obtener datos de ingresos publicitarios para las campañas de SKAdNetwork.
Obtener ingresos publicitarios a nivel de usuario de su plataforma de mediación permite a Singular enviar ingresos publicitarios atribuidos a fuentes de medios que pueden aceptar estos datos para ejecutar campañas AdROAS.
Ver instrucciones y fragmentos de código para la implementación del SDK [AQUÍ].
4.3. Seguimiento de desinstalación
Para habilitar el seguimiento de desinstalación para su aplicación Android, primero configure la aplicación en la plataforma Singular como se detalla en Configuración del seguimiento de desinstalación. A continuación, siga las instrucciones que se indican a continuación.
Nota: Google dejó obsoletas las API de GCM en abril de 2018. Utiliza Firebase Cloud Messaging (FCM) para el seguimiento de desinstalaciones, como se describe a continuación.
I. Integrarse con FCM:
Para realizar un seguimiento de las desinstalaciones, puedes utilizar los servicios de la plataforma Firebase Cloud Messaging (FCM). Si aún no está utilizando FCM siga las instrucciones de Google sobre cómo configurar una aplicación cliente de Firebase Cloud Messaging en Android.
Requisitos de FCM ( fuente )
Los clientes FCM requieren dispositivos con Android 4.1 o superior que también tengan instalada la aplicación Google Play Store, o un emulador que ejecute Android 4.1 con las API de Google. Ten en cuenta que no estás limitado a desplegar tus aplicaciones Android a través de Google Play Store.
Los usuarios/dispositivos que no se ejecuten en versiones compatibles de Android no estarán disponibles para el seguimiento de desinstalación de Singular.
II. Actualice el archivo AndroidManifest.xml:
Actualice su archivo AndroidManifest.xml para añadir el filtro de intención necesario para su aplicación (sustituya MyFirebaseMessagingService por su clase que implemente el servicio Firebase):
<service android:name=".java.MyFirebaseMessagingService"
android:exported="false">
<intent-filter>
action android:name="com.google.firebase.MESSAGING_EVENT" />
</intent-filter>
</service>
III. Registrar y enviar el token de dispositivo FCM:
Por último, establezca el token de dispositivo FCM después de inicializar su SingularConfig en OnCreate(), como se indica a continuación:
Singular.setFCMDeviceToken(String fcmDeviceToken);
4.4. Recopilación de la referencia de instalación en dispositivos antiguos
Nota: Google está dejando obsoleta la difusión de intent install_referrer. Consulte: ¿Sigue utilizando InstallBroadcast? Cambie a la Play Referrer API antes del 1 de marzo de 2020
El referrer de instalación es la herramienta más precisa de Singular para determinar la atribución, además de ayudar a Singular a detectar y analizar los intentos de fraude. Es un identificador proporcionado por Google Play Store que apunta al anuncio en el que el usuario hizo clic antes de instalar la aplicación.
En los dispositivos que tienen la última versión de Google Play Store, el SDK de Singular recopila el valor de referencia de instalación automáticamente (ya que Singular está integrado con la última API de referencia de Google Play).
Para recopilar el referente de instalación en dispositivos más antiguos:
Si tienes un receptor de referencia de instalación existente:
Lo más probable es que tu aplicación ya tenga un BroadcastReceiver que reciba el INSTALL_REFERRER de Android.
Si es así, sólo tiene que ir al método onReceive del BroadcastReceiver y añadir la siguiente línea:
new SingularInstallReceiver().onReceive(context, intent);
Por ejemplo, si su receptor existente se llama MyCustomInstallReceiver, debería tener el siguiente aspecto:
public class MyCustomInstallReceiver extends BroadcastReceiver {
@Override
public void onReceive(Context context, Intent intent) {
// Pass install referrer information on to Singular
new SingularInstallReceiver().onReceive(context, intent);
// ...
}
}
Si no hay ningún otro receptor de referencia de instalación:
Si no tiene ningún receptor de referencia de instalación en su aplicación, puede dejar que Singular SDK registre el único receptor simplemente añadiendo lo siguiente a su etiqueta <application> en su archivo de manifiesto:
<receiver android:exported="true" android:name="com.singular.sdk.SingularInstallReceiver">
<intent-filter>
<action android:name="com.android.vending.INSTALL_REFERRER" />
</intent-filter>
</receiver>
4.5. Gestión de sesiones
A partir de Android API 14 (Ice Cream Sandwich), Singular SDK puede gestionar automáticamente las sesiones. Si la minSdkVersion de su aplicación es 14 o superior, no se requiere ninguna configuración adicional para la gestión de sesiones.
Modificación del tiempo de espera de la sesión
Por defecto, si la aplicación se ejecuta en segundo plano durante 60 segundos o más antes de volver al primer plano, el SDK registra una nueva sesión.
Para cambiar el valor del tiempo de espera, utilice withSessionTimeoutInSec(<tiempo de espera en segundos>)en SingularConfig antes de inicializar el SDK.
Por ejemplo
// Fijar el tiempo de espera de la sesión en 120 segundos
SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET")
.withSessionTimeoutInSec(120);
Gestión manual de sesiones
Si el minSdkVersion de su aplicación es inferior a 14, deberá gestionar las sesiones manualmente llamando a los dos métodos de gestión de sesiones del SDK de Singular, onActivityPaused y onActivityResumed, desde cada una de sus actividades.
Nota: Si tiene una clase de actividad base común personalizada de la que derivan todas las demás actividades, puede colocar estas llamadas a onActivityResumed y onActivityPaused en los "métodos onResume y onPause" de la actividad común.
Método Singular.onActivityResumed | |
---|---|
Descripción | Llame a este método dentro del método onResume de la actividad para gestionar la sesión de Singular. |
Firma | public static void onActivityResumed() |
Ejemplo de uso |
|
Método Singular.onActivityPaused | |
Descripción | Llame a este método dentro del método onPause de la actividad para gestionar la sesión de Singular. |
Firma | public static void onActivityPaused() |
Ejemplo de uso |
|
4.6. Uso de la interfaz JavaScript
Singular proporciona una interfaz JavaScript que puede utilizar para llamar a Singular desde el código JavaScript de su aplicación.
Por ejemplo, si configura la interfaz JavaScript, puede enviar eventos a Singular desde código JavaScript de la siguiente manera:
Ejemplo de evento
SingularInterface.event('event');
SingularInterface.event('test',
JSON.stringify({"a1":"bar", "a2":"boo", "a3":"baz"}));
La interfaz admite los siguientes métodos SDK:
- setCustomUserID
- unsetCustomUserID
- event
- revenue
Para habilitar la interfaz JavaScript, añada las siguientes líneas de código a su actividad principal, donde "myWebView" es el nombre de su webview.
SingularJSInterface singularJSInterfaceInstance = new SingularJSInterface(this);
singularJSInterfaceInstance.setWebViewId(R.id.webview);
myWebView.addjavascriptInterface(singularJSInterfaceInstance, "SingularInterface");
Notas:
- Si tiene más de un webview, haga esto para cada uno.
- Recomendamos colocar el código en el método onCreate de su aplicación.
Su método onCreate puede tener este aspecto:
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
WebView myWebView = (WebView) this.findViewById(R.id.webview);
WebSettings webSettings = myWebView.getSettings();
webSettings.setjavaScriptEnabled(true);
myWebView.loadUrl("file:///android_asset/index.html");
SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET");
Singular.init(this, config);
SingularJSInterface singularJSInterfaceInstance =
new SingularJSInterface(this);
singularJSInterfaceInstance.setWebViewId(R.id.webview);
myWebView.addjavascriptInterface(singularJSInterfaceInstance,
"SingularInterface");
}
4.7. Recopilación del OAID (Open Advertising ID)
En los países que no utilizan Google Play, los dispositivos Android no disponen de un ID de publicidad de Google (GAID, también llamado AIFA en Singular). En su lugar, los dispositivos pueden ofrecer un identificador llamado OAID (Open Advertising Identifier) que puede utilizarse para rastrear sesiones y eventos procedentes del dispositivo.
OAID se ofrece actualmente en dispositivos de Huawei y de marcas que pertenecen a la Mobile Security Alliance (MSA).
Para que tu app pueda recoger el OAID, primero tienes que integrar el SDK de la MSA y el SDK de OAID de Huawei. Necesitas integrar ambos SDKs para poder recoger el OAID en todas las plataformas que lo ofrecen.
A continuación, para indicar al SDK Singular que utilice OAID para el seguimiento, añada una llamada a withOAIDCollection en el objeto config antes de inicializar Singular.
SingularConfig config = new SingularConfig("SDK KEY","SDK SECRET")
.withOAIDCollection();
Singular.init(context, config);
El SDK de Singular detectará automáticamente si el dispositivo tiene un OAID, así como qué SDK de OAID debe utilizarse para recopilar el identificador.
4.8. Recopilación del número IMEI
Si tu aplicación se ofrece en países que no utilizan Google Play, los dispositivos no tienen un identificador de publicidad de Google. En este caso, es posible que desee recopilar el IMEI (International Mobile Equipment Identity) del dispositivo en su lugar.
Nota: si utilizas los servicios de Google Play, no debes recopilar el número IMEI porque supone una infracción del acuerdo de servicio de Google Play.
Para recopilar el número IMEI
Añade el permiso android.permission.READ_PHONE_STATE al archivo AndroidManifest.xml de la aplicación:
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
Añade código como el siguiente para obtener el número IMEI del dispositivo:
TelephonyManager telephonyManager = (TelephonyManager)getSystemService(Context.TELEPHONY_SERVICE);
String imei = null;
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
imei = telephonyManager.getImei();
} else {
imei = telephonyManager.getDeviceId();
}
Para enviar el número IMEI a Singular, utiliza uno de los siguientes métodos:
Recomendado: Establezca el número IMEI en SingularConfig utilizando withIMEI antes de inicializar Singular SDK, como en el siguiente ejemplo. De este modo, Singular dispondrá del número IMEI desde la primera sesión.
SingularConfig config = new SingularConfig("SDK KEY","SDK SECRET")
.withIMEI("537769845792516");
Singular.init(context, config);
Para establecer el número IMEI en cualquier punto del código después de la inicialización del SDK, llame a setIMEI.
Singular.setIMEI Método | |
---|---|
Descripción | Envía el número IMEI del dispositivo a Singular. |
Firma | public void setIMEI(string IMEIString) |
Ejemplo de uso |
|
4.9. Cumplimiento de las leyes de privacidad de datos
Singular proporciona una funcionalidad de protección de la privacidad para ayudarle a cooperar con cualquier socio que pueda estar cumpliendo con las leyes de privacidad del consumidor, como GDPR y CCPA(California Consumer Privacy Act). Estos socios quieren ser notificados si el usuario final ha dado su consentimiento para compartir su información privada.
Si ha implementado una forma de solicitar a los usuarios su consentimiento para compartir su información, utilice el método limitDataSharing para notificar a Singular la elección del usuario:
Utilice Singular .limitDataSharing(false) para indicar que el usuario ha consentido (optado) en compartir su información.
Utilice Singular.limitDataSharing( true) si el usuario no dio su consentimiento.
Singular utiliza LimitDataSharing en los"Postbacks de privacidad del usuario", así como en la transmisión de esta información a los socios que la requieren para cumplir con la normativa pertinente. Consulte "Privacidad del usuario y Limitar el uso compartido de datos" para obtener más información.
Nota: El uso del método es opcional, pero puede haber información de atribución que el socio compartirá con Singular sólo si se notifica específicamente que el usuario ha optado por ello.
Método Singular.limitDataSharing | |
---|---|
Firma | Singular.limitDataSharing(booleanshouldLimitDataSharing) |
Descripción | Notificar a Singular el consentimiento del usuario (opt-in) para compartir datos privados. El método Limitar el uso compartido de datos te ofrece una opción para controlar si tu app envía datos del usuario a terceros. Esto resulta útil si quieres restringir el uso compartido de datos en función de las preferencias del usuario o los requisitos de privacidad. |
Ejemplo de uso |
|
Métodos adicionales para el cumplimiento de GDPR
El SDK de Singular proporciona varios métodos para ayudarle a cumplir con las políticas GDPR y comunicar a Singular el consentimiento o no consentimiento del usuario para el seguimiento.
Método Singular.trackingOptIn | |
---|---|
Descripción | Notificar a Singular el consentimiento del usuario (opt-in) para el seguimiento. El método TrackingOptIn() se utiliza para enviar un evento «gdpr» a los servidores de Singular. Si no llama a este método, la aplicación continuará rastreando a los usuarios como si hubieran dado su consentimiento, pero no los marcará específicamente como GDPR opt-in. Si su aplicación necesita cumplir con el GDPR (Reglamento General de Protección de Datos), debe llamar a esta función para asegurarse de que el consentimiento del usuario se registra correctamente. |
Ejemplo de uso |
|
Método Singular .stopAllTracking | |
Descripción |
Detiene todas las actividades de seguimiento de este usuario en esta aplicación.
Nota: Al llamar a este método se desactiva el SDK, incluso después de reiniciar la aplicación (el estado es persistente). La única forma de volver a activar el seguimiento es llamando a resumeAllTracking().
|
Ejemplo de uso |
|
Singular.resumeAllTracking Método | |
Descripción | Reanuda el seguimiento para este usuario en esta aplicación. |
Ejemplo deuso |
|
Singular .isAllTrackingStoppedMétodo | |
Descripción | Comprueba el estado del seguimiento de este usuario en esta aplicación. Devuelve true si el seguimiento se ha detenido mediante StopAllTracking() y no se ha reanudado. |
Ejemplo deuso |
|