观看视频,详细了解集成过程。我们建议您同时使用视频和下面的书面指南。
开始之前:SDK 先决条件
按照集成 Singular SDK 中的步骤进行操作:规划和先决条件》中的步骤。
这些步骤是任何 Singular SDK 集成的先决条件。
安装 SDK
使用 Gradle 添加 SDK
注:从 Gradle 7 开始,Android 建议 在 settings.gradle 中 使用 集中式版本库声明, 而不是项目或模块级别的 build.gradle 声明。
-
在settings.gradle文件中添加Singular SDK 仓库:
dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() maven{ url = uri("https://maven.singular.net/") } } }
或在旧版本的 Gradle 中,在project/build.gradle 文件中添加Singular SDK 仓库:
repositories { mavenCentral() maven { url 'https://maven.singular.net/' } }
-
在app/build.gradle 的依赖列表中添加Singular 库:
dependencies { ... implementation 'com.google.android.gms:play-services:6.5.87' implementation 'com.singular.sdk:singular_sdk:12.7.2' ... }
此外,如果你的应用程序是通过三星 Galaxy Store 发布的,请添加以下内容以支持三星 Galaxy Store 的安装引用程序:
dependencies { ... implementation 'store.galaxy.samsung.installreferrer:samsung_galaxystore_install_referrer:4.0.0' ... }
-
如果已禁用 Singular SDK 的传递依赖关系,请在app/build.gradle 中添加以下内容:
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 或更高版本,请在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。
- 解压 SDK 包,将Singular.aar添加到 Android 项目的 libs 目录中。如果该目录不存在,请在项目文件夹中创建名为libs的目录(通常位于 <project>/app/libs)。
将我们的 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.7.2</version>
</dependency>
您可以使用 Eclipse AAR 插件: gradle-eclipse-aar-plugin
如果不想使用该插件,请按照以下步骤操作:
- 解压缩singular_sdk-12.7.2.aar。
- 将 classes.jar 重命名为 singular_sdk-12.7.2.jar(这是主 SDK jar)。
- 以任何方式将 "com.android.installreferrer:installreferrer:2.2 "库添加到项目中。
- 将 AAR 中 AndroidManifest.xml 中的 BIND_GET_INSTALL_REFERRER_SERVICE 权限复制到您的 AndroidManifest.xml 中。
- 将 AAR 中 AndroidManifest.xml 中的 CHECK_LICENSE 权限复制到 AndroidManifest.xml 中。
使用 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.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" />
要支持三星 Galaxy Store 的安装推荐器,请添加以下内容:
<queries>
<package android:name="com.sec.android.app.samsungapps" />
</queries>
集成 SDK
注意:在实施 Singular SDK 时,切记要遵守业务所在地区颁布的各种隐私法,包括 GDPR、CCPA 和 COPPA。更多信息,请参阅SDK 选择加入和选择退出实践。
导入Singular库
要导入 Singular 库,请在MainActivity文件中添加以下导入内容:
import com.singular.sdk.*;
import com.singular.sdk.*
初始化 Singular SDK
使用私有函数初始化 Singular SDK
要启用会话跟踪和归因功能,必须在每次启动应用程序时初始化 Singular SDK。我们建议创建一个私有方法initSingularSDK() ,并从MainActivity的onCreate() 方法中调用它。
请按照以下步骤操作:
- 添加函数:将以下方法放入MainActivity 类(或任何入口点Activity )。
- 插入凭证:用 Singular 面板中的 Singular SDK 密钥和秘密替换"SDK KEY" 和"SDK SECRET" 。
-
更新 SingularConfig 对象:在初始化 SDK 之前,必须创建一个SingularConfig对象。可以选择在此设置 SDK 首选项。请使用下面的 SingularConfig 方法参考来查看这些选项:
SingularConfig 方法参考:查看所有可用的".with "选项下表列出了所有可用的 SingularConfig 对象".with "方法,可用于为应用程序添加选项和功能。
你可以在下面的章节或 "高级选项"中找到每个功能的详细信息。
方法
说明
.withFacebookAppId(String facebookAppID)
配置 Facebook 应用程序 ID。Meta Install Referrer "归因需要该 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)。
- 调用函数:在用户界面设置之后、记录事件之前,在onCreate() 中调用initSingularSDK() 。
以下是基本实现:
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());
}
}
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}")
}
}
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)
}
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
// Initialize Singular SDK
initSingularSDK()
}
密钥详情
- 放置:将此方法添加到MainActivity 中,而不是Application 类中,以确保正确的会话跟踪。
- 错误处理: try-catch 块可记录初始化错误(如无效凭据),而不会导致应用程序崩溃。
- 深度链接(可选):要处理深层链接(例如,启动应用的 URL),请参阅我们的《支持深层链接》文章,了解扩展设置。
- 支持 META 安装 Referrer Attribution:添加config.withFacebookAppId("FacebookAppID") 配置选项,启用"元安装推荐人 "归属。
专业提示:如果您的应用程序支持多个入口点(如深度链接),请确保在每个相关活动的onCreate() 中调用initSingularSDK() ,以保证行为一致。