基本整合

文档
新功能:视频指南

观看视频,详细了解集成过程。我们建议您同时使用视频和下面的书面指南。

开始之前:SDK 先决条件

按照集成 Singular SDK 中的步骤进行操作:规划和先决条件》中的步骤。

这些步骤是任何 Singular SDK 集成的先决条件。


安装 SDK

使用 Gradle 添加 SDK

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

  1. settings.gradle文件中添加Singular SDK 仓库

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

    或在旧版本的 Gradle 中,在project/build.gradle 文件中添加Singular SDK 仓库

    project/build.gradle
    repositories {
         mavenCentral()
         maven { url 'https://maven.singular.net/' }
    }
  2. app/build.gradle 的依赖列表中添加Singular 库

    app/build.gradle
    dependencies {
        ...
        implementation 'com.google.android.gms:play-services:6.5.87'
        implementation 'com.singular.sdk:singular_sdk:12.7.2'
        ...
    }

    此外,如果你的应用程序是通过三星 Galaxy Store 发布的,请添加以下内容以支持三星 Galaxy Store 的安装引用程序:

    app/build.gradle
    dependencies {
         ...
         implementation 'store.galaxy.samsung.installreferrer:samsung_galaxystore_install_referrer:4.0.0'
         ...
    }
  3. 如果已禁用 Singular SDK 的传递依赖关系,请app/build.gradle 中添加以下内容:

    app/build.gradle
    dependencies {
        ...
        implementation 'com.android.installreferrer:installreferrer:2.2'
        implementation 'com.google.android.gms:play-services-appset:16.0.0'
        ...
    }
  4. 如果您的应用程序未实施Google Play Services API 17.0.0 或更高版本,请在app/build.gradle文件中添加以下依赖关系:

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

注意:Gradle 1.x-2.x 用户应使用 "compile"(编译)而不是 "implementation"(实施)来添加依赖关系。

不使用 Gradle 添加 SDK

手动下载 SDK
  1. 从页面顶部的链接下载 SDK。
  2. 解压 SDK 包,将Singular.aar添加到 Android 项目的 libs 目录中。如果该目录不存在,请在项目文件夹中创建名为libs的目录(通常位于 <project>/app/libs)。
使用 Maven 添加 SDK

将我们的 maven 仓库添加到项目的 pom.xml:

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.7.2</version>
</dependency>
使用 Eclipse 添加 SDK

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

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

  1. 解压缩singular_sdk-12.7.2.aar。
  2. 将 classes.jar 重命名为 singular_sdk-12.7.2.jar(这是主 SDK jar)。
  3. 以任何方式将 "com.android.installreferrer:installreferrer:2.2 "库添加到项目中。
  4. 将 AAR 中 AndroidManifest.xml 中的 BIND_GET_INSTALL_REFERRER_SERVICE 权限复制到您的 AndroidManifest.xml 中。
  5. 将 AAR 中 AndroidManifest.xml 中的 CHECK_LICENSE 权限复制到 AndroidManifest.xml 中。

使用 Proguard 时的要求

proguard.config 文件中添加以下代码行:

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.xml文件的<manifest>标记下添加这些权限:

AndroidManifest.xml
<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" />
如果要集成儿童 SDK,请排除 com.google.android.gms.permission.AD_ID 权限。

要支持三星 Galaxy Store 的安装推荐器,请添加以下内容:

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

集成 SDK

注意:在实施 Singular SDK 时,切记要遵守业务所在地区颁布的各种隐私法,包括 GDPR、CCPA 和 COPPA。更多信息,请参阅SDK 选择加入和选择退出实践

导入Singular库

要导入 Singular 库,请在MainActivity文件中添加以下导入内容:

Java (MainActivity.java) Kotlin (MainActivity.kt)
import com.singular.sdk.*;

初始化 Singular SDK

使用私有函数初始化 Singular SDK

要启用会话跟踪和归因功能,必须在每次启动应用程序时初始化 Singular SDK。我们建议创建一个私有方法initSingularSDK() ,并从MainActivityonCreate() 方法中调用它。

请按照以下步骤操作:

  1. 添加函数:将以下方法放入MainActivity 类(或任何入口点Activity )。
  2. 插入凭证:用 Singular 面板中的 Singular SDK 密钥和秘密替换"SDK KEY""SDK SECRET"
  3. 更新 SingularConfig 对象:在初始化 SDK 之前,必须创建一个SingularConfig对象。可以选择在此设置 SDK 首选项。请使用下面的 SingularConfig 方法参考来查看这些选项:

    SingularConfig 方法参考:查看所有可用的".with "选项

    下表列出了所有可用的 SingularConfig 对象".with "方法,可用于为应用程序添加选项和功能。

    你可以在下面的章节或 "高级选项"中找到每个功能的详细信息。

    方法

    说明

    .withFacebookAppId(String facebookAppID)

    配置 Facebook 应用程序 ID。Meta Install Referrer "归因需要该 ID。

    请参阅"在哪里可以找到应用程序的 Facebook App ID?

    .withCustomUserId(String customId)

    向 Singular 发送用户 ID。

    .withSingularLink(getIntent(), SingularLinkHandler handler)

    启用与 Singular 链接的深度链接。

    .withDDLTimeoutInSec(长超时)

    设置首次打开应用程序时,Singular 搜索延迟深层链接的时间长度。

    .withOpenURI(URI openURI)

    从意图中获取 URI(用于在应用程序通过非 Singular 链接打开时处理深层链接)。

    .withGlobalProperty(String key, String value, boolean overrideExisting)

    将全局属性设置为给定值。键和值将与应用程序发送的任何事件/会话一起发送到 Singular。

    .withSessionTimeoutInSec(长超时)

    设置会话超时。

    .withFCMDeviceToken(String token)

    设置第一次会话时要发送的 FCM 令牌。

    .withLoggingEnabled ()

    启用日志记录。

    .withLogLevel (int 级别)

    配置日志记录级别(默认为 Log.ERROR)。

  4. 调用函数:在用户界面设置之后、记录事件之前,在onCreate() 中调用initSingularSDK()

以下是基本实现:

Java - MainActivity Kotlin - MainActivity
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中的使用示例

Java - MainActivity Kotlin - MainActivity
@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)

}

密钥详情

  • 放置:将此方法添加到MainActivity 中,而不是Application 类中,以确保正确的会话跟踪。
  • 错误处理: try-catch 块可记录初始化错误(如无效凭据),而不会导致应用程序崩溃。
  • 深度链接(可选):要处理深层链接(例如,启动应用的 URL),请参阅我们的《支持深层链接》文章,了解扩展设置
  • 支持 META 安装 Referrer Attribution:添加config.withFacebookAppId("FacebookAppID") 配置选项,启用"元安装推荐人 "归属。

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