邀请模块

本页介绍如何使用 Playol SDK 提供的邀请模块，帮助游戏实现高效分享、精准拉新、组队联机等功能。通过平台托管的短链生成与参数传递机制，开发者无需自建跳转逻辑，即可实现完整的邀请链路闭环，从生成 → 分享 → 跳转 → 参数注入全流程自动完成。

---

📌 一、使用场景

• 玩家邀请好友加入游戏（支持单人或多人联机）
• 活动页面引流拉新（带邀请码、兑换码等）
• 分享房间 ID，实现一键入房/组队匹配
• 基于平台短链系统，追踪来源与绑定关系
• 页面加载时 SDK 自动注入邀请参数，无需解析 URL

---

🧩 二、方法与调用方式

🔗 创建邀请链接

createInviteLink(params)

异步生成一个游戏专属的邀请链接，可携带任意上下文参数

const link = await window.playolSDK.invite.createInviteLink({
  roomId: 'abc123',
  source: 'friend'
})
console.log('生成的邀请链接:', link)

📌 参数说明：

• params 类型为 { [key]: string | number }
• 所有键必须为字符串，值为字符串或数字
• 若格式非法将直接中止调用，避免生成无效链接

---

📤 显示邀请按钮

showInviteButton(params)

调用平台内置邀请弹窗，快速生成并展示邀请链接

const link = await window.playolSDK.invite.showInviteButton({
  event: 'spring2025',
  roomId: 'room-789'
})
console.log('返回的邀请链接:', link)

📌 说明：

• 与 createInviteLink() 接口相同，可传入任意业务参数
• 自动适配移动端 UI 样式，无需自行设计界面

---

📥 获取邀请参数

inviteParams

被邀请用户打开链接后，SDK 会将邀请参数自动注入，可直接读取使用

const params = window.playolSDK.invite.inviteParams
console.log('邀请参数:', params)

📌 说明：

• inviteParams 只包含游戏在创建邀请链接时传入的字段
• 游戏按原始字段名读取即可，无需处理额外逻辑

---

⚙️ 三、参数校验机制

• 传入参数必须为对象，键为字符串，值为字符串或数字；
• 不支持数组、嵌套对象、null、布尔等类型；
• 无效参数将被 SDK 拒绝处理，避免异常数据污染；

---

🛠️ 四、推荐实践场景

场景	推荐方式
玩家邀请好友进房间	createInviteLink(params) + 手动分享按钮
活动/节日引流	showInviteButton(params)
判断是否为邀请跳转用户	判断 inviteParams 是否存在相关字段
获取传入的房间号或活动标识	inviteParams.roomId / inviteParams.event

---

📦 五、常见问题解答

Q: 邀请链接包含哪些参数？

A: 游戏在创建链接时传入的参数会原样注入，无需开发者额外处理，平台相关字段不会暴露给游戏。

Q: 是否支持自定义参数？

A: 支持。开发者可传入任意 key-value 对象作为上下文内容，用于联机、活动、奖励识别等。

Q: 被邀请用户进入后如何获取参数？

A: 通过 window.playolSDK.invite.inviteParams 即可直接获取传入内容。

Q: 用户是否可以多次生成邀请？

A: 可以，每次调用接口生成的短链均为独立链接，支持数据隔离与多渠道投放。

Q: 参数格式错误会怎样？

A: SDK 内部包含校验逻辑，格式不合法将拒绝调用，避免无效数据注入。

---

🔗 相关文档推荐

👉 用户模块 ｜ 游戏模块 ｜ 数据模块 ｜ 支付模块