API功能

一、启动配置接口

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

设置config地址

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

• 接口说明

Bonree withConfigAddress(java.lang.String configAddress)

• 示例

  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)

• 示例

  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)

• 示例

  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)

• 示例

  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)

• 示例

  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)

• 示例

  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)

• 示例

  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)

• 示例

  Bonree.withAppID("c1f18f3a-ba47-408a-9f80-ea87b6c083dk")
        .withSyncStart(true)
        .start(getApplicationContext());

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

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

Bonree withUseCustomLaunch(boolean used)

• 示例

  Bonree.withAppID("c1f18f3a-ba47-408a-9f80-ea87b6c083dk")
        .withUseCustomLaunch(true)
        .start(getApplicationContext());

设置持续丢帧时间

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

Bonree withDropFrameTime(int dropFrameTime)

• 示例

  Bonree.withAppID("c1f18f3a-ba47-408a-9f80-ea87b6c083dk")
        .withDropFrameTime(5)
        .start(getApplicationContext());

设置SDK自身请求Header

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

Bonree withSDKRequestHeaders(Map<String, String> headers)

• 示例

  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)

• 示例

  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);

• 示例

 Bonree.setUserID("18988888888");

• 以 Key-Value 形式给用户更加详细的附加信息。

static void setExtraInfo(java.util.Map<java.lang.String,java.lang.Object>extraInfo)

• 示例

   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对象传入即可

• 示例

   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)

• 示例

   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);

• 示例

 @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);

• 示例

 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);

• 示例

  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)

• 示例

 Bonree.setCustomLog("login successful...");

自定义指标

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

static void setCustomMetric(java.lang.String name,long value)

• 示例

 Bonree.setCustomMetric("自定义指标",System.currentTimeMillis());

自定义方法

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

static void setCustomMethodStart(java.lang.String name);
static void setCustomMethodEnd(java.lang.String name);

• 示例

public void onNetworkLoad(){
        Bonree.setCustomMethodStart("onNetworkLoad");
        //do something
        SystemClock.sleep(5000);
        Bonree.setCustomMethodEnd("onNetworkLoad");
}

自定义网络

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

static void setCustomNetwork(NetworkCustomEventBean 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)

• 接口说明

• 示例

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

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)

• 接口说明

• 示例

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)

• 接口说明

• 示例

 Bonree.setOnlineTrackingAuthenticationCallBack(()->{
        //务必在接收到SDK的授权请求回调30s之内调用此授权接口告知SDK是否允许调试，超时则认为当次调试被拒绝。
        if(DEBUG){
        //可根据自身业务灵活更改校验条件，如可以在此回调内弹出向用户询问授权的弹窗(*此回调为子线程，禁止直接更新UI)，由用户决定授权与否再调用authorizeOnlineTracking授权接口。
        Bonree.authorizeOnlineTracking(true);
        }
 });