SDK-基础/通用

如研发自研内购，则不能接入此登录 API，需自研登录 API

说明：SDK 提供了便捷的登录方法，可以自动获取并缓存用户的 openid 和 unionid（需要联系管理员进行appid后端登记）

请勿把游戏业务逻辑强依赖登录回调，以免阻塞游戏正常运行

参数	类型	必填	描述	示例值
isSetConfig	boolean	否	是否允许sdk自动执行setConfig设置用户信息(openid和unionid)，默认为 true	true
useCache	boolean	否	是否缓存并使用用户数据，默认为 true	true

示例代码

try {
  const userData = await sdk.login();
  console.log('登录成功:', userData);
  // userData 包含: { id, openid, unionid }
} catch (error) {
  console.error('登录失败:', error);
}

// 禁用缓存，每次都重新登录，并写入/覆盖本地的登录态storage - 强烈不推荐，除非登录态过期重刷登录态
try {
    const userData = await sdk.login({ useCache: false });
} catch(error) {
    console.error('登录失败:', error);
}

// 仅获取用户数据，不设置到SDK配置中
try {
    const userData = await sdk.login({ isSetConfig: false });
} catch(error) {
    console.error('登录失败:', error);
}

setConfig

setConfig(config: Config): void

说明：用于设置或修改配置

参数	类型	必填	描述	示例值
openid	string	是	用户在小游戏内的 openid （openid必须在此设置）	获取 openid / unionid 如无后台能力请联系我们提供登录接口支持
unionid	string	是	用户在同个开发者账号下的unionid，联系文档管理员进行开放平台绑定，即可自动获取	获取 openid / unionid 如无后台能力请联系我们提供登录接口支持
user_id	string	是	自定义的用户唯一 id。或用户在该小游戏下的角色 id，用于区分多个角色。最小粒度级别的用户 id。没有则传空字符串	'8f7e2eb1-249c-48d1-856c-3fcb05fec0cb'
nickname	string	是	用户在该小游戏下的角色名/ 昵称。没有则传空字符串	'john'
ab_test_id	string	否	用户在参与 AB 实验时，被分配到的 ab_test_id。当参与 AB 实验时必传	'xxxxxx'

SDK 需要在游戏启动时就初始化，而此时用户尚未登录，未获得用户的相关信息，这种情况下可以先初始化 sdk，获得 sdk 实例。当用户登录成功获得 openid 就立即调用 sdk.setConfig() 方法添加配置，补充用户信息，否则上报事件中会没有 openid 等字段信息。

// wx.login登录成功后或本地有缓存，设置相关信息
sdk.setConfig({
  user_id: 'user123',
  openid: 'wx_abcdef',
  unionid: 'union_123456',
  nickname: '小红',
  ab_test_id: 'group_a_homepage_redesign_20250101'
});

sdk.setConfig() 方法可以多次调用，后传入的值将覆盖前者：

// setConfig 多次调用示例：
sdk.setConfig({
    user_id: '456',
    nickname: '小李',
});
sdk.setConfig({
    user_id: 'user111456', // 会覆盖上一次 setConfig 的值
    openid: '789'
});
// 最新的值是：
{
    user_id: 'user111456',
    nickname: '小李',
    openid: '789'
}

getIpLocation（必接）

getIpLocation(): Promise<Record<string, any>>

说明：用于获取玩家网络ip位置信息

使用场景：根据海外隐私合规要求，请在游戏启动时最先调用此方法，当 is_allowed 为 false 时不允许用户访问小游戏，且不允许保存该用户的任何信息至服务器（包括但不限于登录/存档等操作，违规存储海外用户数据的需承担相关责任）。请给于提示弹窗，提示语：【This mini-program is currently unavailable in your region. Thank you for your understanding!】，当用户点击【Confirm】按钮后，请调用 wx.exitMiniProgram() / tt.exitMiniProgram() 接口让用户退出小游戏。

返回：object类型，属性如下：

属性名	类型	说明
is_allowed	boolean	是否为允许访问的ip，true代表该ip的用户可以访问小游戏，false代表不可访问

使用：

sdk.getIpLocation().then(res => {
    console.log(res)
    // {
    //   "is_allowed": true, //是否为允许访问的ip，true代表该ip的用户可以访问小游戏，false代表不可访问
    // }
}).catch(err => {
    console.log(err);
    // {
    //   "is_allowed": true, //当该接口报错时，osdk会返回该字段为true
    //   "raw": {
    //       "code": XXX, //请求错误码
    //       "msg": "", // 错误信息
    //   }
    // }
});

setConfig

getIpLocation（必接）

相关文档

数据验证

自定义事件上报