开放平台V2文档

# 广告

当前SDK支持在游戏内创建并嵌入激励视频广告、插屏广告和Banner广告，接入之前需登录《快手开放平台控制台》 (opens new window)后台，进入"商业化 > 流量主"，新建对应类型的广告并获取广告位ID。

# 激励视频广告

# 创建激励视频广告

调用 sdkInstance.createRewardedVideoAd(options) 接口创建激励视频广告实例，建议提前创建好广告实例，在需要展示的时候直接调用实例的 show 方法展示即可。

// 创建激励视频广告实例，建议提前创建好广告实例，在需要展示的时候直接调用实例的 show 方法展示即可
const rewardedVideoAd = sdkInstance.createRewardedVideoAd({
  adUnitId: "yourAdUnitId", // 请联系相关运营人员于快手开放平台后台创建并生成
  adPlatform: "kuaishou",
  adPosition: "",
  onClose: function(response) {
    console.log(response.code); // 响应状态码，此处为0
    console.log(response.data); // 响应数据
    console.log(response.data.isCompleted); // 广告任务是否已完成，true 表示已完成，false 表示未完成
  },
  onError: function(error) {
    console.log(error.code); // 响应状态码，此处为非0状态码
    console.log(error.message); // 错误消息
  }
});

// 先判断 rewardedVideoAd 是否存在再使用
// 因为当用户的客户端基础库版本过低时，调用 sdkInstance.createRewardedVideoAd 接口将返回 undefined
// 若传递了 adMultiton、adMultitonRewardTimes、adMultitonRewardMsg 等参数，且用户的客户端基础库版本低于 11.11.40，调用 sdkInstance.createRewardedVideoAd 接口也将返回 undefined
if (rewardedVideoAd) {
  // 展示激励视频广告
  rewardedVideoAd.show(options?, callback?);

  // 销毁激励视频广告实例
  rewardedVideoAd.destroy();
}

最低基础库版本要求

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

若传递了 adMultiton、adMultitonRewardTimes、adMultitonRewardMsg 等参数，则要求用户客户端基础库版本不低于 11.11.40！

注意事项

默认情况下，游戏内创建的激励视频广告组件实例是一个全局单例，重复打开并观看广告时，无需多次创建，可直接使用首次创建的广告组件实例，调用实例的 show 方法展示即可！

创建激励视频广告实例的参数说明如下表所示：

选项 类型 必填 默认值 说明
adUnitId string 是 -- 广告位ID，请联系相关运营人员于快手开放平台后台创建并生成
adMultiton boolean 否 false 是否开启再得广告模式（仅支持安卓系统的快手或快手极速版）
adMultitonRewardTimes number 否 -- 额外观看广告的次数，合法的数据范围为 1-4，仅在 adMultiton 为 true 时必填
adMultitonRewardMsg string[] 否 -- 再得广告的奖励文案，用户每看完一个广告都会展示，如“再看1个获得xxxx”，其中 xxxx 就 adMultitonRewardMsg 中的文案，按顺序依次展示，单个文案最大长度为 7，仅在 adMultiton 为 true 时必填
adPlatform string 否 kuaishou 广告平台
adPosition string 否 -- 广告展示位置，预留参数，有就填写
onClose function 否 --

关闭激励视频广告时的回调函数，返回值中的 isCompleted 属性标记了用户是否已完成广告任务：

  • true - 用户已完成广告任务，可以下发游戏奖励
  • false - 用户未完成广告任务，不可下发游戏奖励
onError function 否 -- 激励视频广告出错时的回调函数，返回值为当前错误信息

调用 sdkInstance.createRewardedVideoAd(options) 接口，将返回一个激励视频广告实例，默认是隐藏的，需要调用 rewardedVideoAd.show() 方法将其展示；具体实例方法如下表所示：

方法 类型 说明
show function 用于展示激励视频广告
destroy function 用于销毁激励视频广告实例

# 展示激励视频广告

调用实例的 show 方法，可展示激励视频广告，一般从屏幕下方推入。

// 先判断 rewardedVideoAd 是否存在再使用
// 因为当用户的客户端基础库版本过低时，调用 sdkInstance.createRewardedVideoAd 接口将返回 undefined
// 若传递了 adMultiton、adMultitonRewardTimes、adMultitonRewardMsg 等参数，且用户的客户端基础库版本低于 11.11.40，调用 sdkInstance.createRewardedVideoAd 接口也将返回 undefined
if (rewardedVideoAd) {
  // 广告实例的 show 方法用于展示广告
  rewardedVideoAd.show({ adPosition: "" }, function(showResponse) {
    // 响应状态码 showResponse.code 为 0 时表示展示成功，其他非 0 状态码均表示展示失败
    // 展示失败时，可调用 rewardedVideoAd.load() 尝试手动重新加载
  });
}

实例 show 方法有两个参数：options、callback，均为非必填，具体说明如下表所示：

选项 类型 必填 默认值 说明
options object 否 -- 广告参数
    options.adPosition string 否 -- 广告展示位置，此属性会在展示广告时覆盖 createRewardedVideoAd 接口中设置的属性，并以此进行数据上报
callback function 否 -- 调用 show 方法完成时的回调函数（展示成功或失败均会调用）；回调函数的返回值见下文说明

调用实例 show 方法完成时，其回调函数（展示成功或失败均会调用）的返回值说明如下表所示：

选项 类型 说明
code number 响应状态码，为 0 时表示展示成功，其他非 0 状态码均表示展示失败
data object / null 展示成功时返回相应广告数据（因快手API原因，此处可能为空），失败时返回 null
message string 展示成功或失败时的相应描述信息

# 销毁激励视频广告

调用实例的 destroy 方法，可销毁激励视频广告实例。

// 先判断 rewardedVideoAd 是否存在再使用
// 因为当用户的客户端基础库版本过低时，调用 sdkInstance.createRewardedVideoAd 接口将返回 undefined
// 若传递了 adMultiton、adMultitonRewardTimes、adMultitonRewardMsg 等参数，且用户的客户端基础库版本低于 11.11.40，调用 sdkInstance.createRewardedVideoAd 接口也将返回 undefined
if (rewardedVideoAd) {
  // 销毁激励视频广告实例
  rewardedVideoAd.destroy();
}

# 广告奖励发放

在创建激励视频广告实例时，需设置 onClose 事件回调函数，当关闭事件被触发时，通过事件回调函数的返回值判断是否应该下发相应的广告奖励：

// 创建激励视频广告实例，建议提前创建好广告实例，在需要展示的时候直接调用实例的 show 方法展示即可
const rewardedVideoAd = sdkInstance.createRewardedVideoAd({
  adUnitId: "yourAdUnitId", // 请联系相关运营人员于快手开放平台后台创建并生成
  adPlatform: "kuaishou",
  adPosition: "",
  onClose: function(response) {
    // 用户已完成广告任务，即广告正常播放结束
    if (response.data.isCompleted) {
      // 这里可以通知游戏服务器下发广告奖励
    }
    // 用户未完成广告任务，即广告播放中途退出
    else {
      // 这里可以提示用户尚未完成广告播放
    }
  }
});

如上例所示，onClose 事件回调函数的返回值中，response.data.isCompleted 属性取值如下所示：

  • true - 表示用户已完成广告任务，即广告正常播放结束，此时可以下发广告奖励
  • false - 表示用户未完成广告任务，即广告播放中途退出，此时不可下发广告奖励

# 示例代码

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

/**
* 创建激励视频广告实例；建议提前创建好广告实例，在需要展示的时候直接调用实例的 show 方法展示即可
* @param {Object} options 广告参数
*/
const rewardedVideoAd = sdkInstance.createRewardedVideoAd({
  adUnitId: "yourAdUnitId", // 请联系相关运营人员于快手开放平台后台创建并生成
  adPlatform: "kuaishou",
  adPosition: "",
  onClose: function(response) {
    console.log(response.code); // 响应状态码，此处为0
    console.log(response.data); // 响应数据
    console.log(response.data.isCompleted); // 广告任务是否已完成，true 表示已完成，false 表示未完成
  },
  onError: function(error) {
    console.log(error.code); // 响应状态码，此处为非0状态码
    console.log(error.message); // 错误消息
  }
});

/**
* 用于展示广告
* @param {Object} options 广告参数
* @param {Number} times 广告展示失败后的重试次数
*/
const showRewardedVideoAd = function(options, times) {
  // 先判断 rewardedVideoAd 是否存在再使用
  // 因为当用户的客户端基础库版本过低时，调用 sdkInstance.createRewardedVideoAd 接口将返回 undefined
  // 若传递了 adMultiton、adMultitonRewardTimes、adMultitonRewardMsg 等参数，且用户的客户端基础库版本低于 11.11.40，调用 sdkInstance.createRewardedVideoAd 接口也将返回 undefined
  if (!rewardedVideoAd) {
    return sdkInstance.modal.message("暂不支持激励视频广告");
  }

  // 广告实例的 show 方法用于展示广告，默认是隐藏的
  rewardedVideoAd.show(options, function(response) {
    // 响应状态码 response.code 为 0 时表示展示成功
    if (response.code == 0) {
      console.log("广告展示成功");
    }
    // 其他非 0 状态码均表示展示失败
    else {
      // 重试次数大于0时进行重试
      if (times > 0) {
        showRewardedVideoAd(options, times--);
      }
      // 反之弹出错误消息 response.message，亦可自定义失败提示
      else {
        sdkInstance.modal.message(response.message);
      }
    }
  });
};

/**
* 展示广告，例如点击游戏内按钮时调用此方法进行展示
* @param {Object} options 广告参数
* @param {Number} times 广告展示失败后的重试次数
*/
showRewardedVideoAd({ adPosition: "" }, 3);

# 插屏广告

# 创建插屏广告

调用 sdkInstance.createInterstitialAd(options) 接口创建插屏广告实例，建议提前创建好广告实例，在需要展示的时候直接调用实例的 show 方法展示即可。

// 创建插屏广告实例，建议提前创建好广告实例，在需要展示的时候直接调用实例的 show 方法展示即可
const interstitialAd = sdkInstance.createInterstitialAd({
  adUnitId: "yourAdUnitId", // 请联系相关运营人员于快手开放平台后台创建并生成
  adPlatform: "kuaishou",
  adPosition: "",
  onClose: function(response) {
    console.log(response.code); // 响应状态码，此处为0
    console.log(response.data); // 响应数据
  },
  onError: function(error) {
    console.log(error.code); // 响应状态码，此处为非0状态码
    console.log(error.message); // 错误消息
  }
});

// 先判断 interstitialAd 是否存在再使用
// 因为当用户的客户端基础库版本过低时，调用 sdkInstance.createInterstitialAd 接口将返回 undefined
if (interstitialAd) {
  // 展示插屏广告
  interstitialAd.show(options?, callback?);

  // 销毁插屏广告实例
  interstitialAd.destroy();
}

最低基础库版本要求

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

注意事项

游戏内创建插屏广告组件时，每次调用该方法创建插屏广告都会返回一个全新的实例！

创建插屏广告实例的参数说明如下表所示：

选项 类型 必填 默认值 说明
adUnitId string 是 -- 广告位ID，请联系相关运营人员于快手开放平台后台创建并生成
adPlatform string 否 kuaishou 广告平台
adPosition string 否 -- 广告展示位置，预留参数，有就填写
onClose function 否 -- 关闭插屏广告时的回调函数，返回值为当前广告数据
onError function 否 -- 插屏广告出错时的回调函数，返回值为当前错误信息

调用 sdkInstance.createInterstitialAd(options) 接口，将返回一个插屏广告实例，默认是隐藏的，需要调用 interstitialAd.show() 方法将其展示；具体实例方法如下表所示：

方法 类型 说明
show function 用于展示插屏广告
destroy function 用于销毁插屏广告实例

# 展示插屏广告

调用实例的 show 方法，可展示插屏广告。

// 先判断 interstitialAd 是否存在再使用
// 因为当用户的客户端基础库版本过低时，调用 sdkInstance.createInterstitialAd 接口将返回 undefined
if (interstitialAd) {
  // 广告实例的 show 方法用于展示广告
  interstitialAd.show({ adPosition: "" }, function(showResponse) {
    // 响应状态码 showResponse.code 为 0 时表示展示成功，其他非 0 状态码均表示展示失败
  });
}

实例 show 方法有两个参数：options、callback，均为非必填，具体说明如下表所示：

选项 类型 必填 默认值 说明
options object 否 -- 广告参数
    options.adPosition string 否 -- 广告展示位置，此属性会在展示广告时覆盖 createInterstitialAd 接口中设置的属性，并以此进行数据上报
callback function 否 -- 调用 show 方法完成时的回调函数（展示成功或失败均会调用）；回调函数的返回值见下文说明

调用实例 show 方法完成时，其回调函数（展示成功或失败均会调用）的返回值说明如下表所示：

选项 类型 说明
code number 响应状态码，为 0 时表示展示成功，其他非 0 状态码均表示展示失败
data object / null 展示成功时返回相应广告数据（因快手API原因，此处可能为空），失败时返回 null
message string 展示成功或失败时的相应描述信息

# 销毁插屏广告

调用实例的 destroy 方法，可销毁插屏广告实例。

// 先判断 interstitialAd 是否存在再使用
// 因为当用户的客户端基础库版本过低时，调用 sdkInstance.createInterstitialAd 接口将返回 undefined
if (interstitialAd) {
  // 销毁插屏广告实例
  interstitialAd.destroy();
}

# 示例代码

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

/**
* 创建插屏广告实例；建议提前创建好广告实例，在需要展示的时候直接调用实例的 show 方法展示即可
* @param {Object} options 广告参数
*/
const interstitialAd = sdkInstance.createInterstitialAd({
  adUnitId: "yourAdUnitId", // 请联系相关运营人员于快手开放平台后台创建并生成
  adPlatform: "kuaishou",
  adPosition: "",
  onClose: function(response) {
    console.log(response.code); // 响应状态码，此处为0
    console.log(response.data); // 响应数据
  },
  onError: function(error) {
    console.log(error.code); // 响应状态码，此处为非0状态码
    console.log(error.message); // 错误消息
  }
});

/**
* 用于展示广告
* @param {Object} options 广告参数
* @param {Number} times 广告展示失败后的重试次数
*/
const showInterstitialAd = function(options, times) {
  // 先判断 interstitialAd 是否存在再使用
  // 因为当用户的客户端基础库版本过低时，调用 sdkInstance.createInterstitialAd 接口将返回 undefined
  if (!interstitialAd) {
    return sdkInstance.modal.message("暂不支持插屏广告");
  }

  // 广告实例的 show 方法用于展示广告，默认是隐藏的
  interstitialAd.show(options, function(response) {
    // 响应状态码 response.code 为 0 时表示展示成功
    if (response.code == 0) {
      console.log("广告展示成功");
    }
    // 其他非 0 状态码均表示展示失败
    else {
      // 重试次数大于0时进行重试
      if (times > 0) {
        showInterstitialAd(options, times--);
      }
      // 反之弹出错误消息 response.message，亦可自定义失败提示
      else {
        sdkInstance.modal.message(response.message);
      }
    }
  });
};

/**
* 展示插屏广告，例如在游戏关卡结束或暂停时调用
* @param {Object} options 广告参数
* @param {Number} times 广告展示失败后的重试次数
*/
showInterstitialAd({ adPosition: "" }, 3);

# Banner广告

# 创建Banner广告

调用 sdkInstance.createBannerAd(options) 接口创建Banner广告实例，建议提前创建好广告实例，在需要展示的时候直接调用实例的 show 方法展示即可。

// 创建Banner广告实例，建议提前创建好广告实例，在需要展示的时候直接调用实例的 show 方法展示即可
const bannerAd = sdkInstance.createBannerAd({
  adUnitId: "yourAdUnitId", // 请联系相关运营人员于快手开放平台后台创建并生成
  adIntervals: 30, // 广告自动刷新时间间隔，单位为秒，默认30秒
  adPlatform: "kuaishou",
  adPosition: "",
  style: {
    top: 0,       // Banner广告组件的上边距
    left: 0,      // Banner广告组件的左边距
    width: 300,   // Banner广告组件的宽度
    height: 150   // Banner广告组件的高度
  },
  onLoad: function(response) {
    console.log(response.code); // 响应状态码，此处为0
    console.log(response.data); // 响应数据
  },
  onClose: function(response) {
    console.log(response.code); // 响应状态码，此处为0
    console.log(response.data); // 响应数据
  },
  onError: function(error) {
    console.log(error.code); // 响应状态码，此处为非0状态码
    console.log(error.message); // 错误消息
  },
  onResize: function(response) {
    console.log(response.data.width); // Banner广告的实际宽度
    console.log(response.data.height); // Banner广告的实际高度
  }
});

// 先判断 bannerAd 是否存在再使用
// 因为当用户的客户端基础库版本过低时，调用 sdkInstance.createBannerAd 接口将返回 undefined
if (bannerAd) {
  // 展示Banner广告
  bannerAd.show(options?, callback?);

  // 隐藏Banner广告
  bannerAd.hide();

  // 销毁Banner广告实例
  bannerAd.destroy();
}

最低基础库版本要求

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

注意事项

游戏内创建Banner广告组件时，每次调用该方法创建Banner广告都会返回一个全新的实例，全局只会存在一个Banner广告实例！

创建Banner广告实例的参数说明如下表所示：

选项 类型 必填 默认值 说明
adUnitId string 是 -- 广告位ID，请联系相关运营人员于快手开放平台后台创建并生成
adIntervals number 否 -- 广告自动刷新时间间隔，单位为秒，参数值必须大于等于 30，该参数不传入时则不会自动刷新
adPlatform string 否 kuaishou 广告平台
adPosition string 否 -- 广告展示位置，预留参数，有就填写
style object 是 -- 广告组件的样式配置
    style.top number 是 -- 广告组件的上边距
    style.left number 是 -- 广告组件的左边距
    style.width number 是 -- 广告组件的宽度
    style.height number 是 -- 广告组件的高度
onLoad function 否 -- Banner广告加载成功时的回调函数
onClose function 否 -- 关闭Banner广告时的回调函数
onError function 否 -- Banner广告出错时的回调函数，返回值为当前错误信息
onResize function 否 -- Banner广告尺寸变化时的回调函数，返回值包含实际的宽度和高度

调用 sdkInstance.createBannerAd(options) 接口，将返回一个Banner广告实例，默认是隐藏的，需要调用 bannerAd.show() 方法将其展示；具体实例方法如下表所示：

方法 类型 说明
show function 用于展示Banner广告
hide function 用于隐藏Banner广告
destroy function 用于销毁Banner广告实例

# 展示Banner广告

调用实例的 show 方法，可展示Banner广告。

// 先判断 bannerAd 是否存在再使用
// 因为当用户的客户端基础库版本过低时，调用 sdkInstance.createBannerAd 接口将返回 undefined
if (bannerAd) {
  // 广告实例的 show 方法用于展示广告
  bannerAd.show({ adPosition: "" }, function(showResponse) {
    // 响应状态码 showResponse.code 为 0 时表示展示成功，其他非 0 状态码均表示展示失败
  });
}

实例 show 方法有两个参数：options、callback，均为非必填，具体说明如下表所示：

选项 类型 必填 默认值 说明
options object 否 -- 广告参数
    options.adPosition string 否 -- 广告展示位置，此属性会在展示广告时覆盖 createBannerAd 接口中设置的属性，并以此进行数据上报
callback function 否 -- 调用 show 方法完成时的回调函数（展示成功或失败均会调用）；回调函数的返回值见下文说明

调用实例 show 方法完成时，其回调函数（展示成功或失败均会调用）的返回值说明如下表所示：

选项 类型 说明
code number 响应状态码，为 0 时表示展示成功，其他非 0 状态码均表示展示失败
data object / null 展示成功时返回相应广告数据（因快手API原因，此处可能为空），失败时返回 null
message string 展示成功或失败时的相应描述信息

# 隐藏Banner广告

调用实例的 hide 方法，可隐藏Banner广告；隐藏后广告不会销毁，可以再次调用 show 方法展示。

// 先判断 bannerAd 是否存在再使用
// 因为当用户的客户端基础库版本过低时，调用 sdkInstance.createBannerAd 接口将返回 undefined
if (bannerAd) {
  // 广告实例的 hide 方法用于隐藏广告
  bannerAd.hide();
}

# 销毁Banner广告

调用实例的 destroy 方法，可销毁Banner广告实例。

// 先判断 bannerAd 是否存在再使用
// 因为当用户的客户端基础库版本过低时，调用 sdkInstance.createBannerAd 接口将返回 undefined
if (bannerAd) {
  // 销毁Banner广告实例
  bannerAd.destroy();
}

# 示例代码

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

/**
* 创建Banner广告实例；建议提前创建好广告实例，在需要展示的时候直接调用实例的 show 方法展示即可
* @param {Object} options 广告参数
*/
const bannerAd = sdkInstance.createBannerAd({
  adUnitId: "yourAdUnitId", // 请联系相关运营人员于快手开放平台后台创建并生成
  adIntervals: 30,
  adPlatform: "kuaishou",
  adPosition: "",
  style: {
    top: 0,
    left: 0,
    width: 300,
    height: 150
  },
  onLoad: function(response) {
    console.log(response.code); // 响应状态码，此处为0，表示加载成功
  },
  onClose: function(response) {
    console.log(response.code); // 响应状态码，此处为0
    console.log(response.data); // 响应数据
  },
  onError: function(error) {
    console.log(error.code); // 响应状态码，此处为非0状态码
    console.log(error.message); // 错误消息
  },
  onResize: function(response) {
    console.log(response.data.width); // Banner广告的实际宽度
    console.log(response.data.height); // Banner广告的实际高度
  }
});

/**
* 用于展示Banner广告
* @param {Object} options 广告参数
*/
const showBannerAd = function(options, times) {
  // 先判断 bannerAd 是否存在再使用
  // 因为当用户的客户端基础库版本过低时，调用 sdkInstance.createBannerAd 接口将返回 undefined
  if (!bannerAd) {
    return sdkInstance.modal.message("暂不支持Banner广告");
  }

  // 广告实例的 show 方法用于展示广告，默认是隐藏的
  bannerAd.show(options, function(response) {
    // 响应状态码 response.code 为 0 时表示展示成功
    if (response.code == 0) {
      console.log("Banner广告展示成功");
    }
    // 其他非 0 状态码均表示展示失败
    else {
      // 重试次数大于0时进行重试
      if (times > 0) {
        showBannerAd(options, times--);
      }
      // 反之弹出错误消息 response.message，亦可自定义失败提示
      else {
        sdkInstance.modal.message(response.message);
      }
    }
  });
};

/**
* 用于隐藏Banner广告
*/
const hideBannerAd = function() {
  // 先判断 bannerAd 是否存在再使用
  // 因为当用户的客户端基础库版本过低时，调用 sdkInstance.createBannerAd 接口将返回 undefined
  if (!bannerAd) {
    return sdkInstance.modal.message("暂不支持Banner广告");
  }

  // 广告实例的 hide 方法用于隐藏广告，默认是隐藏的
  bannerAd.hide();
  console.log("Banner广告隐藏成功");
};

/**
* 展示Banner广告，例如在游戏主界面时调用此方法进行展示
* @param {Object} options 广告参数
* @param {Number} times 广告展示失败后的重试次数
*/
showBannerAd({ adPosition: "" }, 3);

/**
* 隐藏Banner广告，例如开始游戏时调用此方法进行隐藏
*/
hideBannerAd();
Last Updated: 2025/12/29 17:34:01

← 游戏对局回放（选接） →