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

1. 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/' }
       }

2. 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'
         ...
       }

3. 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'
       ...
   }

4. 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+'
        ...
   }

1.2. Añadir el SDK sin Gradle

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

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

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

<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

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

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

1. 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").
2. Opcionalmente, las preferencias del SDK que desee establecer.
3. META Install Atribución de referencias

   Configuración SDK necesaria para activar la atribución "Meta Install Referrer":

   1. 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");

   Dónde puedo encontrar el Facebook App ID de una aplicación?

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)

    ...
}

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.

<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.

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.

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

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.

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.

• 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.

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.

Singular.setCustomUserId("custom_user_id");

Singular.unsetCustomUserId();

Singular.setDeviceCustomUserId("custom_user_id");

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.

// Establezca dos propiedades globales y anule los valores existentes
SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET")
  .withGlobalProperty(“MyProperty”, “MyValue”, true)
  .withGlobalProperty(“AnotherProperty”, “AnotherValue”, true);

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.

boolean result = Singular.setGlobalProperty(“MyProperty”, “MyValue”, true);

Map<String, String> map = Singular.getGlobalProperties();

Singular.unsetGlobalProperty(“MyProperty”);

Singular.clearGlobalProperties();

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.

// Ejemplo 1: Envíe el evento estándar sng_tutorial_complete con los atributos estándar recomendados.
JSONObject att = new JSONObject();
att.put(Attributes.sngAttrContent.toString(), <TUTORIAL NAME>);
att.put(Attributes.sngAttrContentId.toString(), <CONTENT ID>);
att.put(Attributes.sngAttrContentType.toString(), <TYPE OF CONTENT>);
att.put(Attributes.sngAttrSuccess.toString(), <LOGIN SUCCESS VALUE>);

Singular.eventJSON(Events.sngTutorialComplete.toString(), att);

// Ejemplo 2: Enviar un evento personalizado llamado "bonus_points_earned" con un atributo personalizado.
JSONObject att = new JSONObject();
att.put("Points", 500);
Singular.eventJSON("Bonus Points Earned", att);

// Ejemplo 1: Envíe el evento estándar sng_tutorial_complete con los atributos estándar recomendados.
val att = new JSONObject()
att.put(Attributes.sngAttrContent.toString(), "TUTORIAL NAME")
att.put(Attributes.sngAttrContent.toString(), "CONTENT ID")
att.put(Attributes.sngAttrContent.toString(), "TYPE OF CONTENT")
att.put(Attributes.sngAttrContent.toString(), "LOGIN SUCCESS VALUE")

Singular.eventJSON(Events.sngTutorialComplete.toString(), att)

// Ejemplo 2: Enviar un evento personalizado llamado "bonus_points_earned" con un atributo personalizado.
val att = new JSONObject()
att.put("Points", 500)
Singular.eventJSON("Bonus Points Earned", att)

// Ejemplo 1: Envíe el evento estándar sng_tutorial_complete con los atributos estándar recomendados.
Singular.event(Events.sngTutorialComplete.toString(),
  Attributes.sngAttrContent.toString(), <TUTORIAL NAME>,
  Attributes.sngAttrContentId.toString(), <CONTENT ID>,
  Attributes.sngAttrContentType.toString(), <TYPE OF CONTENT>,
  Attributes.sngAttrSuccess.toString(), <SUCCESS>
);

// Ejemplo 2: Enviar el evento estándar "Suscribir" (sng_subscribe), sin atributos.
Singular.event(Events.sngSubscribe.toString());

// Ejemplo 3: Enviar un evento personalizado llamado "bonus_points_earned" con un atributo personalizado.
Singular.event("Bonus Points Earned", "Points", 500);

// Ejemplo 1: Envíe el evento estándar sng_tutorial_complete con los atributos estándar recomendados.
Singular.event(Events.sngTutorialComplete.toString(),
  Attributes.sngAttrContent.toString(), "TUTORIAL NAME",
  Attributes.sngAttrContentId.toString(), "CONTENT ID",
  Attributes.sngAttrContentType.toString(), "TYPE OF CONTENT",
  Attributes.sngAttrSuccess.toString(), "SUCCESS"
)

// Ejemplo 2: Enviar el evento estándar "Suscribir" (sng_subscribe), sin atributos.
Singular.event(Events.sngSubscribe.toString())

// Ejemplo 3: Enviar un evento personalizado llamado "bonus_points_earned" con un atributo personalizado.
Singular.event("Bonus Points Earned", "Points", 500)

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:

1. Singular obtiene todos los detalles de la transacción, lo que enriquece sus informes de Singular.
2. 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.

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.

// Enviar un evento de ingresos a Singular + el objeto de compra que se recibió de la biblioteca de facturación de Google.
Singular.revenue("USD", 5.50, purchase);

// Envía un evento de ingresos a Singular, pasando el nombre del evento y el objeto de compra.
Singular.customRevenue("MyCustomRevenue", "USD", 
    5.50, purchase);

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.

// Enviar un evento de ingresos a Singular con los detalles del producto
Singular.revenue("EUR", 5.00, "SKU1928375", 
"Reservation Fee", "Fee" , 1, 5.00);

// Enviar un evento de ingresos a Singular sin detalles del producto
Singular.revenue("USD", 5.50);

// Envíe un evento de ingresos a Singular con el nombre del evento y los detalles del producto.
Singular.customRevenue("MyCustomRevenue", "EUR", 5.00, 
"SKU1928375", "Reservation Fee", "Fee" , 1, 5.00);

// Enviar un evento de ingresos a Singular con el nombre del evento
Singular.customRevenue("MyCustomRevenue", "USD", 5.50);

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.

Guías de seguimiento de eventos híbridos

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

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.

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.

@Override
protected void onResume() {
    super.onResume();
    Singular.onActivityResumed();
    .... // otro código, si procede
}

@Override
protected void onPause() {
    super.onPause();
    Singular.onActivityPaused();
    .... // otro código, si procede
}

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");

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(IMEIString);

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.

// El usuario ha optado por compartir datos
Singular.limitDataSharing(false);

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.

Singular.trackingOptIn();

Singular.stopAllTracking();

Singular.resumeAllTracking();

Singular.isAllTrackingStopped();