用户体验数据

自定义Trace埋点

由于 TingYun_SDK 默认关注系统类和方法，无法关注「业务代码」的耗时情况，使用「自定义埋点」接口可以补全「页面体验分析」和「操作体验分析」模块中的【分解图】，能够帮助开发者清晰的了解其业务代码的耗时及调用情况。

• 相关接口

注意：「自定义Trace埋点」接口需要成对调用，请勿跨方法、跨进程以及在异步加载和递归调用中使用该接口。

/**
 * @param tracerName 为当前方法所在方法名或自定义名称，支持中文、英文、数字、下划线，但不能包含空格或其他的转义字符
 */
NBSAppAgent.beginTracer(String tracerName);
NBSAppAgent.endTracer(String tracerName);

• 代码示例

//用户可以在SDK初始化后的任意方法前后添加自定义Trace
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);
    init();
}

private void init() {
    //方法开始前添加beginTracer
    NBSAppAgent.beginTracer(“这是Init方法”); 
    try {
        ………
    } catch (NameNotFoundException e) {
        e.printStackTrace();
    }
    //方法结束后添加endTracer
    NBSAppAgent.endTracer(“这是Init方法”);
}

自定义冷启动耗时

TingYun_SDK 默认计算 SDK 初始化开始至第一个页面加载结束的时间为「冷启动耗时」，研发人员可以根据自身应用需求更改计算「冷启动耗时」的结束点。

• 开启自定义冷启动耗时控制开关

  • 相关接口

    /**
     * @param isCustom 默认为 false，设置为 true 开启自定义启动耗时
     */
    NBSAppAgent.isCustomAppStart(boolean isCustom);

  • 代码示例

    public class MyApplication extends Application {
        @Override
        public void onCreate() {  
        	NBSAppAgent.setLicenseKey("AppKey")
        	.isCustomAppStart(true)//在初始化SDK时调用,开启自定义启动时间功能
        	.start(this.getApplicationContext());
        }
    }

• 设置自定义冷启动耗时的结束点

该接口需要与「isCustomAppStart」配合使用，当设置「isCustomAppStart」接口为 true 时，「setCustomOnResumeEndIns」接口设置生效。

• 相关接口

  /** 
   * @param className 需传入启动的第一个 Activity 的 class.getName，需在第一个 Activity onResume() 结束之后调用 
   */ 
  NBSAppAgent.setCustomOnResumeEndIns(String className);

  • 代码示例

    public class MyApplication extends Application { 
        @Override public void onCreate() { 
            NBSAppAgent.setLicenseKey("AppKey") 
            .isCustomAppStart(true)//在初始化SDK时调用,开启自定义启动时间功能 
            .start(this.getApplicationContext()); 
        } 
    } 
    
    public class SplashActivity extends Activity { 
        //启动的第一个Activity 
    } 
    
    public class MainActivity extends Activity { 
        //启动的第二个Activity 
        @Override public void onResume() { 
            super.onResume(); 
            NBSAppAgent.setCustomOnResumeEndIns(SplashActivity.class.getName()); //以第二个Activity的onResume()方法作为启动结束时间 
        } 
    }

自定义操作

通过「自定义操作」来定义一个【业务操作】用以了解其性能表现情况.

• 相关接口

注意：「自定义操作」接口需要成对调用，actionName不可为空，支持跨方法、跨线程调用。

/**
 * @param actionName 操作名称
 */
standbyEventActionStart(String actionName);
standbyEventActionEnd(String actionName);

• 代码示例

private void login() {   
    NBSAppAgent.standbyEventActionStart(“login”); 
    
    	………
    
    NBSAppAgent.standbyEventActionEnd(“login”);
}

设置 ViewID

设置 viewId 后，平台「操作分析」和「可视化命名」功能会优先使用该属性进行归类。

• 相关接口

/**
 * @param view 为要设置 ID 的控件
 * @param viewId 为设置的控件 ID，viewId 最多可包含 128 个字符,支持英文、数字、下划线
 */
NBSAppAgent.setViewId(View view, String viewId);

• 代码示例

Button button = findViewById(R.id.bt_login);
NBSAppAgent.setViewId(button, "login");

设置 ViewName

设置ViewName后，平台「操作分析」和「可视化命名」功能会优先使用该属性进行归类。

• 相关接口

/**
 * @param view View 对象
 * @param description ViewName，最多包含 128 个字符
 */
setViewContent(View view, String description)

• 代码示例

Button button = findViewById(R.id.bt_login);
NBSAppAgent.setViewContent(button, "登录");

设置 PageName「视图别名」

设置 PageName 后，平台「操作分析」和「可视化命名」功能会优先使用该属性进行归类。

• 相关接口

/**
 * @param activity Activity 对象
 * @param fragment Fragment 对象
 * @param alias PageName，最多可包含 128 个字符
 */
setPageName(Activity activity, String alias)
setPageName(Fragment fragment, String alias)

• 代码示例

public class MainActivity extends AppCompatActivity{
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_uiactivity);
        NBSAppAgent.setPageName(this, "主页");
    }
}

采集列表操作 item 位置

若项目使用的是 androidx 包的 RecyclerView，且重写了 onBindViewHolder()，SDK 可以自动嵌码采集 item 位置数据。若项目使用的是 ListView（GridView） 或 support 包的 RecyclerView ，需要手动调用 setRowTagForList() 方法采集 item 位置数据。

• 相关接口

/**
 * 采集 support 包的 RecyclerView 或 ListView（GridView），需要在 Adapter 中埋点
 * @param obj item View
 * @param position 位置
 */
NBSActionInstrumentation.setRowTagForList(Object obj, int position)

• 代码示例

//  如果使用了 support 包的 RecyclerView，需要在 Adapter 的 onBindViewHolder() 方法末行埋点
public void onBindViewHolder(RecyclerView.ViewHolder holder, int position) {
    ...// 其他代码
    NBSActionInstrumentation.setRowTagForList(holder.itemView, position);
}
@Override
public void onBindViewHolder(@NonNull RecyclerView.ViewHolder holder, int position, @NonNull List payloads) {
    super.onBindViewHolder(holder, position, payloads);
    ...// 其他代码
    NBSActionInstrumentation.setRowTagForList(holder.itemView, position);
}

//  如果使用了 ListView 或 GridView，需要在 Adapter 的 getView() 方法末行埋点
public View getView(int position, View convertView, ViewGroup parent) {
    ...// 其他代码
    NBSActionInstrumentation.setRowTagForList(view, position);
    return view;
}

设置 View 状态

页面加载过程中，SDK 以一定间隔扫描当前页面中 View 的状态计算页面是否加载完成，可以通过 setViewStatus() 对 View 设置状态，SDK 将优先使用设置的状态。

• 相关接口

/**
 * @param view View 对象
 * @param NBSViewStatus view 状态标记，支持以下三种状态：
 * NBSViewStatus.VIEW_STATUS_VALID，有效
 * NBSViewStatus.VIEW_STATUS_INVALID，无效
 * NBSViewStatus.VIEW_STATUS_IGNORE)，忽略
 */
setViewStatus(View view, NBSViewStatus viewStatus)

• 代码示例

TextView tv = new TextView(this);
NBSAppAgent.setViewStatus(tv, NBSViewStatus.VIEW_STATUS_IGNORE);// 对 tv 设置为忽略状态

设置扫描间隔

可以自定义扫描页面中 View 的时间间隔，默认 50ms 扫描一次。

• 相关接口

/**
 * @param scanInterval 扫描间隔，单位毫秒，默认 50ms，最小可设置为 50ms
 */
setPageScanInterval(int scanInterval)

• 代码示例

NBSAppAgent.setPageScanInterval(100);// 扫描间隔设置为 100ms

设置扫描超时

可以自定义扫描页面中 View 的超时时间，默认 5s。

• 相关接口

/**
 * @param timeout 超时时间，单位为秒，默认 5 秒，可以设置 5 - 15 秒
 */
setPageLoadTimeoutSec(int timeout)

• 代码示例

NBSAppAgent.setPageLoadTimeoutSec(10);// 设置扫描超时时间为 10 秒

自定义页面耗时

可以通过自定义页面耗时方法，设置页面结束时间点。

• 开启自定义冷启动耗时控制开关

  • 相关接口

    /**
     * @return 返回页面 ID
     * @param isCustom 当前页面是否使用自定义页面结束点
     */
    NBSAppAgent.customPageLoad(boolean isCustom);

  • 代码示例

    public class MainActivity extends Activity {
        String pageId;
        @Override
        public void onCreate() {  
        	pageId = NBSAppAgent.customPageLoad(true);
        }
    }

• 设置页面耗时的结束点

  该接口需要与「customPageLoad」配合使用，当设置「customPageLoad」接口为 true 时，「customPageLoadFinish」接口设置生效。

  • 相关接口

    /** 
     * @param pageId 需调用自定义页面时的 pageId
     * @param clasz 需当前自定义页面第一个加载的 Activity 或 Fragment 的 class 
     */ 
    NBSAppAgent.customPageLoadFinish(String pageId, Class clasz);

  • 代码示例

    public class MainActivity extends Activity {
        String pageId;
        @Override
        public void onCreate() {  
        	pageId = NBSAppAgent.customPageLoad(true);
        }
        
        public void loadFinish() {// 在页面加载完成后，调用 customPageLoadFinish()
            NBSAppAgent.customPageLoadFinish(pageId, MainActivity.class); 
        } 
    }