获取免费设计
· 开发者 · 6 分钟阅读

使用 Google Play Developer API 更新你的 Play 商店信息

使用 Google Play Developer API 更新你的 Play 商店信息
TL;DR. 通过 Android Publisher API 更新 Play 商店信息是一次事务。你先开启一次 edit(edits.insert),在其中修改商店文案和图片(edits.listings.update、edits.images.upload),然后用 edits.commit 校验并发布,或用 edits.abandon 放弃。commit 之前一切都不会生效。认证方式是 Google Cloud 服务账号,几乎所有人都会栽的一步是:服务账号必须在 Play Console 中被邀请,仅在 Google Cloud IAM 里赋予角色是不够的。

Google Play Developer API(正式名称为 Android Publisher API)让你无需打开 Play Console 就能修改商店信息:标题、描述、截图、宣传图。如果你要从 CMS 推送本地化文案、从构建流水线同步截图,或一次性更新几十种语言的商店信息,这正是你需要的工具。下面是完整正确的操作流程,包括官方文档语焉不详的那些细节。

edit 是一次事务,而不是一组实时写入

能省你最多麻烦的心智模型是:你永远不会直接编辑线上信息。你打开一个 edit,它是应用当前已发布状态的私有暂存副本,商店信息、图片、发布轨道,所有内容都会被复制进去。你在这个副本上做所有修改,然后一次性提交全部,或者放弃它,就当什么都没发生过。

Google 自己的措辞很直白:“edit 中的更改在提交之前不会生效。”提交时,如果没有校验错误,edit 中的所有更改会一并生效,替换掉当前状态;如果校验失败,API 会抛出错误,线上信息保持不变。所以整个生命周期正好是四个动作:

  • edits.insert:创建 edit,获取 editId。
  • 修改:对各语言文案用 edits.listings.update,对截图和图片用 edits.images.upload / deleteall。
  • edits.commit:校验全部内容,然后原子性地一并发布。
  • edits.abandon:丢弃草稿,线上信息不受影响。

有一个硬性限制需要围绕它来设计:同一账号同一时间只能打开一个 edit,如果有人提交了某个 edit,或通过 Play Console 界面编辑了该应用,该应用其他所有已打开的 edit 都会失效。把 edit 当作短生命周期的对象,打开、写入、提交,不要在有人手动点击控制台的同时让 edit 长时间保持打开。

认证:服务账号,加上大家都会忘的那步邀请

对于自动化更新器,你需要的是服务账号,而不是用户 OAuth。这里涉及两个真正独立的系统:

  1. Google Cloud。创建一个服务账号,为项目启用 Google Play Android Developer API,下载 JSON 密钥。你只需要 https://www.googleapis.com/auth/androidpublisher 这一个 scope。
  2. Play Console。前往用户和权限,点击邀请新用户,粘贴服务账号的邮箱地址(...@...iam.gserviceaccount.com 格式),并授予其对该应用的访问权限。只有这样,该密钥才能操作你的商店信息。

还有一个前提条件:应用必须已经存在,并且至少发布过一次(在控制台中至少上传过一个 APK/AAB)。你无法纯粹通过 API 从零启动一个全新应用。

四个调用,以 REST 形式展示

更新商店文案

edits.listings.update 是一次 PUT,即对该语言商店信息的完全替换。你发送的内容就是新的信息;你没有包含的字段会被清空,而不是保留。所以如果你只想改简短描述,也必须把标题和完整描述一并发送,否则它们会被清空。如果你真的只想做部分修改,另有一个 edits.listings.patch,只合并你提供的字段。对大多数流水线来说,完整 PUT 更清爽,反正你本来就是从数据源渲染完整信息,整体替换正是正确做法。

三个文案字段及其限制:title 最多 30 个字符,shortDescription 最多 80 个字符,fullDescription 最多 4000 个字符。每种语言对应一个信息资源,通过 URL 中的 BCP-47 语言标签区分(en-US、de-DE、ja-JP 等)。要更新十种语言,你需要在同一个 edit 内调用十次 listings.update,然后一次 commit 将它们一并发布。

上传截图和宣传图

图片按语言和图片类型附加。图片类型是一个枚举值,商店信息中的每个素材位都对应以下值之一:

  • phoneScreenshots、sevenInchScreenshots、tenInchScreenshots:手机和平板截图集。
  • tvScreenshots、wearScreenshots:Android TV 和 Wear OS。
  • featureGraphic:商店信息顶部展示的 1024×500 宣传横幅。
  • icon、tvBanner:应用图标和 TV 横幅。

edits.images.upload 会向 edit 添加指定语言和类型的一张图片。它并不提供“设置整个数组”的调用,所以替换截图的可靠模式是:先对该语言和图片类型调用 edits.images.deleteall,再按你想展示的顺序上传新的一组图片。edits.images.list 读取 edit 中当前的内容,edits.images.delete 可按 id 删除单张图片,用于精细调整。所有这些操作在提交之前都只存在于 edit 内部。

提交,以及“上线”到底意味着什么

有几点值得说清楚,因为它们常让人意外:

  • 无需新构建版本。提交一个仅涉及商店信息的 edit不需要新的 APK/AAB。文案和图片属于元数据,你可以在现有发布版本上任意次数地更新它们(应用只需已存在过一次发布)。
  • commit 先校验,再发布。如果某张截图尺寸不对,或某字段超长,commit 会失败,线上信息永远不会改变,你修复后重新提交即可。
  • 并非即时生效。成功提交后,更改最长可能需要数小时才会显示,和在 Play Console 中手动编辑一样。不要把 commit 返回的 200 当作“用户已经能看到”。
  • 放弃是免费的。如果试运行结果不对,edits.abandon 会丢弃草稿,对线上信息零影响。适合在没有风险的情况下验证流水线。

无代码路径:设计、翻译、发布

如果你有工程时间可投入,也有可同步的数据源,上面这套 API 就是合适的工具。但它不能制作素材。你仍然需要设计截图、撰写标题和两段描述,并为每种语言都准备好这些内容,API 只会发送你交给它的东西。

这正是 Mokbi 负责的部分。你在浏览器中设计截图,同时起草标题、简短描述和完整描述,一次性将整套商店信息翻译成50 种语言,这样上面那十次 listings.update 调用发送的就是真实、本地化的文案,而不是占位文字。

那提交本身呢?Mokbi 同样会完成。对于 Google Play,它在幕后精确执行的正是这套流程(edits.insert → listings.update → 上传图片 → commit),让你的本地化商店信息和素材上线,而无需你亲手写上面提到的任何一行代码。对于 App Store,它会在 App Store Connect 中把版本填好、准备就绪,等待提交,因为苹果要求你亲自点击最终的 Submit 按钮并通过审核。设计截图和宣传图、撰写商店文案、翻译成50 种语言、再推送上线,是一套连续完成的流程。

接下来读什么

打开编辑器 →