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

Seguir
Avatar
Jared Ornstead
Updated
Documento

SDK de Flutter - Referencia 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 propiedad 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 realizar un seguimiento de los enlaces profundos copiados en el portapapeles del dispositivo. Si está activada, el SDK comprobará si hay enlaces Singular en el portapapeles al iniciar la aplicación.

Firma

bool clipboardAttribution

Ejemplo de uso

Dart 
import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.clipboardAttribution = true;

collectOAID

Propiedad collectOAID de SingularConfig

Habilita la recopilación del identificador de dispositivo anónimo abierto (OAID) en dispositivos Android. OAID es un identificador publicitario utilizado principalmente en China.

Firma

bool collectOAID

Ejemplo de uso

Dart 
import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.collectOAID = true;

conversionValueUpdatedCallback

Propiedad conversionValueUpdatedCallback de SingularConfig

Establece una función de devolución de llamada que se activa cuando se actualiza el valor de conversión de SKAdNetwork (sólo iOS). Esta llamada de retorno recibe el nuevo valor de conversión como parámetro.

Firma

ConversionValueUpdatedCallback? conversionValueUpdatedCallback

Ejemplo de uso

Dart 
import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.conversionValueUpdatedCallback = (int conversionValue) {
  print('SKAdNetwork conversion value updated: $conversionValue');
};

conversionValuesUpdatedCallback

Propiedad SingularConfig.conversionValuesUpdatedCallback

Establece una función de devolución de llamada para los valores de conversión de SKAdNetwork 4.0+ (sólo iOS 16.1+). Esta devolución de llamada recibe el valor de conversión fino, el valor de conversión grueso y el estado de bloqueo.

Firma

ConversionValuesUpdatedCallback? conversionValuesUpdatedCallback

Ejemplo de uso

Dart 
import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.conversionValuesUpdatedCallback = (int conversionValue, int coarse, bool lock) {
  print('Fine: $conversionValue, Coarse: $coarse, Locked: $lock');
};

customSdid

Propiedad singularConfig.customSdid

Establece un identificador de dispositivo singular (SDID) personalizado. Esto le permite proporcionar su propio identificador de dispositivo en lugar de utilizar el generado por el SDK.

Firma

String? customSdid

Ejemplo de uso

Dart 
import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.customSdid = 'my_custom_device_id_123';

customUserId

Propiedad customUserId de SingularConfig

Establece un identificador de usuario personalizado durante la inicialización del SDK. Esto asocia todos los eventos con el identificador de usuario de su aplicación desde el principio.

Firma

String? customUserId

Ejemplo de uso

Dart 
import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.customUserId = 'user_12345';

deviceAttributionCallback

Propiedad deviceAttributionCallback de SingularConfig

Establece una función de devolución de llamada que recibe los datos de atribución del dispositivo. Esta devolución de llamada se activa cuando la información de atribución está disponible en los servidores de Singular.

Firma

DeviceAttributionCallback? deviceAttributionCallback

Ejemplo de uso

Dart 
import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.deviceAttributionCallback = (Map<String, dynamic> attributes) {
  print('Attribution data received:');
  attributes.forEach((key, value) {
    print('  $key: $value');
  });
};

didSetSdidCallback

Propiedad didSetSdidCallback de SingularConfig

Establece una función de devolución de llamada que se activa después de que el SDK haya establecido el ID de dispositivo Singular (SDID).

Firma

SdidAccessorCallback? didSetSdidCallback

Ejemplo de uso

Dart 
import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.didSetSdidCallback = (String sdid) {
  print('SDID has been set: $sdid');
};

enableLogging

Propiedad enableLogging de SingularConfig

Activa el registro de depuración para Singular SDK. Cuando está activada, el SDK genera registros detallados que ayudan a depurar y solucionar problemas.

Firma

bool enableLogging

Ejemplo de uso

Dart 
import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.enableLogging = true;

enableOdmWithTimeoutInterval

Propiedad SingularConfig.enableOdmWithTimeoutInterval

Activa On-Device Matching (ODM) con un intervalo de tiempo de espera especificado en segundos. ODM mejora la precisión de la atribución comparando los identificadores de dispositivo localmente antes de enviar los datos a los servidores de Singular.

Firma

int enableOdmWithTimeoutInterval

Ejemplo de uso

Dart 
import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.enableOdmWithTimeoutInterval = 5; // 5 seconds timeout

facebookAppId

Propiedad SingularConfig.facebookAppId

Establece el ID de la aplicación de Facebook para la integración de atribución de Facebook. Esto permite un seguimiento de atribución adecuado para las campañas publicitarias de Facebook.

Firma

String? facebookAppId

Ejemplo de uso

Dart 
import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.facebookAppId = '1234567890123456';

globalProperties

Propiedad SingularConfig.globalProperties

Establece una lista de propiedades globales durante la inicialización del SDK. Estas propiedades se incluirán automáticamente con cada evento rastreado por el SDK.

Firma

List<SingularGlobalProperty> globalProperties

Ejemplo de uso

Dart 
import 'package:singular_flutter_sdk/singular_config.dart';
import 'package:singular_flutter_sdk/singular_global_property.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.globalProperties = [
  SingularGlobalProperty('app_version', '2.5.0', true),
  SingularGlobalProperty('user_tier', 'premium', false)
];

imei

Propiedad singularConfig.imei

Establece el IMEI (International Mobile Equipment Identity) del dispositivo para el seguimiento. Se utiliza principalmente en determinados mercados asiáticos en los que el IMEI es un identificador de dispositivo común.

Firma

String? imei

Ejemplo de uso

Dart 
import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.imei = '123456789012345';

limitAdvertisingIdentifiers

Propiedad limitAdvertisingIdentifiers de SingularConfig

Limita la recopilación de identificadores de publicidad (IDFA en iOS, GAID en Android) durante la inicialización del SDK. Cuando está activada, el SDK no recopilará ni transmitirá identificadores de publicidad.

Firma

bool limitAdvertisingIdentifiers

Ejemplo de uso

Dart 
import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.limitAdvertisingIdentifiers = true;

limitDataSharing

Propiedad singularConfig.limitDataSharing

Limita el uso compartido de datos con terceros durante la inicialización del SDK. Si está activada, el SDK restringirá el uso compartido de datos de atribución con redes publicitarias y otros socios.

Firma

bool? limitDataSharing

Ejemplo de uso

Dart 
import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.limitDataSharing = true;

logLevel

Propiedad SingularConfig.logLevel

Establece el nivel de registro del SDK. Los valores más altos proporcionan una salida de registro más detallada con fines de depuración.

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

int logLevel

Ejemplo de uso

Dart 
import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.logLevel = 5; // Maximum logging detail

manualSkanConversionManagement

Propiedad manualSkanConversionManagement de SingularConfig

Activa la gestión manual del valor de conversión de SKAdNetwork (sólo iOS). Cuando está activada, el SDK no actualiza automáticamente los valores de conversión, lo que le permite tener un control total sobre cuándo y cómo se establecen los valores de conversión.

Firma

bool manualSkanConversionManagement

Ejemplo de uso

Dart 
import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.manualSkanConversionManagement = true;

sdidReceivedCallback

Propiedad SingularConfig.sdidReceivedCallback

Establece una función de devolución de llamada que se activa cuando el ID de dispositivo singular (SDID) se recibe del servidor o se recupera del almacenamiento local.

Firma

SdidAccessorCallback? sdidReceivedCallback

Ejemplo de uso

Dart 
import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.sdidReceivedCallback = (String sdid) {
  print('SDID received: $sdid');
};

sessionTimeout

Propiedad SingularConfig.sessionTimeout

Establece la duración del tiempo de espera de la sesión en segundos. Tras este periodo de inactividad, el SDK considerará que se trata de una nueva sesión cuando se vuelva a abrir la aplicación.

Firma

double sessionTimeout

Ejemplo de uso

Dart 
import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.sessionTimeout = 60.0; // 60 seconds

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 que se agote el tiempo de espera.

Firma

double shortLinkResolveTimeOut

Ejemplo de uso

Dart 
import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.shortLinkResolveTimeOut = 10.0; // 10 seconds

singularLinksHandler

Propiedad singularConfig.singularLinksHandler

Establece un controlador de devolución de llamada para los enlaces singulares (enlaces profundos). Esta llamada de retorno se activa cuando un usuario abre la aplicación a través de un enlace corto Singular o un enlace profundo diferido.

Firma

SingularLinksHandler? singularLinksHandler

Ejemplo de uso

Dart 
import 'package:singular_flutter_sdk/singular_config.dart';
import 'package:singular_flutter_sdk/singular_link_params.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.singularLinksHandler = (SingularLinkParams params) {
  print('Deep link received:');
  print('  Deep link: ${params.deeplink}');
  print('  Passthrough: ${params.passthrough}');
  print('  Is deferred: ${params.isDeferred}');
};

skAdNetworkEnabled

Propiedad SingularConfig.skAdNetworkEnabled

Activa o desactiva la integración de SKAdNetwork (sólo iOS). Si está activada, el SDK gestionará automáticamente las actualizaciones de valores de atribución y conversión de SKAdNetwork.

Firma

bool skAdNetworkEnabled

Ejemplo de uso

Dart 
import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.skAdNetworkEnabled = true;

waitForTrackingAuthorizationWithTimeoutInterval

Propiedad singularConfig.waitForTrackingAuthorizationWithTimeoutInterval

Establece un intervalo de tiempo de espera en segundos para la autorización de App Tracking Transparency (ATT) en iOS. El SDK retrasará la inicialización hasta que el usuario responda a la solicitud de ATT o se alcance el tiempo de espera.

Firma

int waitForTrackingAuthorizationWithTimeoutInterval

Ejemplo de uso

Dart 
import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.waitForTrackingAuthorizationWithTimeoutInterval = 30; // 30 seconds

Ejemplo completo de configuración

A continuación se muestra un ejemplo completo que muestra cómo configurar el SDK Singular con múltiples opciones para una aplicación Flutter.

Dart 
import 'package:flutter/material.dart';
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';
import 'package:singular_flutter_sdk/singular_link_params.dart';
import 'package:singular_flutter_sdk/singular_global_property.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    initSingularSDK();
  }

  void initSingularSDK() {
    // Create configuration object
    SingularConfig config = SingularConfig(
      'YOUR_API_KEY',
      'YOUR_SECRET_KEY'
    );

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

    // Set custom user ID if available
    config.customUserId = 'user_12345';

    // Configure session timeout
    config.sessionTimeout = 60.0;

    // Enable clipboard attribution
    config.clipboardAttribution = true;

    // Configure SKAdNetwork (iOS)
    config.skAdNetworkEnabled = true;
    config.manualSkanConversionManagement = false;
    config.waitForTrackingAuthorizationWithTimeoutInterval = 30;

    // Set conversion value callbacks (iOS)
    config.conversionValueUpdatedCallback = (int conversionValue) {
      print('SKAdNetwork conversion value updated: $conversionValue');
    };

    config.conversionValuesUpdatedCallback = (int cv, int coarse, bool lock) {
      print('SKAdNetwork values - Fine: $cv, Coarse: $coarse, Lock: $lock');
    };

    // Configure deep link handling
    config.singularLinksHandler = (SingularLinkParams params) {
      print('Singular Link detected');
      print('Deep link: ${params.deeplink}');
      print('Passthrough params: ${params.passthrough}');
      print('Is deferred: ${params.isDeferred}');

      // Handle deep link navigation
      if (params.deeplink != null) {
        // Navigate to appropriate screen based on deep link
      }
    };

    // Set short link timeout
    config.shortLinkResolveTimeOut = 10.0;

    // Configure attribution callback
    config.deviceAttributionCallback = (Map<String, dynamic> attributes) {
      print('Attribution data received:');
      attributes.forEach((key, value) {
        print('  $key: $value');
      });
    };

    // Configure SDID callbacks
    config.sdidReceivedCallback = (String sdid) {
      print('SDID received: $sdid');
    };

    config.didSetSdidCallback = (String sdid) {
      print('SDID has been set: $sdid');
    };

    // Set global properties
    config.globalProperties = [
      SingularGlobalProperty('app_version', '2.5.0', true),
      SingularGlobalProperty('user_tier', 'premium', false),
      SingularGlobalProperty('environment', 'production', true)
    ];

    // Configure Facebook integration
    config.facebookAppId = '1234567890123456';

    // Privacy settings
    config.limitDataSharing = false;
    config.limitAdvertisingIdentifiers = false;

    // Android-specific settings
    config.collectOAID = true;

    // Enable On-Device Matching
    config.enableOdmWithTimeoutInterval = 5;

    // Start the SDK
    Singular.start(config);

    print('Singular SDK initialized successfully');
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Singular Flutter Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: Scaffold(
        appBar: AppBar(
          title: Text('Singular SDK Demo'),
        ),
        body: Center(
          child: Text('Singular SDK Initialized'),
        ),
      ),
    );
  }
}