SDK de Android - Referencia de configuración

Este documento ofrece una referencia integral de todas las opciones de configuración disponibles en el Singular SDK para aplicaciones Android. El objeto SingularConfig le permite personalizar el comportamiento del SDK, incluidos los ajustes de tracking, las opciones de atribución, los controles de privacidad y más. Cada método de configuración se presenta con una descripción, una firma y ejemplos prácticos de uso.

Ejemplo completo de configuración

Configuración integral del SDK

El siguiente ejemplo muestra cómo crear una configuración integral encadenando varios métodos de configuración.

Ejemplo completo

// Create comprehensive configuration
val config = SingularConfig("SDK KEY", "YOUR_SECRET")
    // Basic options
    .withSessionTimeoutInSec(120)
    .withLoggingEnabled()
    .withLogLevel(Log.VERBOSE)

    // User identification
    .withCustomUserId("user_123456")

    // Global properties
    .withGlobalProperty("app_version", "1.2.3", true)
    .withGlobalProperty("user_type", "premium", true)

    // Deep links
    .withOpenURI(intent.data)
    .withSingularLink(intent, { params ->
        params.deeplink?.let { deeplink ->
            println("Deep link: $deeplink")
            handleDeepLink(deeplink)
        }
    }, 10)

    // Attribution callback
    .withSingularDeviceAttribution { attributionData ->
        println("Attribution: $attributionData")
    }

    // Push notifications
    .withFCMDeviceToken(fcmToken)

    // Privacy settings
    .withLimitDataSharing(false)

    // Email attribution
    .withESPDomains(listOf("mailchimp.com", "sendgrid.net"))

    // Facebook integration
    .withFacebookAppId("YOUR_FACEBOOK_APP_ID")

// Initialize the SDK
Singular.init(context, config)

// Create comprehensive configuration
SingularConfig config = new SingularConfig("SDK KEY", "YOUR_SECRET")
    // Basic options
    .withSessionTimeoutInSec(120)
    .withLoggingEnabled()
    .withLogLevel(Log.VERBOSE)

    // User identification
    .withCustomUserId("user_123456")

    // Global properties
    .withGlobalProperty("app_version", "1.2.3", true)
    .withGlobalProperty("user_type", "premium", true)

    // Deep links
    .withOpenURI(getIntent().getData())
    .withSingularLink(getIntent(), new SingularLinkHandler() {
        @Override
        public void onResolved(SingularLinkParams params) {
            if (params.getDeeplink() != null) {
                System.out.println("Deep link: " + params.getDeeplink());
                handleDeepLink(params.getDeeplink());
            }
        }
    }, 10)

    // Attribution callback
    .withSingularDeviceAttribution(new SingularDeviceAttributionHandler() {
        @Override
        public void onDeviceAttributionInfoReceived(Map<String, Object> attributionData) {
            System.out.println("Attribution: " + attributionData);
        }
    })

    // Push notifications
    .withFCMDeviceToken(fcmToken)

    // Privacy settings
    .withLimitDataSharing(false)

    // Email attribution
    .withESPDomains(Arrays.asList("mailchimp.com", "sendgrid.net"))

    // Facebook integration
    .withFacebookAppId("YOUR_FACEBOOK_APP_ID");

// Initialize the SDK
Singular.init(context, config);

Constructor

Constructor de SingularConfig

Inicializa un nuevo objeto SingularConfig con su clave API y su secreto. Este es el primer paso para configurar el Singular SDK.

Firma

public SingularConfig(String apiKey, String secret);

Ejemplo de uso

// Create configuration object
val config = SingularConfig("SDK KEY", "YOUR_SECRET")

// Create configuration object
SingularConfig config = new SingularConfig("SDK KEY", "YOUR_SECRET");

withBrandedDomains

Método SingularConfig.withBrandedDomains

Define dominios de marca para la atribución de la web a la aplicación. Esto le permite especificar dominios personalizados que se deben trackear para fines de atribución.

Al llamar a este método se reemplazan los dominios de marca configurados previamente. Pase la lista completa en una sola llamada en lugar de encadenar varias llamadas.

Firma

public SingularConfig withBrandedDomains(List<String> brandedDomains);

Ejemplo de uso

// Set branded domains for web-to-app attribution
val brandedDomains = listOf("yourcompany.com", "go.yourcompany.com")
val config = SingularConfig("API_KEY", "SECRET")
    .withBrandedDomains(brandedDomains)

// Set branded domains for web-to-app attribution
List<String> brandedDomains = Arrays.asList("yourcompany.com", "go.yourcompany.com");
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withBrandedDomains(brandedDomains);

withCustomSdid

Método SingularConfig.withCustomSdid

Función Enterprise: Define un SDID (Singular Device ID) personalizado. Esto le permite proporcionar su propio identificador de dispositivo en lugar de usar el generado por Singular.

Firma

public SingularConfig withCustomSdid(String customSdid, SDIDAccessorHandler accessorHandler);

Ejemplo de uso

// Set custom SDID with callback
val config = SingularConfig("API_KEY", "SECRET")
    .withCustomSdid("custom-device-id-12345", object : SDIDAccessorHandler {
        override fun didSetSdid(result: String) {
            println("SDID was set: $result")
            // Perform any actions needed after SDID is set
        }

        override fun sdidReceived(result: String) {
            println("SDID received: $result")
            // Existing SDID returned by the SDK
        }
    })

// Set custom SDID with callback
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withCustomSdid("custom-device-id-12345", new SDIDAccessorHandler() {
        @Override
        public void didSetSdid(String result) {
            System.out.println("SDID was set: " + result);
            // Perform any actions needed after SDID is set
        }

        @Override
        public void sdidReceived(String result) {
            System.out.println("SDID received: " + result);
            // Existing SDID returned by the SDK
        }
    });

withCustomUserId

Método SingularConfig.withCustomUserId

Establece un ID de usuario personalizado durante la inicialización del SDK. Esto le permite asociar los datos de Singular con su propio sistema de identificación de usuarios desde el inicio.

Firma

public SingularConfig withCustomUserId(String customUserId);

Ejemplo de uso

// Set custom user ID at initialization
val config = SingularConfig("API_KEY", "SECRET")
    .withCustomUserId("user_123456")

// Set custom user ID at initialization
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withCustomUserId("user_123456");

withESPDomains

Método SingularConfig.withESPDomains

Define los dominios ESP (proveedores de servicios de email) para la atribución por email. Esto le permite especificar qué dominios de email deben considerarse para la atribución.

Al llamar a este método se reemplazan los dominios ESP configurados previamente. Pase la lista completa en una sola llamada en lugar de encadenar varias llamadas.

Firma

public SingularConfig withESPDomains(List<String> espDomains);

Ejemplo de uso

// Set ESP domains for email attribution
val espDomains = listOf("mailchimp.com", "sendgrid.net", "campaign-monitor.com")
val config = SingularConfig("API_KEY", "SECRET")
    .withESPDomains(espDomains)

// Set ESP domains for email attribution
List<String> espDomains = Arrays.asList("mailchimp.com", "sendgrid.net", "campaign-monitor.com");
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withESPDomains(espDomains);

withFacebookAppId

Método SingularConfig.withFacebookAppId

Define el ID de la aplicación de Facebook para la integración de atribución con Facebook. Esto permite al SDK trackear la atribución de campañas de Facebook.

Firma

public SingularConfig withFacebookAppId(String facebookAppId);

Ejemplo de uso

// Set Facebook App ID
val config = SingularConfig("API_KEY", "SECRET")
    .withFacebookAppId("YOUR_FACEBOOK_APP_ID")

// Set Facebook App ID
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withFacebookAppId("YOUR_FACEBOOK_APP_ID");

withFCMDeviceToken

Método SingularConfig.withFCMDeviceToken

Define el token de dispositivo FCM (Firebase Cloud Messaging) en la inicialización. Esto habilita el tracking de notificaciones push y la detección de desinstalaciones desde el inicio.

La llamada se ignora si el token es null o está vacío. Invoque este método solo cuando disponga de un token FCM válido.

Firma

public SingularConfig withFCMDeviceToken(String fcmDeviceToken);

Ejemplo de uso

// Set FCM token at initialization if available
val config = SingularConfig("API_KEY", "SECRET")
    .withFCMDeviceToken(fcmToken)

// Set FCM token at initialization if available
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withFCMDeviceToken(fcmToken);

withGlobalProperty

Método SingularConfig.withGlobalProperty

Define una propiedad global durante la inicialización del SDK. Esta propiedad se enviará con todos los eventos trackeados por el SDK. Es un método de configuración que admite encadenamiento.

El SDK admite un máximo de 5 propiedades globales. Las llamadas adicionales por encima de este límite se ignoran sin emitir error.

Firma

public SingularConfig withGlobalProperty(String key, String value, boolean overrideExisting);

Ejemplo de uso

// Add global properties at initialization
val config = SingularConfig("API_KEY", "SECRET")
    .withGlobalProperty("app_version", "1.2.3", true)
    .withGlobalProperty("user_type", "free", true)

// Add global properties at initialization
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withGlobalProperty("app_version", "1.2.3", true)
    .withGlobalProperty("user_type", "free", true);

withIMEI

Método SingularConfig.withIMEI

Define el IMEI del dispositivo para tracking en la inicialización. Es útil en regiones donde el tracking por IMEI está permitido y se prefiere.

Firma

public SingularConfig withIMEI(String imei);

Ejemplo de uso

// Set device IMEI at initialization
val config = SingularConfig("API_KEY", "SECRET")
    .withIMEI("123456789012345")

// Set device IMEI at initialization
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withIMEI("123456789012345");

withLimitAdvertisingIdentifiers

Método SingularConfig.withLimitAdvertisingIdentifiers

Habilita el modo de identificadores publicitarios limitados en aplicaciones con audiencia mixta. Esta opción afecta la forma en que el SDK recopila y utiliza los identificadores del dispositivo para tracking.

Firma

public SingularConfig withLimitAdvertisingIdentifiers();

Ejemplo de uso

// Enable limited identifiers mode
val config = SingularConfig("API_KEY", "SECRET")
    .withLimitAdvertisingIdentifiers()

// Enable limited identifiers mode
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withLimitAdvertisingIdentifiers();

withLimitDataSharing

Método SingularConfig.withLimitDataSharing

Establece el estado de limitación de uso compartido de datos en la inicialización. Utilice este método para limitar el uso compartido de datos según el consentimiento del usuario o los requisitos de privacidad.

Firma

public SingularConfig withLimitDataSharing(boolean shouldLimitDataSharing);

Ejemplo de uso

// Enable limited data sharing at initialization
val config = SingularConfig("API_KEY", "SECRET")
    .withLimitDataSharing(true)

// Enable limited data sharing at initialization
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withLimitDataSharing(true);

withLogLevel

Método SingularConfig.withLogLevel

Define el nivel de log para los registros del SDK. Los niveles disponibles son:

NONE = -1
VERBOSE = Log.VERBOSE (constante de Android, valor numérico 2)
DEBUG = Log.DEBUG (3)
INFO = Log.INFO (4)
WARNING = Log.WARN (5)
ERROR = Log.ERROR (6)

El nivel de log por defecto es Log.ERROR. Para que se genere salida, también debe habilitar el logging mediante withLoggingEnabled().

Firma

public SingularConfig withLogLevel(int level);

Ejemplo de uso

import android.util.Log

// Set verbose logging for detailed debugging
val config = SingularConfig("API_KEY", "SECRET")
    .withLoggingEnabled()
    .withLogLevel(Log.VERBOSE)

import android.util.Log;

// Set verbose logging for detailed debugging
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withLoggingEnabled()
    .withLogLevel(Log.VERBOSE);

withLoggingEnabled

Método SingularConfig.withLoggingEnabled

Habilita el logging del SDK. Es útil para depuración y resolución de problemas durante el desarrollo. Se recomienda deshabilitar el logging en builds de producción.

Firma

public SingularConfig withLoggingEnabled();

Ejemplo de uso

// Enable logging for debug builds
val config = SingularConfig("API_KEY", "SECRET")
    .withLoggingEnabled()

// Enable logging for debug builds
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withLoggingEnabled();

withOAIDCollection

Método SingularConfig.withOAIDCollection

Habilita la recopilación de OAID (Open Anonymous Device Identifier). Se utiliza principalmente para tracking en China, donde Google Play Services no está disponible.

Firma

public SingularConfig withOAIDCollection();

Ejemplo de uso

// Enable OAID collection for China
val config = SingularConfig("API_KEY", "SECRET")
    .withOAIDCollection()

// Enable OAID collection for China
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withOAIDCollection();

withOpenURI

Método SingularConfig.withOpenURI

Define el URI que abrió la aplicación. Se utiliza para la atribución de deep links y debe configurarse cuando la aplicación se abre a través de un deep link.

Firma

public SingularConfig withOpenURI(Uri openUri);

Ejemplo de uso

// In your Activity's onCreate or onNewIntent
val uri = intent.data
val config = SingularConfig("API_KEY", "SECRET")
    .withOpenURI(uri)

// In your Activity's onCreate or onNewIntent
Uri uri = getIntent().getData();
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withOpenURI(uri);

withPushNotificationPayload

Método SingularConfig.withPushNotificationPayload

Define el payload de la notificación push para la atribución. Esto permite al SDK procesar los datos de la notificación push durante la inicialización.

Firma

public SingularConfig withPushNotificationPayload(Intent intent, String[] ... pushNotificationLinkPath);

Ejemplo de uso

// Set push notification payload with custom link paths
val config = SingularConfig("API_KEY", "SECRET")
    .withPushNotificationPayload(
        intent,
        arrayOf("data", "deeplink"),
        arrayOf("notification", "data", "url"),
        arrayOf("custom", "link")
    )

// Set push notification payload with custom link paths
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withPushNotificationPayload(
        intent,
        new String[]{"data", "deeplink"},
        new String[]{"notification", "data", "url"},
        new String[]{"custom", "link"}
    );

withSdidAccessorHandler

Método SingularConfig.withSdidAccessorHandler

Función Enterprise: Define una función de callback que se invoca cuando se recibe el SDID (Singular Device ID). Esto le permite acceder al SDID en cuanto esté disponible.

Firma

public SingularConfig withSdidAccessorHandler(SDIDAccessorHandler accessorHandler);

Ejemplo de uso

// Set callback for when SDID is received
val config = SingularConfig("API_KEY", "SECRET")
    .withSdidAccessorHandler(object : SDIDAccessorHandler {
        override fun didSetSdid(result: String) {
            println("SDID was set: $result")
        }

        override fun sdidReceived(result: String) {
            println("SDID received: $result")
            // Store or use the SDID as needed
            storeDeviceIdentifier(result)
        }
    })

// Set callback for when SDID is received
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withSdidAccessorHandler(new SDIDAccessorHandler() {
        @Override
        public void didSetSdid(String result) {
            System.out.println("SDID was set: " + result);
        }

        @Override
        public void sdidReceived(String result) {
            System.out.println("SDID received: " + result);
            // Store or use the SDID as needed
            storeDeviceIdentifier(result);
        }
    });

withSessionTimeoutInSec

Método SingularConfig.withSessionTimeoutInSec

Define el tiempo de espera de la sesión en segundos. Determina cuánto dura la sesión de un usuario después de que la aplicación pasa a segundo plano. El valor por defecto es 60 segundos.

Firma

public SingularConfig withSessionTimeoutInSec(long timeout);

Ejemplo de uso

// Set session timeout to 2 minutes
val config = SingularConfig("API_KEY", "SECRET")
    .withSessionTimeoutInSec(120)

// Set session timeout to 2 minutes
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withSessionTimeoutInSec(120);

withSingularDeviceAttribution

Método SingularConfig.withSingularDeviceAttribution

Función BETA: Define una función de callback que se invoca cuando hay datos de atribución del dispositivo disponibles en la respuesta de /start . El callback se ejecuta en un hilo en segundo plano, por lo que debe despachar cualquier trabajo de UI al hilo principal.

Clave	Tipo	Notas
`network`	String	Fuente de atribución. "organic" para instalaciones no atribuidas.
`campaign_id`	String	Presente solo cuando hay atribución.
`campaign_name`	String	Presente solo cuando hay atribución.
`click_timestamp`	Long (microsegundos epoch)	Presente solo cuando hay atribución. Divida entre 1.000.000 para obtener segundos.

El callback se invoca únicamente cuando la respuesta de /start contiene un objeto attribution_info . Para instalaciones orgánicas, solo se completa el campo network.

Firma

public SingularConfig withSingularDeviceAttribution(SingularDeviceAttributionHandler handler);

Ejemplo de uso

// Set device attribution callback
val config = SingularConfig("API_KEY", "SECRET")
      .withSingularDeviceAttribution { attributionData ->
          println("Attribution data received: $attributionData")

          val source         = attributionData["network"]        as? String
          val campaignName   = attributionData["campaign_name"]  as? String
          val campaignId     = attributionData["campaign_id"]    as? String
          val clickTimestamp = attributionData["click_timestamp"]?.toString()?.toLongOrNull()

          campaignName?.let { showCampaignSpecificContent(it) }
      }

// Set device attribution callback
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
  .withSingularDeviceAttribution(new SingularDeviceAttributionHandler() {
    @Override
    public void onDeviceAttributionInfoReceived(Map<String, Object> attributionData) {
      Log.d("Singular", "Attribution data received: " + attributionData);
      String source        = (String) attributionData.get("network");
      String campaignName  = (String) attributionData.get("campaign_name");
      String campaignId    = (String) attributionData.get("campaign_id");
      Object clickTsObj    = attributionData.get("click_timestamp");
      Long   clickTimestamp = clickTsObj != null
          ? Long.parseLong(clickTsObj.toString())
          : null;
      if (campaignName != null) {
          showCampaignSpecificContent(campaignName);
      }
    }
});

withSingularLink

Métodos SingularConfig.withSingularLink

Configura Singular Links (deep links) para la atribución. Este método establece el handler que procesa los deep links y el tiempo de espera para la resolución de los enlaces cortos.

Cuando se omite el argumento shortlinkTimeoutSec, el SDK utiliza un valor predeterminado de 10 segundos. Si la acción del intent es ACTION_VIEW, el SDK también marca la sesión como abierta con un deep link.

Firmas

public SingularConfig withSingularLink(Intent intent, SingularLinkHandler handler);

public SingularConfig withSingularLink(Intent intent, SingularLinkHandler handler,
                                       long shortlinkTimeoutSec);

Ejemplo de uso

// Set Singular Links handler
val config = SingularConfig("API_KEY", "SECRET")
    .withSingularLink(intent, { params ->
        // Check if we have a deep link
        params.deeplink?.let { deeplink ->
            println("Deep link received: $deeplink")
            // Navigate based on the deep link
            navigateToScreen(deeplink)
        }

        // Check if this is a deferred deep link
        if (params.isDeferred) {
            println("This is a deferred deep link")
        }

        // Access passthrough parameters
        params.passthrough?.let { passthrough ->
            println("Passthrough data: $passthrough")
        }
    }, 10)

// Set Singular Links handler
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withSingularLink(intent, new SingularLinkHandler() {
        @Override
        public void onResolved(SingularLinkParams params) {
            // Check if we have a deep link
            if (params.getDeeplink() != null) {
                System.out.println("Deep link received: " + params.getDeeplink());
                // Navigate based on the deep link
                navigateToScreen(params.getDeeplink());
            }

            // Check if this is a deferred deep link
            if (params.isDeferred()) {
                System.out.println("This is a deferred deep link");
            }

            // Access passthrough parameters
            if (params.getPassthrough() != null) {
                System.out.println("Passthrough data: " + params.getPassthrough());
            }
        }
    }, 10);

SDK de Android - Referencia de métodos de configuración

SDK de Android - Referencia de configuración

Ejemplo completo de configuración

Configuración integral del SDK

Ejemplo completo

Constructor

Constructor de SingularConfig

Firma

Ejemplo de uso

withBrandedDomains

Método SingularConfig.withBrandedDomains

Firma

Ejemplo de uso

withCustomSdid

Método SingularConfig.withCustomSdid

Firma

Ejemplo de uso

withCustomUserId

Método SingularConfig.withCustomUserId

Firma

Ejemplo de uso

withESPDomains

Método SingularConfig.withESPDomains

Firma

Ejemplo de uso

withFacebookAppId

Método SingularConfig.withFacebookAppId

Firma

Ejemplo de uso

withFCMDeviceToken

Método SingularConfig.withFCMDeviceToken

Firma

Ejemplo de uso

withGlobalProperty

Método SingularConfig.withGlobalProperty

Firma

Ejemplo de uso

withIMEI

Método SingularConfig.withIMEI

Firma

Ejemplo de uso

withLimitAdvertisingIdentifiers

Método SingularConfig.withLimitAdvertisingIdentifiers

Firma

Ejemplo de uso

withLimitDataSharing

Método SingularConfig.withLimitDataSharing

Firma

Ejemplo de uso

withLogLevel

Método SingularConfig.withLogLevel

Firma

Ejemplo de uso

withLoggingEnabled

Método SingularConfig.withLoggingEnabled

Firma

Ejemplo de uso

withOAIDCollection

Método SingularConfig.withOAIDCollection

Firma

Ejemplo de uso

withOpenURI

Método SingularConfig.withOpenURI

Firma

Ejemplo de uso

withPushNotificationPayload

Método SingularConfig.withPushNotificationPayload

Firma

Ejemplo de uso

withSdidAccessorHandler

Método SingularConfig.withSdidAccessorHandler

Firma

Ejemplo de uso

withSessionTimeoutInSec

Método SingularConfig.withSessionTimeoutInSec

Firma

Ejemplo de uso

withSingularDeviceAttribution

Método SingularConfig.withSingularDeviceAttribution

Firma