简介

Tenjin 的原生安卓 SDK。

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

目录

• 权限
• SDK 集成
  • Google Play 服务
  • OAID
    • MSA OAID
    • 华为 OAID
    • 华为 Install Referrer
  • Proguard

• 集成

  • App Initilization
  • App Store
  • GDPR
  • 购买事件
  • 自定义事件
  • Deferred Deeplink
  • App Subversion

• 测试

权限

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

如果您使用的广告网络需要 IMEI 进行设备定位，您需要添加以下权限的启用：

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

SDK 集成

Android Studio

1. 点击这里 下载最新版的安卓 SDK。
2. 选择 New > Module将Tenjin SDK 添加到您的 Android Studi o项目中。
3. 在“新建模块”对话框中，选择 Import .JAR.AAR Package 选项并点击下一步。
   
   
   
   
4. 选择 tenjin.jar 或 tenjin.aar 文件并点击完成。
5. 在应用模块的 build.gradle 文件中，确保将以下添加到 dependencies block 中：

dependencies {
  compile project(":tenjin")
}

Google Play 服务和 Install Referrer

如果您通过 Google Play 分发您的 App，您需要添加 Google Play Services 和 Install Referrer 库，添加在 build.gradle 文件中。

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

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.23.aar')

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

通过添加以下代码将 App Store Type 的值设置为 other:

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

instance.setAppStore(TenjinSDK.AppStoreType.other);

华为 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}'
}

通过添加以下代码将 App Store Type 值设置为 other:

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

instance.setAppStore(TenjinSDK.AppStoreType.other);

华为的 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}'

}

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 Object[][] getContents();
}
-keepattributes *Annotation*

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

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

集成

App 初始化

1. 在 Tenjin Organization 标签页 拿到您的 API_KEY。
2. 在 Activity 中导入 Tenjin import com.tenjin.android.TenjinSDK;
3. 在 onResume 方法中，您的 main Activity class 需要添加如下代码:

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

instance.connect();

App Store

Google Play 为默认的应用商店，如果您需要在其他应用商店中进行发布，在 TenjinSDK.AppStoreType.* 中更新为对应的值:

1. AndroidManifest.xml:

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

1. setAppStore():

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

instance.setAppStore(TenjinSDK.AppStoreType.{{APP_STORE_TYPE_VALUE}});

根据您的应用所在的平台，将 AppStoreType 的值替换为以下选项中的一个：

• googleplay
• amazon
• other

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 = "<API_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

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

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

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

instance.connect();

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

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

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

instance.connect();

设备相关参数

内购事件

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

请注意： 您需要添加你的产品的 public key 到 Tenjin dashboard > Your Android App > Edit。您可以从 Google Play Developer Console > 获取您的 Base64-encoded RSA public key，路径为： Select your app > Development Tools > Services & APIs.

在 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 来验证内购收据，您将会看到类似以下内容：

自定义事件

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

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

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

String apiKey = <API_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, String value) 或者 eventWithNameAndValue(String name, int value).

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

String apiKey = <API_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 面板可以在对应的自定义事件名称下，汇总并平均对应的值。请注意，如果这个值不是整数，目前面板是不会显示的。

Deferred Deeplink

Tenjin 支持有将用户指向 App 特定部分的功能。这个用户被 Tenjin 归因之后，您可以利用 getDeeplink 和数据回调的方法获得延迟的深度链接。 这里 有更详细说明帮助您测试。

import com.tenjin.android.TenjinSDK;
import com.tenjin.android.Callback;

public class TenjinDemo extends ActionBarActivity {

    //...other callbacks are here

    @Override
    public void onResume() {
        //standard code
        super.onResume()

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

        instance.getDeeplink(new Callback() {
            @Override
            public void onSuccess(boolean clickedTenjinLink, boolean isFirstSession, Map<String, String> data) {
                if (clickedTenjinLink) {
                    if (isFirstSession) {
                        if (data.containsKey(TenjinSDK.DEEPLINK_URL)) {
                           // use the deferred_deeplink_url to direct the user to a specific part of your app
                        }
                    }
                }
            }
        });

        //Your other code...
        ...

    }

以下是可以通过 deferred deeplink callback 回调的参数：

在 Tenjin v1.7.1 之后的 SDK 上，您可以通过查看 isFirstSession 参数来处理安装后的逻辑。比如，您有一个付费应用，您可以通过以下方法来注册此次的付费安装：

import com.tenjin.android.TenjinSDK;

public class TenjinDemo extends ActionBarActivity {

    //...other callbacks are here

    @Override
    public void onResume() {
        //standard code
        super.onResume()

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

        instance.getDeeplink(new Callback() {
            @Override
            public void onSuccess(boolean clickedTenjinLink, boolean isFirstSession, Map<String, String> data) {
                if (isFirstSession) {
                  // send paid app price and revenue to Tenjin
                }
            }
        });

        //Your other code...
        ...

    }

用于 A/B 测试的 App Subversion 参数（需要 DataVault 权限）

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

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

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

集成测试

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