SDK 接入概要

初始化接口

void init ( ... );

事件接口调用结构

						
onStart // 应用启动
    onSubStart // 关卡或页面的开始
        // 关卡中发生的事件
        onBuy, onUse, onEvent … 等事件接口
        onPassFail 关卡成功或失败
    onSubEnd // 关卡或页面的结束
    
    // 关卡外发生的事件
onEnd // 应用退出，Back按键强制退出调用onExit
					

获取 APPKEY

1，登录 天梯游戏统计 后台，进入我的应用界面，在应用汇总窗口点击 “创建新应用”。如图：

2，输入应用的相关信息后，点击 “提交应用”，即可。如图：

3，得到唯一的 APPKEY，接入 SDK 时使用。如图：

Android SDK 导入

下载 SDK 压缩包后解压至本地目录，需要将 logger/sdk/libs/android 目录下的 applogger.jar，applogger.so 和 AppLogger.h 添加到应用工程中。

1，开发环境配置

Android Studio 导入

(1) 将 applogger.jar 和包含 .so 文件的目录(armeabi, armeabi-v7a, x86, ...)复制到工程的 libs 目录下，复制目录时，只选择当前工程所支持的架构。

(2) 在 Module 的 buid.gradle 文件中添加 .so 库目录配置：

						
android {
    sourceSets {
    	main.jniLibs.srcDirs = ['libs']
    }
}
					

Eclipse 导入

(1) applogger.jar 的导入

1.1) 将 logger/sdk/libs/android 目录下的 applogger.jar 复制到工程根目录的 libs 文件夹中（若没有 libs 目录，则选中工程右键“New” -> Folder -> 命名为 “libs”）。

1.2) 右键单击工程，选择 Build Path 中的 Configure Build Path...，选中Libraries，并通过 Add Jars... 导入工程 libs 目录下的 applogger.jar 文件（最新的 ADT工具会自动导入 libs 目录下的 jar 包，故该步骤可以省略）。

(2) applogger.so 的导入

纯 Java 的 Android 项目，将 libs/android 目录下的所有子目录 (armeabi, armeabi-v7a, x86, ...) 复制到工程目录下的 libs 目录中。复制目录时，只选择当前工程所支持的架构。

2，编译配置

(1) 在 Android 工程加载自己项目 .so 的地方，添加对 liblogger.so 的引用。注意，liblogger.so 的加载顺序，需要在自己的 .so 之前：

						
static {
    System.loadLibrary("logger"); //liblogger.so的加载，在demo lib前面
    System.loadLibrary("your_app_lib"); //demo lib
}
					

(2) 如果使用 AppLogger 的 C++ 接口，需修改 Android.mk 文件

						
LOCAL_PATH := $(call my-dir)
#——— 开始添加,加载 liblogger.so ———
include $(CLEAR_VARS)
LOCAL_MODULE:=liblogger

#如果使用 Android Studio 环境
LOCAL_SRC_FILES:=$(TARGET_ARCH_ABI)/liblogger.so

#如果使用 NDK 环境
#LOCAL_SRC_FILES:=../logger/sdk/libs/android/$(TARGET_ARCH_ABI)/liblogger.so
include $(PREBUILT_SHARED_LIBRARY)
#——— 结束添加 ———

include $(CLEAR_VARS)
LOCAL_MODULE := your_app_lib
……
LOCAL_SRC_FILES := xxx.cpp
LOCAL_C_INCLUDES := $(LOCAL_PATH)/../xxx

#——— 开始添加,引入 Applogger.h 路径 ———
LOCAL_C_INCLUDES += $(LOCAL_PATH)/../logger/sdk
#——— 结束添加 ———
……

#——— 开始添加,引用 liblogger.so ———
#放在 BUILD_SHARED_LIBRARY 前
LOCAL_SHARED_LIBRARIES := liblogger
#——— 结束添加 ———
					

3，AndroidManifest.xml 配置

Android 应用的可以通过 AndroidManifest.xml 修改一些参数定义。包括应用ID与渠道定义，以及 SDK 基本权限定义。

(1) Meta-Data

						
<meta-data android:name="TT_APPID" android:value="XXXXXXXXXXXXXXXX" />
<meta-data android:name="TT_CHANNEL" android:value="渠道名称" />
					

(2) 权限

						
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
					

Android SDK 初始化

定义

void init (Context context, String appId, String appChannel);

Android 下通常在 第一个 Activity 的 onCreate() 中调用初始化接口:

import com.tianti.AppLogger;

public class MainActivity extends Activity {
    ...
    
    @Override
    public void onCreate(Bundle savedInstanceState) {
    	...
    	AppLogger.init(this, appId, appChannel);
    	...
    }
    ...
}
					

功能

初始化数据统计服务

用法

appId 和 appChannel 通常在 AndroidManifest.xml 中指定，特殊情况下也可以直接通过 init 接口指定。init 接口优先于 AndroidManifest.xml 中的定义。

						
<manifest …… >
……
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

<application …… >
……
<meta-data android:name="TT_APPID" android:value="XXXXXXXXXXXXXXXX" />
<meta-data android:name="TT_CHANNEL" android:value="渠道名称" />
</application>
</manifest>
					

基本事件

启动应用 onStart

定义

void onStart ();

功能

应用启动事件

用法

用于当应用启动或从后台切换到前台时

通常在 Activity::onResume 事件中调用

通过 onStart 接口可以获得应用的 新增，活跃，启动，安装，升级 等等各种基本数据。如图：

退出应用 onEnd

定义

void onEnd ();

功能

应用退出事件

用法

用于当应用退出或退到后台时

通常在 Activity::onPause 事件中调用

通过 onEnd 接口，可以统计应用的使用时长等各种数据。如图：

彻底退出应用 onExit

定义

void onExit ();

功能

彻底退出应用的事件

用法

Back 按键退出应用(System.exit, Process.Kill)，用 onExit 强制声明退出整个应用。

关卡与页面

关卡或页面开始 onSubStart

定义

void onSubStart (const char* name);

功能

进入一个关卡或页面

用法

在进入一个关卡或页面时，调用 onSubStart 接口

onSubStart 事件接口可以帮助统计系统获得关卡 新增用户，活跃用户，启动次数，进入次数，离开次数，滞留人数，最大关卡，最后关卡 等各种指标数据。如图：

关卡或页面结束 onSubEnd

定义

void onSubEnd (const char* name);

功能

退出指定关卡或页面

用法

在退出一个关卡或页面时，调用 onSubEnd 接口

关卡过关或失败 onPassFail

定义

void onPassFail (bool bPass);

功能

过关或失败

用法

关卡过关或失败时，立即调用 onPassFail 接口

关卡与页面子事件

所有子事件缺省都算在最后关卡中（STAGE_LAST）

如果需要把子事件计算到特定关卡或页面，请指定子事件中的 stage 参数

现金购买 onBuy

定义

void onBuy (const char* payService, const char* item, int count, float value, const char* stage = STAGE_LAST);

功能

现金购买虚拟币， onBuy 事件接口提交的数据，将作为收入数据，在后端报表中用各种收入图表展现。

用法

当用现金进行购买时，请调用 onBuy 事件接口

onBuy 事件缺省统计到最后关卡中，所以你可以看到各个关卡的各种与收入相关的数据，如，收入，新增付费用户，活跃付费用户，当天购买用户

虚拟货币交易 onExchange

定义

void onExchange (const char* item, int count, const char* stage = STAGE_LAST);

功能

虚拟币兑换为道具

用法

数据分析人员可以观察到各个关卡的兑换次数，兑换项目等详细数据，以及各个数据的分布状况

道具使用 onUse

定义

void onUse (const char* item, int count, const char* stage = STAGE_LAST);

功能

使用道具或点数

收集 onCollect

定义

void onCollect (const char* item, int count, const char* stage = STAGE_LAST);

功能

收集点数/道具

奖励 onReward

定义

void onReward (const char* item, int count, const char* stage = STAGE_LAST);

功能

奖励虚拟币或道具

用法

发生奖励行为时，立即调用 onReward 接口

分享 onShare

定义

void onShare (const char* service, const char* item, const char* stage = STAGE_LAST);

功能

分享到社交服务上

用法

当用户进行分享操作时，立即调用 onShare 事件接口

产出与消耗(游戏平衡) onBalance

定义

void onBalance (const char* name, const char* item, int value, const char* stage = STAGE_LAST);

功能

游戏内虚拟货币的产出与消耗数据分析，通过产出与消耗可以观察游戏平衡情况。

用法

name 用 +,- 符号前缀，声明是产出或消耗。

玩家分享奖励： onBalance ("+宝石", "奖励", 100);

玩家购买时装： onBalance ("-宝石", "时装A", 200);

升级事件(玩家/角色/宠物) onLevelUp

定义

void onLevelUp (const char* name, const char* oldLevel, const char* newLevel, const char* stage = STAGE_LAST);

功能

玩家/角色/宠物的等级变化事件，统计玩家等级分布

用法

级别(oldLevel, newLevel)建议用版本号形式

自定义事件 onEvent

定义

void onEvent (const char* name, const char* stage = STAGE_LAST);

功能

用户自定义事件

用法

自定义事件将以列表形式罗列出来，并显示最近几天的自定义事件变化

自定义事件可以是一个简单的名称，例如 dm_show，也可以是包含 / 的多级名称，例如 main/dm_show, main/dm_close, …

对于 main/dm_show 形式的事件，在统计报表中将把所有 main/ 开头的时间一起对比显示。

所以如果想对比观察一组事件，可以给这些事件一个一样的分组名称作为前缀，并用 / 分隔。

事件列表：

相同前缀的事件之间对比：

在线参数

启用在线参数

定义

void enableOnlineConfig ();

功能

启用在线参数同步功能，缺省不启用在线参数功能

用法

在 init 接口后调用 enableOnlineConfig

获取在线参数

定义

string getOnlineConfig (string key, string defaultValue="");

功能

获得某个在线参数的具体数据，如果没有指定，返回 defaultValue

用法

先调用 enableOnlineConfig，然后可以任意多次调用 getOnlineConfig

存量数据统计

清除存量数据

定义

void clearStatus();

功能

清除所有存量数据

设置存量数据

定义

void setStatus(const char* key, int value, bool bAutoConvert = true);

功能

设置存量数据，服务器端将对存量数据自动分区间统计，或根据指定的区间统计

例如：玩家当前有多少宝石，用了多少宝石，收集了多少宝石等等这类长期累积的数据可以通过 setStatus 的接口统计。

用法

通常在 init 之后尽快调用 setStatus 接口，把客户端的累计存量数据汇报给服务器

存量数据每天第一次启动的时候提交到服务器

开发者

启用错误统计

定义

void enableCrashReport();

功能

启用错误统计，捕捉应用中发生崩溃时的堆栈信息，用于定位程序中引起错误的代码，缺省为不启用崩溃统计

用法

在 init 接口之后调用 enableCrashReport

日志输出设置

定义

void setDebugLog (int mode, int level);

功能

调试信息输出控制

用法

mode 与 level 具体定义：

							
#define DEBUG_OFF       0    //不输出调试信息
#define DEBUG_LOGCAT    1    //输出到 logcat(用于联机调试)
#define DEBUG_LOGFILE   2    //输出到 文件（applogger.log）, 用于脱机调试
#define DEBUG_LOGALL    3    //输出到 logcat 和 文件（applogger.log）

#define DEBUG_LEVEL_VERBOSE    0    //输出所有级别调试信息
#define DEBUG_LEVEL_INFO       1    //输出INFO级别以上调试信息
#define DEBUG_LEVEL_WARN       2    //输出WARN级别以上调试信息
#define DEBUG_LEVEL_ERROR      3    //输出ERROR级别以上调试信息
					

其他

启动间隔控制参数

定义

void setSessionInterval (int v);

功能

设置合并间隔，当上次退出时间与本次启动时间间隔小于该参数所指定的值时，合并上次与本次启动

联网控制

定义

void setOnline (bool online);

功能

一般仅用于小范围测试时（如，玩家输入邀请码才能进入游戏）。邀请码验证通过后，才算正常初始化 SDK

玩家/用户参数

定义

void setUser (const char* level, int age = -1, const char* gender = NULL, const char* userId = NULL, const char* userService = NULL);

功能

设置用户信息，包括用户级别，年龄，性别, …

						
onStart // 应用启动
    onSubStart // 关卡或页面的开始
        // 关卡中发生的事件
        onBuy, onUse, onEvent … 等事件接口
        onPassFail 关卡成功或失败
    onSubEnd // 关卡或页面的结束
    
    // 关卡外发生的事件
onEnd // 应用退出，Back按键强制退出调用onExit