先决条件
在安装 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 bucket 下载相应的
Plugins.zip文件:-
标准 SDK(v5.6.0):
下载标准 SDK 插件 -
儿童 SDK(v5.6.0):
下载儿童 SDK 插件
-
标准 SDK(v5.6.0):
- 提取到资产:提取下载的文件并将其移动到 Unity 项目中的Assets > Plugins。
-
配置 iOS 框架:导航至 "资产">"插件">"iOS",然后选择
Singular.xcframework。 - 嵌入二进制文件:在 "检查器 "窗格中,选中"添加到嵌入式二进制文件 "选项。
安卓配置提示
配置 Android 构建设置以确保 SDK 功能正常。 Unity 提供了多种自定义 Android 清单和 Gradle 文件的方法。
您可以使用以下两种方法之一修改 AndroidManifest:
方法 1:Unity 自定义清单
- 导航至 "文件" > "构建设置" > "播放器设置" > "发布设置"。
- 在 "Publishing Settings(发布设置)"部分下启用"Custom Main Manifest(自定义主清单)"。
-
Unity 会在Assets/Plugins/Android/AndroidManifest.xml 中生成一个默认的
AndroidManifest.xml文件。 - 编辑该文件以添加所需的权限和配置。
来源:Unity Android Manifest 文档Unity Android Manifest 文档
方法 2:安卓工作室
- 使用 "文件">"构建设置">"导出项目"从 Unity导出项目。
- 在 Android Studio 中打开导出的项目。
-
直接在 Android Studio 中编辑
AndroidManifest.xml文件。
方法 1:Unity 自定义模板
- 导航至 "文件">"构建设置">"播放器设置">"发布设置"。
- 在 "发布设置 "部分启用"自定义 Gradle 模板"。
-
Unity 会在Assets/Plugins/Android/mainTemplate.gradle 生成
mainTemplate.gradle文件。 - 在该文件中添加您的自定义 Gradle 配置。
来源:Unity Gradle 概述文档Unity Gradle 概述文档
方法 2:Android Studio
- 从 Unity 导出项目。
- 在 Android Studio 中打开项目。
-
直接编辑应用程序的
build.gradle文件。
在 Unity 中构建 Android 应用程序时,您可能会遇到 "类重复"(Duplicate class)错误,这是由于多个 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.10.0.aar -> jetified-singular_sdk-12.10.0-runtime (com.singular.sdk:singular_sdk:12.10.0)
解决方案 1:使用外部依赖关系管理器 (EDM4U)
如果您的项目使用Unity 外部依赖关系管理器(推荐),请在依赖关系 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.10.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.10.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 项目。
- 导航至类 > UnityAppController.mm。
-
找到
applicationDidBecomeActive方法。 - 添加以下代码以记录 IDFV:
// Log IDFV for testing
NSLog(@"Singular === IDFV: %@", [[[UIDevice currentDevice] identifierForVendor] UUIDString]);
- 在 Xcode 中构建并运行应用程序。
- 检查 Xcode 控制台日志中的 IDFV 输出。
- 复制 IDFV 并将其添加为Singular SDK 控制台中的测试设备。
通过在 Xcode 项目中配置关联域(Associated Domains),启用用于深度链接的通用链接。
深度链接设置步骤
- 添加关联域:在 Xcode 中,导航到应用程序目标的 "签名和功能"选项卡。
- 启用能力:单击[+] 能力并添加"关联域"。
-
添加域:以下列格式添加您的 Singular 跟踪域:
applinks:yourdomain.sng.link - 配置团队 ID:在 Singular 控制面板中,导航至应用程序设置并添加苹果团队 ID。 这将允许 Singular 生成和托管通用链接所需的苹果应用程序站点协会(AASA)文件。
重要提示:如果没有正确配置关联域和团队 ID,通用链接将无法工作,用户也无法通过 Singular 跟踪链接打开您的应用程序。
集成 SDK
创建 SingularSDK 游戏对象
Singular SDK 需要在你的 Unity 场景层次结构中创建一个 GameObject 才能运行。 你可以使用提供的预制件或手动创建来添加此 GameObject。
将预置添加到场景
- 在 "项目"窗格中,导航至 "包" > "Singular" > "SingularSDK" > "预制件"。
- 将SingularSDKObject预制件拖入 "层次结构"窗格。
- 现在,预制件就可以在检查器中进行配置了。
手动创建游戏对象
- 在层次结构窗格中,右键单击并选择 "创建空"。
-
将 GameObject 命名为
SingularSDKObject(需要准确名称)。 - 选中 GameObject 后,导航至Inspector窗格。
- 单击 "添加组件"。
- 搜索"Singular "并选择Singular SDK脚本组件。
关键:GameObject 必须准确命名为SingularSDKObject ,SDK 才能正常运行。
配置 SDK 设置
通过 Unity 检查器配置 SDK 证书和初始化设置。SDK 与 Singular 服务器通信时需要您的 API 密钥和秘钥。
添加 API 凭据
- 选择 SingularSDKObject:点击层次结构中的 SingularSDKObject。
- 找到凭据:登录Singular 账户,导航至 "开发工具" > "SDK 集成" > "SDK 密钥"。
- 复制密钥:复制SDK 密钥和SDK Secret。
- 粘贴到检查器中:在 Unity 的 Inspector 窗格中,将凭证粘贴到Singular API Key和Singular API Secret字段中。
关键:请勿使用 Singular Reporting API Key,只能使用 SDK Integration 页面中特定于 SDK 的 API Key 和 Secret。使用错误的凭证会导致数据无法发送到 Singular。
验证集成:配置完成后,使用Singular SDK 控制台测试您的实施,确保事件被正确跟踪。
默认检查器设置
SingularSDKObject 自带合理的默认设置。了解这些设置有助于你根据应用程序的要求定制 SDK 行为。
- 唤醒时初始化:默认已启用。 当 GameObject 唤醒时,SDK 会自动初始化。 如果您需要延迟初始化以满足隐私同意或其他要求,请禁用此选项。
- 启用 SKAN:默认已启用(仅限 iOS)。 在托管模式下启用 SKAdNetwork 归属,Singular 会根据您配置的转换模型自动更新转换值。
- 等待跟踪授权:设为 0(禁用)。如果您的应用程序显示 iOS App Tracking Transparency (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 日:如果启用了AMM报告,则无需配置 Meta Install Referrer。
如果您需要支持传统的 Meta Install Referrer 归属方法,请将您的 Facebook 应用程序 ID 添加到 SingularSDKObject 配置中。
配置步骤
- 在场景层次结构中选择SingularSDKObject。
- 在 "检查器 "窗格中找到"Facebook 应用 ID "字段。
- 输入您的 Facebook 应用 ID(可在 Facebook 开发者控制台中找到)。
其他资源:
初始化 SDK
隐私合规性:实施 Singular SDK 时,请遵守您所在运营地区的隐私法,包括 GDPR、CCPA、COPPA 等。有关指导,请参阅SDK 选择加入和选择退出实践。
每次启动应用程序时都要初始化Singular SDK。SDK初始化对所有Singular归因功能都至关重要,并为计算用户留存指标创建新会话。
自动初始化
默认情况下,当您的场景通过 Unity 的Awake() 方法加载时,SingularSDK.cs 脚本会自动初始化 SDK。如果在检查器中启用了 "唤醒时初始化",则无需额外代码。
手动初始化
如果您需要在特定时间初始化 SDK(例如,在获得用户同意后),请禁用自动初始化并手动调用初始化方法。
手动初始化设置
- 在场景层次结构中选择SingularSDKObject。
- 在 "检查器 "窗格中,取消选中 "唤醒时初始化"。
-
准备初始化时,在代码中调用
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 在多个线程之间不具备线程安全性。
高级配置
配置会话超时
自定义应用程序返回前台时,在 SDK 创建新会话之前,应用程序可以在后台停留多长时间。
会话超时配置
默认会话超时为 60 秒。要更改此值,请
- 在场景层次结构中选择SingularSDKObject。
- 在 "检查器 "窗格中,找到 "会话超时 Sec"字段。
- 以秒为单位输入所需的超时值(例如,120 为 2 分钟)。
- 如果使用默认的 60 秒超时值,则保留为 0。
最佳实践:设置会话超时时,请考虑应用程序的典型使用模式。会话时间较短的游戏可能会受益于较短的超时,而生产力应用程序可能需要较长的超时。
从 .unitypackage 升级到 UPM
如果要从传统的.unitypackage 安装方法迁移到现代的 Unity Package Manager (UPM) 方法,请遵循以下关键升级步骤。
关键:在安装 UPM 包之前,您必须手动删除所有现有的 Singular SDK 文件。否则将导致冲突和构建错误。
升级步骤
在通过 Unity 软件包管理器安装 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并删除以下奇异文件:
-
所有
.h头文件(如SingularSDK.h) -
所有
.m实现文件(如SingularUnityBridge.m) -
Singular.xcframework文件夹
重要:只删除 Singular 特有的文件。注意不要删除项目可能依赖的其他插件文件。
4.验证清洁状态
- 删除文件后,完全关闭 Unity。
- 删除项目目录中的Library文件夹,以强制 Unity 重新导入资产。
- 重新打开 Unity 项目。
- 等待 Unity 完成重新导入资产。
- 确认没有编译错误后再继续安装 UPM。
5.安装 UPM 软件包
现在,您已准备好通过 Unity 包管理器安装 Singular SDK。请按照本指南顶部的UPM 安装说明进行操作。