# 快手小游戏JSSDK

# 接入必读

发行SDK需要接管小游戏用户登录行为，cp必须按照STEP 4: 接入登录调用SDK提供的方法进行登录。SDK登录成功后会返回发行用户id、小游戏用户openid、小游戏用户unionid等信息。特别注意，cp研发不要再调用ks.login进行登录，否则会造成发行SDK登录失败。
用户观看广告行为数据上报的准确性会直接影响小游戏发行的效果，请cp研发同学务必按照STEP 5: 接入广告上报行为上报完所有类型广告的创建、加载、展示、关闭、隐藏事件。
cp需要确保接入发行SDK的游戏不会自主回传广告事件给快手磁力引擎，否则会造成投放数据紊乱，造成投放损失。
对于发行SDK未代理的快手小游戏官方api，请cp研发同学参照快手小游戏官方开发文档 (opens new window)直接调用官方api。

# STEP 1：接入准备

# 添加服务器域名

在快手小游戏后台添加https://api.mcfrogtech.com和https://api.shxqwl.com到request合法域名。

# 提供小游戏信息

提供小游戏名（AppName）、小游戏ID（AppID）和密钥（AppSecret）给发行对接技术人员，为了安全起见，SDK会将密钥存储在服务端，不会在客户端存储。AppID和AppSecret在小游戏开发者后台获取。

# CP提供历史用户已注册激活校验接口

如果待接入的小游戏不是一个新包或者CP已经进行过投放，为了保证投放数据准确性，CP需要提供可用来校验小游戏用户是否在CP投放期内已经完成注册激活过程的API接口，API接口需要满足以下条件：

# API名

CP可以自定义API名，将API名提供给发行对接技术人员。

# 调用方式

GET

# 请求参数

参数	类型	默认值	必填	说明
open_id	string	无	是	小游戏用户open_id

# 响应参数

参数	类型	默认值	必填	说明
registered	boolean	无	是	是否注册激活，true表示已经注册激活，false表示没有注册激活。

# STEP 2: 下载集成SDK

# 下载SDK

点击下载最新版本 (opens new window)

# 集成SDK

下载的SDK压缩包提供了如下多种SDK，cp研发可以根据自己的研发场景选取合适的SDK集成。

压缩文件目录	SDK类型	适用场景
esm	es6模块化的SDK	小游戏打包构建工具支持es6模块的场景，通过es6模块导入语法`import`导入SDK。如果在Cocos 3中使用该SDK，需要将`index.js`改名为`index.mjs`后以携带文件名后缀的方式导入，例如`import ksAppSDK from 'index.mjs'`。SDK模块导出的各类变量可以查看目录下的`index.d.ts`文件。
cjs	commonjs模块化的SDK	小游戏打包构建工具支持commonjs模块的场景，通过commonjs模块导入语法`require`导入SDK。SDK模块导出的各类变量可以查看目录下的`index.d.ts`文件。
global	全局环境运行的SDK	在全局环境中引入SDK，需要小游戏开发工具支持全局运行脚本的能力。SDK会在全局对象`window`上挂载`McfrogtechMiniSDK`对象，该对象包含SDK实例`ksAppSDK`以及各类枚举类型，cp研发可以参考目录下的`mcfrogetch.d.ts`文件查看包含的具体内容。如果使用`ts`作为开发语言，为了防止`ts`类型报错，可以把目录中的`mcfrogetch.d.ts`文件拖到项目根目录下。

# STEP 3: 初始化SDK

# 方法定义

interface InitOptions {
  appId: string;
}

function init(options: InitOptions): void;

# 参数介绍

属性	类型	默认值	必填	说明
appId	string	无	是	小游戏appId

# 返回值介绍

void。

# 调用示例

ksAppSDK.init({
  appId: <your ks minigame appId>,
});

# STEP 4: 接入登录

# 方法定义

interface LoginData {
  user_id: string;
  open_id: string;
  union_id: string;
}

function login(): Promise<LoginData>

# 参数介绍

void。

# 返回值介绍

返回一个Promise对象，Promise对象返回值包含的属性说明如下：

属性	类型	默认值	必填	说明
user_id	string	无	是	发行平台定义的用户id。CP研发可以用来映射业务用户id。
open_id	string	无	是	小游戏用户openid。
union_id	string	无	是	小游戏用户unionid。

# 调用示例

ksAppSDK.login().then(({ user_id, open_id, union_id }) => {
  console.log(user_id, open_id, union_id);
}).catch((e) => {
  console.error(e);
});

# STEP 5: 接入广告行为上报

为了更好地帮助小游戏进行推广，需要CP方上报用户广告关键行为给SDK。

# 方法定义

enum KsAdTraceName {
  // 创建广告
  CreateAd = 'create_ad',
  // 加载广告
  LoadAd = 'load_ad',
  // 曝光广告
  ShowAd = 'show_ad',
  // 关闭广告
  CloseAd = 'close_ad',
  // 隐藏广告
  HideAd = 'hide_ad'
}

enum KsAdType {
  // 激励视频广告
  RewardedVideo = 'rewarded_video',
  // 插屏广告
  Interstitial = 'interstitial',
  // banner广告
  Banner = 'banner',
}

interface KsAdTraceData {
  // 广告位 id
  unitId: string;
  // 广告类型
  type: KsAdType;
}

function reportAdTrace(traceName: KsAdTraceName, params: KsAdTraceData): Promise<void>;

# 参数介绍

参数	类型	默认值	必填	说明
traceName	KsAdTraceName枚举	无	是	广告行为事件名称，创建、加载、曝光、关闭、隐藏分别对应`create_ad`、`load_ad`、`show_ad`、`close_ad`、`hide_ad`。
params	KsAdTraceData	无	是	广告行为对应数据，`unitId`字段上报广告单元id，`type`字段上报广告类型，取值为`rewarded_video`（激励视频广告）、`interstitial`（插屏广告）、`banner`（banner广告）。

# 返回值介绍

Promise<void>。

# 调用示例

尽量上报全创建、加载、曝光、关闭、隐藏这五类事件，以便于精确的分析广告行为，更有利于投放。

ksAppSDK.reportAdTrace(KsAdTraceName.CreateAd, {
  unitId: 'testunitId',
  type: KsAdType.RewardedVideo,
}).then(() => {
  console.log('事件上报成功');
}).catch(() => {
  console.error('事件上报失败');
});