先决条件
在安装 Singular Unity SDK 之前,请完成以下必备步骤,以确保集成过程顺利。
必备条件:
- 完成规划步骤:请遵循《集成 Singular SDK:规划与先决条件》中的指南。这些步骤是任何 Singular SDK 集成的必备条件。
- 检查依赖项管理器:请确认您的项目是否使用了Google EDM4U(Unity 外部依赖项管理器)。了解有关 Google EDM4U 的更多信息。
-
从 .unitypackage 升级?如果您正在从旧版
.unitypackage迁移至新版UPM包,请在继续操作前阅读升级说明。
安装
通过 Unity 包管理器 (UPM) 安装
Singular Unity SDK 通过 Unity 包管理器使用 Git URL 进行安装。请按照以下步骤将 SDK 添加到您的项目中。
安装步骤
- 打开包管理器:在 Unity 中,依次选择 窗口 > 包管理器。
- 从 Git 添加包:点击左上角的[+] 按钮,然后选择 “从 Git URL 添加包”。
-
输入 Git URL:
-
标准 SDK:输入
https://github.com/singular-labs/Singular-Unity-SDK.git -
针对儿童版 SDK:输入
https://github.com/singular-labs/Singular-Unity-SDK.git#kids
-
标准 SDK:输入
- 完成安装:点击“添加” 以安装 SDK 包。
未使用 Google EDM4U?如果您的项目未 使用 外部依赖管理器,则必须手动下载并添加 原生 依赖项。
手动安装依赖项
-
下载依赖项:从 Singular 的 S3 存储桶下载相应的
Plugins.zip文件:-
标准 SDK (v5.7.0):
下载标准 SDK 插件 -
儿童 SDK (v5.6.0):
下载儿童版 SDK 插件
-
标准 SDK (v5.7.0):
- 解压至 Assets 文件夹:将下载的文件解压 并将其移动到 Unity 项目中的Assets > Plugins文件夹。
-
配置 iOS 框架:导航至
Assets > Plugins > iOS,并选择
Singular.xcframework。 - 嵌入二进制文件:在检查器面板中,勾选 选项 “添加到嵌入式二进制文件”。
Android 配置提示
请配置您的 Android 构建设置,以确保 SDK 功能正常。 Unity 提供了多种方式来定制 Android 清单文件和 Gradle 文件。
您可以通过以下两种方法之一修改 AndroidManifest:
方法 1:Unity 自定义清单
- 导航至 文件 > 构建设置 > 播放器设置 > 发布设置。
- 在 “发布设置” 部分启用“自定义主清单”。
-
Unity 会在
Assets/Plugins/Android/AndroidManifest.xml
路径下生成一个默认的
AndroidManifest.xml文件。 - 编辑此文件以添加所需的权限和配置。
方法 2:Android Studio
- 通过 Unity 中的 “文件” > “构建设置” > “导出项目” 导出项目。
- 在 Android Studio 中打开导出的项目。
-
直接在
Android Studio
中编辑
AndroidManifest.xml文件。
方法 1:Unity 自定义模板
- 导航至 文件 > 构建设置 > 播放器设置 > 发布设置。
- 在 “发布设置” 部分启用“自定义 Gradle 模板”。
-
Unity 会在
Assets/Plugins/Android/mainTemplate.gradle
路径下生成一个
mainTemplate.gradle文件。 - 将您的自定义 Gradle 配置添加到此文件中。
方法 2:Android Studio
- 从 Unity 导出项目。
- 在 Android Studio 中打开该项目。
-
直接编辑应用的
build.gradle文件。
在 Unity 中构建 Android 应用时,可能会遇到由多个 SDK 包含相同 传递性依赖项所导致的“类重复” 错误。当同时使用 AppLovin SDK 和 Singular SDK 时,这种情况通常会发生在 Android Vending Licensing 库上。
错误示例:
Duplicate class com.android.vending.licensing.ILicensingService found in modules
applovin-sdk-13.5.0.aar -> jetified-applovin-sdk-13.5.0-runtime (com.applovin:applovin-sdk:13.5.0)
and singular_sdk-12.11.0.aar -> jetified-singular_sdk-12.11.0-runtime (com.singular.sdk:singular_sdk:12.11.0)
解决方案 1:使用外部依赖管理器 (EDM4U)
如果您的项目使用 Unity外部依赖管理器(推荐), 请在Dependencies XML文件中添加排除规则。
-
在您的
Unity 项目中找到
*Dependencies.xml文件(通常位于Assets/Editor或类似位置)。 - 为其中一个 SDK 依赖项添加排除规则:
<dependencies>
<androidPackages>
<androidPackage spec="com.applovin:applovin-sdk:13.5.0">
<androidSdkPackageIds>
<exclude group="com.android.vending" module="licensing"/>
</androidSdkPackageIds>
</androidPackage>
<androidPackage spec="com.singular.sdk:singular_sdk:12.11.0" />
</androidPackages>
</dependencies>
注意:此方法比修改 Gradle 模板更具持久性, 因为 Android Resolver 在解析过程中可能会覆盖自定义模板的更改。
解决方案 2:使用自定义 Gradle 模板
如果您未使用 EDM4U,请直接在 Gradle 配置文件中 应用排除规则。
- 导航至 文件 > 构建设置 > 播放器设置 > 发布设置。
- 启用“自定义主 Gradle 模板” 或“自定义启动器 Gradle 模板”。
-
打开
Assets/Plugins/Android/mainTemplate.gradle(或launcherTemplate.gradle)。 - 在依赖项块中添加排除规则:
dependencies {
implementation('com.applovin:applovin-sdk:13.5.0') {
exclude group: 'com.android.vending', module: 'licensing'
}
implementation 'com.singular.sdk:singular_sdk:12.11.0'
}
替代方案:通过在 依赖项块之后添加以下内容来应用全局排除:
configurations.all {
exclude group: 'com.android.vending', module: 'licensing'
}
验证解析
- 应用排除规则后,请通过删除 Library/Bee和 Temp 文件夹来清理项目。
- 在 Unity 中重新构建您的 Android 项目。
- 验证构建输出中是否不再出现 类重复错误。
原理:这两个 SDK都将 相同的 Android 授权库作为传递性依赖项打包。 该排除规则指示 Gradle 仅使用其中一份,从而 解决了冲突。
如果您的项目使用 ProGuard 进行代码混淆,请在
proguard-unity.txt 文件中添加
以下
保留规则,以
防止
Singular SDK 被移除:
-keep class com.singular.sdk.** { *; }
-keep public class com.android.installreferrer.** { *; }
-keep public class com.singular.unitybridge.** { *; }
iOS 配置提示
配置 iOS 特定设置以启用正确的归因、深度链接 和测试功能。
在为 iOS 构建 Unity 项目后、 在 Xcode 中构建之前,请更新 CocoaPods 依赖项,以确保您 拥有 最新的 SDK 版本。
cd /path/to/your/ios/project
pod repo update
pod update
为测试集成效果,请记录 IDFV(供应商标识符) 以便快速将测试设备添加到 Singular SDK 控制台。
添加 IDFV 日志
- 从 Unity 构建后打开您的 Xcode 项目。
- 导航至Classes > UnityAppController.mm。
-
找到
applicationDidBecomeActive方法。 - 添加以下代码以记录 IDFV:
// Log IDFV for testing
NSLog(@"Singular === IDFV: %@", [[[UIDevice currentDevice] identifierForVendor] UUIDString]);
- 在 Xcode 中构建并运行您的应用。
- 检查 Xcode 控制台日志中的 IDFV 输出。
- 复制 IDFV,并在 Singular SDK 控制台中将其添加为测试设备。
通过在 Xcode 项目中配置关联域名, 启用用于深度链接的通用链接。
深度链接设置步骤
- 添加关联域名:在 Xcode 中,导航 至应用目标的“签名与功能” 选项卡。
- 启用功能:点击 [+] 功能,并添加 “关联域名”。
-
添加域名:以以下格式添加您的 Singular 追踪
域名:
applinks:yourdomain.sng.link - 配置团队 ID:在 Singular 仪表盘中, 导航至应用设置,并添加您的 Apple 团队 ID。 这将允许 Singular 生成并托管通用链接所需的 Apple App Site Association (AASA) 文件。
重要提示:若未正确配置 关联 域名和团队 ID,通用链接将无法正常工作, 用户 将无法通过 Singular 追踪 链接打开您的应用。
如果您正在使用其他会注册 UnityAppController 的 SDK (例如 Firebase、Adjust 或 AppsFlyer),可能会遇到 冲突,导致 Singular 无法正确初始化。 在 Unity 中,同一时间只能有一个类注册为 UnityAppController 。
要解决此冲突:
-
在您的
Xcode 项目中打开
SingularSwizzledAppController.m文件。 - 取消该文件中所有代码的注释。
-
打开
SingularAppDelegate.m并确认以下行未被注释掉:IMPL_APP_CONTROLLER_SUBCLASS(SingularAppDelegate)
这使得 Singular 能够通过使用 方法替换(swizzling)而非子类化 UnityAppController 来与其他 SDK 协同工作。
集成 SDK
创建 SingularSDK GameObject
Singular SDK 需要在 Unity 场景层级中 有一个 GameObject 才能运行。 您可以通过使用提供的预制件或手动创建 来添加此 GameObject。
将预制体添加到场景
- 在“项目”面板中,导航至 Packages > Singular > SingularSDK > Prefabs。
- 将SingularSDKObject预制体拖入 您的 层级视图中。
- 现在可以在检查器中配置该预制件了。
手动创建 GameObject
- 在“层级”面板中,右键单击并 选择 “创建空对象”。
-
将 GameObject 命名为
SingularSDKObject(必须 使用此确切名称)。 - 选中该 GameObject 后,转到 检查器面板。
- 点击“添加组件”。
- 搜索“Singular”,并选择 Singular SDK脚本组件。
重要提示:GameObject 必须命名为
完全
SingularSDKObject ,SDK 才能
正常运行。
配置 SDK 设置
通过 Unity 检查器配置 SDK 凭据和初始化设置。API 密钥和密钥密文是 SDK 与 Singular 服务器通信的必备条件。
添加 API 凭据
- 选择 SingularSDKObject:在“层级视图”中点击 SingularSDKObject。
- 查找凭据:登录您的 Singular账户 并导航至 开发者工具 > SDK 集成 > SDK 密钥。
- 复制密钥:复制您的SDK 密钥和 SDK 密钥密文。
- 粘贴至检查器:在 Unity 的检查器面板中,将凭据粘贴 到Singular API 密钥和 Singular API 密钥字段中。
重要提示:请勿使用 Singular 报告 API 密钥。 请仅使用 SDK 集成 页面中专属的 SDK API 密钥和密钥密文。使用错误的凭据将导致数据无法发送 至 Singular。
验证集成:配置完成后,请使用 Singular SDK控制台 测试您的 实现,以确保事件被正确追踪。
默认检查器设置
SingularSDKObject 提供了合理的默认设置。了解这些 设置 有助于您根据应用需求自定义 SDK 的行为。
- 在唤醒时初始化:默认启用。 当 GameObject 唤醒时,SDK 会自动初始化。 如果您需要因 隐私 同意或其他要求而延迟初始化,请禁用此选项。
- 启用 SKAN:默认启用(仅限 iOS )。 在受管模式下启用 SKAdNetwork 归因,此时 Singular 会根据您 配置的 转化模型自动更新转化值。
- 等待追踪授权:设置 为 0(禁用)。如果您的应用显示 iOS 应用追踪 透明度 (ATT) 提示,请将此值设为 300 秒。这将延迟 SDK 会话,直到用户对 ATT 提示作出响应,确保 在获得同意后能够捕获 IDFA。如果不使用 ATT,请 保留 为 0。
- 启用日志记录:默认启用。 输出 SDK 调试日志,以协助集成和故障排除。 在生产环境构建中应禁用此选项。与 日志级别设置配合使用(见下文)。
-
日志级别:默认设置为 3(信息)。
控制
日志详细程度。数值越低,生成的日志越详细:
// Based on Android Logger log levels public enum LogLevel { Verbose = 2, // Most verbose Debug = 3, Info = 4, // Default Warn = 5, Error = 6, Assert = 7 // Least verbose }注意:详细日志主要 在 Android 平台上可用。
- DDL 超时(秒):设置为 0(使用 60 秒 默认值)。决定 SDK 等待服务器返回延迟 深链数据的时间长度。如果在此超时后仍未找到延迟深链,服务器将停止搜索。
- 会话超时(秒):设置为 0(使用 60 秒 默认值)。定义应用在后台运行多长时间后, 当 返回前台时 SDK 才会创建新会话。
- 短链接解析超时:设置为 0 (使用 10 秒默认值)。等待短链接 解析的最长时长。 若短链接无法解析,此设置可防止用户长时间等待,从而 保障用户体验。
其他配置选项
自 2025 年 6 月 18 日起:Meta 的 高级移动测量 (AMM) 已无需再实现 Meta 安装引荐来源。 如果启用了 AMM 报告,则无需配置 Meta 安装引荐来源。
若需支持旧版 Meta 安装来源归因 方法,请将您的 Facebook App ID 添加至 SingularSDKObject 配置中。
配置步骤
- 在您的 场景 层级中选择SingularSDKObject。
- 在检查器面板中,找到 “Facebook App ID” 字段。
- 输入您的 Facebook App ID(可在 Facebook 开发者 控制台中找到)。
其他资源:
初始化 SDK
隐私合规:在实施 Singular SDK 时,请遵守您运营所在地区的隐私法律,包括 GDPR、CCPA、COPPA 等。有关指导,请参阅 SDK 同意与退出实践。
每次应用启动时,请初始化 Singular SDK。SDK 初始化 对所有 Singular 归因功能至关重要,并会创建一个 新会话用于计算用户留存指标。
自动初始化
默认情况下,当场景通过Unity的Awake() 方法加载时,
SingularSDK.cs 脚本会自动初始化
SDK。若在Inspector中启用了“Initialize On Awake”
选项,则无需额外编写代码。
手动初始化
如果您需要在特定时间初始化 SDK(例如,在 获得用户同意之后),请禁用自动初始化并手动调用 初始化方法。
手动初始化设置
- 在场景层级视图中选中SingularSDKObject。
- 在检查器面板中,取消勾选“Initialize On Awake”。
-
在代码中调用 `
SingularSDK.InitializeSingularSDK()` 以进行初始化。
InitializeSingularSDK 方法
当自动初始化被禁用时,请使用此方法手动初始化 SDK。
using UnityEngine;
using Singular;
public class GameInitializer : MonoBehaviour
{
void Start()
{
// Perform any required setup (e.g., consent management)
CheckUserConsent();
// Initialize Singular SDK after consent is obtained
// SDK Key and Secret are configured on the SingularSDKObject
SingularSDK.InitializeSingularSDK();
}
void CheckUserConsent()
{
// Your consent logic here
}
}
线程安全:请始终在与其他 Unity API 调用相同的线程中 调用 Singular Unity SDK 方法。该 SDK 在多线程环境下 不具备线程安全性。
高级配置
Google Ads iOS 集成转化测量必备
如果您的应用运行针对 iOS 14.5 及以上版本用户的 Google Ads 广告系列,则需要执行额外的 SDK 配置步骤以支持 iOS 集成转化测量 (ICM)。这包括:
- 集成 Google 的设备端测量 (ODM) SDK
- 更新至 Singular iOS SDK v12.8.1 及以上版本(Unity 版需 v5.5.0 及以上,Flutter/Cordova 版需 v1.8.0 及以上,React Native 版需 v3.9.0 及以上)
- 添加
-ObjC链接器标志,并在SingularConfig中启用enableOdmWithTimeoutInterval
注意:启用enableOdmWithTimeoutInterval 会延迟SDK的初始化,并可能推迟深度链接回调。请在SDK的初始实现阶段完成此配置,以避免后续返工。
配置会话超时
自定义应用在后台停留的时间,当应用返回前台时,SDK 会在该时间后创建新的会话。
会话超时配置
默认会话超时时间为 60 秒。要更改此值:
- 在场景层级中选择SingularSDKObject。
- 在检查器面板中,找到“会话超时(秒)”字段。
- 输入所需的超时值(以秒为单位,例如 120 表示 2 分钟)。
- 若保留为 0,则使用默认的 60 秒超时。
最佳实践:设置会话超时时,请考虑应用的典型使用模式。对于频繁进行短时会话的游戏,较短的超时时间可能更合适;而生产力类应用则可能需要更长的超时时间。
从 .unitypackage 升级到 UPM
如果您要从旧版的.unitypackage 安装
方法迁移到现代的Unity Package Manager (UPM) 方案,请遵循以下
关键升级步骤。
重要提示:在安装 UPM 包之前,必须手动删除所有 现有的 Singular SDK 文件。若未执行此操作,将导致冲突和构建 错误。
升级流程
在通过 Unity Package Manager 安装 SDK 之前,请按顺序完成以下步骤:
1. 删除代码文件
导航至项目的 /Code
文件夹(通常为Assets/Singular/Code )
并删除所有与 Singular 相关的 C# 脚本。
2. 移除 Android 依赖项
导航至 /Plugins/Android 并删除以下 Singular 文件:
-
所有名称中包含“singular”的
.aar文件 -
所有名称中包含“singular”的
.jar文件 -
singular-sdk.aar -
install-referrer-*.aar -
singular-unitybridge.aar
3. 移除 iOS 依赖项
导航至/Plugins/iOS并 删除以下 Singular 文件:
-
所有名称中包含“singular”的
.h头文件(例如:SingularSDK.h) -
所有
.m实现文件 (例如:SingularUnityBridge.m) -
Singular.xcframework文件夹
重要提示:仅删除 Singular 专属 文件。请务必注意,不要删除项目可能依赖的其他插件 文件。
4. 验证清理状态
- 删除文件后,请完全关闭 Unity。
- 删除项目目录中的Library文件夹 以强制 Unity 重新导入资源。
- 重新打开您的 Unity 项目。
- 等待 Unity 完成资源的重新导入。
- 在继续进行 UPM 安装之前, 请确认没有编译错误。
5. 安装 UPM 包
现在您已准备好通过 Unity 包管理器 安装 Singular SDK。请遵循 本指南顶部的 UPM 安装说明。