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

Documento

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

Este documento proporciona una referencia exhaustiva de todas las opciones de configuración disponibles en el SDK Singular para aplicaciones Flutter. 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, una firma y ejemplos prácticos de uso.

clipboardAttribution

Propiedad SingularConfig.clipboardAttribution

Habilita la atribución de portapapeles para el SDK. Si está activada, el SDK comprobará el portapapeles del dispositivo en busca de enlaces de atribución durante la inicialización.

Firma

bool clipboardAttribution = false;

Ejemplo de uso

// Enable clipboard attribution
config.clipboardAttribution = true;

collectOAID

Propiedad collectOAID de SingularConfig

Activa la recopilación de OAID (Open Anonymous Device Identifier) en los dispositivos Android compatibles. Se trata de un identificador alternativo utilizado en algunas regiones, especialmente en China.

Firma

bool collectOAID = false;

Ejemplo de uso

// Enable OAID collection
config.collectOAID = true;

conversionValueUpdatedCallback

Propiedad conversionValueUpdatedCallback de SingularConfig

Establece una función de devolución de llamada a la que se llamará cuando se actualice el valor de conversión de SKAdNetwork. Esto es específico de iOS y le permite reaccionar ante cambios en el valor de conversión.

Firma

ConversionValueUpdatedCallback? conversionValueUpdatedCallback;

Ejemplo de uso

// Set conversion value updated callback
config.conversionValueUpdatedCallback = (int conversionValue) {
    print("Conversion value updated to: $conversionValue");
    // Update UI or take other actions based on the new conversion value
};

conversionValuesUpdatedCallback

Propiedad SingularConfig.conversionValuesUpdatedCallback

Establece una función de devolución de llamada a la que se llamará cuando se actualicen los valores de conversión de SKAdNetwork 4.0. Esto es específico de iOS 16.1+ y permite reaccionar ante cambios en los valores finos, gruesos y de bloqueo.

Firma

ConversionValuesUpdatedCallback? conversionValuesUpdatedCallback;

Ejemplo de uso

// Set conversion values updated callback for SKAdNetwork 4.0
config.conversionValuesUpdatedCallback = (int conversionValue, int coarse, bool lock) {
    print("Conversion values updated - Fine: $conversionValue, Coarse: $coarse, Lock: $lock");
    // Update UI or take other actions based on the new conversion values
};

customSdid

Propiedad singularConfig.customSdid

Característica 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

String? customSdid;

Ejemplo de uso

// Set custom SDID
config.customSdid = "custom-device-id-12345";

customUserId

Propiedad SingularConfig.customUserId

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

String? customUserId;

Ejemplo de uso

// Set custom user ID
config.customUserId = "user_123456";

deviceAttributionCallback

Propiedad deviceAttributionCallback de SingularConfig

Característica BETA: Establece una función de devolución de llamada que se llamará cuando estén disponibles los datos de atribución del dispositivo. Esto permite acceder a los datos de atribución en cuanto están disponibles.

Firma

DeviceAttributionCallback? deviceAttributionCallback;

Ejemplo de uso

// Set device attribution callback
config.deviceAttributionCallback = (Map attributionData) {
    print("Attribution data received: $attributionData");
    
    // Access specific attribution parameters
    final campaign = attributionData["campaign"];
    final source = attributionData["source"];
    final adSet = attributionData["adSet"];
    
    // Update UI or take actions based on attribution data
    if (campaign != null) {
        showCampaignSpecificContent(campaign);
    }
};

didSetSdidCallback

Propiedad didSetSdidCallback de SingularConfig

Característica empresarial: Establece una función de callback que se llamará cuando se establezca el SDID (Singular Device ID). Esto le permite recibir una notificación cuando el SDID personalizado se ha establecido correctamente.

Firma

SdidAccessorCallback? didSetSdidCallback;

Ejemplo de uso

// Set custom SDID
config.customSdid = "custom-device-id-12345";

// Set callback for when SDID is set
config.didSetSdidCallback = (String sdid) {
    print("SDID was set: $sdid");
    // Perform any actions needed after SDID is set
};

enableLogging

Propiedad SingularConfig.enableLogging

Habilita el registro detallado para el SDK. Cuando está activada, el SDK generará registros detallados que pueden ayudar a depurar.

Firma

bool enableLogging = false;

Ejemplo de uso

// Enable logging for debugging
config.enableLogging = true;

espDomains

Propiedad SingularConfig.espDomains

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

Firma

List espDomains = [];

Ejemplo de uso

// Set ESP domains for email attribution
config.espDomains = [
    "mailchimp.com",
    "sendgrid.net",
    "campaign-monitor.com"
];

facebookAppId

Propiedad SingularConfig.facebookAppId

Establece el ID de la aplicación de Facebook para la atribución de Facebook. Esto permite al SDK atribuir instalaciones y eventos de campañas de Facebook.

Firma

String? facebookAppId;

Ejemplo de uso

// Set Facebook App ID for attribution
config.facebookAppId = "123456789012345";

imei

Propiedad SingularConfig.imei

Establece el IMEI (International Mobile Equipment Identity) del dispositivo. Suele utilizarse en mercados en los que el IMEI es un identificador común para la atribución.

Firma

String? imei;

Ejemplo de uso

// Set IMEI (only if you have proper permission to access it)
config.imei = "123456789012345";

limitDataSharing

Propiedad limitDataSharing de SingularConfig

Establece el estado de limitación de compartición de datos durante la inicialización del SDK. Utilice esta propiedad para limitar el uso compartido de datos en función del consentimiento del usuario o de requisitos de privacidad.

Firma

bool? limitDataSharing;

Ejemplo de uso

// Get user consent status
bool hasUserConsent = getUserConsentStatus();

// Set data sharing limitation based on consent
config.limitDataSharing = !hasUserConsent;

limitedIdentifiersEnabled

Propiedad limitedIdentifiersEnabled de SingularConfig

Activa o desactiva el uso de identificadores limitados. Esta opción afecta al modo en que el SDK recopila y utiliza los identificadores de dispositivo para el seguimiento y la atribución.

Firma

bool limitedIdentifiersEnabled = false;

Ejemplo de uso

// Enable limited identifiers mode
config.limitedIdentifiersEnabled = true;

logLevel

Propiedad SingularConfig.logLevel

Establece el nivel de registro del SDK. Controla el nivel de detalle de los registros generados por el SDK. El valor predeterminado es -1 (sin registro). Los valores más comunes son: 0 (error), 1 (warning), 2 (info), 3 (debug), 4 (verbose).

Firma

int logLevel = -1;

Ejemplo de uso

// Set log level to debug
config.logLevel = 3;

manualSkanConversionManagement

Propiedad manualSkanConversionManagement de SingularConfig

Habilita la gestión manual de los valores de conversión de SKAdNetwork. Cuando está activada, el SDK no actualizará automáticamente los valores de conversión, permitiéndole controlarlos manualmente.

Firma

bool manualSkanConversionManagement = false;

Ejemplo de uso

// Enable manual SKAdNetwork conversion management
config.manualSkanConversionManagement = true;

pushNotificationsLinkPaths

Propiedad pushNotificationsLinkPaths de SingularConfig

Establece las rutas para buscar enlaces profundos en las cargas útiles de las notificaciones push. Esto ayuda al SDK a encontrar y procesar enlaces de atribución en las notificaciones push.

Firma

List<List<String>> pushNotificationsLinkPaths = [[]];

Ejemplo de uso

// Set push notification link paths
config.pushNotificationsLinkPaths = [
    ["data", "deeplink"],
    ["notification", "data", "url"],
    ["custom", "link"]
];

sdidReceivedCallback

Propiedad SingularConfig.sdidReceivedCallback

Característica empresarial: Establece una función de callback que se llamará cuando se reciba el SDID (Singular Device ID). Esto le permite acceder al SDID tan pronto como esté disponible.

Firma

SdidAccessorCallback? sdidReceivedCallback;

Ejemplo de uso

// Set callback for when SDID is received
config.sdidReceivedCallback = (String sdid) {
    print("SDID received: $sdid");
    // Store or use the SDID as needed
    storeDeviceIdentifier(sdid);
};

sessionTimeout

Propiedad SingularConfig.sessionTimeout

Establece el tiempo de espera de la sesión en segundos. Determina cuánto tiempo dura una sesión de usuario después de que la aplicación pase a segundo plano. El valor por defecto es -1, que utiliza el tiempo de espera por defecto del SDK (60 segundos).

Firma

double sessionTimeout = -1;

Ejemplo de uso

// Set session timeout to 2 minutes
config.sessionTimeout = 120;

shortLinkResolveTimeOut

Propiedad SingularConfig.shortLinkResolveTimeOut

Establece el tiempo de espera en segundos para la resolución de enlaces cortos. Determina cuánto tiempo esperará el SDK a que se resuelva un enlace corto antes de continuar con la inicialización. El valor predeterminado es 10 segundos.

Firma

double shortLinkResolveTimeOut = 10.0;

Ejemplo de uso

// Set short link resolve timeout to 15 seconds
config.shortLinkResolveTimeOut = 15.0;

singularLinksHandler

Propiedad singularConfig.singularLinksHandler

Establece una función de devolución de llamada para gestionar los enlaces profundos procesados por Singular. Esto permite que su aplicación responda a los enlaces profundos utilizados en la atribución.

Firma

SingularLinksHandler? singularLinksHandler;

Ejemplo de uso

// Set singular links handler
config.singularLinksHandler = (SingularLinkParams params) {
    // Check if we have a deep link
    if (params.deeplink != null) {
        print("Deep link received: ${params.deeplink}");
        
        // Navigate based on the deep link
        navigateToScreen(params.deeplink!);
    }
    
    // Check if this is a deferred deep link
    if (params.isDeferred == true) {
        print("This is a deferred deep link");
    }
    
    // Access passthrough parameters
    if (params.passthrough != null) {
        print("Passthrough data: ${params.passthrough}");
    }
    
    // Access all URL parameters from the OpenURL/Deeplink. Does not work with Deferred Deep Links.
    if (params.urlParameters != null) {
        print("URL parameters: ${params.urlParameters}");
    }
};

skAdNetworkEnabled

Propiedad SingularConfig.skAdNetworkEnabled

Activa o desactiva la compatibilidad con SKAdNetwork. Esto es específico de iOS y controla si el SDK utilizará SKAdNetwork de Apple para la atribución. El valor por defecto es true.

Firma

bool skAdNetworkEnabled = true;

Ejemplo de uso

// Disable SKAdNetwork support if needed
config.skAdNetworkEnabled = false;

waitForTrackingAuthorizationWithTimeoutInterval

Propiedad singularConfig.waitForTrackingAuthorizationWithTimeoutInterval

Establece el intervalo de tiempo de espera en segundos para la respuesta de autorización de seguimiento del usuario en iOS 14+. Determina cuánto tiempo esperará el SDK a la respuesta de solicitud de ATT antes de continuar con la inicialización. El valor predeterminado es 0, lo que significa que el SDK no esperará a la respuesta del aviso de ATT.

Firma

int waitForTrackingAuthorizationWithTimeoutInterval = 0;

Ejemplo de uso

// Wait up to 5 seconds for ATT prompt response
config.waitForTrackingAuthorizationWithTimeoutInterval = 5;

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 en lugar de una propiedad, lo que permite una configuración encadenada.

Firma

void withGlobalProperty(String key, String value, bool overrideExisting)

Ejemplo de uso

// Add global properties
config.withGlobalProperty("app_version", "1.2.3", true);
config.withGlobalProperty("user_type", "free", true);

Ejemplo de configuración completa

Configuración completa del SDK

El siguiente ejemplo muestra cómo crear una configuración completa estableciendo varias propiedades y métodos de configuración juntos.

Ejemplo completo

SingularConfig config = new SingularConfig('SDK KEY', 'SDK SECRET');
config.waitForTrackingAuthorizationWithTimeoutInterval = 60;
config.customUserId = "user_123456"; // Set a custom user ID for tracking
config.withGlobalProperty("key1", "value1", true);
config.limitDataSharing = false; // Allow data sharing (set to true for compliance if needed)
config.facebookAppId = "123456789012345"; // Optional: For Facebook integration
config.singularLinksHandler = (SingularLinkParams params) {
     print('Received deferred deeplink: ');
     deeplinkParams['deeplink'] = params.deeplink;
     deeplinkParams['passthrough'] = params.passthrough;
     deeplinkParams['isDeferred'] = params.isDeferred;
};

Singular.start(config);