常见问题解答

本文档解答了有关 Google Play 游戏电脑版 SDK 和发布方面的常见问题。

创收

1. 为什么在添加新的结算密钥或许可密钥后，我的购买流程会失败并显示错误代码 6？

   在 Google Play 的内部缓存在所有服务环境中同步之前，Google Play 管理中心内新生成的许可密钥会在商务后端中经历数小时的缓存和传播延迟。即使您的游戏客户端可以成功查询商品详情，购买请求也会失败并返回错误代码 6，直到同步完成。上传或更新许可密钥后，请等待几个小时，然后再测试购买交易。

2. 我可以在没有后端服务器的情况下使用购买流程吗？

   从安全角度来看，Google 建议使用后端服务器。

   如需了解详情，请参阅在没有后端服务器的情况下进行处理。

   注意：如需在没有后端服务器的情况下处理购买交易，您需要拥有特殊权限。如果您的游戏需要这些权限，请与您的 Google 合作伙伴联系。

3. 集成 Google Play 游戏电脑版 SDK 后，是否允许使用现有的基于 API 的支付系统？

   所有付款都必须由 Google Play 游戏电脑版 SDK 使用 Google Play 结算服务进行处理。您无法在同一游戏中使用现有的基于 API 的支付方式。

4. 如何在开发者模式下消耗购买交易？

   在开发者模式下，请在 3 分钟内消耗购买交易，否则系统会退款。

5. 是否支持定期付款或订阅？

   近期不会，但欢迎您提供具体用例，以便我们将其添加到未来的路线图中。

6. 我的购买调用中出现的结算错误是什么？

   BillingError 是支付结果的响应。LaunchPurchaseFlow 将立即返回，而不会阻塞，但您必须监听回调，以便了解其何时完成并捕获结果。

7. 如何使用客户端购物验证？

   我们建议使用服务器端购买及其验证流程。 如需通过客户端应用处理购买交易，您的游戏必须在许可清单中。如果您的游戏需要访问权限，请与您的 Google 合作伙伴联系。 如需了解详情，请参阅在没有后端服务器的情况下进行处理。

8. 查询商品详情的 API 限制是什么？

   在对 QueryProductDetails API 的单次调用中，最多可以查询 50 件商品。如果超出此限制，您必须将请求拆分为多个调用。

9. 为什么在加载多个商品 SKU 时，商品查询或购买流程会因内部错误而失败？

   重要提示：如果您的游戏在查询商品目录或发起购买交易时遇到付款失败或 BillingError 错误（例如 C++ 中的 BillingError::kError、C# 中的 BillingError.Error，或 Google 桌面服务日志中的 INTERNAL 和 UNAUTHENTICATED 错误），请先检查您的商品查询实现。如果请求未正确分批和限制，较小的测试商品清单通常会在开发者模式下成功，而完整的生产商品清单则会失败。

   一次查询过多商品 SKU，或在短时间内连续调用 C++ 中的 QueryProductDetails 或 Unity 中的 QueryProductDetailsAsync 太多次（例如，在紧密循环中分派数十个批量调用，或为每个批次创建新的 BillingClient 实例），可能会导致本地 IPC 和后端连接过载。当这些连接重置时，商品详情查询会失败，并且您的游戏无法获取启动购买流程所需的优惠令牌。

   为防止在加载目录时出现这些错误，请遵循以下做法：

   • 遵循每次调用支持的商品数量：在单次 QueryProductDetails 或 QueryProductDetailsAsync 调用中查询不超过 50 件商品，并将返回的 ProductDetails 缓存在内存中，而不是重复查询整个商品目录。如需详细了解支持的批处理限制和查询商品详情，请参阅前面的 API 限制问题、显示可供购买的商品（适用于 C++）和查询商品详情（适用于 Unity）。
   • 避免在短时间内连续多次调用 API：请勿同时或连续分派多个商品查询批次，而不进行节奏控制。重复使用单个 BillingClient 实例，序列化请求或将并发限制为一次最多两到三个正在进行的调用，并在连续批次之间添加短暂延迟。
   • 更新到最新版 SDK：从 Play 游戏电脑版 SDK 下载页面将集成更新到最新版 Google Play 游戏电脑版 SDK（C++ 版为 26.9.261.0，Unity 版为 26.9.261.0），以确保您的客户端包含最新的结算和 IPC 稳定性改进。

10. 在结算客户端中调用“查询购买交易”或“启动购买流程”时，需要哪些参数？

    该函数接受 QueryPurchasesContinuation，这是一个具有 std::function<void(QueryPurchasesResult)> 签名的函数回调。回调会将结果以及所有 ProductPurchaseDetails 传递给您。 此信息可在 includes/billing/models.h 文件中的 SDK 头文件中找到。

    生成的 launch_purchase_flow_result 具有 ok() 和 code() 函数。ok() 函数会返回流程是否成功。code() 函数会返回 BillingError 枚举 (includes/billing/enums.h)，该枚举有 10 种可能的错误情况，例如用户取消或网络连接错误。

11. 结算客户端中的启动购买流程是否支持自定义排序？

    在当前的 SDK 设计中，无法传入您自己的载荷。 不过，您可以提供 obfuscated_account_id 和 obfuscated_profile_id 的任意组合。您可以不提供、仅提供一个或同时提供这两个。

    offer_token 字段是必填字段，用于指定用户在结账流程中尝试购买的购买优惠。目前，Google Play 中的每个 SKU 只有一项优惠（例如，以 10 美元的价格购买一件商品）。未来，Play 结算服务团队将提供对多项优惠的支持。

    为确保在购买流程中断时关联元数据，请在启动购买对话框之前将元数据存储在后端服务器上，并将其与用户的账号 ID、所购 SKU 和当前时间戳相关联。如需了解详情，请参阅将购买交易与内部数据相关联。

12. 从使用 OAuth 的 Google 结算服务切换到基于 DLL 的 Google 结算服务有哪些前提条件？

    游戏可以继续使用 OAuth 登录 Google 来管理已登录的账号，但 Google 建议您停止使用旧版 REST 结算 API。从 REST 结算 API（使用 OAuth2 登录）切换到 SDK 流程可以是一项功能标志操作，因此在游戏切换期间，两者可以共存一段时间。

13. Launch Purchase Flow API 调用是否通过网络浏览器处理？

    不需要，现在购买流程完全在游戏内使用无缝 WebView 叠加层完成，无需离开游戏客户端。

14. 用户是否需要单独登录每款游戏才能进行购买？

    每次游戏会话都会使用 Google Play 游戏中的前台账号，因此您无需再次登录。您在游戏会话开始时在 Google Play 游戏中使用的账号就是发出 API 调用的账号。购买流程将自动使用此账号。

15. 游戏能否同时支持 PC SDK 和旧版支付系统？

    支付系统采用双流程模式，具体取决于游戏二进制文件版本。使用旧 build 的用户继续沿用现有流程，而使用新 build 的用户则过渡到基于 SDK 的付款方式。在过渡期内，两种付款流程的用户会共存。

Windows App Bundle

1. 使用第三方启动器提交 WAB 时，是否需要提供游戏软件包以供审核？

   您只需提交安装程序，无需提交整个游戏包，审核人员可以使用安装程序下载您的游戏包。

   注意：本指南专门针对使用第三方启动器调用游戏的开发者。

2. WAB 文件大小是否有限制？

   对于安装程序发布，您最多可以上传 10 GB 的 WAB 文件。 对于 Play 自管式发布，WAB 文件的大小上限为 200 GB。

3. 为什么我上传 WAB 后，游戏没有安装或显示？

   如果您的游戏在没有预先存在的 PC 版本的情况下上架（“首次 WAB”），系统可能会自动将其置于自管式发布保留状态。这是因为没有可更新的现有基准。 如需完全发布 WAB 并使游戏可供安装，您必须前往 Google Play 管理中心，并手动执行所需的发布操作（例如，点击“发布更改”）。

4. 如何上传 WAB 以进行内部测试？

   与 Google 共享许可清单账号，以便 Google 为其启用内部测试。Google 获得该列表后，会确保将这些用户纳入到新手入门流程中。

5. WAB 软件包应上传到哪里？

   您可以在第一个问题中提到的位置上传 WAB 软件包。但是，您无法手动发布。您必须向 Google 后端工作人员提供精确的世界协调时间 (UTC)（精确到小时）。然后，Google 会配置发布时间表，并确保按时发布。

PC SDK

1. 旧版 API 与 Google Play 游戏电脑版 SDK 有何区别？

   • 旧版 API 仅提供结算功能。
   • PC SDK 支持 Google 桌面服务 (GDS) 和完整的 PC 功能。
   • 使用 PC SDK 时，无需通过浏览器登录 Google。

2. 是否有其他方法可以直接使用游戏启动器启动游戏来初始化 SDK，而无需通过 Google Play 游戏电脑版？

   您的游戏必须通过 Google Play 游戏电脑版客户端启动。如需了解详情，请参阅此开发者文档。

3. PC SDK 是否支持 PEM 认证文件中的多字节字符？

   是的，该 SDK 支持多字节字符进行认证。

4. SDK 如何处理多个实例或账号的 Google 账号登录？

   Google Play 游戏中的每次游戏启动都会被视为一个“游戏会话”，每个“游戏会话”都可以有一个与之关联的账号。它们可以不同。因此，如果您使用账号 A 启动游戏，然后切换到账号 B 并重新启动，则两个账号可以同时运行。

5. Play Install Referrer 集成是否适用于 PC SDK？

   PC SDK（25.5.409.0 及更高版本）支持 Play Install Referrer API。 如需了解详情，请参阅 Play Install Referrer API。

启动器

1. 如果玩家使用第三方启动器而非 Google Play 客户端，其 Play 游戏服务账号会自动同步吗？

   为了使 SDK 函数正常运行，游戏必须直接通过 Google Play 游戏客户端启动。如果游戏由其他进程（例如安装程序或启动器应用）启动，则该进程本身必须从 Google Play 游戏客户端启动。游戏必须将从客户端收到的所有参数传递给客户端进程。

2. 如果 Google Play 游戏启动了第三方游戏启动器，我该如何处理初始化？

   您无需将 SDK 直接集成到启动器中。 不过，您必须将启动器从 Google Play 游戏客户端收到的所有命令行参数直接传递给生成的子进程（游戏可执行文件）。如果初始化失败（例如，返回 kActionRequiredShutdownClientProcess），则必须终止包括启动器在内的所有进程，以便 Google Play 游戏可以尝试自动恢复并重新启动游戏。如需了解详情，请参阅设置指南中的第 5 步。

3. 游戏和启动器进入正式版后，我该如何处理更新和维护？

   后续更新和维护必须通过启动器实施。Google Play 游戏客户端不支持更新功能，因此启动器必须能够更新游戏和启动器本身。

4. 安装程序如何接收用于自动播放的 GPG 会话令牌？

   GPG 会使用 --g_session_token=<token> 命令行参数将该会话令牌传递给安装程序。如需启用此功能，您必须在 play_publishing_config.xml 中设置 acceptsCommandLineArguments="true"。

   安装程序负责提取此令牌并使用它来启动游戏。如果令牌生成失败，GPG 会在没有令牌的情况下启动安装程序（回退）。

初始化

1. 当我使用 Google Play 游戏应用启动游戏时，它会同步我的 Google 账号详细信息吗？

   通过 Google Play 游戏客户端启动游戏后，账号会自动同步，无需再次通过 Google 登录流程登录。

2. 初始化参数可以重复使用多次吗？

   只要 Google Play 游戏客户端正在运行且登录信息有效，就可以实现此目的。不过，在指南中所述的场景中，当用户关闭游戏或游戏因 SDK 初始化失败（例如 kActionRequiredShutdownClientProcess）而退出时，游戏启动的所有进程都必须终止。

3. 有没有办法创建快捷方式来直接打开游戏？

   您可以使用以下 URI 直接打开游戏：

   googleplaygames://launch/?pid=2&id=com.company.gamename

   该 URI 支持检测 Google Play 游戏电脑版客户端是否已打开。如果客户端未打开，Google Play 游戏客户端会在游戏或启动器运行之前打开。您需要管理游戏或启动器，以防止运行多个实例。

4. 有没有办法在不使用 SDK 的情况下验证 Google Play 游戏电脑版安装？

   您可以通过检查是否存在以下 Windows 注册表项，来验证 Google Play 游戏电脑版的安装状态，而无需集成 SDK：

   HKEY_LOCAL_MACHINE\SOFTWARE\Google\Play Games Services

   此键的存在表示机器上已安装 Google Play 游戏服务（在 PC 上运行游戏所需）。如果缺少该密钥，您应引导用户前往 Google Play 游戏电脑版安装页面下载并安装客户端。

测试

1. 是否有任何类似于移动设备的开放式测试或封闭式测试环境？

   虽然我们不提供专用的端到端沙盒，但我们认识到开发者需要一个类似于生产环境的测试环境。我们很快就会提供更强大的解决方案。

2. 如何添加新的测试人员？

   您的 Google 联系人会为每个 PC 项目创建一个电子邮件群组，您必须将测试人员的 Google 账号添加到该群组中。只有此电子邮件群组的成员才有权在 Google Play 游戏中下载测试软件包。

其他

1. 我可以使用 VPN 吗？

   如果开发者需要在不支持 Google Play 游戏电脑版的地区测试游戏，我们建议您使用 VPN 从受支持的地区获取 IP 地址。

   确保在 VPN 上启用 TUN 模式。如需了解如何启用 TUN 模式和配置防火墙，请参阅 VPN 提供方 的操作手册。

   启用 TUN 模式后，安装 Google Play 游戏电脑版和模拟器以进行测试。

2. 如何在 Unity 或 UE 编辑器中开始开发 Google Play 游戏电脑版？

   • 启用开发者模式，然后继续测试。
   • 添加 manifest.xml 和 .dll 文件。如需了解详情，请参阅开发者文档。
   • 注册抢先体验合作伙伴 GUID 以进行测试。

3. 如何正确使用注册表项？

   您应根据根配置单元创建注册表项。您可以根据您的目的和数据的性质，将根配置单元设置为 HKEY_LOCAL_MACHINE 或 HKEY_CURRENT_USER。指南中以 HKEY_LOCAL_MACHINE 配置单元为例。

4. Google 审核 PC 软件包的要求是什么？

   PC 软件包会经过恶意软件扫描，之后审核人员只会测试游戏安装、成功启动和卸载流程。

5. 是否必须集成所有 API？

   其他 API 并非必需，但它们可提供额外的好处。 google::play::billing是应用内购和销售数字内容所必需的。google::play::install_referrer 是跟踪引荐数据所必需的，可帮助您了解哪些流量来源吸引了最多用户下载您的应用。google::play::games::integrity 是通过检测潜在风险设备和未知模拟器来保护您的应用免受恶意攻击者侵害所必需的。

6. 为什么关闭 Google Play 游戏客户端时，有些游戏进程会终止，而有些不会？

   Google 无法控制正在运行的游戏的子进程或进程。 具体行为取决于游戏是模拟 Android 游戏还是 PC 游戏。模拟游戏安装在自己的环境中，因此其行为在很大程度上取决于模拟器的初始化和关停。

7. 我应该使用 Google Play 游戏卸载功能还是自定义卸载程序？

   Google 建议使用我们的 Google Play 游戏卸载功能。

其他帮助

如果您需要本常见问题解答未涵盖的其他帮助，请发送邮件至 [e-mail]