功能说明

此部分内容将介绍2.0各部分功能，如果APP中已经嵌码了1.x的某个版本，则通过阅读此部分内容会更快的了解如何从1.x的版本迁移到2.0版本。

集成方式

2.0的集成方式，与1.5.5之后的版本一致。我们仍将SDK发布到JCenter中去，APP仍然只需要在

app/build.gradle文件的dependencies域中配置网脉Android SDK的依赖。

compile 'com.trs:trs_ta_sdk:2.0.0'

与1.x的兼容性说明

目镜2.0计划尽可能兼容1.x的接口，但是为了达到2.0使用简洁易用的目的，兼容工作就变得异常艰难，所以对于已经废弃的接口和有较大调整的接口我们不在进行兼容。

  • 包名调整，1.5.x的包名为com.trs.tasdk.main，2.0简化为com.trs.ta
  • 初始化接口，2.0中不在包含1.x的初始化接口，2.0会引入一套全新的初始化接口。
  • 行为事件记录功能。兼容目前《浙江新闻》APP正在使用的事件记录接口，去掉了1.4之前已经废弃的事件记录接口。

SDK初始化

针对1.x的初始化接口在实际使用过程中存在的问题，2.0我们加入了两个新的初始化接口。

public static void init(Context context, TAConfigure config);
public static void init(Context context);

在Application中初始化

public class App extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        TAConfigure taConfigure = new TAConfigure.Builder("YOUR_URL", "YOUR_APPKEY", mpID)
                .debugable(true)
                .maximumCachedBeforeSend(40)
                .build();
        TAController.init(this, taConfigure);
    }
}

配合AndroidManifest文件使用

2.0可以在AndroidManifest.xml文件中通过meta-data定义以下信息：

<manifest……>
<uses-permission android:name="android.permission.INTERNET"></uses-permission>
<application ……>
……
<!--服务端地址，必需-->
<meta-data android:value="YOUR_URL" android:name="TA_URL"/>

<!--appKey，必需--> 
<meta-data android:value="YOUR_APP_KEY" android:name="TA_APPKEY"/> 

<!--mpId，必需--> 
<meta-data android:value="YOUR_MPID" android:name="TA_MPID"/> 

<!--渠道，选传-->
<meta-data android:value="CHANNEL_NAME" android:name="TA_CHANNEL"/> 
<!--debug状态,true or fasle，选传-->
<meta-data android:value="false" android:name="TA_DEBUG"/> 

</application>    
</manifest>

在Appplication中调用如下代码：

public class App extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        TAController.init(this);
    }
}

有时你不仅希望在Manifest文件中定义必要的参数外，还希望能通过TAConfigure来配置其他的参数，则可以通过如下方式进行初始化：

public class App extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        //Builer(Context) 会自动读取Manifest文件中定义的参数
        TAConfigure taConfigure = new TAConfigure.Builder(this)
                .debugable(true)
                .maximumCachedBeforeSend(20)
                .build();
        TAController.init(this, taConfigure);

    }
}

需要注意的是：SDK初始化工作仍然需要APP在Application中的onCreate()中完成。新的初始化接口对比1.x内部将会有一个大的优化调整，比如将某些耗时操作移动到子线程中，部分数据实现懒加载，我们尽可能的不影响APP的启动时间。

获取或调整运行时的配置参数

APP可以调用getCurrentConfigure()来获取当前SDK运行的参数配置。

APP可以调用applyConfigure()来调整当前SDK运行的参数配置。

例如某些情况下，APP希望根据用户访问量动态调整SDK的maximumCachedBeforeSend的大小，则可以通过如下代码实现

TAConfigure taConfigure = TAController.getCurrentConfigure();
if (taConfigure.debugable()) {
    taConfigure = new TAConfigure.Builder(taConfigure)
            .maximumCachedBeforeSend(2)
            .build();
    TAController.applyConfigure(taConfigure);

}

需要注意的是：maximumCachedBeforeSend越大代表数据的积留量就越大，数据延迟发送的可能就越高，对于用户行为数据实时分析要求高的APP，不建议设置太大的值。

渠道在初始化接口中设置后就不能再变动，后续的任何渠道更改都不会有变化。

发送自定义设备ID功能

如果APP有自定义的设备ID，则可以通过以下方式来设置自定义的设备ID。

1.在初始化接口中发送设备ID

APP在初始化SDK构建TAConfigure实例时，可以调用deviceId()方法来传入一个设备ID，SDK初始化接口内部在完成初始化工作后，如果发现传入的TAConfigure实例中的deviceId不为空，则会将此deviceId发送给服务端。这相当于APP在调用了初始化接口后紧接着调用了sendAppSelfDeviceID方法来发送deviceId。

如果APP的自定义设备ID生成规则比较耗时，为了不增加APP启动时间，建议在APP在子线程中生成设备ID，然后自行调用sendAppSelfDeviceId()来发送设备ID。

TAConfigure taConfig = new TAConfigure.Builder(TA_URL, APP_KEY, MP_ID)
                .deviceId(YOUR_DEVICE_ID) //设置自定义设备ID
                .build();
TAController.init(this, taConfig);

//等价于

TAConfigure taConfig = new TAConfigure.Builder(TA_URL, APP_KEY, MP_ID)
                .build();
TAController.init(this, taConfig);
TAController.sendAppSelfDeviceID(YOUR_DEVICE_ID);

2.调用sendAppSelfDeviceId()方法发送设备ID

在SDK初始化完成之后，APP可以自行调用sendAppSelfDeviceId()方法来设置自定义ID。

如果之前设置过自定义的设备ID，希望用新的设备ID去关联之前的设备ID，则sendAppSelfDeviceId(String, String)方法完成此目的。

系统事件采集功能

2.0继续沿用1.x的无嵌码系统事件采集的方式，SDK在完成初始化工作之后，就自动开始监测和采集APP的系统事件。

2.0的系统事件采集类型和监测标准也与1.5.5之后的版本没有区别。

SDK采集的APP的系统事件包含3种：

  • APP启动
  • APP挂起
  • APP恢复

其中，APP启动事件判断标准为：

  • APP完全退出后再启动。注意：这里的启动是指APP有可见页面(Activity)显示在屏幕上，才算启动，仅有后台运行不计入启动次数。
  • APP进入挂起状态超过30s后恢复到前台，也算一次启动。

APP完全退出后，推送SDK都有相互拉起功能，虽然手机中存在APP的进程，但是并没有一个可见的画面显示，此情况SDK是不会算做启动。

APP挂起事件判断标准为：

  • APP启动后，有用户可见变为不可见，比如Home键进入后台，锁屏，黑屏，被其他APP覆盖等。

APP恢复事件判断标准为：

  • APP进入挂起状态30s的时间内恢复至前台用户可见。

监听系统事件

在某些情况下，APP希望系统数据的事件更加准确，即希望重写系统事件的某些字段值，APP可以通过调用setApplicationEventListener(ApplicationEventListener)方法来注册一个系统事件的监听接口，一旦SDK收集到APP的系统事件，就会触发onEvent(Activity, TRSAppEvent)方法，APP可以TAEventInfo的某些字段值来达到目的。

常见的情形就是APP想要知道此次启动事件是否来源于通知打开的方式。

//根据Activity的启动Intent中的数据来自定义启动方式，仅供参考
TAController.setApplicationEventListener(new ApplicationEventListener() {
    @Override
    public TaAppEvent onEvent(Activity activity, TRSAppEvent event) {
        Intent intent = activity.getIntent();
        if (intent.getBooleanExtra("isFromNotification", false)) {
            event.setOpenFrom(AppLaunchMode.FROM_NOTIFICATION);
            return event;
        }
        return event;
    }
});

自定义APP启动方式更为简便的方法：可以直接在Activity的启动 Intent中添加自定义的TRSLaunchMode对象，SDK内部会将接下来的启动事件的启动方式更改为用户传入的TRSLaunchMode对象所代表的启动方式。

Intent intentLaunch = new Intent(this, MainActivity.class);
intentLaunch.putExtra(TRSLaunchMode.class.getSimpleName(), TRSLaunchMode.FROM_NOTIFICATION);
startActivity(intent);

设置位置信息功能

2.0仍使用setLocation(long, long)来设置位置信息，与1.x版本一致。

页面及事件记录功能

页面与事件记录功能是SDK的核心功能，2.0新增了IRecorder来进行页面以及事件的采集。

IRecorder包含了两种类型接口：

  • 事件记录接口，包含：记录自定义事件接口、记录用户账户事件接口。
  • 页面记录接口，记录页面时长及信息。

在APP初始化工作完成后，通过调用getRecorder()来获取一个IRecorder接口的实例。

记录自定义事件

/**
 * 记录事件
 * @param code 事件编码
 * @param params 事件信息
 */
void onEvent(String code, Map<String, Object> params);

根据3月27号的需求讨论，事件记录接口将参数传递形式由实体类调整为Map形式以达到APP开发者更灵活的增加自定义信息。

注意： onEvent(String, Map)需要在Activity/Fragment的onStart()与onStop()之间的生命周期时间内调用。

记录页面

1.x中利用一个特殊编码A0010来代表记录页面，2.0单独引入了一对接口来记录页面，接口定义与使用与友盟类似，利用这一对接口APP不仅可以记录Activity形式的页面，也可以记录Fragment形式的页面。需要注意的是SDK内部仍会将页面事件记录为A0010码，所以在其他自定义事件中避免使用A0010。

/**
 * 页面开始
 * @param page 页面名称
 */
void onPageStart(String page);

/**
 * 页面结束
 * @param page 页面名称
 * @param extras 页面信息。
 */
void onPageEnd(String page, Map<String, Object> extras);

强烈建议：onPageStart(String)在Activity/Fragment中的onResume()方法中调用。onPageEnd(String, Map)在Activity/Fragment中的onPause()中调用。

多维度剖析是网脉的重要功能，SDK采集的某一维度的数据与后台的交互都有约定的字段，这样网脉才能更快更好的从某一特定的维度对数据进行剖析，所以在调用onPageEnd(String, Map<String, Object)和onEvent(String, Map<String, Object>)时，对于Map<String, Object>传入的参数中的key有如下要求：

  • 实现某一维度的数据剖析时，如根据栏目ID进行剖析，必须使用保留的固定key。如下表格
  • 用户自定义的key避免与保留key重复，需要以x_开头，如x_username
key 说明 类型 举例
se_dur 事件时长 Long 10000（ms）
se_name 事件名称 String "点击首页"
se_ac 事件细节 String "点击新闻首页"
se_pt 页面名称（该字段对应的是记录页面方法中的page参数，调用的时候，方法中传入的参数会覆盖该字段） String "首页"
se_ot 对象类型 String固定值-“C01”（文章）；“C90“（栏目）；“C11”（图片）；“C21”（视频）；“C31”（活动）；“C41”（服务） "C01"
se_oid 对象ID，如媒立方ID String "1000"
se_osn 对象短名称，如稿件标题 String "19大隆重召开"
se_oids 对象IDs String "100,101, 102"
se_cid 对象分类ID，如栏目ID String "1000"
se_csn 对象分类名称，如栏目名称 String "时政"
se_sw 搜索词，对应搜索事件 String "19大"
se_oam 事件对象的某一数量指标，如文章字数 Integer 100
se_ono 序数，对象序数 Integer 1
se_pp 百分比，如阅读百分比 Double 0.20
se_su 做某个事件是否成功 Boolean true
se_soid 自有对象ID，如稿件ID String "1000"
se_aoid 从属对象ID String "1000"
se_ost 打开方式 Integer固定值-0（普通打开）；1（推动打开）；2（链接打开）；3（后台打开） 1
se_ilurl 外链稿url String "www.baidu.com"

记录用户账户事件

1.x SDK只能在初始化接口中传入一个用户ID，此后再不能调整用户信息，即使用户登出账户，针对此问题2.0增加了一个新的接口来专门记录用户的账户状态变更事件。

/**
 * 记录用户账号事件
 * @param event 用户账号事件类型，{@link TRSAccountEventType}
 * @param account 用户账号信息，{@link TRSUserAccount}
 */
void onEvent(TRSAccountEventType event, TRSUserAccount account);

用户账户事件包含：登录、登出、注册、更改，在TRSAccountEventType中枚举。

新增TRSUserAccount来装载用户的账户信息。

results matching ""

    No results matching ""