Android之数据统计TalkingData集成

来源：互联网发布：mac手机铃声编辑：程序博客网时间：2024/06/08 12:24

Android之TalkingData集成

一、综述

1、适用范围

TalkingData Analytics为移动应用提供数据统计分析服务，通过在应用中加入数据SDK，来在www.talkingdata.com 网站中查阅应用的相关数据。
统计SDK适用于 Android 2.2（API Level 8）及以上的设备。
SDK2.0.X及以上版本支持灵动事件 - 免去在App中添加追踪代码，直接在平台报表中定义数据追踪点，可自动完成追踪码部署。

2、统计标准

数据系统中的基本数据单元依据以下标准定义：

1）新增用户

TalkingData数据系统中的“用户”指用户的一台唯一设备。

2）用户的一次使用

指用户从打开应用的界面至离开界面的完整过程。如用户在离开界面后30秒内重新回到应用中，将被认为是上次使用被打扰后的延续，记为一次完整使用。

3）页面

指Android应用的每个Activity。

4）自定义事件

指用户在应用中进行了特定的操作或达成了特定的条件。例如：用户点击了广告栏、用户进行付费等。自定义事件用于收集任意您期望跟踪的数据。

二、接入数据系统

1、为应用申请App ID

在 www.talkingdata.com 网站中创建一款应用，您将获得一串32位的16进制App ID，用于唯一标识您的一款应用。TalkingData支持跨平台的应用，跨平台应用只需获得一个App ID即可。

2、向工程中导入追踪SDK

1）Eclipse ADT

下载数据统计SDK后解压至本地目录，将其中的TalkingdataAnalytics.jar 拷贝到工程的libs文件夹下。（如需使用灵动分析功能，请使用v2.0.X Beta及以上版本SDK）

2）Android Studio

• 在 Android Studio 项目的 app 目录下新建 libs 目录。
• 将 TalkingdataAnalytics.jar 拷贝到上面新建的 libs 目录下。
• 在 app 目录下的 build.gradle 文件中的 dependencies 依赖项

TalkingdataAnalytics.jar：

dependencies {

…

compile files('libs/TalkingdataAnalytics.jar')

…

}

3、配置ANDROIDMANIFEST.XML文件

权限

用途

INTERNET

允许程序联网和发送统计数据的权限。

ACCESS_NETWORK_STATE

允许应用检测网络连接状态，在网络异常状态下避免数据发送，节省流量和电量。

READ_PHONE_STATE

允许应用以只读的方式访问手机设备的信息，通过获取的信息来唯一标识用户。

ACCESS_WIFI_STATE

获取设备的MAC地址，同样用来标识唯一用户。

WRITE_EXTERNAL_STORAGE

用于保存设备信息，以及记录日志。

GET_TASKS (建议)

获取当前应用是否在显示应用，可以更精准的统计用户活跃

ACCESS_ FINE_LOCATION（可选）

可通过GPS获取设备的位置信息，用来修正用户的地域分布数据，使报表数据更准确。

ACCESS_ COARSE_LOCATION（可选）

用来获取该应用被使用的粗略位置信息。

meta-data

用途

TD_APP_ID

用来唯一标识您的应用，将您创建应用时获得的32个字符组成的App ID写入meta-data中，替换“Your_app_id”即可。

TD_CHANNEL_ID（建议添加）

用来标注应用推广渠道，区分用户的来源来查看统计。您可自定义渠道名来替换value中的“Your_channel_id”。格式：32个字符内，支持中文、英文、数字、空格、英文点和下划线，请勿使用其他符号。

示例代码:

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

<uses-permission

android:name="android.permission.ACCESS_NETWORK_STATE" />

<uses-permission

android:name="android.permission.READ_PHONE_STATE" />

<uses-permission

android:name="android.permission.ACCESS_WIFI_STATE" />

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

......

</activity>

......

android:value="Your_app_id" />

android:value="Your_channel_id" />

</application>

</manifest>

附注：已创建完成的应用，可进入该应用的数据报表页中，在“系统设置”-“编辑应用”页面里能随时查看到获得的App ID。

4、添加SDK初始化代码（重要）

TalkingData Analytics的SDK提供两种初始化的方法：

1）开发者可以通过com.tendcloud.tenddata.TCAgent.init方法手工传入AppId 。

init(final Context context, final String appId, final String partnerId);

//这种方式不需要在Manifest里的meta-data申明了TD_APP_ID和TD_CHANNEL_ID

2）开发者在AndroidManifest里的meta-data里配置AppId和ChannelId。（如上示例代码）

init(final Context context);

//这种方式可以使用多渠道打包工具，方便一次打包多个发布渠道

注意1：为了保证统计到的数据更加的全面，强烈建议不论哪种init 方式，都要在Application的onCreate里调用（不论您的程序是否有后台service还是多进程），如果您的程序里没有自定义的application类，请添加！

注意2：初始化是使SDK开始工作的关键，不进行初始化就对其他接口进行调用，会有引发程序崩溃的严重危险。请开发者一定注意。

5、代码混淆

请开发者在自己的 Proguard 混淆配置文件中添加下面的规则，使得混淆的时候不会影响统计SDK的命名空间：

-keep public class com.tendcloud.tenddata.** { public protected *;}

-keep classmembers class ** {

public void *(***);

}

-keep class com.talkingdata.sdk.TalkingDataSDK {public *;}

-keep class com.apptalkingdata.** {*;}

重要提示：首次从2.1.37及之前版本SDK升级到2.2.2及以后版本时，请务必确认代码混淆方式与我们的集成文档中代码混淆方式一致。

6、添加必须的调用方法（重要）

对于自己感兴趣的页面，通过下面的接口进行该页面生命周期监控，这些调用用于准确跟踪用户每次的应用使用，是准确统计启动、活跃、留存数据的基础：

在每个需要统计的Activity的onResume和onPause方法分别调用TCAgent.onResume 和 TCAgent.onPause接口。

要统计应用内的页面访问数据，需要在每一个要跟踪的页面进入和离开的位置调用onPageStart和onPageEnd。需要注意的是，页面应该是一个接着一个的，不能嵌套调用；进入新页面，必须离开旧页面，否则可能导致页面统计数据异常。

调用方法：

在进入页面的时候加入如下的代码调用：

[java] view plain copy
TCAgent.onPageStart(Context ctx, String pageName);  

在离开页面的时候加入如下的代码调用：

TCAgent.onPageEnd(Context ctx, String pageName);

其中pageName为自定义的页面名称，需要和onPageStart中传入的一致；并且onPageStart和onPageEnd必须成对调用。

三、更多统计分析功能

1、区分渠道查阅数据

给应用的安装包打入特殊的渠道标记，用户安装使用渠道包后，您可以在报表中区分来源单独查询出数据。在您为应用商店、下载站等分发渠道提供应用安装包时可以加入渠道标记，在进行特别的活动时亦可加入渠道标记来单独分析效果。

在AndroidManifest.xml里添加meta-data段，用您定义的渠道名替换value中的“Your_channel_id”。

</meta-data>

渠道名可自行定义，格式：64个字符内，支持中文、英文、数字、空格、英文点和下划线，请勿使用其他符号。

用户的渠道归属：每台设备仅记录给首次安装激活的渠道，同一用户在更替渠道包使用后不会重复计算新增，使用数据归入首次激活渠道。

如果未添加渠道标记，或渠道标记是示例代码中的默认值，用户将会归入为“未知渠道”。

我们提供多渠道打包工具以帮助您快速生成多个不同渠道包，支持V1.2.74版本及以上。该工具修改的渠道ID会优先于手动修改的渠道ID被读取。详见：http://www.talkingdata.com/activity/packTool-Explain/index.html

2、使用自定义事件

自定义事件用于统计任何您期望去跟踪的数据，如：用户点击某功能按钮、填写某个输入框、触发了某个广告等。

我们提供两种使用方法：

1）直接在报表后台中设定追踪点并自动部署追踪代码的“灵动事件”；

2）在App中以触发代码方式追踪数据的“代码事件”。
2.1. 灵动事件

灵动事件支持App界面中的按钮、输入框、单选和多选控件、图片按钮的点击动作自动计数。您不需要书写额外的触发代码，在报表平台中通过动态添加，SDK会自动部署追踪码。

在数据报表的以下位置来动态管理全部“灵动事件”：

[登录平台] - [选择应用，进入报表] – 左菜单进入[事件和转化] – 进入[灵动事件]

2.2. 集成事件

在App中手工添加触发代码方式来记录自定义的数据追踪点；

调用方法

在应用程序要跟踪的事件处加入下面格式的代码，也就成功的添加了一个简单事件到您的应用程序中了：

TCAgent.onEvent(Context ctx, String EVENT_ID);

跟踪多个同类型事件，无需定义多个Event ID，可以使用Event ID做为目录名，而使用Label标签来区分这些事件，可按照下面格式添加代码：

TCAgent.onEvent(Context ctx, String EVENT_ID, String EVENT_LABEL);

为事件添加详尽的描述信息，可以更有效的对事件触发的条件和场景做分析，可按照下面格式添加代码：

TCAgent.onEvent(Context ctx, String EVENT_ID, String EVENT_LABEL, Map<string, object=""> kv);

注: 此Map的Value仅支持字符串（String）和数字（Number）类型，其他类型会自动调用toString()方法转换为String进行处理。在Value使用String格式时，报表中将给出事件发生时每种value出现的频次；Value为Number时，报表将帮助计算value值的总计值和平均数。

如果所有事件都需要传输相同的参数，可以设置全局的Key-Value，这些Key-Value会自动添加到所有自定义事件：

TCAgent.setGlobalKV(String key, Object value);

如果要移除全局Key-Value，则可以调用：

TCAgent.removeGlobalKV(String key);

注: 如果onEvent里传入的Key-Value里的key和全局Key-Value里的key冲突，以onEvent里传入的为准。

示例1：

跟踪某电商应用中首页的5个不同推广位置的点击次数，并收集宣传品的品类、促销价格等信息：

// 可定义eventId=点击首页推荐位；event_LABEL=具体的位置编号

@Override

public void onClick(View v) {

Map<string, object=""> kv = new HashMap<string, object="">();

kv.put("商品类型", "休闲食品");

kv.put("价格","5～10元" );

TCAgent.onEvent(DemoActivity.this, "点击首页推荐位", "第3推广位", kv);

}

注1：这里追踪的事件属于同类型，使用了Label标签的用法。以相同Event ID来作为统一名称，Label来确定不同位置。这样查阅Event ID数据即可了解全部推广位总量点击数据，展开Label可查阅具体某位置数据。

注2：在value取值较离散情况下（如示例中收集的促销价格信息），不要直接填充具体数值，而应划分区间后传入（如9.9元，可定义5～10元的价格区间，传入5～10元），否则value不同取值很可能超过平台最大数目限制，离散数据也对分析人员阅览数据造成影响。

3、应用错误日志分析

收集应用的错误日志可帮助您来修正BUG、改善产品。报表中，我们除了提供错误次数的数据外，还提供错误的详细信息阅览，并会对错误进行合理分类。您可通过两种方式来获取错误日志：让TalkingData SDK自动捕获异常、或您主动传送错误信息给SDK。

SDK自动获取异常信息

为了简化开发者的工作，我们提供自动获取异常信息的功能，但考虑异常信息收集会损耗最终用户流量，因此自动捕获默认为关闭状态。

可向以下方法中传入true（开启自动捕获）或false（关闭自动捕获），来控制自动捕获功能的开关：

TCAgent.setReportUncaughtExceptions(Boolean enabled)

示例：打开自动异常捕获

@Override

public void onCreate(Bundle savedInstanceState) {

super.onCreate(savedInstanceState);

setContentView(R.layout.main);

TCAgent.setReportUncaughtExceptions(true);

}

很多错误发生在应用刚启动时，自动异常捕获依赖于数据SDK已开始工作，如果您期望捕获更全面的异常信息，请在程序最先启动处加入以下代码，以使数据SDK更早开始工作，收集异常。

TCAgent.init(this);

主动传送异常信息。

您也可主动调用以下方法将抛出的exception信息传入至方法中的第二个参数中（主动捕获关闭状态下依然有效）：

TCAgent.onError(Activity activity, Throwable throwable)

示例：

try {

File file = new File("filePath");

if(!file.exists()){

file.createNewFile();

}

} catch (IOException e) {

TCAgent.onError(this, e);

}

四、使用营销推送组件

1、用途和用法

营销推送组件帮助您获得利用数据进行精准推送的能力，结合数据平台提供的各种人群，可以实时编辑发送内容，对任意人群完成推送，并支持实时查阅推送效果数据，不断对比效果，优化营销方法。

营销推送更强大之处在于，您不仅可以选择使用TalkingData提供的推送通道，他还可以与个推、极光等推送平台组合使用，让以往的粗放推送都可达到实时精准化，并实时查阅效果数据。

2、集成TalkingData推送

增加以下的调用方法，来让您的应用可以接收推送通知；需注意在获得推送能力的同时，您的应用会在后台中长期运行：

1）打开AndroidManifest.xml，添加推送功能所必要的权限

除之前所需要的权限外，还需要添加以下功能权限

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

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

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

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

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

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

2）添加TalkingDataAppAnalytics所必须的Service。

3）添加TalkingDataAppAnalytics所必须的BroadCastReceiver，以支持接收消息。

<intent-filter>

</intent-filter>

</receiver>

<intent-filter>

</intent-filter>

<intent-filter>

</intent-filter>

</receiver>

通过以下调用方法，可以快速关闭TalkingData推送服务，应用将不会处于后台，同时也无法进行推送：请在 init 前调用setPushDisabled();

3、第三方推送平台与TalkingData组合使用

TalkingData支持从平台中划定精准用户群，组合第三方推送平台来直接发送推送和收集实时数据效果；目前支持两家第三方推送平台：个推、极光。如果您已经是三方推送的使用者，这种方式能让您更舒服的实现精准推送并验证效果。遵循以下方法进行集成

1）您需要在第三方推送平台中申请账户，并已完成三方推送的对接。您需要在对接后确认测试通过，三方推送可以接收到推送消息。

2）添加TalkingData App Analytics所必须的BroadCastReceiver；

如果您使用个推推送：

在AndroidManifest.xml添加如下内容：

<intent-filter>

</intent-filter>

<intent-filter>

</intent-filter>

</receiver>

如果您使用极光推送：（支持版本为1.8.2及以上版本组合使用）

在AndroidManifest.xml添加如下内容：

<intent-filter>

</intent-filter>

<intent-filter>

</intent-filter>

</receiver>

3）完成以上集成后，您还需要在TalkingData平台中配置推送相关的Key；请进入平台“推送营销”-“推送配置”在android平台配置中添加好这些配置。

4）在TalkingData平台中选用三方平台进行实际推送测试。

五、使用易认证功能

1、易认证简介

易认证提供稳定的手机短信认证服务，简易集成，即可获得从认证码下发到安全验证的全部能力。

    这些场景下您可选择使用易认证功能，我们提供多达10000条/日免费认证短信量：
    A、服务型的App，要求用户使用手机号来注册的情况
    B、任何的App，可建议用户做手机号绑定，加强联络用户的能力
    C、提供忘记密码功能，利用短信验证来作为临时登录方式

2、易认证功能开通

您需要首先在统计分析平台中创建好一款产品（或是以前已在使用统计的产品），找到易认证功能标签，点击立即开通，即可为这款产品开通易认证功能，如图：

在功能成功开通后，您会获得集成所必需的标识码，如图：

• app ID : 与统计分析的app ID相同，用来唯一标识您的该款App；

• secret ID：客户端集成时需要传入的安全码，用于避免他人仿冒您的身份来发送短信

• server security：我们提供了最高安全级别的服务器端校验短信认证结果的方式，此标

识码用于服务器方式的身份安全验证

3、集成调用方法

易认证功能无需额外的SDK，使用统计分析V2.1及以上版本SDK可直接集成。

3.1、易认证初始化

启用易认证功能，您需要主动调用易认证初始化方法，这与统计分析初始化不同，需要单独调用。

• 在Application的onCreate里调用]init方法传入App ID和 Secret ID。

• public static void init(Context context, String appId, String secretId);

示例：

public class MainApplication extends Application {

@Override

public void onCreate() {

TalkingDataSMS.init(this,

"App ID",

"Secret ID");

}

3.2、发送短信认证码调用方法

从您的应用向我们的SDK发起请求，申请发送一条认证码短信。成功受理的发送请求，SDK会通知服务器，经由运营商通道直至短信下发。请注意以下限制，对单个App：

• 每个手机号，60S内不可多次请求短信

• 每个手机号，10分钟内最多请求3条认证短信

• 每个手机号，24小时内最多请求5条认证短信

• 每个设备，24小时内最多请求5条认证短信

接口说明：

// 申请认证码

public static final void applyAuthCode(String countryCode,

String mobile, TalkingDataSMSApplyCallback callback) ;

// 重新申请认证码

public static final void reapplyAuthCode(String countryCode,

String mobile, String requestId, TalkingDataSMSApplyCallback callback);

参数说明：

参数

类型

描述

countyrCode（国家码）

String

手机号的国家码，使用全球通用的国家码，不带+号，目前只支持中国大陆。
通常国家码都会在您的客户端中要求用户手动选择。
示例：86

mobile（手机号码）

String

用户的手机号码，中国为11位的手机号码。
通常此项在您的客户端中要求用户手动填写。

requestId

String

仅reapplyAuthCode接口需要填写。
requestId是每次调用发送短信接口后，SDK返回给您的当次请求的识别号。
requestId用于处理用户没有收到认证码短信时，要求进行重发问题。
在携带了requestId参数时，系统会找到之前的相同认证码再发送一次短信；不带此参数系统会发送全新的认证码

callback

TalkingDataSMSApplyCallback

申请认证码回调接口，成功时调用：
public void onApplySucc(String requestId);
失败时调用：
public void onApplyFailed(int errorCode, String errorMessage);

3.3、认证码校验调用方法

从您的应用向我们的SDK发起校验请求，我们会快速验证手机号与认证码是否匹配，并将结果返回给您的应用。

认证码的有效期为30分钟，如果超过了验证时间还没有成功验证，将会失效。

接口说明：

// 在用户填写好认证码后向SDK请求

public static final void verifyAuthCode(String countryCode,

String mobile, String authCode, TalkingDataSMSVerifyCallback callback)

参数说明：

参数

类型

描述

国家码

String

用户选择的国家码

手机号码

String

用户填写的手机号

认证码

String

用户填写的短信认证码

callback

TalkingDataSMSVerifyCallback

验证认证码回调接口，成功时调用：
public void onVerifySucc(String requestId);
失败时调用：
public void onVerifyFailed(int errorCode, String errorMessage);

3.4、requestId特别说明

您在进行集成时应该会注意到，我们的每次成功请求和成功验证时，都会返回一个requestId，这个Id有很多妙用值得您的注意。

在请求发送短信认证码时，携带requestId能很好的处理“重发”的问题，重发状况下用户不会收到多条不一样的认证码，就不会出现校验时不知道该填写哪条认证码的苦恼。

校验成功时，我们返回requestId，用于帮助您区分一个手机号上同时并发的多次短信验证。这样多种不同安全级别的场景下的短信认证都可以同时进行，切不会搞乱，而引发安全问题。

3.5、接口返回码

返回码

描述

451

SECERT_CHECK_FAIL

452

EXCEED_PHONE_APP_DAY_QUOTA

453

APP_KEY_CHECK_FAIL

455

ALREADY_LOCKED

456

LACK_REQUST_PARAM

457

APPLY_TOO_FREQUENTLY

458

EXCEED_DEVICE_APP_DAY_QUOTA

459

EXCEED_PHONE_DAY_QUOTA

460

VERIFY_FAIL_NOT_AMTCH

461

VERIFY_FAIL_EXPIRED

462

VERIFY_FAIL_USED

463

BEEN_LOCKED

471

REGTISTER_JSON_INVALID

472

DUPLICATE_REGISTER_OR_ADD

473

SERVER_ERROR_IN_REGISTER

474

INVALID_DOMAIN

475

INVALID_APPKEY

480

EXCEED_DEVICE_DAY_QUOTA

481

EXCEED_APP_DAY_QUOTA

482

EXCEED_PHONE_SP_VISIT_FREQUENCY_LIMIT

483

EXCEED_DEVELOPER_DAY_QUOTA

484

INVALID_QUERY_PARAM

485

NO_QUERY_RESULT

486

INVALID_PHONE_NUM

487

EXCEED_QUOTA

551

SP_SERVER_FAIL

552

DECOMPRESS_HTTP_BODY_FAIL

553

NO_SUCH_RECORD

554

CHECK_CRC_FAIL

557

SERVER_STORAGE_ERROR

558

JSON_PARSE_ERROR

559

SERVER_IO_FAIL

560

SERVER_GEN_DECRET_FAIL

561

CHECK_QUOTA_BUILD_KEY_FAIL

570

NO_MONTH_DB

601

申请认证码需要间隔60s

602

验证请求过于频繁，请稍后再试

604

SDK内部错误

605

接口传入参数错误

其他

请参照NSURLError

五、重点问题解答

问题1：如何确定我的集成是正确的？

解答：集成后请进行必要的真机测试，登录统计后台查阅数据，数据已有体现后才说明集成正确。测试中请务必注意：

确保AndroidManifest.xml里的参数和必要的权限已正确添加，检查INTERNET, ACCESS_NETWORK_STATE, READ_PHONE_STATE，WIFI这些权限已添加；

确保App ID添加正确，没有输入多余的空格等难发现的字符；

确保每个Activity中的对onResume和onPause方法进行了正确调用；

测试渠道包数据，确保Channel ID添加正确，并确认该设备没有被计入其他的渠道中。

应用安装于设备后需要打开应用才可记录数据，测试过程确保您的设备网络连接正常。

通过检查logcat里输出的TAG为TalkingData的日志信息可帮助判定问题：

TalkingData Analytics SDK会在初始化时会输出类似下边的日志，其中会显示SDK检测到的APP_ID和CHANNEL_ID：
例如：

03-15 16:17:56.236 I/TDLog ( 1784): TD_APP_ID in AndroidManifest.xml is:400ea56751ad479e81dxxxxxx.

03-15 16:17:56.236 I/ TDLog ( 1784): TD_CHANNEL_ID in AndroidManifest.xml is:gfan.

当SDK成功向服务器传输数据时，会有类似下边的日志输出：
例如：

03-15 16:19:06.721 D/ TDLog ( 1784): Post data to server...

03-15 16:19:09.643 D/ TDLog ( 1784): server return success:true

03-15 16:19:09.643 D/ TDLog ( 1784): Send Success, Clear Data

问题2：如何避免混淆对统计SDK的影响？

解答：有些开发者对打了统计SDK的程序进行混淆时，有可能会覆盖某些java类，导致统计SDK无法正常工作，解决方法如下：

请开发者在混淆配置文件proguard.cfg或proguard-project.txt的最后加上-keep public class com.tendcloud.tenddata.** { public protected *;}使得混淆的时候不会影响统计SDK的命名空间。

问题3：打入数据SDK的应用，混淆后导出APK时报Warning而导出失败？

解答：有一些字段或API引用只支持Android 2.3或以上版本的类库，就会导致引用Android较低的版本在导出apk时发生Warning的错误，解决方法如下：

请开发者在混淆配置文件proguard.cfg或proguard-project.txt的最上方加上-dontwarn com.tendcloud.tenddata.**。

问题4：打入SDK的应用，运行时会在Logcat里有Tag为TDLog的日志，如何关闭？

解答：这些日志是用于帮助应用开发者检查是否正确集成了TalkingData的SDK。如果应用开发者希望关掉这些日志，可以在应用启动的时候（并且在SDK初始化之前），将日志开关设为false：

TCAgent.LOG_ON = false;

0 0