Unity SDK

Get Started with the Unity SDK

Tenjin Unity SDK 允许客户使用 Unity 开发工具来跟踪应用程序中的事件和安装。 要了解有关 Tenjin 和我们的产品的更多信息，请访问 https://www.tenjin.com.

• 可以参考 这里 来查看我们产品发布的历史记录。
• Tenjin Unity SDK 支持 iOS 和 Android.
• 可查看 iOS 和 Android 文档，并根据需求采用适合的项目。
• 如有任何问题，可邮件至: support@tenjin.com

:::

Library not loaded: @rpath/TenjinSDK.framework/TenjinSDK

目录

• SDK Integration 集成
  • Google Play
  • Amazon store
  • OAID
    • MSA OAID
    • Huawei OAID
  • Proguard
  • App Initilization 初始化
  • App Store
  • ATTrackingManager (iOS)
    • 展示 ATT 授权提示
      • 设置用户追踪说明
  • SKAdNetwork 和 Conversion Value 转化值
  • SKAdNetwork iOS 15+ Postbacks
  • GDPR
  • • CMP Opt in/Opt out
  • 购买事件
    • iOS 内购验证
    • Android 内购验证
  • 自定义事件
  • S2S 服务端集成
  • 应用子版本及 A/B 测试
  • LiveOps 动态运营
  • 用户ID
  • 分析安装ID
  • Retry/cache events and IAP重试逻辑
  • Google DMA参数
  • 展示层级收益集成
  • 集成测试

SDK Integration 集成

1. 下载最新版本 Unity SDK here.

2. 将 TenjinUnityPackage.unitypackage 导入你的项目: Assets -> Import Package.

3. 我们默认包含了 Google Play Services AAR 文件作为我们 SDK 的一部分。如果不需要，你可以进行删除:

 /Assets/Plugins/Android/play-services-*.aar
 /Assets/Plugins/Android/installreferrer-*.aar

我们有一个 demo project - tenjin-unity-sdk-demo 可以让您更好地了解 Unity SDK 的集成。

Google Play

App Store 默认值为 unspecified。 如果你在谷歌应用商店推广，请将此值设为 googleplay。

将 App Store Type 值设为 googleplay:

BaseTenjin instance = Tenjin.getInstance("<SDK_KEY>");

instance.SetAppStoreType(AppStoreType.googleplay);

Amazon store

App Store 默认值为 unspecified。 如果你在亚马逊应用商店推广，请将此值设为 amazon。

将 App Store Type 值设为 amazon:

BaseTenjin instance = Tenjin.getInstance("<SDK_KEY>");

instance.SetAppStoreType(AppStoreType.amazon);

OAID 及其他安卓应用商店

Tenjin 支持使用 OAID 在其他非 Google Play 商店渠道进行推广，您需要集成以下 OAID 库。
如果您需要在安卓中国、华为海外等应用商店推广，请集成以下这些 OAID 库。

MSA OAID

集成 MSA 库, 在此下载 oaid_sdk_1.0.25.aar.

将 oaid_sdk_1.0.25.aar 文件置于你项目中安卓库路径下: /Assets/Plugins/Android

将 App Store Type 值设为 other:

BaseTenjin instance = Tenjin.getInstance("<SDK_KEY>");

instance.SetAppStoreType(AppStoreType.other);

Huawei OAID

对于在华为海外应用商店的推广，你可以集成华为 OAID 库来获取 OAID。可将华为的 OAID 库，在项目中添加以下内容：Huawei AAR file: huawei-ads-identifier.aar. 如果你的应用在 Huawei App Gallery 华为海外应用商店 上架，请下载 Huawei Install Referrer 文件: huawei-ads-installreferrer.aar.

将华为文件置于你项目中安卓库路径下: /Assets/Plugins/Android

将 App Store Type 值设为 other:

BaseTenjin instance = Tenjin.getInstance("<SDK_KEY>");

instance.SetAppStoreType(AppStoreType.other);

Proguard 设置

-keep class com.tenjin.** { *; }
-keep public class com.google.android.gms.ads.identifier.** { *; }
-keep public class com.google.android.gms.common.** { *; }
-keep public class com.android.installreferrer.** { *; }
-keep class * extends java.util.ListResourceBundle {
    protected java.lang.Object[][] getContents();
}
-keepattributes *Annotation*

如果你使用华为库，你可以使用下面设置:

-keep class com.huawei.hms.ads.** { *; }
-keep interface com.huawei.hms.ads.** { *; }

初始化

1. 您可以在应用 App 页面获取 SDK_KEY 。请注意：每个应用的 SDK_KEY 都是唯一的，您可以为每个应用生成最多3个 SDK_KEY 。

   

2. 在项目的 Start() 和 OnApplicationPause() 方法中加入 BaseTenjin instance = Tenjin.getInstance("SDK_KEY") 和 instance.Connect()

using UnityEngine;
using System.Collections;

public class TenjinExampleScript : MonoBehaviour {

  void Start() {
    TenjinConnect();
  }

  void OnApplicationPause(bool pauseStatus) {
    if (!pauseStatus) {
      TenjinConnect();
    }
  }

  public void TenjinConnect() {
    BaseTenjin instance = Tenjin.getInstance("<SDK_KEY>");

    // Sends install/open event to Tenjin
    instance.Connect();
  }
}

注意: 请确保在所有的 Start() 和 OnApplicationPause() 初始化 Tenjin, 而非仅初次应用打开。Tenjin 内部会定期审查客户 SDK 集成情况，如发现未按指引集成，我们可能会即时停用你的账户。

App Store 应用商店类型

我们支持以下应用商店选项,

1. googleplay
2. amazon
3. other

默认情况下, 应用商店类型设置为 unspecified. 请根据自身应用推广情况设置相应的值。安卓中国及华为海外商店推广请设置为 other:

1. AndroidManifest.xml:

<meta-data
    android:name="TENJIN_APP_STORE"
    android:value="{{SET_APP_STORE_TYPE_VALUE}}" />

2. SetAppStoreType():

BaseTenjin instance = Tenjin.getInstance("<SDK_KEY>");

instance.SetAppStoreType(AppStoreType.{{SET_APP_STORE_TYPE_VALUE}});

ATTrackingManager (iOS)

• 从 iOS 14 开始，你可以选择初始话并显示 ATTrackingManager 权限提示，让用户选择允许或不允许。

• 如果用户选择不允许追踪，IDFA 的值将会是0，如果用户选择同意追踪， connect() 方法就会发送 IDFA 到我们的服务器。

• 即便不使用 ATTrackingManager，你也可以调用 Tenjin connect(), 目前 ATTrackingManager 弹窗尚未强制弹出，预计苹果会在2021年初强制推行。

using UnityEngine;
using System.Collections;
using UnityEngine.iOS;

public class TenjinExampleScript : MonoBehaviour {

    void Start() {
      TenjinConnect();
    }

    void OnApplicationPause(bool pauseStatus) {
      if (!pauseStatus) {
        TenjinConnect();
      }
    }

    public void TenjinConnect() {
      BaseTenjin instance = Tenjin.getInstance("SDK_KEY");

#if UNITY_IOS
      if (new Version(Device.systemVersion).CompareTo(new Version("14.0")) >= 0) {
        // Tenjin wrapper for requestTrackingAuthorization
        instance.RequestTrackingAuthorizationWithCompletionHandler((status) => {
          Debug.Log("===> App Tracking Transparency Authorization Status: " + status);

          // Sends install/open event to Tenjin
          instance.Connect();

        });
      }
      else {
          instance.Connect();
      }
#elif UNITY_ANDROID

      // Sends install/open event to Tenjin
      instance.Connect();

#endif
    }
}

展示 ATT 追踪授权提示

要遵守 Apple 的 ATT 指南，您必须提供 ATT 权限提示的描述，然后在您的应用程序中实施权限请求。

注意：在您的游戏中投放广告之前，您必须执行权限请求。

设定用户跟踪描述

Apple 需要开发者描述 ATT 提示的用途。您需要在 Xcode 项目的 Info.plist 文件中使用 NSUserTrackingUsageDescription 设置描述。您必须提供一条消息，告知用户您为何请求使用设备跟踪数据的权限：

• 在您的 Xcode 项目导航器中，打开 Info.plist 文件。
• 单击属性列表编辑器中任意键旁边的添加按钮 (+) 以创建新的属性键。
• 输入键名NSUserTrackingUsageDescription。
• 选择字符串 String 值类型。
• 在值字段中输入应用跟踪透明度消息。一些例子包括：
• “我们将使用您的数据来提供更好的个性化广告体验。”
• “我们会尝试根据您使用的应用程序、您使用的设备以及您所在的国家/地区展示您最感兴趣的应用程序和产品的广告。”
• “我们会尝试根据您使用的应用为您最感兴趣的应用和产品展示广告。”

注意：Apple 提供了特定的应用商店指南 应用商店指南 为所有面向最终用户的隐私相关功能定义了可接受的使用和消息传递。Tenjin 不提供法律意见。因此，此页面上的信息不能替代您寻求自己的法律顾问来确定您的业务和流程的法律要求以及如何解决这些要求。

SKAdNetwork 和 Conversion Values 转化值

作为 SKAdNetwork 的一部分，我们为 updatePostbackConversionValue(_:) 创建的封装方案，可以注册等效的 SKAdNetwork 方案并同时发送 conversion values 到我们的服务器。

updatePostbackConversionValue(_:) 6位值来对应应用内事件，不能二进制形式输入，而应为 0-63 的整数。我们的服务器将拒绝任何无效值。

• 内购为主的游戏样例
• 广告变现为主的游戏样例

对于支持 SKAdNetwork 4.0 的 iOS 16.1 之后的版本，现可通过发送 coarseValue （String 字符串格式，可能的变体为 "low"，"medium" 或者 "high"）以及 lockWindow（Boolean 布尔值）作为更新版回传方法的参数

updatePostbackConversionValue(_ conversionValue: Integer, coarseValue: String)

updatePostbackConversionValue(_ conversionValue: Integer, coarseValue: String, lockWindow: Bool)

• 对于 iOS 版本为 16.1+，即支持 SKAdNetwork 4.0，您可以根据需要多次调用此方法，并可以使转换值低于或高于上一个值。

• 对于 iOS 版本低于 16.1，即所支持的 SKAdnetWork 版本低于 4.0，您仍可以调用此方法，我们的 SDK 将自动检测 iOS 版本并仅更新 conversionValue 转换值。

using UnityEngine;
using System.Collections;

public class TenjinExampleScript : MonoBehaviour {

    void Start() {
      TenjinConnect();
    }

    void OnApplicationPause(bool pauseStatus) {
      if (!pauseStatus) {
        TenjinConnect();
      }
    }

    public void TenjinConnect() {
      BaseTenjin instance = Tenjin.getInstance("SDK_KEY");

#if UNITY_IOS

      // Sends install/open event to Tenjin
      instance.Connect();

      // Sets SKAdNetwork Conversion Value
      // You will need to use a value between 0-63 for <Integer between 0 and 63>
      instance.updatePostbackConversionValue(<Integer between 0 and 63>);
      
       // For iOS 16.1+ (SKAN 4.0)
      instance.updatePostbackConversionValue(<Integer between 0 and 63>, "medium");
      instance.updatePostbackConversionValue(<Integer between 0 and 63>, "medium", true);      

#elif UNITY_ANDROID

      // Sends install/open event to Tenjin
      instance.Connect();

#endif
    }
}

SKAdNetwork and iOS 15+ 广告主回调

需要将 Tenjin 指定为 SK Ad Network 回调接收方，请进行以下操作：

1. 在 Xcode 的项目导航器中选择 Info.plist。
2. 单击"属性/Property"列表编辑器中某个键旁边的添加按钮 (+)，然后按回车键。
3. 输入名称 NSAdvertisingAttributionReportEndpoint。
4. 从"类型/Type"列的弹出菜单中选择"String"。
5. 输入 https://tenjin-skan.com。

以上操作是为适配 Apple 的指引，具体详情可参考网址：
https://developer.apple.com/documentation/storekit/skadnetwork/configuring_an_advertised_app.

GDPR

作为 GDPR 合规的一部分，使用 Tenjin 的 SDK，你可以选择加入和退出设备/用户，或选择要加入或退出的特定于设备的相关参数。OptOut() 不会向 Tenjin 发送任何 API 请求，我们也不会处理任何事件。

使用（opt-in）/禁用 （opt-out）:

void Start () {

  BaseTenjin instance = Tenjin.getInstance("SDK_KEY");

  boolean userOptIn = CheckOptInValue();

  if (userOptIn) {
    instance.OptIn();
  }
  else {
    instance.OptOut();
  }

  instance.Connect();
}

boolean CheckOptInValue()
{
  // check opt-in value
  // return true; // if user opted-in
  return false;
}

• 若您希望选择特定设备相关参数的启用或禁用，您可使用 OptInParams() 或OptOutParams()。

• OptInParams() 只会发送设备相关的指定参数，而OptOutParams() 则会发送除指定参数之外的其他所有与设备相关的参数

-敬请注意，为了在Tenjin系统中准确地追踪设备，我们需要您提供以下重要参数。如有任何一项必要参数未被提供，将导致无法正常处理或记录有关事件。

• 安卓，
  • advertising_id
• iOS，
  • developer_device_id
• 如果你使用 IMEI 或 OAID， 请添加:
  • imei
  • oaid
• 如果你使用 Google Ads 投放，请添加以下字段:
  • platform
  • os_version
  • locale
  • device_model
  • build_id
  • app_verision

如果只想使用 OptInParams()获取与设备相关的特定参数，在下面的样例中, 我们只发送这些设备相关的参数: ip_address, advertising_id, developer_device_id, limit_ad_tracking, referrer, 和 iad:

BaseTenjin instance = Tenjin.getInstance("SDK_KEY");

List<string> optInParams = new List<string> {"ip_address", "advertising_id", "developer_device_id", "limit_ad_tracking", "referrer", "iad"};
instance.OptInParams(optInParams);

instance.Connect();

如果要使用 OptOutParams()发送除特定设备相关参数以外的所有参数，如下样例中，我们会发送除了 locale, timezone, 和 build_id 之外的所有相关的参数。

BaseTenjin instance = Tenjin.getInstance("SDK_KEY");

List<string> optOutParams = new List<string> {"locale", "timezone", "build_id"};
instance.OptOutParams(optOutParams);

instance.Connect();

CMP Opt in/out

您可以使用CMP （目的 1）的条款，实现自动选择opt in/out功能，并返回布尔值(boolean）。该功能基于用户设备中已存储的信息，无需额外交互。

OptInOutUsingCMP()

BaseTenjin instance = Tenjin.getInstance("<SDK_KEY>");
optInOut = instance.OptInOutUsingCMP(); 

设备层级数据

购买事件

iOS 内购验证

iOS 验证 receipt 需要 transactionId 和 receipt (signature 将设置为 null). 对与 receipt，请确保从 unity 发送Payload的receipt(以 base64 编码的 ASN.1 receipt)。

重要提示： 如果你有订阅内购（subscription IAP），你需要在, you will need to add your app's shared secret in the Tenjin dashboard添加你 App 的共享密钥（shared secret）。你的 iOS App-Specific Shared Secret 获取路径： iTunes Connect Console > Select your app > App Information > App-Specific Shared Secret.

Android 内购验证

Android 的 receipt 验证必须提供 receipt 和 signature ， (transactionId 设置为 to null).

重要提示： 你需要在 Tenjin dashboard添加 App 的 public key。获取 Base64-encoded RSA public key 的路径为 Google Play Developer Console > Select your app > Monetize > Monetization setup > Google Play Billing > Licensing: Base64-encoded RSA public key.

Amazon 商店

Amazon 商店内购收据验证需要 receiptId 和 userId 字段.

重要提示: 你需要将 Amazon 密钥添加至 Tenjin 面板。 你可以在开发者账户 Amazon Appstore account 里查看相应的密钥。

iOS 和 Android / Amazon 内购集成示例

在以下示例中，我们使用通用的 MiniJSON 库做 JSON 处理。

public static void OnProcessPurchase(PurchaseEventArgs purchaseEventArgs) {
    var price = purchaseEventArgs.purchasedProduct.metadata.localizedPrice;
    double lPrice = decimal.ToDouble(price);
    var currencyCode = purchaseEventArgs.purchasedProduct.metadata.isoCurrencyCode;

    var wrapper = Json.Deserialize(purchaseEventArgs.purchasedProduct.receipt) as Dictionary<string, object>;  // https://gist.github.com/darktable/1411710
    if (null == wrapper) {
        return;
    }

    var store     = (string)wrapper["Store"]; // GooglePlay, AmazonAppStore, AppleAppStore, etc.
    var payload   = (string)wrapper["Payload"]; // For Apple this will be the base64 encoded ASN.1 receipt. For Android, it is the raw JSON receipt.
    var productId = purchaseEventArgs.purchasedProduct.definition.id;

#if UNITY_ANDROID

  if (store.Equals("GooglePlay")) {
    var googleDetails = Json.Deserialize(payload) as Dictionary<string, object>;
    var googleJson    = (string)googleDetails["json"];
    var googleSig     = (string)googleDetails["signature"];

    CompletedAndroidPurchase(productId, currencyCode, 1, lPrice, googleJson, googleSig);
  }

  if (store.Equals("AmazonApps")) {
    var amazonDetails   = Json.Deserialize(payload) as Dictionary<string, object>;
    var amazonReceiptId = (string)amazonDetails["receiptId"];
    var amazonUserId    = (string)amazonDetails["userId"];

    CompletedAmazonPurchase(productId, currencyCode, 1, lPrice, amazonReceiptId, amazonUserId);
  }

#elif UNITY_IOS

  var transactionId = purchaseEventArgs.purchasedProduct.transactionID;

  CompletedIosPurchase(productId, currencyCode, 1, lPrice , transactionId, payload);

#endif

  }

  private static void CompletedAndroidPurchase(string ProductId, string CurrencyCode, int Quantity, double UnitPrice, string Receipt, string Signature)
  {
    BaseTenjin instance = Tenjin.getInstance("SDK_KEY");
    instance.Transaction(ProductId, CurrencyCode, Quantity, UnitPrice, null, Receipt, Signature);
  }

  private static void CompletedIosPurchase(string ProductId, string CurrencyCode, int Quantity, double UnitPrice, string TransactionId, string Receipt)
  {
    BaseTenjin instance = Tenjin.getInstance("SDK_KEY");
    instance.Transaction(ProductId, CurrencyCode, Quantity, UnitPrice, TransactionId, Receipt, null);
  }

  private static void CompletedAmazonPurchase(string ProductId, string CurrencyCode, int Quantity, double UnitPrice, string ReceiptId, string UserId)
  {
    BaseTenjin instance = Tenjin.getInstance("SDK_KEY");
    instance.TransactionAndroid(ProductId, CurrencyCode, Quantity, UnitPrice, ReceiptId, UserId);
  }

声明： 如果您是第一次在 Tenjin 上集成购买事件，请事先自行确保内购数据的准确性，然后才开始基于内购优化的投放策略。

订阅收入

• 你需要在每个订阅间隔内发送一次订阅交易（例如，对于每月订阅，你需要每月向我们发送1笔交易）。在下面的示例时间轴中，交易事件仅应在“首次收费”和“续订”事件中发送。在试用期间，请勿将交易事件发送给 Tenjin。

• Tenjin不会对重复交易进行重复数据删除。

  

• 如果您有 iOS 订阅内购，则需要在 Tenjin dashboard添加 App 的 public key。iOS 的 Shared Secret 获取路径为 iTunes Connect Console > Select your app > Features > In-App Purchases > App-Specific Shared Secret。

• 有关 iOS 订阅的更多信息，请参阅： Apple 关于使用订阅的文档

• 有关 Android 订阅的更多信息，请参阅 Google Play 收费订阅文档

自定义事件

重要提示: 自定义事件的名称不能超过80个字符。唯一自定义事件数量不能超过500个。

• 在 Unity project 中包含 Assets 文件夹
• 在自定义事件的 projects method 中为命名事件编写以下内容: Tenjin.getInstance("<SDK_KEY>").SendEvent("name") 以及需为整数值的命名事件的以下内容: Tenjin.getInstance("<SDK_KEY>").SendEvent("nameWithValue","value")
• 确保传递的 value 为整数，如果不是整数，则无法被传递。

代码示例：

void MethodWithCustomEvent(){
    //event with name
    BaseTenjin instance = Tenjin.getInstance ("SDK_KEY");
    instance.SendEvent("name");

    //event with name and integer value
    instance.SendEvent("nameWithValue", "value");
}

.SendEvent("name") 可发送应用内关键节点，如 tutorial_complete, registration, or level_1.

.SendEvent("name", "value") 可发送带参数的关键事件。比如， ("coins_purchased", "100") 可用来分析金币购买的总数及平均数。

S2S 服务端集成

Tenjin 提供服务端的集成功能，如果有需要，请发送邮件至 support@tenjin.com 。

应用子版本及 A/B 测试（需要DataVault）

如果你想进行 A/B 测试并查看差异报告，我们可以使用 appendAppSubversion 方法将数字值附加到你的应用程序版本中。例如，如果你的应用程序版本 1.0.1 设置了 appendAppSubversion: @8888，就可以上报 App version 为 1.0.1.8888 的数据。

这些数据将在 DataVault 中，你可以通对应的过 subversion 值来查看报告。

BaseTenjin instance = Tenjin.getInstance("<API KEY>");
instance.AppendAppSubversion(8888);
instance.Connect();

LiveOps 动态运营

Tenjin 支持在 SDK 层面获取用户的来源信息，包括买量渠道及广告计划等。如有需要，请联系您的客户经理。

这将允许广告主实时收集和分析这些用户级归因数据。以下是使用 Tenjin 归因信息回调的实用案例：

• 如果您有自己的数据分析工具，自定义回调将允许您将归因数据与设备级别的游戏内数据联系起来，也就是将推广数据与应用内事件数据相联系。
• 根据用户的来源显示不同的应用程序内容。例如，用户 A 是自然量用户，而用户 B 是 Facebook 买量用户。由于用户 B 可能更喜欢您的应用程序，因此您可能希望为用户 B 显示游戏内的特别优惠，这时就可以使用归因信息回调。如果您想讨论更多具体的用例，请联系 Tenjin 成功经理。

用户 ID

发送事件时可以设置自定义的用户 ID。

.SetCustomerUserId("user_id")

.GetCustomerUserId()

BaseTenjin instance = Tenjin.getInstance("<SDK_KEY>");
instance.SetCustomerUserId("user_id");
string userId = instance.GetCustomerUserId(); 

分析ID Analytics Installation ID

您可以在设备的本地储备中获取分析ID(Analytics Installation ID)，该ID是随机生成的。
GetAnalyticsInstallationId()

BaseTenjin instance = Tenjin.getInstance("<SDK_KEY>");
analyticsId = instance.GetAnalyticsInstallationId; 

Retry/Cache events and IAP 重试逻辑

系统会在网络连接中断或请求失败时，自动缓存事件和应用内购买(IAP)数据。这些事件将在新的事件被添加到队列后，或网络恢复链接后发送。您可以根据实际需求选择启用或禁用该功能。
.SetCacheEventSetting(true)

BaseTenjin instance = Tenjin.getInstance("<SDK_KEY>");
instance.SetCacheEventSetting(true);

Google DMA 参数

若您已集成CMP的模式，Google DMA参数将由Tenjin SDK自动采集，你无需额外在Tenjin SDK上做任何操作。 若您希望取代CMP，或者构建自己的用户协议机制，您可以使用以下方法：

SetGoogleDMAParameters(bool, bool)

BaseTenjin instance = Tenjin.getInstance("<SDK_KEY>");
instance.SetGoogleDMAParameters(adPersonalization, adUserData);

您可以选择加入或退出谷歌 DMA 参数的收集，从而管理谷歌DMA参数的收集。默认情况下会加入，但您可以使用 optInGoogleDMA 或 optOutGoogleDMA 方法轻松更改您的偏好，从而完全控制您的数据隐私设置。

instance.OptInGoogleDMA(); 
instance.OptOutGoogleDMA();

广告展示层级收益集成

Tenjin 目前支持与以下聚合平台展示数据进行集成：

• AppLovin
• Unity LevelPlay
• HyperBid
• AdMob
• Topon
• CAS
• TradPlus

此功能将允许您获取每一个广告展示的明细数据，该功能可用于广告投放渠道基于广告收益的优化策略，以及更精确的用户层级收益计算等。如有需要，请联系您的客户经理。

集成测试

你可以通过我们的 Live Test Device Data Tool 来验证内购查看 SDK 集成是否正常。添加你测试设备的 advertising_id 或 IDFA/GAID 到测试设备名单中。你可以在面板上 DIAGNOSE -> Test Devices 查看。 点击到 SDK Live Data 页，并从 App 端发送事件，如果集成没有问题，你可以很快在面板上看到事件记录。