Unity SDK 集成指南

 

新功能:视频指南

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

开始之前:SDK 先决条件

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

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

1.安装 SDK

1.1.下载并导入 SDK 软件包

导入 Unity 自定义软件包

如果您是从 4.3.2 版或更早版本升级?

在导入新的 unity 包之前,请导航至Assets > Plugins > iOS 并删除以下文件!

  • Attributes.h
  • Events.h
  • libSingular.a
  • Singular.h
  • SingularAdData.h
  • SingularConfig.h
  • SingularLinkParams.h
  1. 下载新的 Singular SDK unitypackage v4.4.2 文件。
  2. 从 Unity 菜单导航至

    • Assets > Import Package > Custom package
    • 选择下载的unitypackage
    • 选择导入

1.2.安卓配置

提示: 使用 Unity 时如何更新 AndroidManifest
  1. 从 Unity v2018.3 版开始,只需启用播放器窗口中的自定义主 Manifest属性(可通过File > Build Settings > Player Settings > Publishing settings 访问),即可添加自己的AndroidManifest 文件。这将为您生成一个默认的AndroidManifest.xml文件,您可以对其进行编辑。

    该文件的位置为:Assets/Plugins/Android/AndroidManifest.xml

    来源:https://docs.unity3d.com/2023.2/Documentation/Manual/android-manifest.html

  2. 从 Unity 导出应用程序后,您可以从 Android Studio 访问AndroidManifest.xml ,而不是使用 Unity 的自定义 Main Manifest 文件。

提示: 使用 Unity 时如何更新 Gradle 设置
  1. 从Unity v2018.3开始,你可以在播放器窗口中添加自己的启用自定义Gradle模板属性(可通过custom Gradle build file ,只需File > Build Settings > Player Settings > Publishing settings )。这会为你生成一个默认的mainTemplate.gradle文件,你可以对其进行编辑。

    该文件的位置是:Assets/Plugins/Android/mainTemplate.gradle

    来源:https://docs.unity3d.com/2023.2/Documentation/Manual/android-gradle-overview.html

  2. 从 Unity 导出应用程序后,您可以从 Android Studio 访问应用程序build.gradle ,而不是使用 Unity 的自定义 Gradle 构建文件。

提示: 您计划支持 Android 12 设备吗?

play-services-ads-identifier-18.0.1.aar 文件到Assets/Plugins/Android/ 文件夹,这样 Unity 就会包含捕获 Google Advertising Identifier 所需的依赖项。如果您已经拥有此依赖项,则可以跳过此步骤。

更新 AndroidManifest 权限

AndroidManifest.xml 文件中,添加以下权限:


<!--  使用互联网连接时需要此许可  -->
<uses-permission android:name="android.permission.INTERNET" />

<!--  需要此权限才能检查是否存在活动的互联网连接  -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!--  检索 Google Play Referrer 数据需要此权限。 -->
<uses-permission android:name="BIND_GET_INSTALL_REFERRER_SERVICE" />

<!--  验证 Google 安装欺诈需要此权限  -->
<uses-permission android:name="com.android.vending.CHECK_LICENSE" />
	
您是否已禁用 Singular SDK 的传递依赖关系
  1. 如果已禁用 Singular SDK 的传递依赖关系,请在应用程序的 build.gradle 中添加以下内容。

    implementation 'com.android.installreferrer:installreferrer:2.2'
    implementation 'com.google.android.gms:play-services-appset:16.0.0'
  2. Singular SDK 需要Google Mobile Ads API,它是Google Play Services APIs 17.0.0+ 的一部分。 如果你已经将 Google Play Services 集成到你的应用程序中,那么就满足了这个要求。如果尚未集成,您可以在应用程序的 build.gradle 文件中加入以下依赖关系,单独集成 Google Mobile Ads:

    implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1+'

    有关详细信息,请参阅 Google 的 Google Play 服务设置指南

您使用的是 Proguard 还是 Eclipse

如果使用 Proguard,请 在 proguard-unity.txt 文件中添加以下代码行:

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

如果使用 Eclipse 构建,请 使用以下方法之一将 AAR 集成到 Eclipse 项目中:

  1. 解压缩singular_sdk-12.x.x.aar。
  2. classes.jar重命名为singular_sdk-12.x.x.jar(这是主 SDK jar)。
  3. 以任何方式将上述 jar 和libs/installreferrer-release.jar(GoogleReferrerAPI 库)集成到 Eclipse 项目中。
  4. 将 AAR 中 AndroidManifest.xml 中的 BIND_GET_INSTALL_REFERRER_SERVICE 权限复制到您的 AndroidManifest.xml。

1.3.iOS 配置

从 Unity 构建后,将以下库/框架链接到您的 Unity XCode 项目。导航至UnityFrameworkTarget,然后选择 "BuildPhases(构建阶段)">"Link Binary with Libraries(链接二进制库)"。添加以下内容:

  • WebKit.framework
  • libsqlite3.0.tbd
  • libz.tbd
  • AdServices.framework (必须添加, 但标记为可选 ,因为它仅适用于 iOS 14.3 及更高版本的设备)。如果计划在 Apple Search Ads 上运行,也必须添加!

重要:如果您计划使用Apple Search Ad 广告系列并希望跟踪归因,则必须在应用程序构建中使用AdServices.framework

2.SDK 集成

2.1.配置 SingularSDKObject

在 Unity 平台层次结构窗格中:

  1. 场景中添加一个"空游戏对象(Empty GameObject)",并准确命名为:SingularSDKObject

  2. SingularSDKObject 中添加脚本组件,并选择SingularSDK 脚本。

  3. SingularSDKObject 的 "检查 "窗格中,在相应字段中粘贴您的Singular SDK 密钥SDK Secret。要获取 SDK 密钥和秘钥,请登录 Singular 账户并访问 "Developer Tools > SDK Integration > SDK Keys")。

    如果Singular SDK Key和Secret应用错误,数据将无法发送到Singular。
    使用 Singular SDK 控制台测试你的实现,以验证行为是否正确。

注: SingularSDKObject 的默认检查窗格设置

检查窗格中启用了以下选项:

  • Initialize On Awake (已选中)

    此设置使 Unity 能够根据应用程序的唤醒状态控制 Singular SDK 初始化。

    请务必遵守应用程序的隐私合规性要求,并根据需要更新此选项。取消选中该选项将禁止根据 "唤醒 "状态初始化 Singular SDK,并需要手动初始化。

  • SKAN Enabled 选中

    从 Unity SDK 4.0.17 版开始, 默认启用SKAdNetwork它在 "托管模式"(Singular 使用您在 Singular 面板中选择的转换模型为您更新 SKAN 转换值)下启用。

    只要您使用的是最新版本的 SDK,就无需设置其他任何内容或添加任何代码即可使用 SKAdNetwork。

  • Wait For Tracking Authorization 设置为 0(关闭

    如果您的应用程序显示应用程序跟踪透明度(ATT)提示,建议将此超时设置为 300 秒。添加超时后,Singular SDK 会话将延迟,允许用户在将事件记录到 Singular 服务器之前授权/拒绝 AppTrackingTransparency 同意。一旦用户回复 ATT 提示,Singular SDK 就会立即继续。如果不显示 ATT,则此选项的默认值应为 0(不等待)。

  • Enable Logging (已选中)

    启用 Singular SDK 的 "详细日志"。必须与 "日志级别 "选项一起使用。

  • Log Level 设置为 3

    允许 Singular SDK 在 LogCat 输出中显示警告日志。

  • Ddl Timeout Sec 设置为 0

    默认情况下,设置为 "0 "时,超时时间为 60 秒,这将告诉 Singular 服务器搜索与最后一次触摸属性相关的深层链接值的时间。如果在 60 秒内没有找到递延深度链接,服务器就会停止搜索。

  • Session Timeout Sec 设置为 0

    这是应用程序从后台返回前台时,Singular SDK 注册新会话前的超时(秒)。默认情况下,设置为 "0 "时,超时时间为 60 秒。如有需要,您可以调整此设置以获得更大的窗口。

  • Shortlink Resolve Timeout 设置为 0

    默认情况下,设置为 "0 "将使用 10 秒超时。 该超时可保护用户体验,如果给定的短链接在指定时间内未解析,Singular SDK 将不会触发深层链接处理程序。

其他检查窗格选项:

启用 Facebook(META 安装推荐人)

要支持META 安装推荐人归属方法,请在 SingularSDKObject 的检测窗格中添加 Facebook 应用程序 ID

  1. 单击主场景中的 SingularSDKObject。
  2. 打开 "检查窗格",找到 "Facebook 应用 ID "字段。
  3. 添加 Facebook 应用程序 ID

2.2.使用 SKAdNetwork

从 Unity SDK 4.0.17 版开始, SKAdNetwork默认启用。 它在 "托管模式"(Singular 使用您在 Singular 面板中选择的转换模型为您更新 SKAN 转换值)中启用。

只要您使用的是最新版本的 SDK,就无需设置其他任何内容或添加任何代码即可使用 SKAdNetwork。

其他信息

在旧版本的 SDK 中启用 SKAdNetwork

如果您使用的是旧版本的 SDK,则需要通过以下方法之一启用 SKAdNetwork:

  • 访问SingularSDKObject ,将SKANEnabled 设置为True
  • 在应用程序代码中调用SingularSDK.SkanRegisterAppForAdNetworkAttribution()
在手动模式下使用 SKAdNetwork(高级)

如果您选择使用自己的逻辑手动管理 SKAN 转换值,则需要执行以下操作:

  • 转到SingularSDKObject ,将manualSKANConversionManagement设为True
  • 在代码中使用以下方法设置和检索转换值。
SingularSDK.SkanUpdateConversionValue 方法
说明

更新 SKAdNetwork 转换值。

注意: 如果您选择手动更新 SKAdNetwork 转换值,请使用此方法。此方法只有在manualSKANConversionManagement设置为True 时才有效。

签名 public void SkanUpdateConversionValue(int value)
使用示例
// 报名活动
Singular.Event("SignUp");

// 将转换值更新为 7
SingularSDK.SkanUpdateConversionValue(7);
SingularSDK.SkanGetConversionValue 方法
说明 获取 Singular SDK 追踪的当前转换值。
签名 public int? SkanGetConversionValue()
使用示例
int? value = SingularSDK.SkanGetConversionValue();
SingularSDK.SetConversionValueUpdatedHandler 方法
说明 设置转换值更新时接收通知的处理程序。
签名 public void SetConversionValueUpdatedHandler(SingularConversionValueUpdatedHandler handler)
使用示例
public class Main : MonoBehaviour, SingularConversionValueUpdatedHandler {
  void Awake() {
    SingularSDK.SetConversionValueUpdatedHandler(this);
  }

  void OnConversionValueUpdated(int value) {
    // 使用转换值
  }
}

2.3.处理 iOS 应用程序跟踪透明度(ATT)同意书

您是否显示了应用程序跟踪透明度(ATT)提示?

从 iOS 14.5 开始,应用程序在访问和共享某些有助于跟踪目的的用户数据(包括设备 IDFA)之前,必须征得用户同意(使用应用程序跟踪透明度框架)。

我们强烈建议您征得用户同意以获取IDFA

建议延迟 Singular SDK 初始化,直到用户回复 ATT 提示。

默认情况下,Singular SDK 会在初始化时发送用户会话。因此,在 Singular SDK 发送第一个会话 之前征求同意和检索 IDFA 至关重要

提示: 如果您的应用程序显示 "应用程序跟踪透明度(ATT)"提示,建议将超时设置为300秒。如果不显示 ATT,则该选项的默认值应保持为 0(无等待)。

要配置waitForTrackingAuthorizationWithTimeoutInterval ,请调整SingularSDKObject 检查窗格中的配置选项。这将设置 Singular SDK 在将事件记录到 Singular 服务器之前等待用户授权/拒绝 AppTrackingTransparency 同意的最长时间(以秒为单位)。

2.4.处理深层链接

深层链接是指向应用程序内部特定内容的链接。当用户在安装了应用程序的设备上点击深层链接时,应用程序就会打开并显示特定的产品或体验。

奇异跟踪链接可以包括深度链接和延迟深度链接(更多信息请参阅我们的深度链接常见问题奇异链接常见问题)。

下面的说明将告诉您如何

  1. 访问导致您的应用程序被打开的跟踪链接、
  2. 读取深度链接目的地,以及
  3. 显示相应内容。

注释

  • 本文假定您的组织正在使用Singular Links- Singular 于 2019 年推出的新追踪链接技术。Singular的老客户可能正在使用Singular较早的跟踪链接(传统链接)。 要支持使用传统链接进行深度链接,请参阅使用传统链接处理深度链接
  • 您应用程序的深度链接目的地需要在 Singular 的 "应用程序 "页面上进行设置(请参阅 "为归因跟踪配置您的应用程序")。

设置深度链接 前提条件

  1. iOS 和 Android 的先决条件:按照Singular 链接先决条件中的说明操作。

  2. Unity 的附加设置:在应用程序的AndroidManifest.xml 文件中,将活动名称属性从默认的 UnityPlayerActivity:

    <activity android:name="com.unity3d.player.UnityPlayerActivity"

    改为

    <activity android:name="com.singular.unitybridge.SingularUnityActivity"

    注: 如果您实施了自定义活动,请在活动的onNewIntent中调用此方法:

    @Override
    protected void onNewIntent(Intent intent) {
        setIntent(intent);
    
        // 在自定义活动的 onNewIntent 中调用此方法
        SingularUnityBridge.onNewIntent(intent);
    }

添加深度链接处理程序

Singular SDK 提供了一种处理机制,用于读取导致应用程序被打开的跟踪链接的详细信息。

要使用处理程序

  1. 实现SingularLinkHandler 接口。
  2. 在类的任意位置调用SetSingularLinkHandler 方法,将类注册为深度链接处理程序。
  3. 调用 SetSingularLinkHandler 时,Singular SDK 会获取跟踪链接并调用OnSingularLinkResolved 方法,将跟踪链接的详细信息传递给它。覆盖此方法可读取链接详细信息并进行处理。

以下示例代码展示了这三个步骤:

public class Main : SingularLinkHandler {
    // ...
    void Awake () {
      // 将该类注册为奇异链接处理程序。
      // 您可以在应用程序运行的任何时候调用该方法。它会获取跟踪链接的详细信息,并调用 OnSingularLnkResolved。
      SingularSDK.SetSingularLinkHandler(this);
    }
    
    public void OnSingularLinkResolved(SingularLinkParams linkParams) {
      // 在 "管理链接 "页面中配置的深层链接目的地
      string deeplink = linkParams.Deeplink;
      
      // 添加到链接的直通参数(如果有)。
      string passthrough = linkParams.Passthrough;
      
      // 链接是否配置为延迟深度链接。
      bool isLinkDeferred = linkParams.IsDeferred;
      
      // 在此处添加代码以处理深层链接
    }
    
    // ...

方法参考

SetSingularLinkHandler
SetSingularLinkHandler 方法
方法描述 注册一个处理程序,用于检索导致打开应用程序的跟踪链接的详细信息。
签名
public void SetSingularLinkHandler(SingularLinkHandler 
handler)
使用示例
public class Main : MonoBehaviour, SingularLinkHandler {
    void Awake () {
        SingularSDK.SetSingularLinkHandler(this)
    }
}
OnSingularLinkResolved
OnSingularLinkResolved Method
说明 SetSingularLinkHandler. 的回调方法 读取并处理跟踪链接的详细信息。
签名
public void OnSingularLinkResolved(SingularLinkParams
linkParams)

:SingularLinkParams 对象包含以下值:

  • Deeplink - 在 Singular 平台的 "管理链接 "页面中配置的深度链接目的地。
  • Passthrough - 添加到链接的直通参数(如果有)。
  • IsDeferred - 链接是否配置为延迟深度链接。
使用示例
public void OnSingularLinkResolved(SingularLinkParams
linkParams){ // 阅读跟踪链接详情并记录 Debug.Log("deeplink: " + linkParams.Deeplink); Debug.Log("passthrough: " + linkParams.Passthrough); Debug.Log("is_deferred: " + linkParams.IsDeferred); }

使用传统链接处理深度链接

如果您是 Singular 的老客户,您可能使用的是传统跟踪链接(Singular 较早的跟踪链接机制),而不是较新的 Singular 链接。传统链接在Create LinkView Links 页面中进行管理,它们也提供深度链接和延迟深度链接功能。

如果贵组织使用传统链接,则需要为深度链接实现一个名为SingularDeferredDeepLinkHandler 的处理程序,而不是上述的 SingularLinksHandler。实现方法非常相似。

2.5.初始化 SDK

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

每次打开应用程序时,都应调用SDK初始化代码,这是所有Singular归因功能的前提条件,它还会向Singular发送一个新会话,用于计算用户留存。

默认情况下,SingularSDK.cs 会在创建场景时通过 Awake 方法自动初始化 SDK

手动初始化

如果您希望在应用程序运行的稍后阶段手动初始化 SDK,请执行以下操作:

  1. 在 SingularSDK 对象的检查窗格中禁用Initialize on Awake 选项。
  2. 使用SingularSDK.InitializeSingularSDK 静态方法初始化 SDK:
SingularSDK.InitializeSingularSDK 方法
说明 如果 Singular SDK 在唤醒时尚未初始化,则对其进行初始化。
签名
public void InitializeSingularSDK()
使用示例
// SDK 密钥和 SDK 保密设置在 
// 与 SingularSDK 相关联的游戏对象 SingularSDK.InitializeSingularSDK();

线程安全注意事项: Singular Unity SDK 应始终从同一线程调用,就像调用其他 Unity 方法一样。

2.6.配置会话超时(可选)

默认情况下,如果应用程序在后台运行 60 秒或更长时间后才返回前台,Singular SDK 就会注册一个新的会话。您可以通过修改 SingularSDKObject 的Session Timeout Sec 属性来更改默认超时值。

2.7.向 Singular 发送用户 ID(可选)

你可以使用 Singular SDK 方法向 Singular 发送内部用户 ID。

注:如果使用Singular 的跨设备解决方案,则必须在所有平台上收集用户 ID。

  • 用户 ID 可以是任何标识符,但不能暴露 PII(个人身份信息),例如,不能使用用户的电子邮件地址、用户名或电话号码。Singular 建议使用仅对第一方数据唯一的哈希值。
  • 传递给Singular的用户ID值也应该是你在所有平台(Web/移动/PC/控制台/离线)上获取的相同的内部用户ID。
  • Singular 将在用户级导出、ETL 和内部 BI 回传(如果配置)中包含用户 ID。用户 ID 是第一方数据,Singular 不会与其他方共享。
  • 使用 Singular SDK 方法设置的用户 ID 值将一直存在,直到使用UnsetCustomUserId 方法取消设置或卸载应用程序为止。关闭或重启应用程序不会取消设置用户 ID。

要设置用户 ID,请使用SetCustomUserId 方法。要取消设置(例如,如果用户 "注销 "账户),请调用UnsetCustomUserId

注意:如果多个用户使用一台设备,我们建议实施注销流程,为每次登录和注销设置取消设置用户 ID。

如果在应用程序打开时已经知道用户 ID,请在初始化 Singular SDK 之前调用SetCustomUserId 。这样,Singular 就能从第一次会话中获得用户 ID。在这种情况下,请在注册流程完成后调用SetCustomUserId

SingularSDK.SetCustomUserId方法
说明 向 Singular 发送用户 ID。
签名 public void SetCustomUserId(string customUserId)
使用示例
SingularSDK.SetCustomUserId("custom_user_id");
SingularSDK.UnsetCustomUserId 方法
说明 取消设置已发送至 Singular 的用户 ID。
签名 public void UnsetCustomUserId()
使用示例
SingularSDK.UnsetCustomUserId();

可选:自定义用户 ID 设备映射

重要: 此高级企业功能仅在特殊情况下可用。实施前请咨询 Singular 解决方案工程师

Singular 可以通过服务器到服务器集成接收额外的移动事件跟踪数据。要使用此功能,必须将用户 ID 映射到 Singular 的移动设备跟踪标识符。

注意:在初始化Singular SDK或获得用户ID后,请尽快调用此方法。

SingularSDK.SetDeviceCustomUserId方法
说明 设置与登录相同的自定义用户 ID,并将其映射到 Singular 的跟踪标识符。
签名 public void SetDeviceCustomUserId(string customUserId)
使用示例
SingularSDK.SetDeviceCustomUserId('CustomUserId');

3.跟踪事件和收入

3.1. 跟踪事件(无收入)

Singular 可以收集应用内事件的相关数据,帮助分析营销活动的效果并衡量关键绩效指标。例如,您的企业可能希望收集用户登录、注册、教程完成或游戏应用中等级提升的数据。

Singular 支持各种标准事件,这些常用事件通常由广告网络支持,用于报告和优化。另一个优点是,当您使用标准事件名称上报时,Singular 会自动识别并将其添加到事件列表中,而无需手动定义。我们建议尽可能使用标准事件。

发送到 Singular 的事件列表(附带属性)应由用户体验/营销/业务团队根据企业的营销关键绩效指标编制。业务团队可参考《 Singular归因客户指南:如何跟踪应用内事件》。

您可以为跟踪的每个事件传递各种属性,请参阅每个事件的推荐标准属性

在代码中,使用 event 或 eventWithArgs 方法向 Singular 发送标准事件。

注:对于标准事件,请使用Unity SDK 标准事件和属性列表中显示的事件的 Unity 名称,如 sngLogin。

对于自定义事件,即贵组织希望测量的事件,如果与 Singular 的任何标准事件不匹配,可使用任何自定义名称(长度最多 32 个字符)。我们建议使用英文名称,以便与可能从 Singular 接收事件的广告网络合作伙伴兼容,以便进行优化。

SingularSDK.Event 方法
说明 向 Singular 发送用户事件以进行跟踪。
签名
public static void Event(string name)
public static void Event(string name, params object[] args)
public static void Event(Dictionary<string, object> args,
string name)

注意:传递字典时,字典值必须是以下类型之一:string、int、long、float、double、null、ArrayList、Dictionary<String,object>

使用示例

// 发送登录标准事件
SingularSDK.Event(sngLogin);
  
// 传递两个键值对的自定义事件
SingularSDK.Event("Myevent", "Key1", "Value1", "Key2", 1234);
// 传递携带字典的JSONEvent事件 SingularSDK.Event(new Dictionary<string, object>() { {"Key1", "Value1"}, {"Key2", new Dictionary<string, object>() { {"SubKey1", "SubValue1"}, {"SubKey2", "SubValue2"} } }}, "JSONEvent");

3.2.跟踪收入

Singular可以收集通过应用程序获得的收入数据,以帮助分析营销活动的绩效和投资回报率。Singular 将在报告、日志导出和回传中提供这些数据。

注意事项 以不同货币报告的任何收入都将自动转换为您在 Singular 账户中设置的首选货币。

您可以使用Unity 内置的 IAP(应用内购买)对象跟踪收入事件。通过这种方式,Singular 可以获得有关购买的所有可用信息,从而提供更丰富的报告内容。Singular 还会获得购买收据,Singular 会在后端使用该收据验证购买行为并排除归因欺诈。

SingularSDK.InAppPurchase 方法
说明 向 Singular 发送 IAP 产品以跟踪购买事件。
签名
public static void InAppPurchase(Product product,
Dictionary<string, object> attributes, bool isRestored = false)
public static void InAppPurchase(string eventName,
Product product, Dictionary<string, object> attributes,
bool isRestored = false)
public static void InAppPurchase(IEnumerable<Product> products, Dictionary<string, object> attributes, bool isRestored = false)
public static void InAppPurchase(string eventName,
IEnumerable<Product> products, Dictionary<string, object>
attributes, bool isRestored = false)

备注

  • product:是从 IAP 收到的产品对象类型:UnityEngine.Purchasing.Product
  • attributes:使用此参数可向 Singular 传递附加信息。如果没有要传递的属性,则传递空值即可。
  • isRestored: 说明该交易是否已被恢复。默认值为否,即:false。
使用示例
// 单一产品的 IAP,无额外属性
SingularSDK.InAppPurchase(myProduct, null);
// 具有单一产品和多个属性的 IAP
var attr = new Dictionary<string, object>() {
["my_first_attribute"] = "value1",
["my_second_attribute"] = "value2"};
 
SingularSDK.InAppPurchase(myProduct, attr);

// IAP 包含单一产品,无额外属性,但具有自定义事件名称

SingularSDK.InAppPurchase("MyCustomProduct",
myProduct, null);

// 包含产品列表的 IAP,无额外属性
SingularSDK.InAppPurchase(myProductList, null);

// IAP 包含产品列表,无额外属性,并具有自定义事件名称

SingularSDK.InAppPurchase("MyCustomProducts",
myProductList, null);
跟踪收入的另一种方法:Revenue和CustomRevenue方法

如果无法使用 Unity IAP对象,Singular SDK 提供了两种 "手动 "向 Singular 传递购买信息的方法:

  • 使用Revenue方法将购买信息传递给 Singular,详细说明交易货币、交易金额和其他可选细节信息。
  • CustomRevenue方法与此非常相似,但也允许你为事件自定义名称。

注意:如果使用 Revenue/CustomRevenue 代替 InAppPurchase,Singular 将无法验证购买收据。

SingularSDK.Revenue方法
说明 向 Singular 发送收入事件。
签名
public static void Revenue(string currency, double amount)

public static void Revenue(string currency,
double amount, string productSKU, string productName,
string productCategory, int productQuantity, double productPrice)
注意:采用三个字母的 ISO 4217标准定义的货币代码形式传递币种,如 "USD"、"EUR"、"INR"。
使用示例
// 发送不带产品详细信息的收入事件
SingularSDK.Revenue("USD", 9.99);

// 发送包含产品详细信息的收入事件
SingularSDK.Revenue("USD", 50.50, "abc123", "myProductName", 
"myProductCategory", 2, 25.50)
SingularSDK.CustomRevenue 方法
说明 向 Singular 发送带有自定义名称的收入事件。
签名
public static void CustomRevenue(string eventName, 
string currency, double amount) public static void CustomRevenue(string eventName,
string currency, double amount, string productSKU,
string productName, string productCategory, int productQuantity,
double productPrice)
注意:采用三个字母的 ISO 4217标准定义的货币代码形式传递币种,如 "USD"、"EUR"、"INR"。
使用示例
// 使用自定义名称发送收入事件
SingularSDK.CustomRevenue("MyCustomRevenue", "USD", 9.99);

// 发送带有自定义名称 + 产品详细信息的收入事件
SingularSDK.CustomRevenue("MyCustomRevenue", "USD", 50.50, 
"abc123", "myProductName", "myProductCategory", 2, 25.50)

3.3.混合事件跟踪(高级)

Singular 建议通过集成到应用程序中的 Singular SDK 发送所有事件和收入。不过,Singular 也可以从其他来源收集事件和收入。

任何非通过 Singular SDK 发送的事件都必须符合 Singular 的服务器到服务器事件文档要求,并提供匹配的设备标识符以正确归属事件。

重要

如果服务器到服务器事件请求中使用的设备标识符在 Singular 中没有匹配的设备标识符,就会出现差异。请注意以下可能性:

  • 如果事件请求是在 Singular SDK 从应用程序会话记录设备标识符之前收到的,那么该事件请求将被视为未知设备的 "第一次会话",Singular 将把该设备作为有机归属
  • 如果 Singular SDK 确实记录了设备标识符,但 Singular SDK 标识符与服务器到服务器事件请求中指定的设备标识符不同,那么事件将被错误归属

混合事件跟踪指南

从内部服务器发送事件

Singular可以收集来自服务器的收入数据,帮助分析营销活动的表现和投资回报率。

要求

  • 从应用内注册或登录事件中捕获并传递设备标识符,并将此数据与服务器上的用户 ID 一起存储。由于用户的设备标识符可能会发生变化,因此请确保在用户生成应用程序会话时更新标识符。这将确保服务器端事件归属于正确的设备。
  • 服务器端事件是平台特定的,只能使用与设备平台相匹配的设备标识符发送(如 iOS 设备的 IDFA 或 IDFV)。
  • 您可以使用 Singular 内部 BI 回传机制将事件实时推送到内部端点,以便更新服务器端的数据集。请参阅内部 BI 回传常见问题
  • 查看服务器到服务器集成指南中的"跟踪收入 "部分,了解详情。
从收入提供商发送事件
RevenueCatadapty等第三方提供商可以向Singular提供购买和订阅收入

请点击以下链接了解如何启用这些合作伙伴。

从分段发送事件

要使 Segment 能与 Singular SDK 并行发送事件到 Singular,必须在 Segment 中添加一个"云模式 "目的地。请点击此处查看我们的指南。

4.高级选项

4.1.创建短链接

注:此功能在 SDK 4.0.16及之后的版本中可用。

使用短链接可将冗长、充满参数的Singular链接转换为更短、更安全的链接,以方便分享。

通常情况下,您需要动态创建短链接,以便应用程序的用户可以与朋友分享,邀请他们使用应用程序。

要创建短链接,您需要

  • 指向应用程序下载地址的Singular链接(请参阅Singular跟踪链接常见问题)。
  • 要动态添加到链接中的任何参数(参数选项列表请参阅跟踪链接参数文档)。
  • 如果您希望跟踪新应用的安装情况,并追溯到共享链接的用户,则需要推荐用户的姓名和 ID

使用createReferrerShortLink方法创建短链接,参见以下示例代码。

void callback(string shortLinkURL, string error){
    // 如果shortLinkURL不为空,请在此处添加您的共享逻辑。 
// 如果出现错误,请根据错误原因添加逻辑以重试/中止/修改传递给函数的参数。 } SingularSDK.createReferrerShortLink( "https://sample.sng.link/B4tbm/v8fp?_dl=https%3A%2F%2Fabc.com", "John Doe", // 推荐人姓名 "342", // 推荐人 ID new Dictionary<string, string>() { // 包含您要添加的任何参数的 Dictionary 对象 {"channel", "sms"} }, callback );

4.2.添加广告收入归因支持

注:从 3.0.0 版开始,Singular 添加了通过 Singular SDK 实现广告收入归因的选项。

广告收入归因仍可通过老方法设置,即使用 API 调用,而无需更新应用程序中的 Singular SDK。但是,如果要衡量 SKAdNetwork 广告活动的广告收入,则必须通过 SDK 实现广告收入归因

为了在Singular SDK中添加广告收入归因支持:

  1. 更新至最新版本的Singular SDK
  2. 根据您使用的广告收入数据聚合平台,在您的 Singular SDK 集成中添加相应的代码片段。

注:以三个字母的 ISO 4217 货币代码传递货币,如 "USD"、"EUR"、"INR"。

AdMob
    1. 备注: 此功能需要在您的 Admob 账户中启用。

      See https://support.google.com/admob/answer/11322405#getstarted

备注: Google AdMob Unity SDK 已更改!

要了解有关当前和以前版本的 Google AdMob Unity SDK 最新迁移的更多信息。请参见此处的 Google 文档: 谷歌 AdMob 移动广告 SDK(Unity)迁移

Admob Unity SDK v8.0.0+ (C#) Admob Unity SDK Legacy (C#)

以下代码适用于 Admob Unity SDK v8.0.0+ 版本

收听 有奖广告事件,详见 在谷歌 AdMob 文档中 这里

private void RegisterEventHandlers(RewardedAd ad)
{
// 当广告估计赚到钱时提高。
ad.OnAdPaid += (AdValue adValue) =>
{
    // 构建并发送奇异 AdMon 事件
    SingularAdData data = new SingularAdData(
       "Admob",
        adValue.CurrencyCode,
        adValue.Value/1000000f);
    Singular.AdRevenue(data);
};
}
AppLovinMax
  1. 读取从 AppLovin MAX 的事件OnInterstitialAdRevenuePaidEvent接收到的对象
C#
MaxSdkBase.AdInfo impressionData;
string adUnitId;
double revenue = MaxSdk.GetAdInfo(adUnitId).Revenue;

SingularAdData data = new SingularAdData(
"AppLovin",
"USD",
revenue); Singular.AdRevenue(data);
IronSource
  1. 读取从 IronSource 的事件OnImpressionSuccess接收到的对象
  2. 确保打开 IronSource 中的 ARM SDK Postbacks 标志
  3. 请参见https://developers.is.com/ironsource-mobile/general/ad-revenue-measurement-postbacks/#step-1
C#
IronSourceImpressionData impressionData;
SingularAdData data = new SingularAdData(
"IronSource",
"USD",
impressionData.revenue); Singular.AdRevenue(data);
TradPlus
  1. 读取从 TradplusAds 事件接收到的对象:AddGlobalAdImpression
  2. TradPlusAdImpression回调中添加 Singular
C#
TradplusAds.Instance().AddGlobalAdImpression(OnGlobalAdImpression);

void OnGlobalAdImpression(Dictionary<string, object="object"> adInfo) {
   double revenue = 0;
   double.TryParse(
adInfo["ecpm"].ToString(),
NumberStyles.Float| NumberStyles.AllowThousands,
CultureInfo.InvariantCulture, out revenue); if(revenue != 0) revenue = revenue / 1000; SingularAdData data = new SingularAdData(
"TradPlus",
"USD",
revenue); SingularSDK.AdRevenue(data); }
其他(通用)
  1. 用相关数据初始化SingularAdData对象
  2. 向 Singular 报告数据
C#
SingularAdData data = new SingularAdData(
   您的广告平台,
   货币代码,
   9.90);

SingularSDK.AdRevenue(data);

4.3.跟踪卸载

注:卸载跟踪仅适用于企业级客户。

安卓卸载跟踪

要启用安卓应用程序的卸载跟踪功能,请首先在 Singular 平台上根据设置卸载跟踪所描述的内容进行应用程序配置。 然后按照以下说明操作。

注意: 谷歌于 2018 年 4 月废弃了 GCM API。请使用 FCM 进行卸载跟踪。

使用 Firebase Cloud Messaging (FCM) 启用卸载跟踪:

1.与 FCM 集成:

要跟踪卸载,您可以使用 Firebase Cloud Messaging (FCM) 平台的服务。如果您尚未使用 FCM,请按照 Google 的说明 在 Android 上设置 Firebase Cloud Messaging 客户端应用程序

FCM 要求(来源)

FCM 客户端需要运行 Android 4.1 或更高版本的设备,同时安装 Google Play Store 应用程序,或运行 Android 4.1 并带有 Google API 的模拟器。请注意,您并不局限于通过 Google Play Store 部署您的 Android 应用程序。

不在支持版本的安卓系统上运行的用户/设备将无法进行Singular卸载跟踪。

2.更新 AndroidManifest.xml 文件:

更新 AndroidManifest.xml 文件,为应用程序添加必要的intent过滤器(用实现 Firebase 服务的类替换如下示例代码中的MyFirebaseMessagingService):

<service android:name=".java.MyFirebaseMessagingService" android:exported="false">
  <intent-filter>
    <action android:name="com.google.firebase.MESSAGING_EVENT" />
  </intent-filter> 
</service>

3.注册并发送 FCM 设备令牌:

获取 FCM 令牌后,将其作为参数传递给 "RegisterTokenForUninstall "方法:

SingularSDK.RegisterTokenForUninstall(String fcmDeviceToken);

请注意,"RegisterTokenForUninstall "方法应在 "SingularSDK.InitializeSingularSDK() "方法之前调用

iOS 卸载跟踪

iOS 上的卸载跟踪基于 Apple 推送通知技术。如果您的应用程序目前不支持推送通知,请参阅 Apple 的 指南。 如果您的应用程序已经支持推送通知,您只需在 SDK 初始化后使用 RegisterTokenForUninstall 方法传递从 APNS 返回的设备令牌即可。

SingularSDK.RegisterTokenForUninstall 方法
说明 传递从 APNS 返回的设备令牌。请注意,APNS 令牌通常是原生形式的二进制数据,但您需要以字符串形式传递。
签名
public static void RegisterTokenForUninstall
(string APNSToken)
使用示例
// 将APNS令牌转换为十六进制字符串传递
  SingularSDK.RegisterTokenForUninstall("ba85ab31a7c7
f5c2f012587f29fb0e596d4b67e7b7b2838fa1a8582c1f7dbdee");

4.4.添加全局属性

Singular SDK 允许你定义自定义附加属性,以便在应用程序发送每个会话和事件时携带这样的自定义属性到 Singular 服务器。 这些属性可以代表有关用户、应用程序模式或状态的信息,也可以代表其他任何信息。一旦设置了这些属性,它们就可以作为报告中的维度,您可以用它们来细分数据。

例如,如果您有一个游戏应用程序,您可以定义一个名为 "级别 "的属性,并将其初始设置为 "0"。应用程序发送的任何会话和事件都将带有 "Level":"0"。一旦用户等级提升,您就可以将该属性置为 "1",以此类推。然后,您就可以获得按用户等级这个维度进行分列的报告,包括会话、事件计数和收入数据等。

  • 最多可以定义5 个全局属性
  • 它们会在应用程序运行期间持续存在(使用您最新设定的值),直到您取消全局属性值的设置或用户卸载应用程序。
  • 每个属性的名称和值最长可包含200 个字符。如果您传递的属性名称或值较长,将被截断为 200 个字符。
  • 全局属性可在用户级导出回传中访问和使用。将来还会在汇总报告给予支持。如果有任何问题或对全局属性支持的更新感兴趣,请联系您在Singular的客户成功经理!

在初始化前设置全局属性

在初始化SDK之前,你可以使用SetGlobalProperty 方法通过SingularSDK设置全局属性。 如果你希望全局属性包含在会话中,请关闭 "唤醒时初始化 "标志。

请注意,由于全局属性及其值会在应用程序运行期间持续存在,因此您要设置的属性可能已被设置为不同的值。使用 overrideExisting 参数可告诉 SDK 是否用新值覆盖现有属性值。

初始化后设置全局属性

在应用程序运行的任何时候,使用以下方法设置、取消设置和检索全局属性。

SingularSDK.SetGlobalProperty 方法
说明

将全局属性设置为给定值。

注意

  • 如果该属性不存在,且已有 5 个其他全局属性,则不会添加该属性。
  • 如果属性已被设置,overrideExisting 参数将决定是否覆盖现有值。
  • 如果属性设置成功,该方法返回true,否则返回false
签名 public static bool SetGlobalProperty(string key, string value, bool overrideExisting)
使用示例
bool result = SingularSDK.SetGlobalProperty("key", "value", false);
SingularSDK.GetGlobalProperties 方法
说明 以 Map 形式读取所有全局属性及其当前值。
特征 public static Dictionary<string, string> GetGlobalProperties()
使用示例
Dictionary<string, string> props = SingularSDK.GetGlobalProperties();
SingularSDK.UnsetGlobalProperty 方法
说明 移除全局属性。
签名 public static void UnsetGlobalProperty(string key)
使用示例
SingularSDK.UnsetGlobalProperty(“test_key”);
SingularSDK.ClearGlobalProperties 方法
说明 删除所有全局属性。
签名 public static void ClearGlobalProperties()
使用示例
SingularSDK.clearGlobalProperties();

4.5.在旧版安卓设备上收集Install Referrer信息

安卓系统中,Install Referrer是 Singular 确定归因的最准确工具,此外还能帮助 Singular 检测和分析欺诈企图。它是 Google Play Store提供的标识符,指向用户在安装应用程序之前点击的广告。

在安装了最新版 Google Play Store 的设备上,Singular SDK 会自动收集Install Referrer信息(因为 Singular 已集成了最新的 Google Play Referrer API)。

要在旧版本设备上收集安装推荐值,请按照 安卓 SDK集成指南中的说明进行操作。

5.遵守数据隐私法

5.1. LimitDataSharing方法

Singular提供隐私保护功能,帮助您与任何可能遵守消费者隐私法(如GDPR和CCPA(加州消费者隐私法))的合作伙伴合作。 这些合作伙伴希望在最终用户同意共享其私人信息时得到通知。

限制数据共享

如果你已经实施了一种征求用户同意共享其信息的方法,请使用limitDataSharing方法通知 Singular 用户的选择:

  • 使用limitDataSharing:NO表示用户同意(选择加入)共享其信息。
  • 如果用户不同意,则使用 limitDataSharing:YES

Singular在"用户隐私回传"中使用限制数据分享,并将此信息传递给需要的合作伙伴,以遵守相关法规。更多信息请参阅"用户隐私和限制数据共享"

注意:该方法的使用是可选的,但可能会有归属信息,只有在明确通知用户已选择的情况下,合作伙伴才会与Singular共享这些信息。

SingularSDK.LimitDataSharing方法
签名 SingularSDK.LimitDataSharing(boolshouldLimitDataSharing)
说明 通知 Singular 用户同意(选择加入)共享其私人数据。
使用示例
// 用户选择允许共享数据
SingularSDK.LimitDataSharing(false);

5.2.遵守 GDPR 的其他方法

Singular SDK 提供了几种方法来帮助你遵守 GDPR 政策,并让 Singular 了解用户是否同意追踪。

SingularSDK.TrackingOptIn方法
说明 通知 Singular 用户同意(选入)跟踪。
使用示例
SingularSDK.TrackingOptIn();
SingularSDK.StopAllTracking方法
说明 停止此用户在此应用程序上的所有跟踪活动。
注意: 调用此方法将有效禁用 SDK,即使应用程序重新启动后也是如此(状态是持久的)!重新启用跟踪的唯一方法是调用 resumeAllTracking方法。
使用示例
SingularSDK.StopAllTracking();
SingularSDK.ResumeAllTracking 方法
说明 在此应用程序上恢复对该用户的跟踪。
使用示例
SingularSDK.ResumeAllTracking();
SingularSDK.IsAllTrackingStopped方法
说明 检查此应用程序中该用户的当前跟踪状态。如果使用 StopAllTracking() 停止了跟踪且未恢复,则返回 true。
使用示例
SingularSDK.IsAllTrackingStopped();