Android SDK

Tenjin 的安卓原生SDK

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

• 请查看我们的 历史版本记录 中的版本详情和变化。
• 我们推荐使用最新的 Android Studio.
• 如果你使用 Unity 插件集成，请在这里查看详细内容： https://github.com/tenjin/tenjin-unity-sdk.
• 如果有任何技术问题，请邮件至 support@tenjin.com， 我们有遍布全球的支持团队为你服务。

目录

• 基础设置
  • Google Play 或 Amazon 应用商店
    • 权限
    • 安卓广告 ID (AAID)
    • 应用商店类型
  • 其他安卓商店
    • 权限
    • 安卓广告 ID (AAID)
    • OAID
      • MSA OAID
      • Huawei OAID
      • Huawei Install Referrer
    • 应用商店类型
• Proguard 设置
• 集成
  • 初始化
  • GDPR
  • • Opt in/out CMP
  • 购买事件
  • 自定义事件
  • S2S 服务端集成
  • 应用子版本及 A/B 测试
  • LiveOps 动态运营
  • 用户ID
  • [分析安装ID
  • Retry-cache重试逻辑
  • 广告展示层级收益集成
  • Google DMA 参数
• 集成测试

基础设置

手动安装

请遵循下方“Android Studio”一节中列出的步骤。

Maven

如果您使用 Maven，就只需添加 com.tenjin:android-sdk:{VERSION} 到Gradle依赖项中，并且添加 mavenCentral()到源存储库（如果还没有的话）。

Android Studio

1. 点击这里 下载最新版的安卓 SDK。
2. 在 Android Studio 里的 Project Navigator， 选择 Project，你将在 Android Studio project 里的 app 模块下看到 libs 文件夹 。
3. 你需要将 tenjin.jar 或 tenjin.aar 文件添加到 libs 文件夹中。
   
4. 在你的 Android Studio 项目的 app 模块，选择 build.gradle 文件，确保将以下添加到 dependencies block 中：

dependencies {
  implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
  implementation files('libs/tenjin.aar')
}

可参考我们的 demo 项目 - tenjin-android-sdk-demo ，这样有助于您更快捷地集成我们的 SDK。

Google Play 或 Amazon 应用商店

如果你在 Google Play 或者 Amazon 应用商店分发你的产品，请参考以下进行设置：

权限

Tenjin SDK 需要以下权限：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <!-- Required to get network connectivity (i.e. wifi vs. mobile) -->

同时从2022年4月1日起，在目标 API 级别设置为32（Android 13）的应用程序上，获得安卓广告ID需要添加以下权限才可以获取 。请尽快添加此权限，另外请注意你需要将安卓 SDK 更新到 1.12.8及以上版本才可适配新的安卓权限。

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

安卓广告 ID (AAID) 和 Install Referrer

在你的 build.gradle 文件中添加 安卓广告 ID (AAID) 和 Install Referrer 库。

dependencies {
  implementation 'com.google.android.gms:play-services-ads-identifier:{version}'
  implementation 'com.android.installreferrer:installreferrer:{version}'
}

应用商店类型

默认商店类型 App Store 是 unspecified 。请根据你上架的应用商店，将 AppStore 值更改为 googleplay 或 amazon。

1. AndroidManifest.xml:

<meta-data
    android:name="TENJIN_APP_STORE"
    android:value="googleplay" />

2. setAppStore():

TenjinSDK instance = TenjinSDK.getInstance(this, "<SDK_KEY>");

instance.setAppStore(TenjinSDK.AppStoreType.googleplay);

初始化

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

2. 在 Activity 中导入 Tenjin import com.tenjin.android.TenjinSDK;

3. 在 onResume 方法中，你的 main Activity class 需要添加如下代码（如果安卓中国应用，请同时在 onCreate 调用以下代码）:

TenjinSDK instance = TenjinSDK.getInstance(this, "<SDK_KEY>");

instance.connect();

注意： 如果您的应用在 onCreate 和 onResume之间会请求用户的同意，使用 onCreate 而不是 onResume 用于 Tenjin SDK 初始化，因为一旦用户不同意将无法在onResume中进行追踪。

注意： 请确保在每一个 main activity onResume 里调用Tenjin。如果我们发现您未按照要求集成，我们会暂停支持并停用您的账户。

其他安卓应用商店

如果你在其他安卓应用商店（包括安卓中国、华为海外等）分发产品，请参照以下设置：

权限

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <!-- Required to get network connectivity (i.e. wifi vs. mobile) -->

同时从2022年4月1日起，在目标 API 级别设置为32（Android 13）的应用程序上，获得安卓广告ID需要添加以下权限才可以获取 。请尽快添加此权限，另外请注意你需要将安卓 SDK 更新到 1.12.8及以上版本才可适配新的安卓权限。

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

安卓广告 ID (AAID) 和 Install Referrer

在你的 build.gradle 文件中添加 安卓广告 ID (AAID) 和 Install Referrer 库。

dependencies {
  implementation 'com.google.android.gms:play-services-ads-identifier:{version}'
  implementation 'com.android.installreferrer:installreferrer:{version}'
}

<uses-permission android:name="android.permission.READ_PHONE_STATE" />

OAID

Tenjin 支持使用 OAID 在其他非 Google Play 商店渠道进行推广。我们有以下用于集成 OAID 库的选项。

MSA OAID

集成 MSA 库，你需要下载 oaid_sdk_1.0.25.aar 和 supplierconfig.json.

在项目 gradle 文件中添加以下内容：

implementation files('libs/oaid_sdk_1.0.25.aar')

并确保在项目中复制了 supplierconfig.json 文件到 assets 文件夹内。

Huawei OAID （华为海外）

对于在华为海外应用商店的推广，你可以集成华为 OAID 库来获取 OAID。可将华为的 OAID 库，在项目中添加以下内容：

在 build.gradle 文件中，为华为 SDK 添加 Maven address：

allprojects {
    repositories {
        google()
        jcenter()
        maven { url 'https://developer.huawei.com/repo/' }
    }
}

dependencies {
    implementation 'com.huawei.hms:ads-identifier:{version}'
}

Huawei Install Referrer

如果你在 华为应用商店（Huawei App Gallery）进行推广，请将上面的 Huawei OAID SDK 和 Install Referrer 库都进行添加。

dependencies {

    implementation 'com.huawei.hms:ads-identifier:{version}'
    implementation 'com.huawei.hms:ads-installreferrer:{version}'

}

App 应用商店类型

默认商店类型 App Store 是 unspecified 。请将 AppStore 值更改为 other 。

1. AndroidManifest.xml:

<meta-data
    android:name="TENJIN_APP_STORE"
    android:value="other" />

2. setAppStore():

TenjinSDK instance = TenjinSDK.getInstance(this, "<SDK_KEY>");

instance.setAppStore(TenjinSDK.AppStoreType.other);

初始化

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

2. 在 Activity 中导入 Tenjin import com.tenjin.android.TenjinSDK;

3. 在 onResume 方法中，你的 main Activity class 需要添加如下代码（如果安卓中国应用，请同时在 onCreate 调用以下代码）:

TenjinSDK instance = TenjinSDK.getInstance(this, "<SDK_KEY>");

instance.connect();

注意： 如果您的应用在 onCreate 和 onResume之间会请求用户的同意，使用 onCreate 而不是 onResume 用于 Tenjin SDK 初始化，因为一旦用户不同意将无法在onResume中进行追踪。

注意： 请确保在每一个 main activity onResume 里调用Tenjin。如果我们发现您未按照要求集成，我们会暂停支持并停用您的账户。

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*

请不要混淆 oaid 库:

-keep class XI.CA.XI.**{*;}
-keep class XI.K0.XI.**{*;}
-keep class XI.XI.K0.**{*;}
-keep class XI.xo.XI.XI.**{*;}
-keep class com.asus.msa.SupplementaryDID.**{*;}
-keep class com.asus.msa.sdid.**{*;}
-keep class com.bun.lib.**{*;}
-keep class com.bun.miitmdid.**{*;}
-keep class com.huawei.hms.ads.identifier.**{*;}
-keep class com.samsung.android.deviceidservice.**{*;}
-keep class com.zui.opendeviceidlibrary.**{*;}
-keep class org.json.**{*;}
-keep public class com.netease.nis.sdkwrapper.Utils {public <methods>;}

如果你使用华为的库，你可以使用以下设置：

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

其它集成

GDPR

通用数据保护条例 (EU) (GDPR) 是欧盟法律中关于欧盟 (EU) 和欧洲经济区 (EEA) 数据保护和隐私的条例。

您需要在第一次打开应用程序时获得用户同意是否允许跟踪，然后将结果写入 checkOptInValue() 。 之后，您可以按照以下代码进行操作。 如果您不需要在您的应用程序中遵守 GDPR，请忽略这整个部分。

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

选择 opt-in/opt-out:

import com.tenjin.android.TenjinSDK;

public class TenjinDemo extends ActionBarActivity {
    @Override
    public void onResume() {
        //standard code
        super.onResume()

        //Integrate TenjinSDK connect call
        String apiKey = "<SDK_KEY>";
        TenjinSDK instance = TenjinSDK.getInstance(this, apiKey);

        boolean userOptIn = checkOptInValue();

        if (userOptIn) {
            instance.optIn();
        }
        else {
            instance.optOut();
        }

        instance.connect();

        //Your other code...
        //...

    }

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

要选择加入/退出特定的设备相关参数，可以使用 OptInParams() 或 OptOutParams()。

• OptInParams() 将仅发送指定的设备相关参数. OptOutParams() 将发送除指定参数外的所有与设备相关的参数。

• 请注意，我们至少需要以下参数来正确地对设备进行追踪监测：

  • ip_address
  • advertising_id
  • limit_ad_tracking
  • referrer

• 如果你使用依赖 IMEI 和/或 OAID 的广告网络，以下参数为必须：

  • imei
  • oaid

• 如果你计划使用 Google AdWords, 以下参数为必需项：

  • platform
  • os_version
  • locale
  • device_model
  • build_id
  • app_verision

如果只想获取设备相关的特定参数，使用 OptInParams()，以下样例中，仅使用了设备相关的参数 ip_address, advertising_id, os_version, os_version_release, limit_ad_tracking, 和 referrer。

String apiKey = "<SDK_KEY>";
TenjinSDK instance = TenjinSDK.getInstance(this, apiKey);

String[] optInParams = {"ip_address", "advertising_id", "limit_ad_tracking","os_version","os_version_release", "referrer"};
instance.optInParams(optInParams);

instance.connect();

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

String apiKey = "<SDK_KEY>";
TenjinSDK instance = TenjinSDK.getInstance(this, apiKey);

String[] optOutParams = {"locale", "timezone", "build_id"};
instance.optOutParams(optOutParams);

instance.connect();

Opt in/out CMP

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

TenjinSDK instance = TenjinSDK.getInstance(this, "<SDK_KEY>");
optInOut = instance.optInOutUsingCMP(); 

设备层级数据

购买事件

理解用户收入和购买行为，你可以发送 transaction 事件到 Tenjin，Tenjin 将为你的 transaction 收据进行验证。

请注意： 你需要添加你的产品的 public key 到 Tenjin dashboard > Your Android App > Edit。你可以从 Google Play Developer Console > 获取你的 Base64-encoded RSA public key，路径为： Select your app > Monetize > Monetization setup > Google Play Billing > Licensing: Base64-encoded RSA public key.

在 Tenjin 面板上添加好 Public Key 后，你可以使用以下方法：

public void transaction(String productId, String currencyCode, int quantity, double unitPrice, String purchaseData, String dataSignature)

示例:

public void sendPurchaseEvent(Purchase purchase, Double price, String currencyCode) {
    String sku = purchase.getSku();
    String purchaseData = purchase.getOriginalJson();
    String dataSignature = purchase.getSignature();

    TenjinSDK instance = getTenjinInstance();
    instance.transaction(sku, currencyCode, 1, price, purchaseData, dataSignature);
}

你可以通过我们的 Live Test Device Data Tool 来验证内购收据，你将会看到类似以下内容：

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

Amazon 商店

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

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

自定义事件

注意： connect() 事件的初始化必须在自定义事件之前进行上报。

你可以使用 Tenjin SDK 上报自定义事件： eventWithName(String name)。

通过 Tenjin服务，你可以通过自定义事件，将买量的渠道和成本和应用内的交互进行关联绑定，示例如下：

String apiKey = <SDK_KEY>;
TenjinSDK instance = TenjinSDK.getInstance(this, apiKey);

//Integrate a custom event with a distinct name - ie. swiping right on the screen
instance.eventWithName("swipe_right");

赋值的自定义事件

你可以使用 Tenjin SDK 上报值为整数的自定义事件： eventWithNameAndValue(String name, int value)。

上报一个有 name （名称）的自定义事件， value （值）需为整数，你可以直接在面板上查看汇总和跟踪的平均值。如果你计划使用 Datavault，这些数值可以被用在更多有用的的指标计算上。

String apiKey = <SDK_KEY>;
TenjinSDK.instance = TenjinSDK.getInstance(this, apiKey);

//Integrate a custom event with a distinct name and value - ie. paying 100 virtual coins for an item
instance.eventWithNameAndValue("item", 100);

通过以上的样例， 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 值来查看报告。

TenjinSDK instance = TenjinSDK.getInstance(this, "<SDK_KEY>");
instance.appendAppSubversion(8888);
instance.connect();

LiveOps 动态运营

Tenjin 支持在 SDK 层面获取用户的来源信息，比如在客户端区分自然量和非自然量用户，我们提供 method 在 SDK 层面获取用户来源信息，该 method 将返回一个map , 里面包括买量渠道及广告计划等。

这将允许开发者实时收集和分析这些用户级归因数据。以下是使用 Tenjin LiveOps 动态运营的可能用例：

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

用户ID

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

.setCustomerUserId(userId: "user_id")

.getCustomerUserId()

TenjinSDK instance = TenjinSDK.getInstance(this, "<SDK_KEY>");
instance.setCustomerUserId(userId: "user_id");
userId = instance.getCustomerUserId(); 

分析ID Analytics Installation ID

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

TenjinSDK instance = TenjinSDK.getInstance(this, "<SDK_KEY>");
analyticsId = instance.getAnalyticsInstallationId; 

Retry Cache 重试逻辑

当请求失败或用户没有网络连接时，您可以启用/禁用重试和缓存事件以及 内购。 这些事件将在新事件添加到队列并且用户恢复连接后发送。

.setCacheEventSetting(setting: true)

TenjinSDK instance = TenjinSDK.getInstance(this, "<SDK_KEY>");
instance.setCacheEventSetting(setting: true);

Google DMA 参数

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

setGoogleDMAParameters(boolean, boolean)

TenjinSDK instance = TenjinSDK.getInstance(this, "<SDK_KEY>");
instance.setGoogleDMAParameters(adPersonalization, adUserData); 

广告展示层级收益集成

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

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

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

Google DMA 参数

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

setGoogleDMAParameters(boolean, boolean)

TenjinSDK instance = TenjinSDK.getInstance(this, "<SDK_KEY>");
instance.setGoogleDMAParameters(adPersonalization, adUserData); 

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

instance.optInGoogleDMA(); 
instance.optOutGoogleDMA(); 

集成测试

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