Android SDK - 配置方法参考

关注
Avatar
Jared Ornstead
Updated
文档

安卓 SDK - 配置方法参考

Singular SDK 通过 SingularConfig 类提供了灵活的配置系统。本文档概述了所有可用的配置选项，以及如何在初始化 SDK 时使用它们。

自定义配置

SingularConfig.withCustomSdid 方法

企业功能：设置自定义奇异设备 ID（SDID）和访问该 ID 的处理程序。

签名

public SingularConfig withCustomSdid(String customSdid, SDIDAccessorHandler accessorHandler)

使用示例

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withCustomSdid("custom-device-id-12345", new SDIDAccessorHandler() {
        @Override
        public void onSDIDAccessed(String sdid) {
            // Handle SDID access
            Log.d("Singular", "SDID accessed: " + sdid);
        }
    });

withCustomUserId

SingularConfig.withCustomUserId 方法

在初始化过程中设置自定义用户 ID。

签名

public SingularConfig withCustomUserId(String customUserId)

使用示例

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withCustomUserId("user_12345");

withDDLHandler

SingularConfig.withDDLHandler 方法

设置延迟深度链接的处理程序。

签名

public SingularConfig withDDLHandler(DeferredDeepLinkHandler handler)

使用示例

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withDDLHandler(new DeferredDeepLinkHandler() {
        @Override
        public void onResolved(String resolvedLink) {
            if (resolvedLink != null) {
                // Handle the deferred deep link
                Log.d("Singular", "Deferred deep link: " + resolvedLink);
            }
        }
    });

withDDLTimeoutInSec

SingularConfig.withDDLTimeoutInSec 方法

设置延迟深度链接解析的超时（秒）。

签名

public SingularConfig withDDLTimeoutInSec(long timeout)

使用示例

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withDDLHandler(deferredDeepLinkHandler)
    .withDDLTimeoutInSec(10); // 10 seconds timeout

withESPDomains

SingularConfig.withESPDomains 方法

设置用于处理电子邮件营销活动归因的 ESP（电子邮件服务提供商）域名列表。

签名

public SingularConfig withESPDomains(List espDomains)

使用示例

Java
List<String> espDomains = new ArrayList<>();
espDomains.add("email.example.com");
espDomains.add("newsletter.example.com");

SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withESPDomains(espDomains);

withFacebookAppId

SingularConfig.withFacebookAppId 方法

设置用于 Facebook 归因的 Facebook 应用程序 ID。

签名

public SingularConfig withFacebookAppId(String facebookAppId)

使用示例

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withFacebookAppId("123456789012345");

withFCMDeviceToken

SingularConfig.withFCMDeviceToken 方法

在初始化过程中设置 Firebase Cloud Messaging 设备令牌。

签名

public SingularConfig withFCMDeviceToken(String fcmDeviceToken)

使用示例

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withFCMDeviceToken("eKh2BNP-Txy4XrjDGmw...");

withGlobalProperty

SingularConfig.withGlobalProperty 方法

在初始化过程中设置全局属性，该属性将包含在所有事件中。

签名

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

使用示例

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withGlobalProperty("app_version", "2.1.0", true)
    .withGlobalProperty("user_type", "free", true);

withIMEI

SingularConfig.withIMEI 方法

在初始化过程中设置用于跟踪的设备 IMEI。

签名

public SingularConfig withIMEI(String imei)

使用示例

Java
// Note: Requires READ_PHONE_STATE permission
String imei = null;
if (ContextCompat.checkSelfPermission(this, Manifest.permission.READ_PHONE_STATE) 
        == PackageManager.PERMISSION_GRANTED) {
    TelephonyManager telephonyManager = (TelephonyManager) getSystemService(Context.TELEPHONY_SERVICE);
    imei = telephonyManager.getDeviceId();
}

SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withIMEI(imei);

withLimitAdvertisingIdentifiers

SingularConfig.withLimitAdvertisingIdentifiers 方法

在初始化过程中限制广告标识符的使用。

签名

public SingularConfig withLimitAdvertisingIdentifiers()

使用示例

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withLimitAdvertisingIdentifiers();

withLimitDataSharing

SingularConfig.withLimitDataSharing 方法

控制是否在初始化过程中限制与合作伙伴和网络共享数据。

签名

public SingularConfig withLimitDataSharing(boolean shouldLimitDataSharing)

使用示例

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withLimitDataSharing(true);

withLogLevel

SingularConfig.withLogLevel 方法

设置 SDK 日志的日志级别。

签名

public SingularConfig withLogLevel(int level)

使用示例

Java
import android.util.Log;

SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withLoggingEnabled()
    .withLogLevel(Log.VERBOSE); // Use Log.VERBOSE, Log.DEBUG, Log.INFO, Log.WARN, Log.ERROR

withLoggingEnabled

SingularConfig.withLoggingEnabled 方法

启用 SDK 日志记录。

签名

public SingularConfig withLoggingEnabled()

使用示例

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withLoggingEnabled();

withOAIDCollection

SingularConfig.withOAIDCollection 方法

启用收集中文设备的 OAID（开放式匿名设备标识符）。

签名

public SingularConfig withOAIDCollection()

使用示例

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withOAIDCollection();

withOpenURI

SingularConfig.withOpenURI 方法

设置打开应用程序的 URI，以便归属。

签名

public SingularConfig withOpenURI(Uri openUri)

使用示例

Java
// In your Activity's onCreate method
Uri data = getIntent().getData();
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withOpenURI(data);

withPushNotificationPayload

SingularConfig.withPushNotificationPayload 方法

设置推送通知有效载荷和从有效载荷中提取深度链接的路径。

签名

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

使用示例

Java
// In your Activity that handles push notifications
Intent intent = getIntent();
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withPushNotificationPayload(intent, new String[]{"singular_link"}, new String[]{"data", "deeplink"});

withSdidAccessorHandler

SingularConfig.withSdidAccessorHandler 方法

企业特征：设置处理程序以访问奇异设备 ID（SDID）。

签名

public SingularConfig withSdidAccessorHandler(SDIDAccessorHandler accessorHandler)

使用示例

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withSdidAccessorHandler(new SDIDAccessorHandler() {
        @Override
        public void onSDIDAccessed(String sdid) {
            // Handle SDID access
            Log.d("Singular", "SDID accessed: " + sdid);
        }
    });

withSessionTimeoutInSec

SingularConfig.withSessionTimeoutInSec 方法

设置会话超时（秒）。

签名

public SingularConfig withSessionTimeoutInSec(long timeout)

使用示例

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withSessionTimeoutInSec(60); // 60 seconds timeout

withSingularDeviceAttribution

SingularConfig.withSingularDeviceAttribution 方法

BETA 功能：设置一个处理函数，以便在设备属性数据可用时接收该数据。

签名

public SingularConfig withSingularDeviceAttribution(SingularDeviceAttributionHandler handler)

使用示例

Java
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withSingularDeviceAttribution(new SingularDeviceAttributionHandler() {
        @Override
        public void onDeviceAttributionInfoReceived(Map deviceAttributionData) {
            // Handle device attribution data
            if (deviceAttributionData != null) {
                for (Object key : deviceAttributionData.keySet()) {
                    Log.d("Singular", key + ": " + deviceAttributionData.get(key));
                }
            }
        }
    });

withSingularLink

SingularConfig.withSingularLink 方法

通过已解析链接的回调设置奇异链接处理。

签名

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

使用示例

Java
// In your Activity's onCreate method
Intent intent = getIntent();
SingularConfig config = new SingularConfig("API_KEY", "API_SECRET")
    .withSingularLink(intent, new SingularLinkHandler() {
        @Override
        public void onResolved(SingularLinkParams params) {
            if (params != null) {
                // Handle the deep link
                String deeplink = params.getDeeplink();
                if (deeplink != null) {
                    Log.d("Singular", "Deep link: " + deeplink);
                    // Navigate to the appropriate screen
                }
                
                // Get passthrough parameters
                String passthrough = params.getPassthrough();
                if (passthrough != null) {
                    Log.d("Singular", "Passthrough: " + passthrough);
                }
                
                // Check if this is a deferred deep link
                boolean isDeferred = params.isDeferred();
                Log.d("Singular", "Is deferred: " + isDeferred);
            }
        }
    }, 10); // 10 seconds timeout

完整配置示例

连锁多个配置选项

下面是一个完整示例，展示了如何在初始化 Singular SDK 时将多个配置选项串联起来。

使用示例

Java
import android.app.Activity;
import android.content.Intent;
import android.net.Uri;
import android.os.Bundle;
import android.util.Log;

import com.singular.sdk.Singular;
import com.singular.sdk.SingularConfig;
import com.singular.sdk.SingularLinkHandler;
import com.singular.sdk.SingularLinkParams;
import com.singular.sdk.SingularDeviceAttributionHandler;

import java.util.ArrayList;
import java.util.List;
import java.util.Map;

public class MainActivity extends Activity {
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        
        // Get the intent that started this activity
        Intent intent = getIntent();
        
        // Initialize Singular SDK with advanced configuration
        SingularConfig config = new SingularConfig("SDK KEY", "YOUR_SECRET")
            // Enable logging for debugging
            .withLoggingEnabled()
            .withLogLevel(Log.DEBUG)
            
            // Set custom user ID if available
            .withCustomUserId("user_12345")
            
            // Configure session timeout
            .withSessionTimeoutInSec(60)
            
            // Set global properties for all events
            .withGlobalProperty("app_version", "2.1.0", true)
            .withGlobalProperty("user_type", "premium", true)
            
            // Handle deep links
            .withSingularLink(intent, new SingularLinkHandler() {
                @Override
                public void onResolved(SingularLinkParams params) {
                    if (params != null) {
                        String deeplink = params.getDeeplink();
                        if (deeplink != null) {
                            Log.d("Singular", "Deep link: " + deeplink);
                            // Navigate based on deep link
                        }
                    }
                }
            }, 10)
            
            // Handle deferred deep links
            .withDDLHandler(new DeferredDeepLinkHandler() {
                @Override
                public void onResolved(String resolvedLink) {
                    if (resolvedLink != null) {
                        Log.d("Singular", "Deferred deep link: " + resolvedLink);
                        // Handle deferred deep link
                    }
                }
            })
            .withDDLTimeoutInSec(5)
            
            // Get device attribution data
            .withSingularDeviceAttribution(new SingularDeviceAttributionHandler() {
                @Override
                public void onDeviceAttributionInfoReceived(Map deviceAttributionData) {
                    if (deviceAttributionData != null) {
                        for (Object key : deviceAttributionData.keySet()) {
                            Log.d("Singular", key + ": " + deviceAttributionData.get(key));
                        }
                    }
                }
            })
            
            // Facebook attribution
            .withFacebookAppId("123456789012345")
            
            // Configure data sharing limitations for privacy
            .withLimitDataSharing(true)
            .withLimitAdvertisingIdentifiers();
        
        // Initialize the SDK with the configuration
        Singular.init(this, config);
    }
    
    @Override
    protected void onResume() {
        super.onResume();
        Singular.onActivityResumed();
    }
    
    @Override
    protected void onPause() {
        super.onPause();
        Singular.onActivityPaused();
    }
}