SDK do Flutter - Referência de métodos de configuração

Seguir
Avatar
Jared Ornstead
Updated
Documento

SDK do Flutter - Referência de Configuração

Este documento fornece uma referência abrangente para todas as opções de configuração disponíveis no SDK Singular para aplicativos Flutter. O objeto SingularConfig permite personalizar o comportamento do SDK, incluindo configurações de rastreamento, opções de atribuição, controles de privacidade e muito mais. Cada propriedade de configuração é apresentada com uma descrição, assinatura e exemplos práticos de uso.

clipboardAttribution

Propriedade SingularConfig.clipboardAttribution

Ativa a atribuição da área de transferência para rastrear links diretos copiados para a área de transferência do dispositivo. Quando ativado, o SDK verificará se há links Singular na área de transferência ao iniciar o aplicativo.

Assinatura

bool clipboardAttribution

Exemplo de uso

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

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

collectOAID

Propriedade SingularConfig.collectOAID

Permite a recolha do Open Anonymous Device Identifier (OAID) em dispositivos Android. O OAID é um identificador de publicidade utilizado principalmente na China.

Assinatura

bool collectOAID

Exemplo de utilização

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

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

conversionValueUpdatedCallback

Propriedade SingularConfig.conversionValueUpdatedCallback

Define uma função de retorno de chamada que é acionada quando o valor de conversão SKAdNetwork é atualizado (apenas iOS). Esta chamada de retorno recebe o novo valor de conversão como parâmetro.

Assinatura

ConversionValueUpdatedCallback? conversionValueUpdatedCallback

Exemplo de utilização

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

Propriedade SingularConfig.conversionValuesUpdatedCallback

Define uma função de chamada de retorno para os valores de conversão da SKAdNetwork 4.0+ (apenas iOS 16.1+). Esta chamada de retorno recebe o valor de conversão fino, o valor de conversão grosseiro e o estado do bloqueio.

Assinatura

ConversionValuesUpdatedCallback? conversionValuesUpdatedCallback

Exemplo de utilização

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

Propriedade SingularConfig.customSdid

Define um ID de dispositivo singular (SDID) personalizado. Isto permite-lhe fornecer o seu próprio identificador de dispositivo em vez de utilizar o gerado pelo SDK.

Assinatura

String? customSdid

Exemplo de utilização

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

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

customUserId

Propriedade SingularConfig.customUserId

Define um identificador de usuário personalizado durante a inicialização do SDK. Isto associa todos os eventos com o ID de utilizador da sua aplicação desde o início.

Assinatura

String? customUserId

Exemplo de utilização

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

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

deviceAttributionCallback

Propriedade SingularConfig.deviceAttributionCallback

Define uma função de retorno de chamada que recebe dados de atribuição do dispositivo. Essa chamada de retorno é acionada quando as informações de atribuição ficam disponíveis nos servidores Singular.

Assinatura

DeviceAttributionCallback? deviceAttributionCallback

Exemplo 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

Propriedade SingularConfig.didSetSdidCallback

Define uma função de retorno de chamada que é acionada depois que a ID do Dispositivo Singular (SDID) foi definida pelo SDK.

Assinatura

SdidAccessorCallback? didSetSdidCallback

Exemplo 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

Propriedade SingularConfig.enableLogging

Habilita o registro de depuração para o SDK Singular. Quando ativado, o SDK produzirá logs detalhados para ajudar na depuração e solução de problemas.

Assinatura

bool enableLogging

Exemplo de uso

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

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

enableOdmWithTimeoutInterval

Propriedade SingularConfig.enableOdmWithTimeoutInterval

Ativa a Correspondência no Dispositivo (ODM) com um intervalo de tempo limite especificado em segundos. O ODM melhora a precisão da atribuição ao fazer a correspondência de identificadores de dispositivos localmente antes de enviar dados para os servidores Singular.

Assinatura

int enableOdmWithTimeoutInterval

Exemplo 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

Propriedade SingularConfig.facebookAppId

Define a ID do aplicativo do Facebook para integração de atribuição do Facebook. Isso permite o rastreamento de atribuição adequado para campanhas de anúncios do Facebook.

Assinatura

String? facebookAppId

Exemplo de uso

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

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

globalProperties

Propriedade SingularConfig.globalProperties

Define uma lista de propriedades globais durante a inicialização do SDK. Essas propriedades serão incluídas automaticamente em todos os eventos rastreados pelo SDK.

Assinatura

List<SingularGlobalProperty> globalProperties

Exemplo 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

Propriedade SingularConfig.imei

Define o IMEI (International Mobile Equipment Identity - Identidade Internacional do Equipamento Móvel) do dispositivo para efeitos de seguimento. É utilizado principalmente em determinados mercados asiáticos, onde o IMEI é um identificador de dispositivo comum.

Assinatura

String? imei

Exemplo de utilização

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

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

limitAdvertisingIdentifiers

Propriedade SingularConfig.limitAdvertisingIdentifiers

Limita a recolha de identificadores de publicidade (IDFA no iOS, GAID no Android) durante a inicialização do SDK. Quando ativado, o SDK não coletará ou transmitirá IDs de publicidade.

Assinatura

bool limitAdvertisingIdentifiers

Exemplo de utilização

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

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

limitDataSharing

Propriedade SingularConfig.limitDataSharing

Limita a partilha de dados com terceiros durante a inicialização do SDK. Quando ativado, o SDK restringirá a partilha de dados de atribuição com redes de anúncios e outros parceiros.

Assinatura

bool? limitDataSharing

Exemplo de utilização

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

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

logLevel

Propriedade SingularConfig.logLevel

Define o nível de registo para o SDK. Valores mais altos fornecem uma saída de registo mais detalhada para fins de depuração.

Os níveis disponíveis são:

  • NONE = -1

  • VERBOSE = Log.VERBOSE (constante do Android, valor numérico 2)

  • DEBUG = Log.DEBUG (3)

  • INFO = Log.INFO (4)

  • WARNING = Log.WARN (5)

  • ERROR = Log.ERROR (6)

Assinatura

int logLevel

Exemplo de utilização

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

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

manualSkanConversionManagement

Propriedade SingularConfig.manualSkanConversionManagement

Ativa a gestão manual dos valores de conversão da SKAdNetwork (apenas iOS). Quando ativado, o SDK não actualizará automaticamente os valores de conversão, dando-lhe controlo total sobre quando e como os valores de conversão são definidos.

Assinatura

bool manualSkanConversionManagement

Exemplo de utilização

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

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

sdidReceivedCallback

Propriedade SingularConfig.sdidReceivedCallback

Define uma função de retorno de chamada que é acionada quando a ID de Dispositivo Singular (SDID) é recebida do servidor ou recuperada do armazenamento local.

Assinatura

SdidAccessorCallback? sdidReceivedCallback

Exemplo de utilização

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

Propriedade SingularConfig.sessionTimeout

Define a duração do tempo limite da sessão em segundos. Após este período de inatividade, o SDK considerará que se trata de uma nova sessão quando a aplicação for reaberta.

Assinatura

double sessionTimeout

Exemplo de utilização

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

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

shortLinkResolveTimeOut

Propriedade SingularConfig.shortLinkResolveTimeOut

Define a duração do tempo limite em segundos para a resolução de links curtos. Determina quanto tempo o SDK aguardará a resolução de um link curto antes de atingir o tempo limite.

Assinatura

double shortLinkResolveTimeOut

Exemplo 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

SingularConfig.singularLinksHandler Propriedade

Define um manipulador de chamada de retorno para Singular Links (links diretos). Esta chamada de retorno é acionada quando um utilizador abre a aplicação através de um link curto Singular ou de um link profundo diferido.

Assinatura

SingularLinksHandler? singularLinksHandler

Exemplo de utilização

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

Propriedade SingularConfig.skAdNetworkEnabled

Habilita ou desabilita a integração com SKAdNetwork (somente iOS). Quando ativado, o SDK processa automaticamente as actualizações de atribuição e de valor de conversão da SKAdNetwork.

Assinatura

bool skAdNetworkEnabled

Exemplo de utilização

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

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

waitForTrackingAuthorizationWithTimeoutInterval

Propriedade SingularConfig.waitForTrackingAuthorizationWithTimeoutInterval

Define um intervalo de tempo limite em segundos para aguardar a autorização do App Tracking Transparency (ATT) no iOS. O SDK atrasará a inicialização até que o utilizador responda à solicitação ATT ou o tempo limite seja atingido.

Assinatura

int waitForTrackingAuthorizationWithTimeoutInterval

Exemplo de uso

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

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

Exemplo de configuração completa

Abaixo está um exemplo abrangente que mostra como configurar o SDK Singular com várias opções para um aplicativo 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'),
        ),
      ),
    );
  }
}