剪贴板属性

SingularConfig.clipboardAttribution 属性

为 SDK 启用剪贴板属性。启用后，SDK 将在初始化过程中检查设备剪贴板中的归属链接。

签名

bool clipboardAttribution = false;

使用示例

// Enable clipboard attribution
config.clipboardAttribution = true;

collectOAID

SingularConfig.collectOAID 属性

在支持的 Android 设备上启用收集 OAID（开放式匿名设备标识符）。这是某些地区（尤其是中国）使用的替代标识符。

签名

bool collectOAID = false;

使用示例

// Enable OAID collection
config.collectOAID = true;

转换值更新回调（conversionValueUpdatedCallback

SingularConfig.conversionValueUpdatedCallback 属性

设置 SKAdNetwork 转换值更新时调用的回调函数。这是 iOS 特有的功能，可让您对转换值变化做出反应。

签名

ConversionValueUpdatedCallback? conversionValueUpdatedCallback;

使用示例

// 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

SingularConfig.conversionValuesUpdatedCallback 属性

设置 SKAdNetwork 4.0 转换值更新时调用的回调函数。这是 iOS 16.1+ 特有的功能，可让您对精细值、粗调值和锁定值的变化做出反应。

签名

ConversionValuesUpdatedCallback? conversionValuesUpdatedCallback;

使用示例

// 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

SingularConfig.customSdid 属性

签名

String? customSdid;

使用示例

// Set custom SDID
config.customSdid = "custom-device-id-12345";

自定义用户标识

SingularConfig.customUserId 属性

在 SDK 初始化过程中设置自定义用户 ID。这样就可以从一开始就将 Singular 数据与自己的用户识别系统关联起来。

签名

String? customUserId;

使用示例

// Set custom user ID
config.customUserId = "user_123456";

deviceAttributionCallback

SingularConfig.deviceAttributionCallback 属性

签名

DeviceAttributionCallback? deviceAttributionCallback;

使用示例

// 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

SingularConfig.didSetSdidCallback 属性

签名

SdidAccessorCallback? didSetSdidCallback;

使用示例

// 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
};

启用记录

SingularConfig.enableLogging 属性

启用 SDK 的详细日志记录。启用后，SDK 将输出有助于调试的详细日志。

签名

bool enableLogging = false;

使用示例

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

espDomains

SingularConfig.espDomains 属性

设置电子邮件归属的 ESP（电子邮件服务提供商）域。这使您可以指定哪些电子邮件域应被视为归属。

签名

List espDomains = [];

使用示例

// Set ESP domains for email attribution
config.espDomains = [
    "mailchimp.com",
    "sendgrid.net",
    "campaign-monitor.com"
];

facebookAppId

SingularConfig.facebookAppId 属性

为 Facebook 归因设置 Facebook 应用程序 ID。这样，SDK 就能对来自 Facebook 营销活动的安装和事件进行归因。

签名

String? facebookAppId;

使用示例

// Set Facebook App ID for attribution
config.facebookAppId = "123456789012345";

imei

SingularConfig.imei 属性

设置设备的 IMEI（国际移动设备标识）。这通常用于以 IMEI 作为通用标识符的市场。

签名

String? imei;

使用示例

// Set IMEI (only if you have proper permission to access it)
config.imei = "123456789012345";

limitDataSharing 属性

SingularConfig.limitDataSharing 属性

在 SDK 初始化过程中设置数据共享限制状态。使用该属性可根据用户同意或隐私要求限制数据共享。

签名

bool? limitDataSharing;

使用示例

// Get user consent status
bool hasUserConsent = getUserConsentStatus();

// Set data sharing limitation based on consent
config.limitDataSharing = !hasUserConsent;

limitedIdentifiersEnabled

SingularConfig.limitedIdentifiersEnabled 属性

启用或禁用有限标识符的使用。该选项会影响 SDK 如何收集和使用设备标识符进行跟踪和归因。

签名

bool limitedIdentifiersEnabled = false;

使用示例

// Enable limited identifiers mode
config.limitedIdentifiersEnabled = true;

日志级别

SingularConfig.logLevel 属性

设置 SDK 的日志级别。它控制 SDK 生成日志的冗长程度。默认值为-1（无日志记录）。常用值有0（错误）、1（警告）、2（信息）、3（调试）、4（详细）。

签名

int logLevel = -1;

使用示例

// Set log level to debug
config.logLevel = 3;

manualSkanConversionManagement

SingularConfig.manualSkanConversionManagement 属性

启用手动管理 SKAdNetwork 转换值。启用后，SDK 不会自动更新转换值，您可以手动控制转换值。

签名

bool manualSkanConversionManagement = false;

使用示例

// Enable manual SKAdNetwork conversion management
config.manualSkanConversionManagement = true;

pushNotificationsLinkPaths

SingularConfig.pushNotificationsLinkPaths 属性

设置在推送通知有效载荷中查找深度链接的路径。这有助于 SDK 查找和处理推送通知中的属性链接。

签名

List<List<String>> pushNotificationsLinkPaths = [[]];

使用示例

// Set push notification link paths
config.pushNotificationsLinkPaths = [
    ["data", "deeplink"],
    ["notification", "data", "url"],
    ["custom", "link"]
];

sdidReceivedCallback

SingularConfig.sdidReceivedCallback 属性

签名

SdidAccessorCallback? sdidReceivedCallback;

使用示例

// Set callback for when SDID is received
config.sdidReceivedCallback = (String sdid) {
    print("SDID received: $sdid");
    // Store or use the SDID as needed
    storeDeviceIdentifier(sdid);
};

会话超时

SingularConfig.sessionTimeout 属性

设置会话超时（以秒为单位）。这决定了应用程序进入后台后用户会话的持续时间。默认值为-1，即使用 SDK 的默认超时（60 秒）。

签名

double sessionTimeout = -1;

使用示例

// Set session timeout to 2 minutes
config.sessionTimeout = 120;

shortLinkResolveTimeOut

SingularConfig.shortLinkResolveTimeOut 属性

设置解析短链接的超时（秒）。这决定了 SDK 在继续初始化之前等待短链接解析的时间。默认值为 10 秒。

签名

double shortLinkResolveTimeOut = 10.0;

使用示例

// Set short link resolve timeout to 15 seconds
config.shortLinkResolveTimeOut = 15.0;

singularLinksHandler

SingularConfig.singularLinksHandler 属性

设置一个回调函数，用于处理由 Singular 处理的深度链接。这样，你的应用程序就能对归属中使用的深层链接做出响应。

签名

SingularLinksHandler? singularLinksHandler;

使用示例

// 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

SingularConfig.skAdNetworkEnabled 属性

启用或禁用 SKAdNetwork 支持。这是 iOS 特有的属性，用于控制 SDK 是否使用 Apple 的 SKAdNetwork 进行归属。默认值为 true。

签名

bool skAdNetworkEnabled = true;

使用示例

// Disable SKAdNetwork support if needed
config.skAdNetworkEnabled = false;

waitForTrackingAuthorizationWithTimeoutInterval

SingularConfig.waitForTrackingAuthorizationWithTimeoutInterval 属性

设置在 iOS 14+ 上等待用户跟踪授权响应的超时间隔（以秒为单位）。这决定了 SDK 在继续初始化之前要等待 ATT 提示响应多长时间。默认值为 0，表示 SDK 不会等待 ATT 提示响应。

签名

int waitForTrackingAuthorizationWithTimeoutInterval = 0;

使用示例

// Wait up to 5 seconds for ATT prompt response
config.waitForTrackingAuthorizationWithTimeoutInterval = 5;

withGlobalProperty

SingularConfig.withGlobalProperty 方法

在 SDK 初始化过程中设置全局属性。该属性将与 SDK 跟踪的所有事件一起发送。这是一个方法而非属性，允许链式配置。

签名

void withGlobalProperty(String key, String value, bool overrideExisting)

使用示例

// Add global properties
config.withGlobalProperty("app_version", "1.2.3", true);
config.withGlobalProperty("user_type", "free", true);

完整配置示例

全面的 SDK 配置

下面的示例演示了如何通过同时设置多个配置属性和方法来创建综合配置。

完整示例

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