- 17 Dec 2024
- 6 阅读时间
- 打印
- 黑暗模式白天模式
Android SDK
- 更新于 17 Dec 2024
- 6 阅读时间
- 打印
- 黑暗模式白天模式
Tenjin 的安卓原生SDK
Tenjin Android SDK 允许客户在他们的 Android 应用程序中跟踪事件和安装。 要了解有关 Tenjin 和我们的产品的更多信息,请访问 https://www.tenjin.com.
- 请查看我们的 历史版本记录 中的版本详情和变化。
- 我们推荐使用最新的 Android Studio.
- 如果你使用 Unity 插件集成,请在这里查看详细内容: https://github.com/tenjin/tenjin-unity-sdk.
- 如果有任何技术问题,请邮件至 support@tenjin.com, 我们有遍布全球的支持团队为你服务。
目录
基础设置
手动安装
请遵循下方“Android Studio”一节中列出的步骤。
Maven
如果您使用 Maven,就只需添加 com.tenjin:android-sdk:{VERSION}
到Gradle
依赖项中,并且添加 mavenCentral()
到源存储库(如果还没有的话)。
Android Studio
- 点击这里 下载最新版的安卓 SDK。
- 在 Android Studio 里的 Project Navigator, 选择 Project,你将在 Android Studio project 里的 app 模块下看到 libs 文件夹 。
- 你需要将
tenjin.jar
或tenjin.aar
文件添加到 libs 文件夹中。
- 在你的 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}'
}
为了能够收集 Meta's Install Referrer, 请将以下查询添加到您的安卓Manifest中
<queries>
<package android:name="com.facebook.katana" />
</queries>
<queries>
<package android:name="com.instagram.android" />
</queries>
如果您尚未设置 Facebook 的 SDK(Meta),请在您的 AndroidManifest.xml 文件中添加以下内容:
<meta-data android:name="com.facebook.sdk.ApplicationId" android:value="@string/facebook_app_id" />
接下来,在你的 strings.xml 文件中添加以下值
<string name="facebook_app_id" translatable="false">YOUR_APP_ID</string>
应用商店类型
默认商店类型 App Store 是 unspecified 。请根据你上架的应用商店,将 AppStore 值更改为 googleplay 或 amazon。
AndroidManifest.xml
:
<meta-data
android:name="TENJIN_APP_STORE"
android:value="googleplay" />
setAppStore()
:
TenjinSDK instance = TenjinSDK.getInstance(this, "<SDK_KEY>");
instance.setAppStore(TenjinSDK.AppStoreType.googleplay);
初始化
您可以在应用 App 页面获取
SDK_KEY
。 请注意:每个应用的SDK_KEY
都是唯一的,您可以为每个应用生成最多3个SDK_KEY
。
在 Activity 中导入 Tenjin
import com.tenjin.android.TenjinSDK;
在
onResume
方法中,你的 mainActivity
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}'
}
对于非 Google Play 安卓应用,如果你使用的 广告渠道 需要 IMEI
进行设备定位,那么可以添加以下权限的启用:
<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 。
AndroidManifest.xml
:
<meta-data
android:name="TENJIN_APP_STORE"
android:value="other" />
setAppStore()
:
TenjinSDK instance = TenjinSDK.getInstance(this, "<SDK_KEY>");
instance.setAppStore(TenjinSDK.AppStoreType.other);
初始化
您可以在应用 App 页面获取
SDK_KEY
。 请注意:每个应用的SDK_KEY
都是唯一的,您可以为每个应用生成最多3个SDK_KEY
。
在 Activity 中导入 Tenjin
import com.tenjin.android.TenjinSDK;
在
onResume
方法中,你的 mainActivity
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 请求,我们也不会处理任何事件。
任何要求处理或使用欧盟公民个人数据的组织/品牌,都需要遵守《通用数据保护条例》(General Data Protection Regulations,简称 GDPR)在访问数据、转移数据、更正数据和删除数据方面的规范。
选择 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 SDK_KEY = "<SDK_KEY>";
TenjinSDK instance = TenjinSDK.getInstance(this, SDK_KEY);
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 SDK_KEY = "<SDK_KEY>";
TenjinSDK instance = TenjinSDK.getInstance(this, SDK_KEY);
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 SDK_KEY = "<SDK_KEY>";
TenjinSDK instance = TenjinSDK.getInstance(this, SDK_KEY);
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();
设备层级数据
参数 | 说明 | 示例 |
---|---|---|
ip_address | IP 地址 | |
advertising_id | 设备的广告标识符 | Android |
limit_ad_tracking | 设备是否限制广告追踪 | Android |
oaid | 启用 Advertising ID 广告标识符 | Android |
imei | 设备的 IMEI | Android |
platform | 平台 | Android |
referrer | Google Play Install Referrer | Android |
os_version | 操作系统版本 | Android |
device | 设备名称 | Android |
device_manufacturer | 设备制造商 | Android |
device_model | 设备型号 | Android |
device_brand | 设备品牌 | Android |
device_product | 设备产品 | Android |
carrier | 电话运营商 | Android |
connection_type | 移动流量或 Wifi | Android |
screen_width | 设备屏幕宽度 | Android |
screen_height | 设备屏幕高度 | Android |
os_version_release | 操作系统版本 | Android |
build_id | 包名 | Android |
locale | 设备区域设置 | Android |
country | 设备国家设置 | Android |
timezone | 时区 | Android |
购买事件
理解用户收入和购买行为,你可以发送 transaction
事件到 Tenjin,Tenjin 将为你的 transaction
收据进行验证。
请注意: 请在Tenjin面板上,找到对应应用的设置,并添加您public key。
添加的路径:Tenjin dashboard >对应APP > Edit
可以从 Google Play Developer Console 页面获取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 上集成购买事件,请事先自行确保内购数据的准确性,然后才开始基于内购优化的投放策略。
在上报购买到 Tenjin 之前,请先 'acknowledge / 确认' 该笔交易。具体详情,请参见谷歌的要求 here
通过我们的新设置,您可以选择 15% 到 30% 的 App Store 收入佣金。 步骤是:
- 转到 CONFIGURE --> APP
- 单击您想要更改的应用程序
- 在“App Store Commission”部分下单击“Edit”
- 选择 30% 或 15% 作为您想要的应用商店佣金。
- 选择开始日期和结束日期(或者,如果您不需要结束日期,可以将结束日期留空)
- 单击“Save”(注意:15% 佣金仅适用于未来日期,不适用于历史日期。因此,请设置从您进行更改之日起开始日期以及未来日期)
Amazon 商店
Amazon商店内购收据验证需要 receiptId
和 userId
字段.
重要提示: 你需要将 Amazon 密钥添加至 Tenjin 面板。 你可以在开发者账户 Amazon Appstore account 里查看相应的密钥。
自定义事件
注意: connect()
事件的初始化必须在自定义事件之前
进行上报。
你可以使用 Tenjin SDK 上报自定义事件: eventWithName(String name)
。
通过 Tenjin服务,你可以通过自定义事件,将买量的渠道和成本和应用内的交互进行关联绑定,示例如下:
String SDK_KEY = <SDK_KEY>;
TenjinSDK instance = TenjinSDK.getInstance(this, SDK_KEY);
//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 SDK_KEY = <SDK_KEY>;
TenjinSDK.instance = TenjinSDK.getInstance(this, SDK_KEY);
//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 提供服务器端集成功能,支持将安装和后续应用内事件直接发送至 Tenjin 服务器,无需集成 SDK。如有需要,请联系 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 成功经理。
注意: LiveOps 动运营为付费功能,如有需要请联系你的客户经理讨论合约事宜。
用户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 端发送事件,如果集成没有问题,你可以很快在面板上看到事件记录。