Unity SDK
  • 21 Jul 2022
  • 8 阅读时间
  • 黑暗模式
    白天模式

Unity SDK

  • 黑暗模式
    白天模式

Get Started with the Unity SDK

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

  • 可以参考 这里 来查看我们产品发布的历史记录。

  • Tenjin Unity SDK 支持 iOS 和 Android.

  • 可查看 iOSAndroid 文档,并根据需求采用适合的项目。

  • 如有任何问题,可邮件至: support@tenjin.com

  • iOS Notes:

    • 如果你使用 Unity iOS SDK v1.12.0 或更高版本,请使用 Xcode 12。
    • 运行时,请确保以下框架已经自动加载到 Xcode build。 如果有缺失,请自行手动添加。
      • AdServices.framework
      • AdSupport.framework
      • AppTrackingTransparency.framework
      • iAd.framework
      • StoreKit.framework
    • 对于 AppTrackingTransparency 隐私授权,请确保更新你项目中 .plist 文件,并添加 Privacy - Tracking Usage Description 隐私 - 追踪用途描述 (NSUserTrackingUsageDescription) 以及你希望展示的文字信息。该库仅适用于 iOS 14.0+ 。
    • 对于 Apple Search Ads Attribution ASA 追踪 , 请确保将 SDK 更新至 v1.12.6+ ,并添加 AdServices.framework 库。该库仅适用于 iOS 14.3+
  • Android:

    1. 如果你已经集成的 SDK 中有安装 Google Play Services 或者使用 PlayServicesResolver, 则可能需要删除以下文件:
 /Assets/Plugins/Android/play-services-ads-identifier--*.aar
 /Assets/Plugins/Android/play-services-basement---*.aar
  1. 如果你使用 Unity 版本 2019.4.21f1 或以上,并且使用Gradle 来创建安卓应用, 你可能遇到以下错误如 DuplicateMethodException 等, 或者发现 referrer install 无法正常工作。如果遇到以上情况,请:
    • 请删除 Assets/Plugins/Android 文件夹下除 tenjin.aar 的所有 *.aar 文件.
    • 将以下添加到你的 mainTemplate.gradle 文件:
          // Android Resolver Repos Start
          ([rootProject] + (rootProject.subprojects as List)).each { project ->
              project.repositories {
                  def unityProjectPath = $/file:///**DIR_UNITYPROJECT**/$.replace("\\", "/")
                  maven {
                      url "https://maven.google.com"
                  }
                  maven {
                      url "https://s3.amazonaws.com/moat-sdk-builds"
                  }
                  maven {
                      url 'https://developer.huawei.com/repo/'
                  }
                  mavenLocal()
                  mavenCentral()
                  google()
              }
          }
      
      // Android Resolver Repos End
          apply plugin: 'com.android.library'
          **APPLY_PLUGINS**
          dependencies {
              implementation fileTree(dir: 'libs', include: ['*.jar'])
          // Android Resolver Dependencies Start
              implementation 'com.android.support:multidex:1.0.3'
              implementation 'com.google.android.gms:play-services-analytics:{version}'
              implementation 'com.android.installreferrer:installreferrer:{version}'
              implementation 'com.huawei.hms:ads-identifier:{version}'
              implementation 'com.huawei.hms:ads-installreferrer:{version}'
              androidTestImplementation('com.android.support.test.espresso:espresso-core:3.0.2', {
                  exclude group: 'com.android.support', module: 'support-annotations'
              })
          // Android Resolver Dependencies End
          **DEPS**}
      
    • Add the following entry to the gradleTemplate.properties file:
      android.useAndroidX=true
      
  2. 如果你在应用初始化时遇到以下错误, 请将 tenjin.aar 从 /Assets/Plugins/Android/Tenjin/libs 移到 /Assets/Plugins/Android/. 同时检查 Proguard 设置 这里.
```
AndroidJavaException: java.lang.NoSuchMethodError: no static method with name='setWrapperVersion'
AndroidJavaException: java.lang.ClassNotFoundException: com.tenjin.android.TenjinSDK
```
  1. 如果你将 Tenjin SDK 更新至 v1.12.9 或以上, 请使用 Unity 3D 2019.4.21f1 及以上版本。如果你使用较低 Unity 版本,请联系我们,我们可以帮你进行 SDK 定制。 同时, 请升级 External Dependency Manager for Unity 到 1.12.167.

有任何技术问题,请邮件至: support@tenjin.com


目录


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("<API_KEY>");

instance.SetAppStoreType(AppStoreType.googleplay);

Amazon store

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

将 App Store Type 值设为 amazon:

BaseTenjin instance = Tenjin.getInstance("<API_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("<API_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("<API_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. Tenjin 面板 获取 <API_KEY>
  2. 在项目的 Start()OnApplicationPause() 方法中加入 BaseTenjin instance = Tenjin.getInstance("API_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("<API_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}}" />
  1. SetAppStoreType():
BaseTenjin instance = Tenjin.getInstance("<API_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("API_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 的一部分,我们为 registerAppForAdNetworkAttribution()updateConversionValue(_:) 创建的封装方案,可以注册等效的 SKAdNetwork 方案并同时发送 conversion values 到我们的服务器。

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

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("API_KEY");

#if UNITY_IOS

      // Registers SKAdNetwork app for attribution
      instance.RegisterAppForAdNetworkAttribution();

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

      // Sets SKAdNetwork Conversion Value
      // You will need to use a value between 0-63 for <YOUR 6 bit value>
      instance.UpdateConversionValue(<your 6 bit value>);

#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 请求,我们也不会处理任何事件。

To opt-in/opt-out:

void Start () {

  BaseTenjin instance = Tenjin.getInstance("API_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;
}
  • To opt-in/opt-out specific device-related parameters, you can use the OptInParams() or OptOutParams().

  • OptInParams() will only send device-related parameters that are specified. OptOutParams() will send all device-related parameters except ones that are specified.

  • Kindly note that we require the following parameters to properly track devices in Tenjin's system. If one of these mandatory parameters is missing, the event will not be processed or recorded.

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

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

BaseTenjin instance = Tenjin.getInstance("API_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("API_KEY");

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

instance.Connect();

设备层级数据

Param Description Platform Reference
ip_address IP Address All
advertising_id Device Advertising ID All Android, iOS
developer_device_id ID for Vendor iOS iOS
oaid Open Advertising ID Android Android
imei Device IMEI Android Android
limit_ad_tracking limit ad tracking enabled All Android, iOS
platform platform All iOS or Android
referrer Google Play Install Referrer Android Android
iad Apple Search Ad parameters iOS iOS
os_version operating system version All Android, iOS
device device name All Android, iOS (hw.machine)
device_manufacturer device manufactuer Android Android
device_model device model All Android, iOS (hw.model)
device_brand device brand Android Android
device_product device product Android Android
device_model_name device machine iOS iOS (hw.model)
device_cpu device cpu name iOS iOS (hw.cputype)
carrier phone carrier Android Android
connection_type cellular or wifi Android Android
screen_width device screen width Android Android
screen_height device screen height Android Android
os_version_release operating system version All Android, iOS
build_id build ID All Android, iOS (kern.osversion)
locale device locale All Android, iOS
country locale country All Android, iOS
timezone timezone All Android, iOS



购买事件

iOS 内购验证

iOS 验证 receipt 需要 transactionIdreceipt (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 > Features > In-App Purchases > App-Specific Shared Secret.

Android 内购验证

Android 的 receipt 验证必须提供 receiptsignature , (transactionId 设置为 to null).

重要提示: 你需要在 Tenjin dashboard添加 App 的 public key。获取 Base64-encoded RSA public key 的路径为 Google Play Developer Console > Select your app > Development Tools > Services & APIs。

iOS 和 Android 内购集成示例

  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 payload   = (string)wrapper["Payload"]; // For Apple this will be the base64 encoded ASN.1 receipt
    var productId = purchaseEventArgs.purchasedProduct.definition.id;

#if UNITY_ANDROID

  var gpDetails = Json.Deserialize(payload) as Dictionary<string, object>;
  var gpJson    = (string)gpDetails["json"];
  var gpSig     = (string)gpDetails["signature"];

  CompletedAndroidPurchase(productId, currencyCode, 1, lPrice, gpJson, gpSig);

#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("API_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("API_KEY");
      instance.Transaction(ProductId, CurrencyCode, Quantity, UnitPrice, TransactionId, Receipt, null);
  }

声明: 如果您是第一次在 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 documentation on Working with Subscriptions

  • 有关 Android 订阅的更多信息,请参阅For more information on Android subscriptions, please see: Google Play Billing subscriptions documentation


自定义事件

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

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

代码示例:

void MethodWithCustomEvent(){
    //event with name
    BaseTenjin instance = Tenjin.getInstance ("API_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") 可用来分析金币购买的总数及平均数。


深度链接 Deeplinks

用户通过广告计划上追踪链接点击并下载后,Tenjin 可以通过深度链接将用户打开应用后定向跳转到指定页面。

注意: 深度链接是付费功能,请联系您在 Tenjin 客户经理了解细节。


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();

广告展示层级收益集成

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

  • AppLovin
  • IronSource
  • HyperBid
  • AdMob

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

展示层级收益数据为付费功能,如有需要请联系你的客户经理讨论合约事宜。


集成测试

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



本文是否有帮助