Session Replay 是火山引擎提供的会话回放解决方案，当前已支持 Android 端 SDK 接入，帮助用户快速实现会话回放。本文为您介绍Android端的Session Replay SDK接入指导

• 目前 DataFinder 会话回放功能支持在 Web（包括 H5） 端、Android端使用，本文为您介绍Android端的使用指导。
• 当前Android端的会话回放 SDK 仅支持SaaS-云原生与SaaS-非云原生环境，暂不支持私有化环境使用。
• 使用 DataFinder 会话回放功能需要同时安装 Finder Android SDK接入指南 与本文介绍的 Session Replay **** SDK。

  注意

  会话回放 Android 端 SDK 目前处于 Beta 验证阶段，接入前可以先联系火山技术人员 ，我们第一时间提供帮助和指引。

1. 集成Finder SDK

Session Replay SDK 依赖 Finder SDK 进行数据回流，在使用弹窗 SDK 前，请确保已经集成了 Finder SDK，接入操作请参见：Finder Android SDK接入指南。

2. 集成会话回放SDK

2.1 引入SDK（推荐Gradle引入方式）

1. 引入火山maven仓库地址。

   • Gradle 7.0 以下

     // 在 project 级别的 build.gradle 中添加 maven 仓库
     // 在 allprojects 的 repositories 中添加 maven 仓库
     allprojects {
         repositories {
             maven {
                 url 'https://artifact.bytedance.com/repository/Volcengine/'
             }
             // 其他仓库
         }
     }
     

   • Gradle 7.0 及以上

     // 在 project 级别的 setting.gradle 中添加 maven 仓库
     dependencyResolutionManagement {
         repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
         repositories {
             // 省略其他
             maven{
                 url 'https://artifact.bytedance.com/repository/Volcengine/'
             }
         }
     }
     

2. 添加SDK依赖。

   //在app:build.gradle下添加
   dependencies {
       // 最新版本请联系火山技术人员获取
       implementation 'com.bytedance.tea:tea_replay:x.x.x'
   }
   

3. 初始化 SDK

3.1 获取初始化必备参数

在开始集成前，首先需要在集团中拥有一个应用，进行 SDK 集成前，您需要获取对应应用的 appkey 信息。

• SaaS-云原生场景下，您可以在「项目中心」->「项目管理」->「项目详情」-> 接入应用的「详情」->「应用 ID」中可查看您的 appkey，详情请参见项目管理。
  
• SaaS-非云原生场景下，您可以在「应用列表」-> 接入应用的「详情」->「应用 ID」中可查看您的 appkey，详情请参见应用列表。
  

3.2 初始化（SaaS云原生&SaaS非云原生版本）

首先您需要初始化 Finder SDK，具体可参考：2.3 初始化 SDK，再初始化会话回放 SDK。

import com.bytedance.applog.AppLog;
   import com.bytedance.session_replay_sdk.config.InitConfig;
   private static final String APP_KEY = "xxxxx";//替换成你自己的appkey
   
    //初始化配置
   InitConfig config = new InitConfig.Builder()
           .setAppKey(APP_KEY)//设置appkey
           .setAutoStart(true)//是否自动启动录制，目前仅支持自动，默认传true即可
           .setEnvironmentType(EnvironmentType.SAAS_BYTE_CLOUD)//设置环境类型，SAAS_BYTE_CLOUD（SaaS-非云原生），SAAS_VOLC_CLOUD（SaaS-云原生）
           .setUBAConfig((s, jsonObject) -> {
               AppLog.onEventV3(eventName, eventParams)
           })//设置UBA上报回调，目前仅支持Finder   
           .setBlockSizeLimit(1024)//设置单个录制文件大小限制，单位kb,默认1024kb
           .setRecordMode(RecordMode.BLOCK)//设置录制模式，默认block模式
           .build();
    //初始化api调用
   SessionReplaySDK.INSTANCE.init(application, mInitConfig); 

3.3 初始化参数详细说明

enum class ReplayQuality {
    NO_BITMAP,//无bitmap模式，完全不截图
    LOW,//低分辨率模式，截图压缩率高
    MIDDLE,//中分辨率模式，截图压缩率中
    HIGH,//高分辨率模式，无损压缩
}

4. 设置回调监听

void setReplayCallBack() {
    SessionReplaySDK.INSTANCE.setReplayEventCallBack(new IReplayEventCallBack() {
        @Override
        public boolean rootViewShouldPush(@NonNull View view) {
             // 参数view是activity / dialog / toast 对应window的根节点
            // 返回true，表示该view 需要被录制
            //返回false, 表示该view不应该被录制
            return true;
        }

        @Override
        public void onRecordingRootViewPush(@NonNull String recordingId) {
            //开始录制时调用，这里需要给录制id赋值，后续在第5条（埋点中注入录制ID参数）中会用到
            mRecordingId = recordingId;
        }

        @Override
        public void onRecordingPause(@NonNull String recordingId) {
            //停止录制时调用，一般是跳出白名单的页面，这里需要将获取到的录制id置空
            mRecordingId = null;
        }

        @Override
        public void onRecordingInit(@NonNull String recordingId) {
          //初始化成功之后回调
        }

        @Override
        public void onRecordingCreated(@NonNull String recordingId) {
          //录制内容上传成功时回调
        }
    });
}

5. 埋点中注入录制ID参数

import com.bytedance.applog.AppLog
import com.bytedance.applog.UriConfig
import com.bytedance.applog.event.AutoTrackEventType
import com.bytedance.applog.event.EventBasicData
import com.bytedance.applog.event.EventPolicy
import com.bytedance.applog.event.EventType

void setEventHandler() {
    AppLog.setEventHandler(new com.bytedance.applog.event.IEventHandler() {
        @Override
        public int acceptType() {
            return EventType.EVENT_ALL;
        }

        @Override
        public EventPolicy onReceive(int eventType, String eventName, JSONObject properties, EventBasicData basisData) {
            try {
                if (!TextUtils.isEmpty(mRecordingId)) {
                    properties.put("\$sr_recording_id", mRecordingId);
                }
            } catch (JSONException ignored) {
                // 忽略异常
            }
            return EventPolicy.ACCEPT;
        }
    });
}

6. 处理网络图片

//如果您的应用统一封装了网图加载的方法或基类，可以在网图统一加载的地方进行设置
void setImageUrl(ImageView imageView,String url) {
    // 将 url 设置到 imageView 的对应 tag 上
    imageView.setTag(SessionReplaySDK.INSTANCE.getRemoteImageTagKey(), url);
}

7. 设置白名单页面（可选）

private void setActivityWhiteList() {
    SessionReplaySDK.INSTANCE.setActivityWhiteList(new HashSet<String>() {{
        //A页面,完整包名+类名
        add("com.xxx.AActivity");
        //B页面完整包名+类名
        add("com.xxx.BActivity");
    }});
}

8. 设置自定义组件（按需）

private void setCustomViewMap() {
    HashMap<String, CustomViewModel> map = new HashMap<String, CustomViewModel>() {{
        // 内部绘制逻辑比较耗时，可以设置延迟截取
        put("com.lynx.xx.LynxView", new CustomViewModel(CustomViewType.ASYNC_VIEW, 60L));
        put("com.xxx.xxx.CustomView", new CustomViewModel(CustomViewType.ASYNC_VIEW, 60L));
        // 普通组件，无需延迟
        put("com.ss.android.tui.component.selector.TUISwitchButton", new CustomViewModel());
    }};
    SessionReplaySDK.INSTANCE.registerCustomViewMap(map);
}

9. 用户手动授权上传（可选）

SessionReplaySDK.INSTANCE.openSingleTimeAuthPanel(
    new AuthConfig.Builder()
        .title("反馈授权提示") // 弹窗标题 文本自己定义
        .content("授权上报您近 1 小时内的操作记录，助您更快解决问题。")//弹窗提示内容 文本自己定义
        .positiveButtonText("上报")//弹窗确认按钮文本 文本自己定义
        .negativeButtonText("取消") //弹窗取消按钮文本 文本自己定义
        .build()
);

10. 使用自定义方式输出日志

initConfig.setCustomLogger(new ILoggerConfig() {
    @Override
    public void v(@NonNull String tag, @NonNull String message, @Nullable Throwable throwable) {
        // 自定义v日志输出
        Log.v(tag, message);
    }

    @Override
    public void d(@NonNull String tag, @NonNull String message, @Nullable Throwable throwable) {
       // 自定义d日志输出
        Log.d(tag, message);
    }

    @Override
    public void i(@NonNull String tag, @NonNull String message, @Nullable Throwable throwable) {
       // 自定义i日志输出
        Log.i(tag, message);
    }

    @Override
    public void w(@NonNull String tag, @NonNull String message, @Nullable Throwable throwable) {
        // 自定义w日志输出
        Log.w(tag, message);
    }

    @Override
    public void e(@NonNull String tag, @NonNull String message, @Nullable Throwable throwable) {
        // 自定义e日志输出
        Log.e(tag, message);
    }
})

1. Block模式（分片上传模式）

使用参考

InitConfig initConfig = new InitConfig.Builder();
initConfig.setRecordMode(RecordMode.BLOCK);//设置为BLOCK模式      

2. Local模式（本地模式）

• 使用参考

  //初始化
  InitConfig initConfig = new InitConfig.Builder();
  initConfig.setRecordMode(RecordMode.LOCAL);//设置为LOCAL模式
  initConfig.setExpireDuration(1000 * 60 * 60)// 设置1小时过期（建议设置， 默认值是7天）
  

• 如何上传

  1. 手动调用flush上传

     SessionReplaySDK.INSTANCE.flush(context);
     

  2. 弹出授权弹窗，用户授权同意后上传

     SessionReplaySDK.INSTANCE.openSingleTimeAuthPanel(
         new AuthConfig.Builder()
             .title("反馈授权提示") // 弹窗标题 文本自己定义
             .content("授权上报您近 1 小时内的操作记录，助您更快解决问题。")//弹窗提示内容 文本自己定义
             .positiveButtonText("上报")//弹窗确认按钮文本 文本自己定义
             .negativeButtonText("取消") //弹窗取消按钮文本 文本自己定义
             .build()
     );
     

1. 不支持Jetpack Compose
2. API限制，minSdkVersion >= 21（Android 5.0+）
3. 不支持视频相关组件（SurfaceView\Texture等）
4. 不支持Webview/Flutter/ReactNative等跨端框架组件