API功能

一、启动配置接口

启动配置类的接口通过链式调用方式随Bonree.withAppID(BONREE_APP_ID).start(this);一同配置,需要在调用start函数之前withAppID之后进行相关配置, 可同时配置多项, start函数后配置无效。

设置config地址

私有化部署用户启动时需要设置私有部署的config地址。

  • 接口说明
Bonree withConfigAddress(java.lang.String configAddress)
参数 说明 参数限制 失败结果
configAddress 私有云config地址 字符串长度大于0,小于等于2083,否则接口调用失败 探针停止
  • 示例
  Bonree.withAppID("c1f18f3a-ba47-408a-9f80-ea87b6c083dk")
        .withConfigAddress("http://192.168.106.24:6666/config")
        .start(getApplicationContext());

配置自定义业务头

配置原生网络请求中的关键Http Request Header的key, 当SDK采集到的实际请求数据中Request Header带有此key,对应的key和value将会被单独展示

Bonree withCustomBusinessHeaders(java.lang.String[]headers)
参数 说明 参数限制 失败结果
headers 要获取的请求头中自定义业务Header的key,可设置多个 数组元素为长度大于0,小于等于256的字符串且不包含特殊字符(仅支持字母数字下划线_连接符-冒号:),否则剔除
数组元素个数大于0,否则接口调用失败
数组元素个数小于等于64,超长截取
当次设置无效
  • 示例
  Bonree.withAppID("c1f18f3a-ba47-408a-9f80-ea87b6c083dk")
        .withCustomBusinessHeaders("User-Agent","Content-Type")
        .start(this);

设置自定义设备ID

通过此方法设置了自定义设备ID,那么SDK将会上报此ID,不再使用默认获取的ID.

Bonree withDeviceID(java.lang.String deviceID)
参数 说明 参数限制 失败结果
deviceID 自定义的设备Id 字符串长度大于0,小于等于256,且不包含特殊字符(仅支持字母数字下划线_连接符-),否则接口调用失败 当次设置无效
  • 示例
  Bonree.withAppID("c1f18f3a-ba47-408a-9f80-ea87b6c083dk")
        .withCustomBusinessHeaders("User-Agent","Content-Type")
        .withDeviceID("custom_device_id")
        .start(getApplicationContext());

设置自定义APP版本

通过此方法设置了自定义设备App版本号,那么SDK将会上报此版本号,不再使用默认获取的版本号.

Bonree withAppVersion(java.lang.String version)
参数 说明 参数限制 失败结果
version 自定义的版本号 字符串长度大于0,小于等于64,否则接口调用失败 当次设置无效
  • 示例
  Bonree.withAppID("c1f18f3a-ba47-408a-9f80-ea87b6c083dk")
        .withCustomBusinessHeaders("User-Agent","Content-Type")
        .withDeviceID("custom device id")
        .withAppVersion("custom app version")
        .start(getApplicationContext());

设置用户渠道ID

区分应用发布的渠道, 渠道信息会在平台的性能数据中做展示

Bonree withChannelID(java.lang.String channelID)
参数 说明 参数限制 失败结果
channelId 自定义的渠道号 符串长度大于0,小于等于256,否则接口调用失败 当次设置无效
  • 示例
  Bonree.withAppID("c1f18f3a-ba47-408a-9f80-ea87b6c083dk")
        .withCustomBusinessHeaders("User-Agent","Content-Type")
        .withDeviceID("custom device id")
        .withAppVersion("custom app version")
        .withChannelID("华为商城")
        .start(getApplicationContext());

多进程初始化sdk

是否在所有进程初始化SDK, 不设置默认关闭

Bonree withAllLaunch(boolean enabled)
参数 说明
enabled true 打开 false 关闭
  • 示例
  Bonree.withAppID("c1f18f3a-ba47-408a-9f80-ea87b6c083dk")
        .withCustomBusinessHeaders("User-Agent","Content-Type")
        .withDeviceID("custom device id")
        .withAppVersion("custom app version")
        .withChannelID("华为商城")
        .withAllLaunch(true)
        .start(getApplicationContext());

Android Box数据采集模式

是否按照Box模式采集ANR指标数据, 不设置默认关闭

 Bonree withAndroidBoxEnabled(boolean enabled)
参数 说明
enabled true 打开 false 关闭
  • 示例
  Bonree.withAppID("c1f18f3a-ba47-408a-9f80-ea87b6c083dk")
        .withCustomBusinessHeaders("User-Agent","Content-Type")
        .withDeviceID("custom device id")
        .withAppVersion("custom app version")
        .withChannelID("华为商城")
        .withAndroidBoxEnabled(true)
        .start(getApplicationContext());

设置同步初始化SDK

是否开启SDK的同步启动

Bonree withSyncStart(boolean isSync)
参数 说明
isSync true 同步启动 false 异步启动
  • 示例
  Bonree.withAppID("c1f18f3a-ba47-408a-9f80-ea87b6c083dk")
        .withSyncStart(true)
        .start(getApplicationContext());

使用自定义冷启动结束时间

是否使用自定义冷启动结束时间

Bonree withUseCustomLaunch(boolean used)
参数 说明
used true 使用自定义结束 false 不使用
  • 示例
  Bonree.withAppID("c1f18f3a-ba47-408a-9f80-ea87b6c083dk")
        .withUseCustomLaunch(true)
        .start(getApplicationContext());

设置持续丢帧时间

判定卡顿时需要的持续丢帧时间

Bonree withDropFrameTime(int dropFrameTime)
参数 说明
dropFrameTime 持续丢帧时间(s),0< dropFrameTime <=30,不设置默认5s
  • 示例
  Bonree.withAppID("c1f18f3a-ba47-408a-9f80-ea87b6c083dk")
        .withDropFrameTime(5)
        .start(getApplicationContext());

设置SDK自身请求Header

本接口用于设置对于SDK自身发起的网络请求中添加自定义请求头

Bonree withSDKRequestHeaders(Map<String, String> headers)
参数 说明
headers 要设置的请求头键值对(最多设置64个,key长度限制256个字符,value长度限制512个字符)
  • 示例
  Map<String, String> headers=new HashMap<>();
  headers.put("headerKey1","headerValue1");
  headers.put("headerKey2","headerValue2");
  headers.put("headerKey3","headerValue3");

  Bonree.withAppID("c1f18f3a-ba47-408a-9f80-ea87b6c083dk")
        .withSDKRequestHeaders(headers)
        .start(this);

开启加密并设置加密信息

本接口用于设置是否使用国密加密SDK自身请求。

加密功能当前仅支持One平台。使用该功能前请务必先与技术支持或实施沟通获取加密Key,保证与平台配置一致,否则会导致SDK数据请求异常。

Bonree withEnableGMSM4Encrypt(byte[] secretKey,String identifier)
参数 说明 参数限制 失败结果
secretKey 加密密钥 必填,byte[] 类型,key长度必须完全等于16个字节 加密功能失效
identifier 密钥标识符 必填,字符串不可为空或空串。
字符串小于等于256,且不包含特殊字符(仅支持字母数字下划线_连接符-)
加密功能失效
  • 示例

  byte[] secretKey = new byte[]{1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16};
//assert secretKey.length == 16;
  String identifier="v30";
  Bonree.withAppID("c1f18f3a-ba47-408a-9f80-ea87b6c083dk")
        .withEnableGMSM4Encrypt(secretKey,identifier)
        .start(getApplicationContext());

  或

  String secretKeyStr ="1234567890123456";
  byte[] secretKey = secretKeyStr.getBytes();
//assert secretKey.length == 16; 务必保证字符实际长度为16字节,请勿使用< >  &  '  " %特殊字符
  String identifier ="v31";
  Bonree.withAppID("c1f18f3a-ba47-408a-9f80-ea87b6c083dk")
        .withEnableGMSM4Encrypt(secretKey,identifier)
        .start(getApplicationContext());

二、数据获取接口

获取设备ID

如果在SDK启动时设置了 withDeviceID 接口,那么会返回自定义的ID

static java.lang.String getDeviceID()
  • 示例
  String deviceID=Bonree.getDeviceID();
  Log.w("TAG","BRSDK: "+deviceID);

获取SDK当前版本

获取当前SDK的版本

static java.lang.String getSdkVersion();
  • 示例
  String sdkVersion=Bonree.getSdkVersion();
  Log.w("TAG","BRSDK: "+sdkVersion);

三、自定义信息设置接口

自定义用户信息

BonreeSDK支持设置与用户相关的信息,从而完成性能数据与实际用户相关联的需求场景。

设置用户信息有两种方式:

  • 设置用户ID,以字符串形式给用户做标识
static void setUserID(java.lang.String userID);
参数 说明 参数限制 失败结果
userID 以字符串形式给用户做标识 字符串可为空或空串。
字符串小于等于256,且不包含特殊字符(仅支持字母数字下划线_连接符-),否则接口调用失败。
当次设置无效
  • 示例
 Bonree.setUserID("18988888888");
  • 以 Key-Value 形式给用户更加详细的附加信息。
static void setExtraInfo(java.util.Map<java.lang.String,java.lang.Object>extraInfo)
参数 说明 参数限制 失败结果
extraInfo kv存储更多的用户信息 Map可为空或空集合。
转JSON后长度在7000字符以内,否则接口调用失败。
当次设置无效
  • 示例
   HashMap<String, Object> userInfo=new HashMap<>(3);
   userInfo.put("phoneNumber","18988888888");
   userInfo.put("clientID","android device id");
   userInfo.put("type","vip");

   Bonree.setExtraInfo(userInfo);

自定义异常

调用接口并传入相应参数,可完成自定义异常数据的统计功能。

static void setCustomException(java.lang.Throwable throwable) //推荐使用,直接将Exception或Throwable对象传入即可
参数 说明 参数限制 失败结果
throwable 异常对象 系统抛出的异常对象,非null 当次设置无效
  • 示例
   try{
      String userName=null;
      Log.w("TAG","user name: "+userName.trim());
   }catch(Exception e){
      e.printStackTrace();
      //推荐使用Throwable重载,直接将对象传入即可
      Bonree.setCustomException(e);
   }
//此重载配置更灵活,可用于业务型异常上报,有关参数可填充符合参数限制的任意内容,平台直接展示。
static void setCustomException(java.lang.String exceptionType,java.lang.String causeBy,java.lang.String errorDump)
参数 说明 参数限制 失败结果
exceptionType 异常类型(必要) 字符串长度大于0,小于等于256,否则接口调用失败。 当次设置无效
causeBy 异常原因 字符串可为空或空串。
字符串小于等于512,超长截取。
-
errorDump 异常信息 超出10000字符时会被切割 字符串可为空或空串。
字符串小于等于10000,超长截取。
  • 示例
   try{
      String userName=null;
      Log.w("TAG","user name: "+userName.trim());
   }catch(Exception e){
      e.printStackTrace();
      String errorDump=StringUtils.join(e.getStackTrace(),"\r\n");
      Bonree.setCustomException(e.getClass().getName(),e.getMessage(),errorDump);
   }

自定义视图

调用接口并传入相应参数,可完成自定义视图数据统计功能。

//自定义视图-页面开始,与页面结束需成对调用,一般调用位置:onResume name视图名称为必填字段,如果为空则调用失败。
static void setCustomPageStart(java.lang.String pageName,java.lang.String param);

//自定义视图-页面结束,与页面开始成对调用,一般调用位置:onPause
static void setCustomPageEnd(java.lang.String pageName,java.lang.String param);
参数 说明 参数限制 失败结果
pageName 视图名字(必要) 字符串长度大于0,小于等于256,否则接口调用失败。 当次设置无效
param 附加信息,可设置为视图别名 字符串可为空或空串。
字符串小于等于256,超长截取。
-
  • 示例
 @Override
 protected void onResume(){
    Bonree.setCustomPageStart(getClass().getName(),"首页");
    super.onResume();
 }

 @Override
 protected void onPause(){
    Bonree.setCustomPageEnd(getClass().getName(),"首页");
    super.onPause();
 }

自定义事件(完整版)

分别调用开始与结束接口并传入相应参数,可完成自定义事件数据与事件持续时间的统计功能。


static void setCustomEventStart(String eventID, String name);
static void setCustomEventStart(String eventID,String name,String label);
static void setCustomEventStart(String eventID, String name, String label, String param);
static void setCustomEventStart(String eventID, String name, String label, String param,Map<String,String> info);
static void setCustomEventEnd(String eventID, String name);
static void setCustomEventEnd(String eventID,String name,String label);
static void setCustomEventEnd(String eventID, String name, String label, String param);
static void setCustomEventEnd(String eventID, String name, String label, String param,Map<String,String> info);
参数 说明 参数限制 失败结果
eventID 事件ID(必要) 字符串长度大于0,小于等于256,否则接口调用失败。 当次设置无效
name 事件名称 字符串可为空或空串。
字符串小于等于256,超长截取。
-
param 附加信息(预留字段,暂无使用场景) 字符串可为空或空串。
字符串小于等于7000,超长截取。
-
info kv存储信息 转JSON后长度在7000字符以内,否则接口调用失败。 -
  • 示例
 Bonree.setCustomEventStart("vip-login","验证码发送","登录");
 Bonree.setCustomEventEnd("vip-login","验证码发送","登录");

 //带有info字段的调用
 HashMap<String, String> info=new HashMap<>(3);
    info.put("eventNumber","10001");
    info.put("eventName","bonree");
    info.put("eventXX","xx");
 Bonree.setCustomEventStart("vip-login","登录失败","登录",null,info);
 Bonree.setCustomEventEnd("vip-login","验证码发送","登录",null,info);

自定义事件(精简版)

调用接口并传入相应参数,可完成自定义事件数据统计功能。

static void setCustomEvent(java.lang.String eventID,java.lang.String name);
static void setCustomEvent(String eventID,String name,String param,Map<String,String> info);
static void setCustomEventWithLabel(String eventID, String name, String label);
static void setCustomEventWithLabel(String eventID, String name, String label, String param,Map<String,String> info);
参数 说明 参数限制 失败结果
eventID 事件ID(必要) 字符串长度大于0,小于等于256,否则接口调用失败。 当次设置无效
name 事件名称 字符串可为空或空串。
字符串小于等于256,超长截取。
-
label 事件标签 字符串可为空或空串。
字符串小于等于256,超长截取。
-
param 附加信息(预留字段,暂无使用场景) 字符串可为空或空串。
字符串小于等于7000,超长截取。
-
info kv存储信息 转JSON后长度在7000字符以内,否则接口调用失败。 -
  • 示例
  Bonree.setCustomEvent("001","注册");
  Bonree.setCustomEventWithLabel("vip-login","登录失败","登录");

  HashMap<String, String> info=new HashMap<>(3);
  info.put("eventNumber","10001");
  info.put("eventName","bonree");
  info.put("eventXX","xx");
  Bonree.setCustomEvent("vip-login","登录失败",null,info);
  Bonree.setCustomEventWithLabel("vip-login","登录失败","登录",null,info);

自定义日志

调用接口并传入相应参数,可完成自定义日志数据统计功能。

static void setCustomLog(java.lang.String logInfo)
参数 说明 参数限制 失败结果
logInfo 日志信息(必要) 字符串长度大于0,否则接口调用失败。
字符串小于等于10000,超长截取。
当次设置无效
  • 示例
 Bonree.setCustomLog("login successful...");

自定义指标

调用接口并传入相应参数,可完成自定义指标数据统计功能。

static void setCustomMetric(java.lang.String name,long value)
参数 说明 参数限制 失败结果
name 指标名称(必要) 字符串长度大于0,小于等于256,否则接口调用失败。 当次设置无效
value 指标值(必要) Long.MAX_VALUE -
  • 示例
 Bonree.setCustomMetric("自定义指标",System.currentTimeMillis());

自定义方法

调用接口并传入相应参数,可完成自定义指标数据统计功能。自定义方法埋点多用于不在SDK自动采集范围内的业务方法或异步方法的手动埋点。

static void setCustomMethodStart(java.lang.String name);
static void setCustomMethodEnd(java.lang.String name);
参数 说明 参数限制 失败结果
name 方法名称(必要) 字符串长度大于0,小于等于256,否则接口调用失败。 当次设置无效
  • 示例
public void onNetworkLoad(){
        Bonree.setCustomMethodStart("onNetworkLoad");
        //do something
        SystemClock.sleep(5000);
        Bonree.setCustomMethodEnd("onNetworkLoad");
}

自定义网络

调用接口并传入相应参数,可完成自定义指标数据统计功能。自定义方法埋点多用于不在SDK自动采集范围内的业务方法或异步方法的手动埋点。

static void setCustomNetwork(NetworkCustomEventBean networkCustomEvent)
参数 说明 参数限制 失败结果
networkCustomEvent 实体结构(必要) 指标结构对象。必传参数。 当次设置无效
@param java.lang.String requestUrl                        //请求地址
@param NetworkCustomEventBean.HttpMethod method            //请求方式
@param java.lang.String targetIp                           //目标IP
@param int targetPort                                      //目标端口
@param int dnsTimeUs                                       //dns查询时间
@param int connectTimeUs                                   //tcp建连时间
@param int sslTimeUs                                        //ssl时间
@param int requestTimeUs                                   //请求时间
@param int responseTimeUs                                  //响应时间
@param int downloadTimeUs                                  //下载用时
@param int downloadSizeByte                                //响应数据大小 
@param NetworkCustomEventBean.ProtocolType protocolType    //协议类型
@param java.util.List cnameArray                         //cname的集合
@param int errorCode                                       //错误码
@param java.lang.String errorMessage                       //错误描叙信息
@param NetworkCustomEventBean.ErrorOccurrentProcess        //错误发生的过程阶段
@param int requestDataSize                                 //请求大小的字段
@param java.lang.String resourceType                       //资源类型
@param Map<String, String> requestHeader                   //请求header
@param Map<String, String> responseHeader;                 //响应header
  • 示例
    Bonree.setCustomNetwork(new NetworkCustomEventBean("https://www.baidu.com",
        NetworkCustomEventBean.HttpMethod.GET,
        443,
        20000,
        10000,
        50000,
        20000,
        500000,
        10000,
        55,
        NetworkCustomEventBean.ProtocolType.HTTP1S
        ));

自定义冷启动结束

在启动配置中配置了withUseCustomLaunch接口后,调用此自定义接口可以设置当前时刻为自定义冷启动事件的结束点

static void recordCustomLaunchEnd()
  • 示例
 Bonree.recordCustomLaunchEnd();

设置自定义请求信息接口

调用接口并传入相应参数,可以给匹配到的网络数据关联自定义的字符串信息。

static void setRequestExtraInfo(String headerKey,String headerValue,String info)
  • 接口说明
参数名 说明 参数限制 失败结果
headerKey 需要匹配的key 字符串长度大于0,小于等于256,否则接口调用失败。 当次设置无效
value 需要匹配的请求头Value 字符串长度大于0,小于等于256,否则接口调用失败。 当次设置无效
info 关联的自定义信息 字符串长度大于0,小于等于256,若为空则清除对应键值缓存的信息。 超长部分会被截断
  • 示例

使用本接口前,需要保证目标请求的请求头中有唯一标识,比如,某请求的请求头如下:

POST /upload HTTP/1.1
Host: sdkupload.bonree.com
Content-Type: application/json
Content-Length: 781
Connection: keep-alive
Br-Content-Encoding: gzip
Operation-Type:vip-login

其中Operation-Type为该请求的唯一标识字段,若要给该请求关联信息

vip-id:8888

则需要在请求发出之前调用

 Bonree.setRequestExtraInfo("Operation-Type","vip-login","vip-id:8888");

自定义操作结束

调用该接口,结束根据调用栈匹配到的操作。该方法必须直接或间接地由操作相关的方法调用,否则调用无效。

static void recordCustomActionEnd()
  • 使用场景

以登录场景为例,

  1. 在LoginActivity点击登录按钮,触发 onClick(View view) 回调;
  2. onClick 回调中,发送 login 请求;
  3. login 请求成功后,持久化用户信息,并跳转到HomeActivity;
  4. 在HomeActivity中刷新首页展示数据;

如果我们定义登录操作的结束点为Home页面用户可见时,那么我们就可以在HomeActivity的 onResume() 函数中中调用自定义操作结束接口来停止上一个登录按钮的事件采集操作。

  • 示例
 @Override
 protected void onResume() {
   super.onResume();
   Bonree.recordCustomActionEnd();
 }

四、OnlineTracking

调试授权接口

调试授权接口,用于在任何时机对SDK后续的tracking调试行为授权或取消授权,只在当次运行生效,不做持久化存储。

static void authorizeOnlineTracking(boolean isAuthorized)
  • 接口说明
参数名 说明 参数限制 失败结果
isAuthorized 授权/取消授权 true false
  • 示例
public class App extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        //可在APP运行初期就授予/取消权限
        Bonree.authorizeOnlineTracking(true);
    }
}

授权回调接口

授权回调接口用于被动式授权,在当次运行未主动调用Bonree.authorizeOnlineTracking(boolean isAuthorized) 接口授权/取消授权的前提下,当SDK客户端收到服务端的调试请求时,会回调此接口传入的callback。

static void setOnlineTrackingAuthenticationCallBack(com.bonree.sdk.agent.Bonree.AuthenticationCallBack callback)
  • 接口说明
参数名 说明 参数限制 失败结果
callback 回调实例 必传非null 当次设置无效
  • 示例
 Bonree.setOnlineTrackingAuthenticationCallBack(()->{
        //务必在接收到SDK的授权请求回调30s之内调用此授权接口告知SDK是否允许调试,超时则认为当次调试被拒绝。
        if(DEBUG){
        //可根据自身业务灵活更改校验条件,如可以在此回调内弹出向用户询问授权的弹窗(*此回调为子线程,禁止直接更新UI),由用户决定授权与否再调用authorizeOnlineTracking授权接口。
        Bonree.authorizeOnlineTracking(true);
        }
 });

results matching ""

    No results matching ""