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.

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

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

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

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

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

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

import 'package:singular_flutter_sdk/singular_config.dart';

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

deviceAttributionCallback

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.

Signature

DeviceAttributionCallback? deviceAttributionCallback

Usage Example

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

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

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

import 'package:singular_flutter_sdk/singular_config.dart';

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

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

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

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

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

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

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

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

import 'package:singular_flutter_sdk/singular_config.dart';

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

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

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

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

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

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

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

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.

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

Flutter SDK - Configuration Methods Reference

Flutter SDK - Configuration Reference

clipboardAttribution

SingularConfig.clipboardAttribution Property

Signature

Usage Example

collectOAID

SingularConfig.collectOAID Property

Signature

Usage Example

conversionValueUpdatedCallback

SingularConfig.conversionValueUpdatedCallback Property

Signature

Usage Example

conversionValuesUpdatedCallback

SingularConfig.conversionValuesUpdatedCallback Property

Signature

Usage Example

customSdid

SingularConfig.customSdid Property

Signature

Usage Example

customUserId

SingularConfig.customUserId Property

Signature

Usage Example

deviceAttributionCallback

SingularConfig.deviceAttributionCallback Property

Signature

Usage Example

didSetSdidCallback

SingularConfig.didSetSdidCallback Property

Signature

Usage Example

enableLogging

SingularConfig.enableLogging Property

Signature

Usage Example

enableOdmWithTimeoutInterval

SingularConfig.enableOdmWithTimeoutInterval Property

Signature

Usage Example

facebookAppId

SingularConfig.facebookAppId Property

Signature

Usage Example

globalProperties

SingularConfig.globalProperties Property

Signature

Usage Example

imei

SingularConfig.imei Property

Signature

Usage Example

limitAdvertisingIdentifiers

SingularConfig.limitAdvertisingIdentifiers Property

Signature

Usage Example

limitDataSharing

SingularConfig.limitDataSharing Property

Signature

Usage Example

logLevel

SingularConfig.logLevel Property

Signature

Usage Example

manualSkanConversionManagement

SingularConfig.manualSkanConversionManagement Property

Signature

Usage Example

sdidReceivedCallback

SingularConfig.sdidReceivedCallback Property

Signature

Usage Example

sessionTimeout

SingularConfig.sessionTimeout Property

Signature

Usage Example

shortLinkResolveTimeOut

SingularConfig.shortLinkResolveTimeOut Property