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