开放平台V2文档

# 游戏对局回放（选接）

游戏对局回放是一组录制游戏画面来生成对局回放，并可以将对局回放分享给朋友的API，收到分享链接的快手用户可点击链接查看回放，或进入游戏等。

注意事项

该能力暂不支持使用快手开发者工具调试，请使用真机预览测试！

# 录制游戏画面

# 接口说明

用于录制游戏画面来生成对局回放。

// 创建并返回一个全局单例录制器
const gameRecorder = sdkInstance.getGameRecorder();

// 先判断 gameRecorder 是否存在再使用
// 因为当用户的客户端基础库版本过低时，调用 sdkInstance.getGameRecorder 接口将返回 undefined
if (gameRecorder) {
  // 监听录制事件，当对应事件触发时，回调函数会被执行，详见下文说明
  gameRecorder.on(event, callback);

  // 取消监听录制事件，当对应事件触发时，回调函数不再执行，详见下文说明
  gameRecorder.off(event, callback);

  // 开始录制游戏画面，返回一个 Promise 对象
  gameRecorder.start();

  // 暂停录制游戏画面，返回一个 Promise 对象
  gameRecorder.pause();

  // 恢复录制游戏画面，返回一个 Promise 对象
  gameRecorder.resume();

  // 结束录制游戏画面，结束录制后可以发起分享，返回一个 Promise 对象
  gameRecorder.stop();

  // 取消录制游戏画面，此时已经录制的内容将被丢弃，返回一个 Promise 对象
  gameRecorder.abort();
}
// 不存在或不支持录制时，弹出相应提示
else {
  sdkInstance.modal.message("暂不支持此功能");
}

最低基础库版本要求

当用户客户端基础库版本过低时，调用 sdkInstance.getGameRecorder() 接口将弹出升级提示，并返回 undefined，需要游戏客户端对返回值做兼容处理！

# 录制器

调用接口 sdkInstance.getGameRecorder() (opens new window) 将返回一个全局单例录制器 GameRecorder (opens new window)。录制游戏画面是一项比较消耗性能的能力，在某些系统、设备上无法进行游戏画面录制，因此在调用游戏画面录制能力前，需先判断当前环境是否支持该能力，如下所示：

// 创建并返回一个全局单例录制器
const gameRecorder = sdkInstance.getGameRecorder();

// 判断是否支持录制游戏画面
if (gameRecorder) {
  // 若支持，再执行后续相关操作
  // ......
}
// 不存在或不支持录制时，弹出相应提示
else {
  sdkInstance.modal.message("暂不支持此功能");
}

所有和录制有关的API都挂载在 GameRecorder (opens new window) 对象上：

调用 GameRecorder.start() (opens new window) 开始录制，调用 GameRecorder.stop() (opens new window) 结束录制：

// 监听录制开始事件，回调函数被执行时表示录制已开始
gameRecorder.on("start", function() {
  // 真正开始录制 5 秒后结束录制
  setTimeout(function() {
    gameRecorder.stop();
  }, 5000);
});

// 监听录制结束事件，回调函数被执行时表示录制已完成
gameRecorder.on("stop", function(result) {
  // 回调函数中可获得录制的视频ID
  console.log(result.videoID);
});

// 开始录制
gameRecorder.start();

如果在录制过程中有玩家思考等待等过程，可以调用 GameRecorder.pause() (opens new window) 暂停录制，然后再用 GameRecorder.resume() (opens new window) 恢复录制：

// 监听录制暂停事件，回调函数被执行时表示录制已暂停
gameRecorder.onPause(function() {
  // 真正开始暂停 5 秒后恢复录制
  setTimeout(function() {
    gameRecorder.resume();
  }, 5000);
});

// 监听录制恢复事件，回调函数被执行时表示录制已恢复
gameRecorder.onResume(function() {
  console.log("录制已恢复");
});

// 暂停录制
gameRecorder.pause();

如果想舍弃已经在录制的视频，可以调用 GameRecorder.abort() (opens new window)：

// 监听录制取消事件，回调函数被执行时表示录制已取消，已经录制的内容将被丢弃
gameRecorder.on("abort", function() {
  console.log("录制已取消");
});

// 取消录制
gameRecorder.abort();

注意事项

如果 stop 事件被触发，则表示已经有一个录制好的视频被输出来了；录制好的视频保存在快手内部，不能被访问到，也不能直接播放，只能发送给朋友；快手内部只会保存最近一次录制的视频，发起分享时也只会分享这个最近一次录制的视频！

# 监听录制事件

GameRecorder.on(event, callback) (opens new window) 用于监听录制事件，包含 event 和 callback 两个参数，当对应事件触发时，回调函数会被执行；参数说明如下表所示：

选项 类型 必填 默认值 说明
event string 是 --

事件类型

  • start - 录制开始事件
  • pause - 录制暂停事件
  • resume - 录制恢复事件
  • stop - 录制结束事件
  • abort - 录制取消事件
  • error - 错误事件，当录制和分享过程中发生错误时触发该事件
callback function 是 -- 事件触发时执行的回调函数

注意事项

当事件类型为 stop、error 时，其对应的事件回调函数参数各不相同，其它事件回调函数都是无参的。

当 stop 事件触发时，其回调函数的参数说明如下表所示：

选项 类型 说明
videoID number 视频ID
// 监听录制结束事件
gameRecorder.on("stop", function(result) {
  console.log(result.videoID); // 视频ID
});

当 error 事件触发时，其回调函数的参数说明如下表所示：

选项 类型 说明
error object 错误对象
    error.code number 错误码
    error.msg string 错误信息
// 监听录制错误事件
gameRecorder.on("error", function(result) {
  console.log(result.error.code); // 错误码
  console.log(result.error.msg); // 错误信息
});

# 取消监听录制事件

GameRecorder.off(event, callback) (opens new window) 用于取消监听录制事件，包含 event 和 callback 两个参数，当对应事件触发时，回调函数不再执行；参数说明如下表所示：

选项 类型 必填 默认值 说明
event string 是 --

事件类型

  • start - 录制开始事件
  • pause - 录制暂停事件
  • resume - 录制恢复事件
  • stop - 录制结束事件
  • abort - 录制取消事件
  • error - 错误事件，当录制和分享过程中发生错误时触发该事件
callback function 是 -- 事件触发时不再执行的回调函数

# 开始录制

GameRecorder.start() (opens new window) 用于开始录制游戏画面。

# 暂停录制

GameRecorder.pause() (opens new window) 用于暂停录制游戏画面。

# 恢复录制

GameRecorder.resume() (opens new window) 用于恢复录制游戏画面。

# 结束录制

GameRecorder.stop() (opens new window) 用于结束录制游戏画面，结束录制后可以发起分享。

# 放弃录制

GameRecorder.abort() (opens new window) 用于放弃录制游戏画面，此时已经录制的内容将被丢弃。

# 示例代码

注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！

// 创建并返回一个全局单例录制器
const gameRecorder = sdkInstance.getGameRecorder();

// 判断 gameRecorder 是否存在再使用，若存在且支持录制，则优先注册好相关的事件监听
// 因为当用户的客户端基础库版本过低时，调用 sdkInstance.getGameRecorder 接口将返回 undefined
if (gameRecorder) {
  // 监听录制开始事件
  gameRecorder.on("start", function() {
    sdkInstance.modal.message("录制已开始");
  });

  // 监听录制暂停事件
  gameRecorder.on("pause", function() {
    sdkInstance.modal.message("录制已暂停");
  });

  // 监听录制恢复事件
  gameRecorder.on("resume", function() {
    sdkInstance.modal.message("录制已恢复");
  });

  // 监听录制结束事件
  gameRecorder.on("stop", function(result) {
    sdkInstance.modal.message("录制已结束");
  });

  // 监听录制取消事件
  gameRecorder.on("abort", function() {
    sdkInstance.modal.message("录制已取消");
  });

  // 监听录制错误事件
  gameRecorder.on("error", function(result) {
    sdkInstance.modal.message(result.error.msg);
  });
}

// 绘制"开始录制"按钮，并在点击时调用 gameRecorder.start() 开始录制
// 此处 addButton 仅为演示，实际按钮的创建与点击事件回调函数由开发者自行使用游戏引擎实现
addButton({
  text: "开始录制",
  handler: function() {
    // 检查是否支持录制游戏画面
    if (!gameRecorder) {
      return sdkInstance.modal.message("暂不支持此功能");
    }

    // 开始录制
    gameRecorder.start();
  }
});

// 绘制"结束录制"按钮，并在点击时调用 gameRecorder.stop() 结束录制
// 此处 addButton 仅为演示，实际按钮的创建与点击事件回调函数由开发者自行使用游戏引擎实现
addButton({
  text: "结束录制",
  handler: function() {
    // 检查是否支持录制游戏画面
    if (!gameRecorder) {
      return sdkInstance.modal.message("暂不支持此功能");
    }

    // 结束录制
    gameRecorder.stop();
  }
});

# 分享游戏对局回放

# 接口说明

用于分享生成的游戏对局回放。

sdkInstance.shareGameRecorderVideo(options);

# 参数说明

参数说明如下表所示：

选项 类型 必填 默认值 说明
templateId string 否 -- 分享文案模板ID，通过指定该参数来选择分享文案，文案内容需在快手开放平台设置且通过审核
videoId number 否 -- 待发布的视频ID或视频ID数组；如果不传该字段，则默认发布最后一次录制生成的视频数据；若录屏失败则不会生成视频ID，发布录屏会失败
query object 否 -- 分享时携带的额外参数；点击分享消息进入游戏后，可通过 sdkInstance.launchOptions.query 或调用快手原生方法 ks.getLaunchOptionsSync() 获取该信息
success function 否 -- 接口调用成功的回调函数
fail function 否 -- 接口调用失败的回调函数
complete function 否 -- 接口调用完成的回调函数，成功或失败均会调用

# 示例代码

注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！

// 创建并返回一个全局单例录制器
const gameRecorder = sdkInstance.getGameRecorder();

// 用于临时存放录制好的视频ID
let videoId = "";

// 判断 gameRecorder 是否存在再使用，若存在且支持录制，则优先注册好相关的事件监听
// 因为当用户的客户端基础库版本过低时，调用 sdkInstance.getGameRecorder 接口将返回 undefined
if (gameRecorder) {
  // 监听录制开始事件
  gameRecorder.on("start", function() {
    sdkInstance.modal.message("录制已开始");
  });

  // 监听录制结束事件
  gameRecorder.on("stop", function(result) {
    videoId = result.videoID;
    sdkInstance.modal.message("录制已结束");
  });

  // 监听录制错误事件
  gameRecorder.on("error", function(result) {
    sdkInstance.modal.message(result.error.msg);
  });
}

// 绘制"开始录制"按钮，并在点击时调用 gameRecorder.start() 开始录制
// 此处 addButton 仅为演示，实际按钮的创建与点击事件回调函数由开发者自行使用游戏引擎实现
addButton({
  text: "开始录制",
  handler: function() {
    // 检查是否支持录制游戏画面
    if (!gameRecorder) {
      return sdkInstance.modal.message("暂不支持此功能");
    }

    // 开始录制
    gameRecorder.start();
  }
});

// 绘制"结束录制"按钮，并在点击时调用 gameRecorder.stop() 结束录制
// 此处 addButton 仅为演示，实际按钮的创建与点击事件回调函数由开发者自行使用游戏引擎实现
addButton({
  text: "结束录制",
  handler: function() {
    // 检查是否支持录制游戏画面
    if (!gameRecorder) {
      return sdkInstance.modal.message("暂不支持此功能");
    }

    // 结束录制
    gameRecorder.stop();
  }
});

// 绘制"分享游戏对局回放"按钮，并在点击时调用 sdkInstance.shareGameRecorderVideo(options) 时分享游戏对局回放
// 此处 addButton 仅为演示，实际按钮的创建与点击事件回调函数由开发者自行使用游戏引擎实现
addButton({
  text: "分享游戏对局回放",
  handler: function() {
    // 判断是否存在录制好的视频
    if (!videoId) {
      sdkInstance.modal.message("暂无可分享视频");
    }

    // 分享游戏对局回放
    sdkInstance.shareGameRecorderVideo({
      videoId: videoId,
      query: {
        param1: 1,
        param2: 2
      },
      success: function(response) {
        console.log(response);
      },
      fail: function(error) {
        console.log(error);
        sdkInstance.modal.message(error.message);
      },
      complete: function() {
        // do something here...
      }
    });
  }
});
Last Updated: 2025/2/10 16:44:50

← 分享 →