Flutter SDK - Configuration Methods Reference

Follow
Avatar
Jared Ornstead
Updated

Flutter SDK - Configuration Reference

This document provides a comprehensive reference for all configuration options available in the Singular SDK for Flutter applications. The SingularConfig object allows you to customize the SDK's behavior, including tracking settings, attribution options, privacy controls, and more. Each configuration property is presented with a description, signature, and practical usage examples.

brandedDomains

SingularConfig.brandedDomains Property

Custom link domains the SDK should treat as Singular Links. Add every branded domain you use for tracking links — without this, only the sng.link domains registered on the Manage Links page are recognized. Defaults to an empty list.

Signature

List<String> brandedDomains

Usage Example

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.brandedDomains = ['go.yourcompany.com', 'promo.yourcompany.com'];

clipboardAttribution

SingularConfig.clipboardAttribution Property

Enables clipboard attribution for tracking deep links copied to the device clipboard. When enabled, the SDK will check the clipboard for Singular links upon app launch.

Signature

bool clipboardAttribution

Usage Example

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

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

collectOAID

SingularConfig.collectOAID Property

Enables collection of Open Anonymous Device Identifier (OAID) on Android devices. OAID is an advertising identifier used primarily in China.

Signature

bool collectOAID

Usage Example

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

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

conversionValueUpdatedCallback

SingularConfig.conversionValueUpdatedCallback Property

Sets a callback function that is triggered when the SKAdNetwork conversion value is updated (iOS only). This callback receives the new conversion value as a parameter.

Signature

ConversionValueUpdatedCallback? conversionValueUpdatedCallback

Usage Example

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

SingularConfig.conversionValuesUpdatedCallback Property

Sets a callback function for SKAdNetwork 4.0+ conversion values (iOS 16.1+ only). This callback receives the fine conversion value, coarse conversion value, and lock status.

Signature

ConversionValuesUpdatedCallback? conversionValuesUpdatedCallback

Usage Example

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

SingularConfig.customSdid Property

Sets a custom Singular Device ID (SDID). This allows you to provide your own device identifier instead of using the SDK-generated one.

Signature

String? customSdid

Usage Example

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

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

customUserId

SingularConfig.customUserId Property

Sets a custom user identifier during SDK initialization. This associates all events with your application's user ID from the start.

Signature

String? customUserId

Usage Example

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

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

deviceAttributionCallback

BETA Feature - Sets a callback function to be called when device attribution data is available.

SingularConfig.deviceAttributionCallback Property

Sets a callback function that receives device attribution data. This callback is triggered when attribution information becomes available from the Singular servers.

Only fields that have a value are included, so check for a key before reading it. Most installs return a subset — which fields are present depends on the touchpoint Singular matched.

Key Type Notes
network String Always present when the callback fires. "Organic" when no touchpoint was matched.
campaign_id String Present when the touchpoint provides it.
campaign_name String Present when the touchpoint provides it.
subcampaign_id String Present when the touchpoint provides it. Not available from every source.
subcampaign_name String Present when the touchpoint provides it. Not available from every source.
creative_id String Present when the touchpoint provides it. Not available from every source.
creative_name String Present when the touchpoint provides it. Not available from every source.
passthrough String Present when passthrough values were attached to the link.
match_type String Present when the touchpoint provides it. Contact Singular if you need the value set.
click_timestamp int Present when the touchpoint provides it. Epoch microseconds — divide by 1,000,000 for seconds.

Signature

DeviceAttributionCallback? deviceAttributionCallback

Usage Example

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

SingularConfig.didSetSdidCallback Property

Sets a callback function that is triggered after the Singular Device ID (SDID) has been set by the SDK.

Signature

SdidAccessorCallback? didSetSdidCallback

Usage Example

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

SingularConfig.enableLogging Property

Enables debug logging for the Singular SDK. When enabled, the SDK will output detailed logs to help with debugging and troubleshooting.

Signature

bool enableLogging

Usage Example

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

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

enableOdmWithTimeoutInterval

SingularConfig.enableOdmWithTimeoutInterval Property

Enables On-Device Matching (ODM) with a specified timeout interval in seconds. ODM improves attribution accuracy by matching device identifiers locally before sending data to Singular servers.

Signature

int enableOdmWithTimeoutInterval

Usage Example

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

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

espDomains

SingularConfig.espDomains Property

Domains belonging to an Email Service Provider that wraps your Singular Links. When a link arrives on one of these domains the SDK follows the redirect to recover the underlying Singular Link, so the click is still attributed. Defaults to an empty list.

Signature

List<String> espDomains

Usage Example

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.espDomains = ['sl.esp.link', 'links.youresp.com'];

facebookAppId

SingularConfig.facebookAppId Property

Sets the Facebook App ID for Facebook attribution integration. This enables proper attribution tracking for Facebook ad campaigns.

Signature

String? facebookAppId

Usage Example

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

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

globalProperties

SingularConfig.globalProperties Property

Sets a list of global properties during SDK initialization. These properties will be automatically included with every event tracked by the SDK.

Signature

List<SingularGlobalProperty> globalProperties

Usage Example

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

SingularConfig.imei Property

Sets the device IMEI (International Mobile Equipment Identity) for tracking. This is primarily used in certain Asian markets where IMEI is a common device identifier.

Signature

String? imei

Usage Example

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

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

limitAdvertisingIdentifiers

SingularConfig.limitAdvertisingIdentifiers Property

Limits the collection of advertising identifiers (IDFA on iOS, GAID on Android) during SDK initialization. When enabled, the SDK will not collect or transmit advertising IDs.

Signature

bool limitAdvertisingIdentifiers

Usage Example

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

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

limitDataSharing

SingularConfig.limitDataSharing Property

Limits data sharing with third parties during SDK initialization. When enabled, the SDK will restrict sharing attribution data with ad networks and other partners.

Signature

bool? limitDataSharing

Usage Example

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

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

logLevel

SingularConfig.logLevel Property

Sets the logging level for the SDK. Higher values provide more detailed logging output for debugging purposes.

Available levels are:

  • NONE = -1

  • VERBOSE = Log.VERBOSE (Android constant, numeric value 2)

  • DEBUG = Log.DEBUG (3)

  • INFO = Log.INFO (4)

  • WARNING = Log.WARN (5)

  • ERROR = Log.ERROR (6)

Signature

int logLevel

Usage Example

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

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

manualSkanConversionManagement

SingularConfig.manualSkanConversionManagement Property

Enables manual SKAdNetwork conversion value management (iOS only). When enabled, the SDK will not automatically update conversion values, giving you full control over when and how conversion values are set.

Signature

bool manualSkanConversionManagement

Usage Example

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

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

pushNotificationsLinkPaths

SingularConfig.pushNotificationsLinkPaths Property

Where to find the Singular Link inside your push notification payloads. Each entry is a list of keys forming a path through the payload, so add one entry per payload shape your app receives. Defaults to [[]].

Signature

List<List<String>> pushNotificationsLinkPaths

Usage Example

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

SingularConfig config = SingularConfig('API_KEY', 'SECRET_KEY');
config.pushNotificationsLinkPaths = [
  ['sng_link'],                             // Top-level key
  ['data', 'url'],                          // Nested path
  ['rootObj', 'nestedObj', 'singularLink'], // Deep nested path
];

sdidReceivedCallback

SingularConfig.sdidReceivedCallback Property

Sets a callback function that is triggered when the Singular Device ID (SDID) is received from the server or retrieved from local storage.

Signature

SdidAccessorCallback? sdidReceivedCallback

Usage Example

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

SingularConfig.sessionTimeout Property

Sets the session timeout duration in seconds. After this period of inactivity, the SDK will consider it a new session when the app is reopened.

Signature

double sessionTimeout

Usage Example

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

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

shortLinkResolveTimeOut

SingularConfig.shortLinkResolveTimeOut Property

Sets the timeout duration in seconds for resolving short links. This determines how long the SDK will wait for a short link to resolve before timing out.

Signature

double shortLinkResolveTimeOut

Usage Example

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 Property

Sets a callback handler for Singular Links (deep links). This callback is triggered when a user opens the app via a Singular short link or deferred deep link.

Signature

SingularLinksHandler? singularLinksHandler

Usage Example

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

SingularConfig.skAdNetworkEnabled Property

Enables or disables SKAdNetwork integration (iOS only). When enabled, the SDK will automatically handle SKAdNetwork attribution and conversion value updates.

Signature

bool skAdNetworkEnabled

Usage Example

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

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

waitForTrackingAuthorizationWithTimeoutInterval

SingularConfig.waitForTrackingAuthorizationWithTimeoutInterval Property

Sets a timeout interval in seconds to wait for the App Tracking Transparency (ATT) authorization on iOS. The SDK will delay initialization until the user responds to the ATT prompt or the timeout is reached.

Signature

int waitForTrackingAuthorizationWithTimeoutInterval

Usage Example

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

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

Complete Configuration Example

Below is a comprehensive example showing how to configure the Singular SDK with multiple options for a Flutter application.

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'),
        ),
      ),
    );
  }
}