快速开始

本页将引导你如何在游戏中正确初始化 Playol SDK，并完成关键参数配置。

Playol SDK 是一套为 HTML5 游戏量身打造的集成解决方案，帮助你在零服务端开发的前提下，快速完成用户系统、支付、数据存储、广告调用、国际化等功能对接。

你只需要在游戏入口处进行一次初始化，即可接入平台能力。

---

📦 一、引入 SDK 脚本

<script async src="https://static.playol.com/sdk/playol-sdk-v2.0.5.js"></script>

SDK 为平台异步加载方式，引入后将自动在 window.playolSDK 上挂载全局实例。

---

🚀 二、判断 SDK 是否加载成功

为避免因网络异常或加载失败导致游戏逻辑报错，建议使用如下判断代码：

<script>
if (window.playolSDK === undefined) {
  throw new Error('Playol SDK 加载失败！请检查网络或脚本链接');
}
</script>

---

⚙️ 三、注入初始化参数

Playol SDK 在加载完成后，需要通过 initSDKParam 方法注入一些基础配置，例如 appKey、testMode 等。

<script>
window.playolSDK.initSDKParam({
  appKey: 'your-app-key',       // 游戏在平台上的唯一标识
  testMode: 'on'                // 是否开启测试模式（默认关闭）
})
</script>

参数说明：

参数名	类型	是否必填	说明
appKey	string	✅ 必填	游戏唯一标识，从平台分发获取
testMode	string	❌ 选填	可选值为 'on' / 'off'，默认关闭

💡 测试模式用于本地开发调试，可绕过部分平台校验逻辑，线上环境请务必关闭。

---

✅ 四、SDK 自动完成的能力（初始化后自动生效）

初始化完成后，SDK 会自动完成以下行为：

• 获取并监听用户信息变更；
• 同步平台语言环境用于国际化；
• 注入邀请参数、支付参数、广告状态；
• 初始化本地数据同步机制（data模块）；
• 注册事件钩子用于游戏行为埋点。

你可以直接通过如下方式获取平台注入参数：

const appSecret = window.playolSDK.appSecret
const channelID = window.playolSDK.channelID

📘 字段说明：

字段名	类型	说明
appSecret	string	平台提供的 SDK 公钥，用于 SDK 与平台的信任校验与数据验证。 一般用于平台端鉴权、加密传输场景，前端仅需读取，无需处理。
channelID	string	广告渠道标识，用于追踪当前用户是从哪个广告平台/渠道进入游戏。 此字段由平台根据流量来源自动注入，可用于数据归因与分账分析等用途。

⚠️ 这两个字段均为平台自动注入，只读不可修改，可根据需要传给后端做进一步校验。

---

🛠️ 五、建议的加载顺序（推荐写法）

以下是推荐的初始化代码结构，确保加载顺序、异常兜底和参数注入完整：

<script async src="https://static.playol.com/sdk/playol-sdk-v2.0.5.js"></script>

<script>
  window.addEventListener('load', () => {
    if (window.playolSDK === undefined) {
      throw new Error('Playol SDK 加载失败！');
    }

    // 初始化平台参数
    window.playolSDK.initSDKParam({
      appKey: 'your-app-key',
      testMode: 'on'
    });

    // 获取当前用户信息（可选）
    const userInfo = window.playolSDK.user.userInfo;
    console.log('用户信息:', userInfo);
  });
</script>

---

📌 温馨提示

• 请务必确保 SDK 脚本在 HTML 最外层 head 或 body 中引用，避免被打包工具遗漏；
• 如果你使用 Vue/React/Uniapp 等框架，请在主入口文件中判断 window.playolSDK 是否存在；
• 所有 Playol SDK API 均可通过 window.playolSDK.* 调用，文档中的模块会继续提供详细说明。

---

接下来你可以继续阅读：
👉 国际化配置 | 用户模块 | 支付模块