游戏沙盒使用指南
欢迎使用Playol沙盒测试！这是一个在线调试环境，您无需复杂的配置，只需上传您的游戏包，即可在一个集成的界面中完成所有SDK功能的测试与调试，极大提升开发效率。
🎈一、前置条件
在开始沙盒测试前，请确保您已完成以下步骤：
- 注册账号
您必须拥有一个有效的Playol开发者账号。 - 集成SDK
已按照Playol SDK使用文档将最新版本的SDK集成到您的游戏项目中。 - 配置测试环境
在您的代码中，已将SDK设置为测试模式。
🗂️二、界面导览
上传游戏后，您将看到如下界面：
左侧栏 - SDK数据监控面板
实时显示SDK调用日志、成功/失败状态、返回数据等。这是您排查问题的核心工具。中间区域 - 游戏预览窗口
您上传的游戏将在此处运行，就像在真机环境中一样。右侧栏 - SDK自动检测面板
平台会自动扫描您游戏包中已集成的SDK模块，并显示其状态（如：✅ appKey已经初始化）。
🥊三、快速开始：四步进入测试
进入平台
- 登录Playol开发者平台。
- 在左侧菜单栏中找到并点击 “沙盒测试”。
上传游戏包
- 在沙盒测试页面，您会看到一个清晰的拖放区域。
- 将您的游戏安装包直接拖入该区域，或点击该区域从本地选择。
- 点击提交系统会自动开始上传和解析。
注意：当前页面会显示文件数量，每个文件都有独立的上传状态，对于上传失败的文件您可以选择批量上传，也可选择单独文件上传
等待环境初始化
上传完成后，系统会自动为您完成以下工作：
- 在后台创建一个临时的测试游戏项目。
- 生成专用的沙盒测试环境配置。
- 启动一个模拟器容器来运行您的游戏。
- 自动检测您集成的SDK模块。
开始交互测试
环境准备就绪后，界面将分为左、中、右三栏。您现在可以：
- 在中间的游戏窗口中直接操作您的游戏。
- 触发SDK功能（如登录、上报成就等）。
- 在左侧栏实时观察对应的SDK调用日志和数据。
- 在右侧栏确认所有SDK模块是否被正确识别。
🧩四、核心功能模块测试说明
👤 用户模块测试
测试内容
- 验证SDK是否能正确注入用户信息、能否成功拉取最新数据、以及是否能监听用户变更事件。
操作流程
- 游戏加载完成后，在浏览器控制台中输入
console.log(window.playolSDK.user.userInfo)，检查左侧栏的SDK数据监控面板是否打印出了正确的用户信息对象（包含 userId, userName, avatar, sex, userType）。 - 在您的游戏中调用
await window.playolSDK.user.getUserInfo()，在左侧栏观察异步请求日志，确认其返回的数据与缓存的userInfo一致。
🎮 游戏模块测试
测试内容
- 验证游戏行为事件（加载、运行、状态）上报、以及成就、排行榜、资产数据的同步功能。
操作流程
- 资源加载： 在游戏开始加载时调用
window.playolSDK.game.loadingStart()，加载结束时调用loadingStop()。在左侧栏观察是否有对应的上报记录。 - 游戏状态： 进入游戏主场景时调用
playStart()，暂停时调用playStop()。在左侧栏确认状态上报成功。 - 成就系统： 在达成某个成就条件时（如通关），调用
window.playolSDK.game.syncAchievement('ACHIEVEMENT_KEY', 1)。在左侧栏检查上报数据是否正确。 - 排行榜： 在得分改变或关卡结束时，调用
window.playolSDK.game.syncRankData(1000)。在左侧栏确认分数值已成功上报。 - 资产同步： 在玩家获得奖励或消耗道具时，调用
window.playolSDK.game.syncAssets('gold', 500)。在左侧栏查看上报的资产键名和数值是否正确。
📊 数据模块测试
测试内容
- 验证用户游戏数据（存档、配置）的设置、获取、删除及云同步功能。
操作流程
- 数据设置 (Set)： 在游戏中操作后（如更改设置、进入新关卡），调用
window.playolSDK.data.set(...)。在左侧栏观察是否有成功的设置操作日志。 - 获取指定数据 (Get)： 调用
const data = await window.playolSDK.data.get('currentLevel')。在左侧栏确认是否发起了获取请求并成功返回了之前设置的值。 - 获取所有数据 (GetAll)： 调用
await window.playolSDK.data.getAll()。在左侧栏检查是否返回了一个包含所有已设置键值对的完整对象。 - 数据删除 (Del)： 调用
window.playolSDK.data.del('musicOn')。随后再次调用get('musicOn')，在左侧栏确认该键值已被成功删除（返回 null 或 undefined）。 - 清理测试: 测试结束后，可调用
clear()方法清空测试数据，为下一次测试准备一个干净的环境。
📺 广告模块测试
测试内容
- 验证激励视频广告和普通插页广告的触发、回调以及广告拦截检测功能。
操作流程
激励广告测试
- 在游戏中点击触发激励广告的按钮（如“看广告得金币”），调用
window.playolSDK.ad.openRewardAd({...})。 - 在左侧栏观察广告流程日志：beforeAd 被调用 -> 观看测试广告 -> 根据观看结果，触发 adViewed（完整观看）或 adDismissed（跳过）回调 -> 最终一定会触发 afterAd 回调。
- 重点检查
afterAd回调返回的res.status和res.msg，并根据状态（1为成功）在您的游戏中发放奖励。
插页广告测试
- 在游戏自然中断点（如关卡结束、暂停时），调用
window.playolSDK.ad.openNormalAd({...})。 - 在左侧栏观察 beforeAd 和 afterAd 回调日志，确认广告展示流程完成。
广告拦截检测
- 调用
const isBlocked = await window.playolSDK.ad.hasAdblock()。 - 在左侧栏查看返回的检测结果，并测试您游戏中针对拦截用户的提示逻辑。
🤝 邀请模块测试
测试内容
- 验证邀请链接的创建、分享以及读取邀请参数的功能。
操作流程
创建邀请链接
- 在游戏中调用
const link = await window.playolSDK.invite.createInviteLink({ roomId: 'testRoom123', source: 'test' })。 - 在左侧栏观察生成的邀请短链日志，并检查其是否成功返回。您可以复制此链接在浏览器中打开进行下一步测试。
使用内置邀请UI
- 调用
showInviteButton方法，测试平台内置的分享弹窗UI是否能正常调起和显示。
读取邀请参数（被邀请端）
- 新开浏览器标签页，粘贴上一步生成的邀请链接并访问。
- 游戏加载后，在浏览器控制台或您的游戏代码中读取
window.playolSDK.invite.inviteParams。 - 在左侧栏的数据监控面板中，检查是否成功注入了邀请参数（如 roomId: 'testRoom123'）。您的游戏逻辑应能正确读取这些参数并执行相应操作（如自动加入房间）。
🌐 国际化配置测试
测试内容
- 验证游戏是否能正确获取并应用由平台注入的语言环境配置。
操作流程
获取当前语言
- 游戏初始化后，立即调用
const lang = window.playolSDK.i18n.language。 - 在左侧栏检查获取到的语言标识符（如 'en', 'th', 'zh'）是否正确。
应用语言配置
- 观察您的游戏界面（UI文本 、菜单等）是否根据获取到的
lang值切换到了对应的语言包。
语言切换测试（模拟）
- 您可以通过直接修改平台浏览器地址栏URL的方式或者在语言切换下拉菜单来模拟不同语言的用户访问。
- 刷新页面后，检查游戏语言是否已切换至目标语言（如泰语、越南语）。
📢五、如何查看测试结果与排查问题
实时日志（左侧栏）
这是您最重要的调试工具。所有SDK与平台的交互都会在这里实时打印，包括：
- API 请求
调用了哪个接口，发送了什么参数。 - API 响应
平台返回了哪些数据（成功或错误）。 - 回调通知
SDK给游戏的回调（如广告奖励发放）。
当功能失败时，首先检查此处是否有错误代码和错误信息。
自动检测报告（右侧栏）
此面板直观显示了您游戏包集成了哪些SDK模块。如果某个您认为已集成的模块显示“未检测到”，请检查：
- SDK初始化代码是否正确。
- 游戏包是否是最新集成的版本。
📦六、常见问题解答（FAQ）
Q: 上传游戏包后无法启动或显示白屏怎么办？
A: 请检查您的游戏包是否完整，并确认它能在标准的Android模拟器上正常运行。白屏通常是游戏本身兼容性问题。
Q: 为什么左侧栏看不到任何SDK日志？
A: 这通常意味着SDK未能成功初始化或您的游戏未正确调用SDK方法。请检查：
- 您的代码是否已调用
window.playolSDK.initSDKParam(...)方法。 - 上传的包是否是集成了SDK测试版本
Q: 测试数据会被保留吗？
A: 不会。每次关闭测试页面后，所有临时数据都会被清除。每次重新上传都是一个全新的、干净的环境。
Q: 我可以同时测试多个游戏吗？
A: 目前平台一次仅支持运行一个游戏实例。测试新游戏时需要重新上传。