Android API 接口说明

接口概览

类名	说明
StatService	提供MTA标准接口
StatConfig	统计配置类，可设置sdk常用的选项

StatService 类

提供MTA标准接口

初始化并启动 MTA

作用：启动MTA线程，加载数据库配置信息，初始化环境，同时还对多版本SDK进行冲突检测

调用位置: 1、对于普通app：AndroidManifest.xml指定首先启动的activity的onCreate()处，StatConfig类的方法之后 2、对于lib工程，在其它所有StatService方法被调用之前

[原型]

public static boolean StatService.startStatService(Context ctx, String appkey, String mtaSdkVersion)

[参数]

参数	说明
ctx	页面的设备上下文
appkey	MTA提供的appkey
requiredMtaVer	当前app依赖的MTA SDK版本号，只能为com.tencent.stat.common.StatConstants.VERSION，用于SDK版本冲突检测
MtaSDkException	异常：启动失败时会抛出MtaSDkException异常，可能是参数出错，也可能是SDK版本冲突，具体的冲突解决办法见 注意事项中的“SDK冲突问题”。同时，MTA会自动禁止所有功能

[示例]

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_mtamain);
    // androidManifest.xml指定本activity最先启动
    // 因此，MTA的初始化工作需要在本onCreate中进行
    // 在startStatService之前调用StatConfig配置类接口，使得MTA配置及时生
    String appkey = "amtaandroid0";
    // 初始化并启动MTA
    try {
        // 第三个参数必须为：com.tencent.stat.common.StatConstants.VERSION    
        StatService.startStatService(this, appkey,
        com.tencent.stat.common.StatConstants.VERSION);
        Log.d("MTA","MTA初始化成功")
    } catch (MtaSDkException e) {
        // MTA初始化失败
        Log.d("MTA","MTA初始化失败"+e)
    }
}

【次数统计】Key-Value参数的事件

[原型]

public static void StatService.trackCustomKVEvent(Context ctx, String event_id, Properties properties)

[参数]

参数	说明
ctx	页面的设备上下文，不能为null
event_id	自定义事件的id，不能为null或" "
properties	String类型的key-Value对

[示例]

public void onOKBtnClick(View v) {
    // 统计按钮被点击次数，统计对象：OK按钮
    Properties prop = new Properties();
    prop.setProperty("name", "OK ");
    StatService.trackCustomKVEvent(this, "button_click", prop);
}
public void onBackBtnClick(View v) {
    // 统计按钮被点击次数，统计对象：back按钮
    Properties prop = new Properties();
    prop.setProperty("name", "back ");
    StatService.trackCustomKVEvent(this, "button_click", prop);
}

【时长统计】Key-Value参数事件

可以指定事件的开始和结束时间，来上报一个带有统计时长的事件。 [原型]

public static void trackCustomBeginKVEvent(Context ctx, String event_id, Properties properties)
public static void trackCustomEndKVEvent(Context ctx, String event_id, Properties properties)

[参数]

参数	说明
ctx	设备上下文，不能为null
event_id	自定义事件的id，不能为null或" "
properties	String类型的key-Value对

[示例]

public void onClick(View v) {
    Properties prop = new Properties();
    prop.setProperty("level", "5");
    // 统计用户通关所花时长，关卡等级： 5
    // 用户通关前
    StatService.trackCustomBeginKVEvent(this, "playTime", prop);
    // 用户正在游戏中….
    // …….
    // 用户通关完成时
    StatService.trackCustomEndKVEvent(this, "playTime", prop);
}

【时长统计】带有统计时长的自定义参数事件

可以指定事件的开始和结束时间，来上报一个带有统计时长的事件 [原型]

public static void trackCustomBeginEvent(Context ctx, String event_id,String... args)
public static void trackCustomEndEvent(Context ctx, String event_id,String... args)

[参数]

参数	说明
ctx	设备上下文，不能为null
event_id	自定义事件的id，不能为null或" "
args	自定义事件的参数

[示例]

public void onClick(View v) {
    // 统计用户通关所花时长
    // 用户通关前
    StatService.trackCustomBeginEvent(this, "playTime", "level5");
    // 用户正在游戏中….
    // …….
    // 用户通关完成时
    StatService.trackCustomEndEvent(this, "playTime", "level5");

注意：trackCustomBeginEvent和trackCustomEndKvent必须成对出现，且参数列表完全相同，才能正常上报事件。

页面统计

统计某个页面的访问情况

[原型]

public static void onPause(Context ctx)
public static void onResume(Context ctx)

或者

public static void trackBeginPage(Context ctx, String pageName)
public static void trackEndPage(Context ctx, String pageName)

记录用户进入activity时间， 需要同时在onPause中调用 onPause(Context) 才能统计用户访问activity时长。 开发者可以在其activity类中通过继承

[参数]

参数	说明
ctx	页面的设备上下文
pageName	自定义页面名称，需跟trackEndPage 一一匹配使用

[示例]

@Override
protected void onResume() {
    super.onResume();
    StatService.onResume(this);
}
···
···
@Override
protected void onPause() {
    super.onPause();
    StatService.onPause(this);
}

注意：

• onResume和onPause或trackBeginPage和trackEndPage需要成对使用才能正常统计activity，为了统计准确性，建议在每个activity中都调用以上接口，否则可能会导致MTA上报过多的启动次数

• 如果使用3.0.0以上版本，默认通过监控Activity生命周期采集页面时长，无需额外添加代码，若低于此版本建议升级至最新版

账号统计

[原型]

     /**
     * 上报单个账号，通常用于登陆/刷票登陆/第三方登陆等时机调用
     * @param context 上下文
     * @param account 待上报的账号
     */
    public static void reportMultiAccount(Context context, final StatMultiAccount account);

    /**
     * 上报多个账号，适用于App内部已经绑定了多个账号的情况下使用
     * @param context 上下文
     * @param accountList 待上报的账号列表
     */
    public static void reportMultiAccount(Context context, final List<StatMultiAccount> accountList);   

    /**
     * 获取SDK内部账号列表
     * @return 账号列表
     */
    public static Map<StatMultiAccount.AccountType, StatMultiAccount> getMultiAccount();

    /**
     * 根据账号类型删除某个账号，通常用于注销时调用
     * @param context   上下文
     * @param accountType   待删除的账号类型
     */
    public static void removeMultiAccount(Context context, StatMultiAccount.AccountType accountType);

[示例]

    // 登陆时调用
    StatMultiAccount account = new StatMultiAccount(
            StatMultiAccount.AccountType.PHONE_NO, "1380000000");
    long time = System.currentTimeMillis() / 1000;
    // 登陆时间，单秒为秒
    account.setLastTimeSec(time);
    // 过期时间
    account.setExpireTimeSec(time + 24 * 60);
    StatService.reportMultiAccount(context, account);

    // 注销时调用
    StatService.removeMultiAccount(context, StatMultiAccount.AccountType.PHONE_NO);

会话统计

会话统计用于统计启动次数，由SDK本身维护，通常开发者无需额外设置或调用接口。

如有需要可以调用以下接口，也会视为用户打开一次新的会话：

[原型]

public static void startNewSession(Context ctx)

[参数]

参数	说明
ctx	页面的设备上下文

其他接口

将本地缓存的消息发送至服务器

[原型]

public static void commitEvents(Context ctx,int maxNumber)

[参数]

参数	说明
ctx	设备上下文，不能为null
maxNumber	消息上报的最大个数。若为-1，则上报所有缓存在本地的消息，若为为N且N>0，则上报至多N条信息

StatConfig 类

统计配置类，可设置sdk常用的选项 注意：此类中的方法通常需要在StatService类所有的方法前调用，例如app的onCreate方法

APP设置接口

1. 会话时长（默认30000ms，30000ms回到应用的用户视为同一次会话）

void StatConfig.setSessionTimoutMillis(int sessionTimoutMillis)

2. 消息失败重发次数（默认3）

void StatConfig.setMaxSendRetryCount(int maxSendRetryCount)

3. 用户自定义时间类型事件的最大并行数量（默认1024）

void StatConfig.setMaxParallelTimmingEvents(int max)

4. 设置安装渠道

void StatConfig.setInstallChannel(String installChannel)

5. 设置app key

void StatConfig.setAppKey(Context ctx, String appkey)

6. 设置统计功能开关（默认为true）

void StatConfig.setEnableStatService(boolean enableStatService)

如果为false，则关闭统计功能，不会缓存或上报任何信息。

7. 设置session内产生的消息数量（默认为0，即无限制）

void StatConfig.setMaxSessionStatReportCount(int maxSessionStatReportCount)

如果为0，则不限制；若大于0，每个session内产生的消息数量不会超过此值，若超过了，新产生的消息将会被丢弃。

8. 设置每天/每个进程时间产生的会话数量（默认为20）

为防止开发者调用MTA不合理导致上报大量的会话数量（sesion），SDK默认每天/每个进程时间内最多产生的会话数量，当达到此值时，SDK不再产生并上报新的会话。当进程重启或跨天时，会被清0。

void StatConfig.setMaxDaySessionNumbers (int maxDaySessionNumbers)

9. 设置单个事件最大长度（默认为4k，单位：bytes）

为防止上报事件长度过大导致用户流量增加，SDK默认不上报超过4k的单个事件；对于错误异常堆栈事件，异常堆栈长度不超过100（可以超过4k）。

void StatConfig.setMaxReportEventLength (int maxReportEventLength)

10. 支持多进程（默认为false） SDK默认支持多线程并发，但对于多进程并发，需要开启本配置，否则可能会出现数据库读写异常。

void StatConfig.setEnableConcurrentProcess(boolean enableConcurrentProcess)

数据上报相关的设置接口

1. 设置最大缓存未发送消息个数（默认1024）

void StatConfig.setMaxStoreEventCount(int maxStoreEventCount)

缓存消息的数量超过阈值时，最早的消息会被丢弃。

2.（仅在发送策略为BATCH时有效）设置最大批量发送消息个数（默认30）

void StatConfig.setMaxBatchReportCount(int maxBatchReportCount)

3.（仅在发送策略为PERIOD时有效）设置间隔时间（默认为24* 60，即1天）

void StatConfig.setSendPeriodMinutes(int minutes)

4. 开启SDK LogCat开关（默认false）

void StatConfig.setDebugEnable(boolean debugEnable)

（注意：在发布产品时，请将此开关设为false）

5. 智能选择发送策略功能：如果是WIFI网络，自动切换至实时发送（不会覆盖原有的发送策略），否则，保持原有的策略。 注意：由于每次发送消息都要检查网络状态，用户交互极其频繁的应用（如水果忍者）需慎重使用。

public static void setEnableSmartReporting(boolean isEnable)

在线参数

[原型]

String StatConfig.getCustomProperty(String key, String defaultValue)

[参数]

key: 用户在前台配置的key

[返回值]

对应key的value值，若不存在则返回defaultValue

protected void someAction() { 
    // 获取在线参数onlineKey
    String onlineValue = StatConfig.getCustomProperty("onlineKey", "off" );
    if(onlineValue.equalsIgnoreCase("on")){
        // do something
    }else{
        // do something else
    }