文档

下载安卓 SDK 12.10.0 版

儿童应用程序 SDK 信息

查看更改日志

示例应用程序（Java）
查看完整集成

视频指南

观看此视频，了解集成过程的详细步骤。同时使用视频和下面的书面指南可获得最佳效果。

前提条件

完成集成 Singular SDK中的步骤：中的步骤。

重要：任何 Singular SDK 集成都需要这些前提步骤。

安装

安装方法

注意：Android Studio 现在默认新项目使用Kotlin DSL(build.gradle.kts)。以下所有代码示例同时显示了Kotlin DSL（推荐）和Groovy DSL格式。

方法 1：Gradle（推荐）

添加 SDK 仓库

在项目的依赖关系管理中配置 Singular Maven Repository。

注意：从 Gradle 7 开始，Android 建议在settings.gradle 或settings.gradle.kts中使用集中式版本库声明，而不是项目或模块级别的build.gradle 声明。

Gradle 7+ 配置

在设置文件中添加 Singular SDK 仓库：

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://maven.singular.net/")
        }
    }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url 'https://maven.singular.net/'
        }
    }
}

旧版本的 Gradle

对于旧版本的 Gradle，请将版本库添加到项目级构建文件中：

repositories {
    mavenCentral()
    maven {
        url = uri("https://maven.singular.net/")
    }
}

repositories {
    mavenCentral()
    maven {
        url 'https://maven.singular.net/'
    }
}

添加 Singular 库依赖

将 Singular 库添加到应用程序模块的依赖关系中。

dependencies {
    implementation("com.singular.sdk:singular_sdk:12.10.0")
}

dependencies {
    implementation 'com.singular.sdk:singular_sdk:12.10.0'
}

疑难解答：重复类问题

当多个依赖项包含相同的库时，可能会遇到重复类错误。使用旧版本时，这种情况通常发生在 Google Play 服务库中。

常见错误示例：

Duplicate class com.google.android.gms.common.api.ResultCallback found in modules play-services-6.5.87.aar and play-services-basement-17.6.0.aar

解决方法：排除冲突的依赖关系

要解决重复类问题，请从 Singular SDK 或其他导致冲突的依赖关系中排除冲突的传递依赖关系。

dependencies {
    // Exclude specific Google Play Services modules from Singular SDK
    implementation("com.singular.sdk:singular_sdk:12.10.0") {
        exclude(group = "com.google.android.gms", module = "play-services")
    }

    // Add the specific Google Play Services libraries your app needs
    implementation("com.google.android.gms:play-services-ads-identifier:17.0.0")
    implementation("com.google.android.gms:play-services-appset:16.0.2")
}

dependencies {
    // Exclude specific Google Play Services modules from Singular SDK
    implementation('com.singular.sdk:singular_sdk:12.10.0') {
        exclude group: 'com.google.android.gms', module: 'play-services'
    }

    // Add the specific Google Play Services libraries your app needs
    implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0'
    implementation 'com.google.android.gms:play-services-appset:16.0.2'
}

全局排除规则

如果重复类冲突影响到整个项目中的多个依赖项，可以应用全局排除规则。

configurations.all {
    exclude(group = "com.google.android.gms", module = "play-services")
}

configurations.all {
    exclude group: 'com.google.android.gms', module: 'play-services'
}

验证依赖关系的解决

应用排除规则后，请验证依赖关系树以确保冲突得到解决。

./gradlew app:dependencies --configuration debugRuntimeClasspath

此命令会显示应用程序的完整依赖关系树，显示哪些库已包含，哪些库已排除。

三星 Galaxy 应用商店支持

如果您的应用程序是通过 Samsung Galaxy Store 发布的，请添加 Samsung Galaxy Store install referrer 依赖关系。

dependencies {
    implementation("store.galaxy.samsung.installreferrer:samsung_galaxystore_install_referrer:4.0.0")
}

dependencies {
    implementation 'store.galaxy.samsung.installreferrer:samsung_galaxystore_install_referrer:4.0.0'
}

传递依赖关系

如果您已禁用 Singular SDK 的传递依赖关系，请手动将这些必要库添加到应用程序模块的依赖关系中。

dependencies {
    implementation("com.android.installreferrer:installreferrer:2.2")
    implementation("com.google.android.gms:play-services-appset:16.0.0")
}

dependencies {
    implementation 'com.android.installreferrer:installreferrer:2.2'
    implementation 'com.google.android.gms:play-services-appset:16.0.0'
}

谷歌播放服务依赖项

如果您的应用程序没有执行 Google Play Services API 17.0.0 或更高版本，请添加以下依赖项。

dependencies {
    implementation("com.google.android.gms:play-services-ads-identifier:17.0.0")
}

dependencies {
    implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0+'
}

方法 2：手动安装

其他安装方法

手动下载

下载 SDK AAR 文件并手动集成到您的项目中。

下载 SDK：从本页顶部的链接下载 SDK
解压缩并添加至库：解压缩 SDK 软件包，并将Singular.aar 添加到 Android 项目的 libs 目录中。
创建 libs 目录：如果不存在，请在项目文件夹中创建一个名为libs 的目录（通常位于<project>/app/libs ）。

方法 3：Maven 安装

安装 Maven

将 Singular Maven 资源库添加到项目的pom.xml文件中。

<project ...>
    <repositories>
        <repository>
            <id>singular.net</id>
            <url>http://maven.singular.net/</url>
        </repository>
    </repositories>
</project>

添加依赖关系：

<dependency>
    <groupId>com.singular.sdk</groupId>
    <artifactId>singular_sdk</artifactId>
    <version>12.10.0</version>
</dependency>

方法 4：Eclipse 安装

Eclipse 安装

按照以下步骤使用 Eclipse 集成 SDK。

您可以使用 Eclipse AAR 插件：gradle-eclipse-aar-plugin

如果不想使用该插件，请按照以下步骤操作：

解压缩 AAR：解压缩singular_sdk-12.10.0.aar
重命名 JAR 文件：将classes.jar重命名为singular_sdk-12.10.0.jar （这是主 SDK jar
添加安装引用程序：将com.android.installreferrer:installreferrer:2.2库添加到您的项目中
复制权限：将BIND_GET_INSTALL_REFERRER_SERVICE 权限从 AAR 中的AndroidManifest.xml 复制到AndroidManifest.xml
复制许可权限：将CHECK_LICENSE 权限从 AAR 中的AndroidManifest.xml 复制到您的AndroidManifest.xml

ProGuard 配置

ProGuard 规则

在proguard.config 文件中添加以下规则，以防止代码混淆问题。

-keep class com.singular.sdk.** { *; }
-keep public class com.android.installreferrer.** { *; }
# Uncomment this line in case your are calling the 'revenue' function using the Google billing library
#-keep public class com.android.billingclient.** { *; }

所需权限

AndroidManifest 配置

在AndroidManifest.xml 文件的<manifest> 标记下添加这些权限。

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="BIND_GET_INSTALL_REFERRER_SERVICE" />
<uses-permission android:name="com.android.vending.CHECK_LICENSE" />
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

如果您集成了Kids SDK，请排除com.google.android.gms.permission.AD_ID 权限。

三星 Galaxy 商店查询

要支持 Samsung Galaxy Store 的安装推荐器，请在AndroidManifest.xml 文件中添加以下内容。

<queries>
    <package android:name="com.sec.android.app.samsungapps" />
</queries>

SDK 集成

隐私合规性：在实施 Singular SDK 时，请继续遵守业务所在地区颁布的隐私法，包括 GDPR、CCPA 和 COPPA。请参阅SDK 选择加入和选择退出实践以获取指导。

导入 Singular SDK

添加导入声明

在 MainActivity 文件中导入 Singular 库。

import com.singular.sdk.*

import com.singular.sdk.*;

初始化 SDK

创建初始化函数

要启用会话跟踪和归因，请在每次启动应用程序时创建一个私有方法并从 MainActivity 的onCreate() 方法中调用该方法，从而初始化 Singular SDK。

请按照以下步骤操作：

添加函数：将初始化方法放在 MainActivity 类（或任何入口点 Activity）中
插入凭证：用仪表板中的 Singular SDK 密钥和秘密替换SDK KEY和SDK SECRET
更新 SingularConfig：在初始化 SDK 之前，创建 SingularConfig 对象并设置任何 SDK 偏好设置（请参阅下面的配置选项
调用函数：在用户界面设置后、事件日志记录前，在onCreate() 中调用initSingularSDK()

基本实现

使用基本配置创建初始化方法。

private fun initSingularSDK() {
    // Configure Singular with SDK key and secret
    val config = SingularConfig("SDK KEY", "SDK SECRET")

    try {
        Singular.init(applicationContext, config)
        Log.d("Singular", "SDK initialized successfully")
    } catch (e: Exception) {
        Log.e("Singular", "SDK initialization failed: ${e.message}")
    }
}

private void initSingularSDK() {
    // Configure Singular with SDK key and secret
    SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET");

    try {
        Singular.init(getApplicationContext(), config);
        Log.d("Singular", "SDK initialized successfully");
    } catch (Exception e) {
        Log.e("Singular", "SDK initialization failed: " + e.getMessage());
    }
}

从 MainActivity onCreate 调用

在 MainActivity 的onCreate() 方法中调用初始化方法。

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    // Initialize Singular SDK
    initSingularSDK()

    // Proceed with your app setup (e.g., UI initialization)
}

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    // Initialize Singular SDK
    initSingularSDK();

    // Proceed with your app setup (e.g., UI initialization)
}

实施指南

在实现 SDK 初始化时，请遵循以下主要指南。

放置：在 MainActivity（而不是应用程序类）中添加初始化方法，以确保正确的会话跟踪
错误处理：try-catch 块可记录初始化错误（如无效凭证），而不会导致应用程序崩溃。
深度链接：要处理深层链接（启动应用程序的 URL），请参阅支持深层链接进行扩展设置
META 安装 Referrer：添加config.withFacebookAppId("FacebookAppID") 以启用Meta 安装 Referrer 归属。

自 2025 年 6 月 18 日起，Meta 的高级移动测量报告 (AMM)不再需要实施 Meta Install Referrer。如果启用了 AMM 报告，则不建议实施 Meta 安装 Referrer。

专业提示：如果您的应用程序支持多个入口点（如深度链接），请确保在每个相关活动的onCreate() 中调用initSingularSDK() ，以保证行为一致。

配置选项

SingularConfig 方法

通过 SingularConfig 对象，您可以使用可链式配置方法自定义 SDK 行为。有关所有可用选项，请参阅下表。

方法	说明
`.withFacebookAppId(String facebookAppID)`	配置 Facebook 应用程序 ID。Meta 安装 Referrer 归属所需的。请参阅在哪里可以找到应用程序的 Facebook App ID？自 2025 年 6 月 18 日起，Meta 的高级移动测量报告 (AMM)不再需要实施 Meta Install Referrer。如果启用了 AMM 报告，则不建议实施 Meta Install Referrer。
`.withCustomUserId(String customId)`	将用户 ID 发送至 Singular
`.withSingularLink(getIntent(), SingularLinkHandler handler)`	使用 Singular 链接启用深度链接
`.withDDLTimeoutInSec(long timeout)`	设置首次打开应用程序时 Singular 搜索延迟深度链接的时间长度
`.withOpenURI(URI openURI)`	从意图中获取 URI（在应用程序通过非 Singular 链接打开时处理深层链接
`.withGlobalProperty(String key, String value, boolean overrideExisting)`	将全局属性设置为给定值。键和值将随应用程序发送的任何事件/会话一起发送到 Singular
`.withSessionTimeoutInSec(long timeout)`	设置会话超时
`.withFCMDeviceToken(String token)`	设置第一次会话要发送的 FCM 标记
`.withLoggingEnabled()`	启用日志记录
`.withLogLevel(int level)`	配置日志记录级别（默认为 Log.ERROR）