Documento

SDK de Android - Referencia de configuración

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

Ejemplo de configuración completa

Configuración completa del SDK

El siguiente ejemplo muestra cómo crear una configuración completa 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)

    // Deferred deep links
    .withDDLHandler { deeplink ->
        deeplink?.let { 
            println("Deferred deep link: $it")
            handleDeepLink(it)
        }
    }
    .withDDLTimeoutInSec(60)

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

    // Deferred deep links
    .withDDLHandler(new DeferredDeepLinkHandler() {
        @Override
        public void onDeferredDeepLink(String deeplink) {
            if (deeplink != null) {
                System.out.println("Deferred deep link: " + deeplink);
                handleDeepLink(deeplink);
            }
        }
    })
    .withDDLTimeoutInSec(60)

    // Attribution callback
    .withSingularDeviceAttribution(new SingularDeviceAttributionHandler() {
        @Override
        public void onDeviceAttribution(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 y secreto de API. Éste es el primer paso en la configuración de 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

SingularConfig.withBrandedDomains Método

Establece dominios de marca para la atribución de web a aplicación. Permite especificar dominios personalizados que deben rastrearse a efectos de atribución.

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 withCustomSdid de SingularConfig

Función de empresa: Establece un SDID (identificador de dispositivo de Singular) personalizado. Esto le permite proporcionar su propio identificador de dispositivo en lugar de utilizar 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") { sdid ->
        println("SDID was set: $sdid")
        // Perform any actions needed after SDID is set
    }

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

withCustomUserId

SingularConfig.withCustomUserId Método

Establece un identificador 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 principio.

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

withDDLHandler

Método withDDLHandler de SingularConfig

Establece un controlador de devolución de llamada para enlaces profundos diferidos (DDL). Esta llamada de retorno se invocará cuando se resuelva un enlace profundo diferido, lo que te permitirá manejar los datos del enlace profundo en tu aplicación.

Firma

public SingularConfig withDDLHandler(DeferredDeepLinkHandler handler);

Ejemplo de uso

// Set deferred deep link handler
val config = SingularConfig("API_KEY", "SECRET")
    .withDDLHandler { deeplink ->
        if (deeplink != null) {
            println("Deferred deep link received: $deeplink")
            // Navigate to the appropriate screen
            handleDeepLink(deeplink)
        }
    }

// Set deferred deep link handler
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withDDLHandler(new DeferredDeepLinkHandler() {
        @Override
        public void onDeferredDeepLink(String deeplink) {
            if (deeplink != null) {
                System.out.println("Deferred deep link received: " + deeplink);
                // Navigate to the appropriate screen
                handleDeepLink(deeplink);
            }
        }
    });

withDDLTimeoutInSec

Método withDDLTimeoutInSec de SingularConfig

Establece el tiempo de espera en segundos para la resolución diferida de enlaces profundos. Determina cuánto tiempo esperará el SDK un enlace profundo diferido antes de continuar con la inicialización. El valor predeterminado es 60 segundos.

Firma

public SingularConfig withDDLTimeoutInSec(long timeout);

Ejemplo de uso

// Set DDL timeout to 30 seconds
val config = SingularConfig("API_KEY", "SECRET")
    .withDDLTimeoutInSec(30)

// Set DDL timeout to 30 seconds
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withDDLTimeoutInSec(30);

withESPDomains

SingularConfig.withESPDomains Método

Establece los dominios ESP (proveedor de servicios de correo electrónico) para la atribución de correo electrónico. Esto permite especificar qué dominios de correo electrónico deben tenerse en cuenta para la atribución.

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 withFacebookAppId de SingularConfig

Establece el ID de la aplicación de Facebook para la integración de la atribución de Facebook. Esto permite al SDK realizar un seguimiento de 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

SingularConfig.withFCMDeviceToken Método

Establece el token de dispositivo FCM (Firebase Cloud Messaging) en la inicialización. Esto permite el seguimiento de notificaciones push y la detección de desinstalaciones desde el principio.

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 withGlobalProperty de SingularConfig

Establece una propiedad global durante la inicialización del SDK. Esta propiedad se enviará con todos los eventos rastreados por el SDK. Se trata de un método de configuración que permite la configuración encadenada.

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

SingularConfig.withIMEI Método

Establece el IMEI del dispositivo para el seguimiento en la inicialización. Esto es útil en regiones donde el rastreo de IMEI está permitido y es preferible.

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

SingularConfig.withLimitAdvertisingIdentifiers Método

Activa el modo de identificadores publicitarios limitados en aplicaciones de público mixto. Esta opción afecta al modo en que el SDK recopila y utiliza los identificadores de dispositivo para el seguimiento.

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

SingularConfig.withLimitDataSharing Método

Establece el estado de limitación del uso compartido de datos en la inicialización. Utilice este método para limitar el uso compartido de datos en función del consentimiento del usuario o de 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 withLogLevel de SingularConfig

Establece el nivel de registro 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)

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

SingularConfig.withLoggingEnabled Método

Activa el registro del SDK. Esto es útil para depurar y solucionar problemas durante el desarrollo. Se recomienda desactivar el registro en las compilaciones 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 withOAIDCollection de SingularConfig

Activa la recopilación de OAID (Open Anonymous Device Identifier). Se utiliza principalmente para el seguimiento 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

SingularConfig.withOpenURI Método

Establece el URI que abrió la aplicación. Se utiliza para la atribución de enlaces profundos y debe establecerse cuando la aplicación se abre a través de un enlace profundo.

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

SingularConfig.withPushNotificationPayload Método

Establece la carga útil de la notificación push para la atribución. Esto permite al SDK procesar los datos de 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 withSdidAccessorHandler de SingularConfig

Característica empresarial: Establece una función de devolución de llamada que se llamará cuando se reciba el SDID (Singular Device ID). Esto le permite acceder al SDID tan pronto como 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 { sdid ->
        println("SDID received: $sdid")
        // Store or use the SDID as needed
        storeDeviceIdentifier(sdid)
    }

// Set callback for when SDID is received
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withSdidAccessorHandler(new SDIDAccessorHandler() {
        @Override
        public void onSdidReceived(String sdid) {
            System.out.println("SDID received: " + sdid);
            // Store or use the SDID as needed
            storeDeviceIdentifier(sdid);
        }
    });

withSessionTimeoutInSec

SingularConfig.withSessionTimeoutInSec Método

Establece el tiempo de espera de la sesión en segundos. Determina cuánto dura una sesión de usuario después de que la aplicación pase a segundo plano. El valor predeterminado 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 withSingularConfig.withSingularDeviceAttribution

Función BETA: Establece una función de devolución de llamada que se llamará cuando los datos de atribución del dispositivo estén disponibles. Esto le permite acceder a los datos de atribución tan pronto como estén disponibles.

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

        // Access specific attribution parameters
        val campaign = attributionData["campaign"] as? String
        val source = attributionData["source"] as? String
        val adSet = attributionData["adSet"] as? String

        // Update UI or take actions based on attribution data
        campaign?.let { showCampaignSpecificContent(it) }
    }

// Set device attribution callback
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withSingularDeviceAttribution(new SingularDeviceAttributionHandler() {
        @Override
        public void onDeviceAttribution(Map<String, Object> attributionData) {
            System.out.println("Attribution data received: " + attributionData);

            // Access specific attribution parameters
            String campaign = (String) attributionData.get("campaign");
            String source = (String) attributionData.get("source");
            String adSet = (String) attributionData.get("adSet");

            // Update UI or take actions based on attribution data
            if (campaign != null) {
                showCampaignSpecificContent(campaign);
            }
        }
    });

withSingularLink

SingularConfig.withSingularLink Métodos

Configura Singular Links (enlaces profundos) para la atribución. Este método configura el manejador para procesar enlaces profundos y el tiempo de espera para la resolución de enlaces cortos.

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 de configuración completa

Configuración completa del SDK

Ejemplo completo

Constructor

Constructor de SingularConfig

Firma

Ejemplo de uso

withBrandedDomains

SingularConfig.withBrandedDomains Método

Firma

Ejemplo de uso

withCustomSdid

Método withCustomSdid de SingularConfig

Firma

Ejemplo de uso

withCustomUserId

SingularConfig.withCustomUserId Método

Firma

Ejemplo de uso

withDDLHandler

Método withDDLHandler de SingularConfig

Firma

Ejemplo de uso

withDDLTimeoutInSec

Método withDDLTimeoutInSec de SingularConfig

Firma

Ejemplo de uso

withESPDomains

SingularConfig.withESPDomains Método

Firma

Ejemplo de uso

withFacebookAppId

Método withFacebookAppId de SingularConfig

Firma

Ejemplo de uso

withFCMDeviceToken

SingularConfig.withFCMDeviceToken Método

Firma

Ejemplo de uso

withGlobalProperty

Método withGlobalProperty de SingularConfig

Firma

Ejemplo de uso

withIMEI

SingularConfig.withIMEI Método

Firma

Ejemplo de uso

withLimitAdvertisingIdentifiers

SingularConfig.withLimitAdvertisingIdentifiers Método

Firma

Ejemplo de uso

withLimitDataSharing

SingularConfig.withLimitDataSharing Método

Firma

Ejemplo de uso

withLogLevel

Método withLogLevel de SingularConfig

Firma

Ejemplo de uso

withLoggingEnabled

SingularConfig.withLoggingEnabled Método

Firma

Ejemplo de uso

withOAIDCollection

Método withOAIDCollection de SingularConfig

Firma

Ejemplo de uso

withOpenURI

SingularConfig.withOpenURI Método

Firma

Ejemplo de uso

withPushNotificationPayload

SingularConfig.withPushNotificationPayload Método

Firma

Ejemplo de uso

withSdidAccessorHandler

Método withSdidAccessorHandler de SingularConfig

Firma