Unity SDK - 基本集成

文档

先决条件

在安装 Singular Unity SDK 之前,请完成以下前提步骤,以确保集成过程顺利进行。

所需先决条件:


安装

通过 Unity 包管理器(UPM)安装

Singular Unity SDK 是通过 Unity 包管理器使用 Git URL 安装的。请按照以下步骤将 SDK 添加到您的项目中。

安装步骤

  1. 打开软件包管理器:在 Unity 中,导航至窗口 > 软件包管理器
  2. 从 Git 添加软件包:点击左上角的[+]按钮并选择"从 Git URL 添加软件包"
  3. 输入 Git URL
    • 对于标准 SDK:输入https://github.com/singular-labs/Singular-Unity-SDK.git
    • 儿童 SDK输入https://github.com/singular-labs/Singular-Unity-SDK.git#kids
  4. 完成安装:单击"添加 "安装 SDK 包。

不使用 Google EDM4U?如果您的项目不使用外部依赖关系管理器,则必须手动下载并添加本地依赖关系。

手动安装依赖项

  1. 下载依赖项:从 Singular 的 S3 bucket 下载相应的Plugins.zip 文件:
  2. 提取到资产:提取下载的文件并将其移动到 Unity 项目中的Assets > Plugins
  3. 配置 iOS 框架:导航至 "资产">"插件">"iOS",然后选择Singular.xcframework
  4. 嵌入二进制文件:在 "检查器 "窗格中,选中"添加到嵌入式二进制文件 "选项。

安卓配置提示

配置 Android 构建设置以确保 SDK 功能正常。 Unity 提供了多种自定义 Android 清单和 Gradle 文件的方法。

如何更新 AndroidManifest.xml
#

您可以使用以下两种方法之一修改 AndroidManifest:

方法 1:Unity 自定义清单

  1. 导航至 "文件" > "构建设置" > "播放器设置" > "发布设置"
  2. 在 "Publishing Settings(发布设置)"部分下启用"Custom Main Manifest(自定义主清单)"。
  3. Unity 会在Assets/Plugins/Android/AndroidManifest.xml 中生成一个默认的AndroidManifest.xml文件。
  4. 编辑该文件以添加所需的权限和配置。

来源:Unity Android Manifest 文档Unity Android Manifest 文档

方法 2:安卓工作室

  1. 使用 "文件">"构建设置">"导出项目"从 Unity导出项目
  2. 在 Android Studio 中打开导出的项目。
  3. 直接在 Android Studio 中编辑AndroidManifest.xml 文件。
如何更新 Gradle 编译文件
#

方法 1:Unity 自定义模板

  1. 导航至 "文件">"构建设置">"播放器设置">"发布设置"。
  2. 在 "发布设置 "部分启用"自定义 Gradle 模板"
  3. Unity 会在Assets/Plugins/Android/mainTemplate.gradle 生成mainTemplate.gradle 文件。
  4. 在该文件中添加您的自定义 Gradle 配置。

来源:Unity Gradle 概述文档Unity Gradle 概述文档

方法 2:Android Studio

  1. 从 Unity 导出项目。
  2. 在 Android Studio 中打开项目。
  3. 直接编辑应用程序的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 文件中添加排除规则。

  1. 在 Unity 项目中找到*Dependencies.xml 文件(通常位于Assets/Editor或类似位置)。
  2. 为 SDK 依赖项之一添加排除规则:
XML
<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 配置文件中应用排除规则。

  1. 导航至 "文件">"构建设置">"播放器设置">"发布设置"。
  2. 启用"自定义主 Gradle 模板 ""自定义启动器 Gradle 模板"
  3. 打开Assets/Plugins/Android/mainTemplate.gradle(或launcherTemplate.gradle )。
  4. 在依赖项块中添加排除规则:
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'
}

替代方案:在依赖项块后添加全局排除规则:

Gradle
configurations.all {
    exclude group: 'com.android.vending', module: 'licensing'
}

验证解决方案

  1. 应用排除规则后,删除Library/BeeTemp文件夹,清理项目。
  2. 在 Unity 中重建 Android 项目。
  3. 确认构建输出中不再出现重复类错误。

为什么会这样?两个 SDK 都捆绑了相同的 Android 许可库作为传递依赖关系。 排除会告诉 Gradle 只使用一个副本,从而解决冲突。

ProGuard 配置
#

如果你的项目使用 ProGuard 进行代码混淆,请在proguard-unity.txt 文件中添加以下保留规则,以防止 Singular SDK 被剥离:

proguard-unity.txt
-keep class com.singular.sdk.** { *; }
-keep public class com.android.installreferrer.** { *; }
-keep public class com.singular.unitybridge.** { *; }

iOS 配置提示

配置 iOS 专用设置,以启用正确的归属、深度链接和测试功能。

更新 CocoaPods 依赖项
#

为 iOS 构建 Unity 项目后,在 Xcode 中构建之前,更新 CocoaPods 依赖项,以确保您拥有最新的 SDK 版本。

Terminal
cd /path/to/your/ios/project
pod repo update
pod update
记录 IDFV 以进行测试
#

测试集成时,请记录 IDFV(供应商标识符),以便在 Singular SDK 控制台中快速添加测试设备。

添加 IDFV 日志

  1. 从 Unity 生成后,打开您的 Xcode 项目。
  2. 导航至类 > UnityAppController.mm
  3. 找到applicationDidBecomeActive 方法。
  4. 添加以下代码以记录 IDFV:
Objective-C
// Log IDFV for testing
NSLog(@"Singular === IDFV: %@", [[[UIDevice currentDevice] identifierForVendor] UUIDString]);
  1. 在 Xcode 中构建并运行应用程序。
  2. 检查 Xcode 控制台日志中的 IDFV 输出。
  3. 复制 IDFV 并将其添加为Singular SDK 控制台中的测试设备。
配置深度链接支持
#

通过在 Xcode 项目中配置关联域(Associated Domains),启用用于深度链接的通用链接。

  1. 添加关联域:在 Xcode 中,导航到应用程序目标的 "签名和功能"选项卡。
  2. 启用能力:单击[+] 能力并添加"关联域"
  3. 添加域:以下列格式添加您的 Singular 跟踪域:applinks:yourdomain.sng.link
  4. 配置团队 ID:在 Singular 控制面板中,导航至应用程序设置并添加苹果团队 ID。 这将允许 Singular 生成和托管通用链接所需的苹果应用程序站点协会(AASA)文件。

重要提示:如果没有正确配置关联域和团队 ID,通用链接将无法工作,用户也无法通过 Singular 跟踪链接打开您的应用程序。


集成 SDK

创建 SingularSDK 游戏对象

Singular SDK 需要在你的 Unity 场景层次结构中创建一个 GameObject 才能运行。 你可以使用提供的预制件或手动创建来添加此 GameObject。

方法 1:使用 Singular 预制件(推荐)
#

将预置添加到场景

  1. 在 "项目"窗格中,导航至 "包" > "Singular" > "SingularSDK" > "预制件"。
  2. SingularSDKObject预制件拖入 "层次结构"窗格。
  3. 现在,预制件就可以在检查器中进行配置了。
方法 2:手动创建游戏对象
#

手动创建游戏对象

  1. 层次结构窗格中,右键单击并选择 "创建空"。
  2. 将 GameObject 命名为SingularSDKObject (需要准确名称)。
  3. 选中 GameObject 后,导航至Inspector窗格。
  4. 单击 "添加组件"。
  5. 搜索"Singular "并选择Singular SDK脚本组件。

关键:GameObject 必须准确命名为SingularSDKObject ,SDK 才能正常运行。

配置 SDK 设置

通过 Unity 检查器配置 SDK 证书和初始化设置。SDK 与 Singular 服务器通信时需要您的 API 密钥和秘钥。

添加 API 凭据

  1. 选择 SingularSDKObject:点击层次结构中的 SingularSDKObject。
  2. 找到凭据:登录Singular 账户,导航至 "开发工具" > "SDK 集成" > "SDK 密钥"。
  3. 复制密钥:复制SDK 密钥SDK Secret
  4. 粘贴到检查器中:在 Unity 的 Inspector 窗格中,将凭证粘贴到Singular API KeySingular 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(信息),用于控制日志记录的冗长程度。数字越小,日志越详细:
    C#
    // 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 秒默认值)。短链接解析的最长等待时间,防止在短链接无法解析时出现长时间等待,从而保护用户体验。

其他配置选项

Facebook (Meta) 安装推荐人配置
#

截至 2025 年 6 月 18 日:如果启用了AMM报告,则无需配置 Meta Install Referrer。

如果您需要支持传统的 Meta Install Referrer 归属方法,请将您的 Facebook 应用程序 ID 添加到 SingularSDKObject 配置中。

配置步骤

  1. 在场景层次结构中选择SingularSDKObject
  2. 在 "检查器 "窗格中找到"Facebook 应用 ID "字段。
  3. 输入您的 Facebook 应用 ID(可在 Facebook 开发者控制台中找到)。

其他资源


初始化 SDK

隐私合规性:实施 Singular SDK 时,请遵守您所在运营地区的隐私法,包括 GDPR、CCPA、COPPA 等。有关指导,请参阅SDK 选择加入和选择退出实践

每次启动应用程序时都要初始化Singular SDK。SDK初始化对所有Singular归因功能都至关重要,并为计算用户留存指标创建新会话。

自动初始化

默认情况下,当您的场景通过 Unity 的Awake() 方法加载时,SingularSDK.cs 脚本会自动初始化 SDK。如果在检查器中启用了 "唤醒时初始化",则无需额外代码。

手动初始化

如果您需要在特定时间初始化 SDK(例如,在获得用户同意后),请禁用自动初始化并手动调用初始化方法。

手动初始化设置

  1. 在场景层次结构中选择SingularSDKObject
  2. 在 "检查器 "窗格中,取消选中 "唤醒时初始化"
  3. 准备初始化时,在代码中调用SingularSDK.InitializeSingularSDK()

InitializeSingularSDK 方法

禁用自动初始化时,使用此方法手动初始化 SDK。

C#
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 秒。要更改此值,请

  1. 在场景层次结构中选择SingularSDKObject
  2. 在 "检查器 "窗格中,找到 "会话超时 Sec"字段。
  3. 以秒为单位输入所需的超时值(例如,120 为 2 分钟)。
  4. 如果使用默认的 60 秒超时值,则保留为 0。

最佳实践:设置会话超时时,请考虑应用程序的典型使用模式。会话时间较短的游戏可能会受益于较短的超时,而生产力应用程序可能需要较长的超时。


从 .unitypackage 升级到 UPM

如果要从传统的.unitypackage 安装方法迁移到现代的 Unity Package Manager (UPM) 方法,请遵循以下关键升级步骤。

迁移说明:从 .unitypackage 迁移到 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.验证清洁状态

  1. 删除文件后,完全关闭 Unity。
  2. 删除项目目录中的Library文件夹,以强制 Unity 重新导入资产。
  3. 重新打开 Unity 项目。
  4. 等待 Unity 完成重新导入资产。
  5. 确认没有编译错误后再继续安装 UPM。

5.安装 UPM 软件包

现在,您已准备好通过 Unity 包管理器安装 Singular SDK。请按照本指南顶部的UPM 安装说明进行操作。