Android SDK - 配置参考

本文档全面介绍了适用于 Android 应用程序的 Singular SDK 中可用的所有配置选项。SingularConfig 对象允许您自定义 SDK 的行为，包括追踪设置、归因选项、隐私控制等。每个配置方法均附带说明、签名和实用使用示例。

完整配置示例

全面 SDK 配置

以下示例展示了如何通过链式调用多个配置方法来创建全面的配置。

完整示例

// Create comprehensive configuration
val config = SingularConfig("SDK KEY", "YOUR_SECRET")
    // Basic options
    .withSessionTimeoutInSec(120)
    .withLoggingEnabled()
    .withLogLevel(Log.VERBOSE)

    // User identification
    .withCustomUserId("user_123456")

    // Global properties
    .withGlobalProperty("app_version", "1.2.3", true)
    .withGlobalProperty("user_type", "premium", true)

    // Deep links
    .withOpenURI(intent.data)
    .withSingularLink(intent, { params ->
        params.deeplink?.let { deeplink ->
            println("Deep link: $deeplink")
            handleDeepLink(deeplink)
        }
    }, 10)

    // Attribution callback
    .withSingularDeviceAttribution { attributionData ->
        println("Attribution: $attributionData")
    }

    // Push notifications
    .withFCMDeviceToken(fcmToken)

    // Privacy settings
    .withLimitDataSharing(false)

    // Email attribution
    .withESPDomains(listOf("mailchimp.com", "sendgrid.net"))

    // Facebook integration
    .withFacebookAppId("YOUR_FACEBOOK_APP_ID")

// Initialize the SDK
Singular.init(context, config)

// Create comprehensive configuration
SingularConfig config = new SingularConfig("SDK KEY", "YOUR_SECRET")
    // Basic options
    .withSessionTimeoutInSec(120)
    .withLoggingEnabled()
    .withLogLevel(Log.VERBOSE)

    // User identification
    .withCustomUserId("user_123456")

    // Global properties
    .withGlobalProperty("app_version", "1.2.3", true)
    .withGlobalProperty("user_type", "premium", true)

    // Deep links
    .withOpenURI(getIntent().getData())
    .withSingularLink(getIntent(), new SingularLinkHandler() {
        @Override
        public void onResolved(SingularLinkParams params) {
            if (params.getDeeplink() != null) {
                System.out.println("Deep link: " + params.getDeeplink());
                handleDeepLink(params.getDeeplink());
            }
        }
    }, 10)

    // Attribution callback
    .withSingularDeviceAttribution(new SingularDeviceAttributionHandler() {
        @Override
        public void onDeviceAttributionInfoReceived(Map<String, Object> attributionData) {
            System.out.println("Attribution: " + attributionData);
        }
    })

    // Push notifications
    .withFCMDeviceToken(fcmToken)

    // Privacy settings
    .withLimitDataSharing(false)

    // Email attribution
    .withESPDomains(Arrays.asList("mailchimp.com", "sendgrid.net"))

    // Facebook integration
    .withFacebookAppId("YOUR_FACEBOOK_APP_ID");

// Initialize the SDK
Singular.init(context, config);

Constructor

SingularConfig 构造函数

使用您的 API 密钥和密文初始化一个新的 SingularConfig 对象。这是配置 Singular SDK 的第一步。

签名

public SingularConfig(String apiKey, String secret);

使用示例

// Create configuration object
val config = SingularConfig("SDK KEY", "YOUR_SECRET")

// Create configuration object
SingularConfig config = new SingularConfig("SDK KEY", "YOUR_SECRET");

withBrandedDomains

SingularConfig.withBrandedDomains 方法

设置用于网页到应用归因的品牌域名。这允许您指定需要为归因目的进行追踪的自定义域名。

调用此方法将替换之前设置的所有品牌域名。请在一次调用中传递完整列表，而不是链式调用多次。

签名

public SingularConfig withBrandedDomains(List<String> brandedDomains);

使用示例

// Set branded domains for web-to-app attribution
val brandedDomains = listOf("yourcompany.com", "go.yourcompany.com")
val config = SingularConfig("API_KEY", "SECRET")
    .withBrandedDomains(brandedDomains)

// Set branded domains for web-to-app attribution
List<String> brandedDomains = Arrays.asList("yourcompany.com", "go.yourcompany.com");
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withBrandedDomains(brandedDomains);

withCustomSdid

SingularConfig.withCustomSdid 方法

企业功能： 设置自定义 SDID（Singular Device ID）。这允许您提供自己的设备标识符，而不是使用 Singular 生成的标识符。

签名

public SingularConfig withCustomSdid(String customSdid, SDIDAccessorHandler accessorHandler);

使用示例

// Set custom SDID with callback
val config = SingularConfig("API_KEY", "SECRET")
    .withCustomSdid("custom-device-id-12345", object : SDIDAccessorHandler {
        override fun didSetSdid(result: String) {
            println("SDID was set: $result")
            // Perform any actions needed after SDID is set
        }

        override fun sdidReceived(result: String) {
            println("SDID received: $result")
            // Existing SDID returned by the SDK
        }
    })

// Set custom SDID with callback
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withCustomSdid("custom-device-id-12345", new SDIDAccessorHandler() {
        @Override
        public void didSetSdid(String result) {
            System.out.println("SDID was set: " + result);
            // Perform any actions needed after SDID is set
        }

        @Override
        public void sdidReceived(String result) {
            System.out.println("SDID received: " + result);
            // Existing SDID returned by the SDK
        }
    });

withCustomUserId

SingularConfig.withCustomUserId 方法

在 SDK 初始化期间设置自定义用户 ID。这允许您从一开始就将 Singular 数据与您自己的用户标识系统关联起来。

签名

public SingularConfig withCustomUserId(String customUserId);

使用示例

// Set custom user ID at initialization
val config = SingularConfig("API_KEY", "SECRET")
    .withCustomUserId("user_123456")

// Set custom user ID at initialization
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withCustomUserId("user_123456");

withESPDomains

SingularConfig.withESPDomains 方法

设置用于邮件归因的 ESP（电子邮件服务提供商）域名。这允许您指定应纳入归因考虑的邮件域名。

调用此方法将替换之前设置的所有 ESP 域名。请在一次调用中传递完整列表，而不是链式调用多次。

签名

public SingularConfig withESPDomains(List<String> espDomains);

使用示例

// Set ESP domains for email attribution
val espDomains = listOf("mailchimp.com", "sendgrid.net", "campaign-monitor.com")
val config = SingularConfig("API_KEY", "SECRET")
    .withESPDomains(espDomains)

// Set ESP domains for email attribution
List<String> espDomains = Arrays.asList("mailchimp.com", "sendgrid.net", "campaign-monitor.com");
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withESPDomains(espDomains);

withFacebookAppId

SingularConfig.withFacebookAppId 方法

设置用于 Facebook 归因集成的 Facebook App ID。这使 SDK 能够追踪 Facebook 广告系列归因。

签名

public SingularConfig withFacebookAppId(String facebookAppId);

使用示例

// Set Facebook App ID
val config = SingularConfig("API_KEY", "SECRET")
    .withFacebookAppId("YOUR_FACEBOOK_APP_ID")

// Set Facebook App ID
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withFacebookAppId("YOUR_FACEBOOK_APP_ID");

withFCMDeviceToken

SingularConfig.withFCMDeviceToken 方法

在初始化时设置 FCM（Firebase Cloud Messaging）设备 token。这可以从一开始就启用推送通知追踪和卸载检测。

如果 token 为 null 或为空，调用将被忽略。请仅在您有有效的 FCM token 时调用此方法。

签名

public SingularConfig withFCMDeviceToken(String fcmDeviceToken);

使用示例

// Set FCM token at initialization if available
val config = SingularConfig("API_KEY", "SECRET")
    .withFCMDeviceToken(fcmToken)

// Set FCM token at initialization if available
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withFCMDeviceToken(fcmToken);

withGlobalProperty

SingularConfig.withGlobalProperty 方法

在 SDK 初始化期间设置全局归因。该归因将随 SDK 追踪的所有事件一起发送。这是一个支持链式调用的配置方法。

SDK 最多支持 5 个全局归因。超出该限制的调用将被静默忽略。

签名

public SingularConfig withGlobalProperty(String key, String value, boolean overrideExisting);

使用示例

// Add global properties at initialization
val config = SingularConfig("API_KEY", "SECRET")
    .withGlobalProperty("app_version", "1.2.3", true)
    .withGlobalProperty("user_type", "free", true)

// Add global properties at initialization
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withGlobalProperty("app_version", "1.2.3", true)
    .withGlobalProperty("user_type", "free", true);

withIMEI

SingularConfig.withIMEI 方法

在初始化时设置用于追踪的设备 IMEI。在允许且首选 IMEI 追踪的地区中使用。

签名

public SingularConfig withIMEI(String imei);

使用示例

// Set device IMEI at initialization
val config = SingularConfig("API_KEY", "SECRET")
    .withIMEI("123456789012345")

// Set device IMEI at initialization
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withIMEI("123456789012345");

withLimitAdvertisingIdentifiers

SingularConfig.withLimitAdvertisingIdentifiers 方法

在混合受众应用中启用受限广告标识符模式。该选项影响 SDK 收集和使用设备标识符进行追踪的方式。

签名

public SingularConfig withLimitAdvertisingIdentifiers();

使用示例

// Enable limited identifiers mode
val config = SingularConfig("API_KEY", "SECRET")
    .withLimitAdvertisingIdentifiers()

// Enable limited identifiers mode
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withLimitAdvertisingIdentifiers();

withLimitDataSharing

SingularConfig.withLimitDataSharing 方法

在初始化时设置数据共享限制状态。请使用此方法根据用户同意或隐私要求来限制数据共享。

签名

public SingularConfig withLimitDataSharing(boolean shouldLimitDataSharing);

使用示例

// Enable limited data sharing at initialization
val config = SingularConfig("API_KEY", "SECRET")
    .withLimitDataSharing(true)

// Enable limited data sharing at initialization
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withLimitDataSharing(true);

withLogLevel

SingularConfig.withLogLevel 方法

设置 SDK 日志记录的日志级别。可用级别包括：

NONE = -1
VERBOSE = Log.VERBOSE（Android 常量，数值 2）
DEBUG = Log.DEBUG (3)
INFO = Log.INFO (4)
WARNING = Log.WARN (5)
ERROR = Log.ERROR (6)

默认日志级别为 Log.ERROR。还必须通过 withLoggingEnabled()启用日志记录才会有输出。

签名

public SingularConfig withLogLevel(int level);

使用示例

import android.util.Log

// Set verbose logging for detailed debugging
val config = SingularConfig("API_KEY", "SECRET")
    .withLoggingEnabled()
    .withLogLevel(Log.VERBOSE)

import android.util.Log;

// Set verbose logging for detailed debugging
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withLoggingEnabled()
    .withLogLevel(Log.VERBOSE);

withLoggingEnabled

SingularConfig.withLoggingEnabled 方法

启用 SDK 日志记录。在开发期间，这对调试和故障排除很有用。建议在生产构建中禁用日志记录。

签名

public SingularConfig withLoggingEnabled();

使用示例

// Enable logging for debug builds
val config = SingularConfig("API_KEY", "SECRET")
    .withLoggingEnabled()

// Enable logging for debug builds
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withLoggingEnabled();

withOAIDCollection

SingularConfig.withOAIDCollection 方法

启用 OAID（Open Anonymous Device Identifier）收集。主要用于无法使用 Google Play Services 的中国地区的追踪。

签名

public SingularConfig withOAIDCollection();

使用示例

// Enable OAID collection for China
val config = SingularConfig("API_KEY", "SECRET")
    .withOAIDCollection()

// Enable OAID collection for China
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withOAIDCollection();

withOpenURI

SingularConfig.withOpenURI 方法

设置打开应用程序的 URI。该 URI 用于深度链接归因，在应用程序通过深度链接打开时应进行设置。

签名

public SingularConfig withOpenURI(Uri openUri);

使用示例

// In your Activity's onCreate or onNewIntent
val uri = intent.data
val config = SingularConfig("API_KEY", "SECRET")
    .withOpenURI(uri)

// In your Activity's onCreate or onNewIntent
Uri uri = getIntent().getData();
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withOpenURI(uri);

withPushNotificationPayload

SingularConfig.withPushNotificationPayload 方法

设置用于归因的推送通知载荷。这允许 SDK 在初始化期间处理推送通知数据。

签名

public SingularConfig withPushNotificationPayload(Intent intent, String[] ... pushNotificationLinkPath);

使用示例

// Set push notification payload with custom link paths
val config = SingularConfig("API_KEY", "SECRET")
    .withPushNotificationPayload(
        intent,
        arrayOf("data", "deeplink"),
        arrayOf("notification", "data", "url"),
        arrayOf("custom", "link")
    )

// Set push notification payload with custom link paths
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withPushNotificationPayload(
        intent,
        new String[]{"data", "deeplink"},
        new String[]{"notification", "data", "url"},
        new String[]{"custom", "link"}
    );

withSdidAccessorHandler

SingularConfig.withSdidAccessorHandler 方法

企业功能： 设置在收到 SDID（Singular Device ID）时调用的回调函数。这允许您在 SDID 可用时立即访问它。

签名

public SingularConfig withSdidAccessorHandler(SDIDAccessorHandler accessorHandler);

使用示例

// Set callback for when SDID is received
val config = SingularConfig("API_KEY", "SECRET")
    .withSdidAccessorHandler(object : SDIDAccessorHandler {
        override fun didSetSdid(result: String) {
            println("SDID was set: $result")
        }

        override fun sdidReceived(result: String) {
            println("SDID received: $result")
            // Store or use the SDID as needed
            storeDeviceIdentifier(result)
        }
    })

// Set callback for when SDID is received
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withSdidAccessorHandler(new SDIDAccessorHandler() {
        @Override
        public void didSetSdid(String result) {
            System.out.println("SDID was set: " + result);
        }

        @Override
        public void sdidReceived(String result) {
            System.out.println("SDID received: " + result);
            // Store or use the SDID as needed
            storeDeviceIdentifier(result);
        }
    });

withSessionTimeoutInSec

SingularConfig.withSessionTimeoutInSec 方法

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

签名

public SingularConfig withSessionTimeoutInSec(long timeout);

使用示例

// Set session timeout to 2 minutes
val config = SingularConfig("API_KEY", "SECRET")
    .withSessionTimeoutInSec(120)

// Set session timeout to 2 minutes
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withSessionTimeoutInSec(120);

withSingularDeviceAttribution

SingularConfig.withSingularDeviceAttribution 方法

BETA 功能： 设置在 /start 响应中提供设备归因数据时要调用的回调函数。该回调在后台线程上触发，因此请将所有 UI 工作分派到主线程。

键	类型	备注
`network`	String	归因来源。 "organic" 表示未归因的安装。
`campaign_id`	String	仅在已归因时存在。
`campaign_name`	String	仅在已归因时存在。
`click_timestamp`	Long（epoch 微秒）	仅在已归因时存在。除以 1,000,000 可转换为秒。

只有当 /start 响应包含 attribution_info 对象时，才会触发该回调。对于自然量安装，仅 network 字段会被填充。

签名

public SingularConfig withSingularDeviceAttribution(SingularDeviceAttributionHandler handler);

使用示例

// Set device attribution callback
val config = SingularConfig("API_KEY", "SECRET")
      .withSingularDeviceAttribution { attributionData ->
          println("Attribution data received: $attributionData")

          val source         = attributionData["network"]        as? String
          val campaignName   = attributionData["campaign_name"]  as? String
          val campaignId     = attributionData["campaign_id"]    as? String
          val clickTimestamp = attributionData["click_timestamp"]?.toString()?.toLongOrNull()

          campaignName?.let { showCampaignSpecificContent(it) }
      }

// Set device attribution callback
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
  .withSingularDeviceAttribution(new SingularDeviceAttributionHandler() {
    @Override
    public void onDeviceAttributionInfoReceived(Map<String, Object> attributionData) {
      Log.d("Singular", "Attribution data received: " + attributionData);
      String source        = (String) attributionData.get("network");
      String campaignName  = (String) attributionData.get("campaign_name");
      String campaignId    = (String) attributionData.get("campaign_id");
      Object clickTsObj    = attributionData.get("click_timestamp");
      Long   clickTimestamp = clickTsObj != null
          ? Long.parseLong(clickTsObj.toString())
          : null;
      if (campaignName != null) {
          showCampaignSpecificContent(campaignName);
      }
    }
});

withSingularLink

SingularConfig.withSingularLink 方法

为归因配置 Singular Links（深度链接）。该方法用于设置处理深度链接的 handler 以及短链接解析的超时时间。

省略 shortlinkTimeoutSec参数时，SDK 使用默认值 10 秒。当 intent action 为 ACTION_VIEW时，SDK 还会将该会话标记为通过深度链接打开。

签名

public SingularConfig withSingularLink(Intent intent, SingularLinkHandler handler);

public SingularConfig withSingularLink(Intent intent, SingularLinkHandler handler,
                                       long shortlinkTimeoutSec);

使用示例

// Set Singular Links handler
val config = SingularConfig("API_KEY", "SECRET")
    .withSingularLink(intent, { params ->
        // Check if we have a deep link
        params.deeplink?.let { deeplink ->
            println("Deep link received: $deeplink")
            // Navigate based on the deep link
            navigateToScreen(deeplink)
        }

        // Check if this is a deferred deep link
        if (params.isDeferred) {
            println("This is a deferred deep link")
        }

        // Access passthrough parameters
        params.passthrough?.let { passthrough ->
            println("Passthrough data: $passthrough")
        }
    }, 10)

// Set Singular Links handler
SingularConfig config = new SingularConfig("API_KEY", "SECRET")
    .withSingularLink(intent, new SingularLinkHandler() {
        @Override
        public void onResolved(SingularLinkParams params) {
            // Check if we have a deep link
            if (params.getDeeplink() != null) {
                System.out.println("Deep link received: " + params.getDeeplink());
                // Navigate based on the deep link
                navigateToScreen(params.getDeeplink());
            }

            // Check if this is a deferred deep link
            if (params.isDeferred()) {
                System.out.println("This is a deferred deep link");
            }

            // Access passthrough parameters
            if (params.getPassthrough() != null) {
                System.out.println("Passthrough data: " + params.getPassthrough());
            }
        }
    }, 10);

Android SDK - 配置方法参考

Android SDK - 配置参考

完整配置示例

全面 SDK 配置

完整示例

Constructor

SingularConfig 构造函数

签名

使用示例

withBrandedDomains

SingularConfig.withBrandedDomains 方法

签名

使用示例

withCustomSdid

SingularConfig.withCustomSdid 方法

签名

使用示例

withCustomUserId

SingularConfig.withCustomUserId 方法

签名

使用示例

withESPDomains

SingularConfig.withESPDomains 方法

签名

使用示例

withFacebookAppId

SingularConfig.withFacebookAppId 方法

签名

使用示例

withFCMDeviceToken

SingularConfig.withFCMDeviceToken 方法

签名

使用示例

withGlobalProperty

SingularConfig.withGlobalProperty 方法

签名

使用示例

withIMEI

SingularConfig.withIMEI 方法

签名

使用示例

withLimitAdvertisingIdentifiers

SingularConfig.withLimitAdvertisingIdentifiers 方法

签名

使用示例

withLimitDataSharing

SingularConfig.withLimitDataSharing 方法

签名

使用示例

withLogLevel

SingularConfig.withLogLevel 方法

签名

使用示例

withLoggingEnabled

SingularConfig.withLoggingEnabled 方法

签名

使用示例

withOAIDCollection

SingularConfig.withOAIDCollection 方法

签名

使用示例

withOpenURI

SingularConfig.withOpenURI 方法

签名

使用示例

withPushNotificationPayload

SingularConfig.withPushNotificationPayload 方法

签名

使用示例

withSdidAccessorHandler

SingularConfig.withSdidAccessorHandler 方法

签名

使用示例

withSessionTimeoutInSec

SingularConfig.withSessionTimeoutInSec 方法

签名

使用示例

withSingularDeviceAttribution

SingularConfig.withSingularDeviceAttribution 方法

签名