gplay-screenshot-automation

Google Play 截图管理

使用此技能，通过 gplay 整理、验证并上传 Android 截图和商店图片到 Google Play 商品详情页。此技能涵盖 gplay 专属的上传/验证流程，不包括截图采集。

采集原始图片属于标准 Android 工具链，并非 gplay 专属：使用 adb shell screencap 截图（然后运行 adb pull），或通过 Espresso / UI Automator 插桩测试按状态采集截图；需要按语言采集时，可使用 setprop persist.sys.locale 切换模拟器区域设置。按语言区域和设备类型整理 PNG 文件，然后使用以下命令。

目录结构

gplay 需要采用 Fastlane 风格的目录树。sync import-images 和 release --screenshots-dir 都会读取此结构：

metadata/
  en-US/
    images/
      phoneScreenshots/
        1_home.png
        2_search.png
      tenInchScreenshots/
        1_home.png
      featureGraphic.png
  de-DE/
    images/
      phoneScreenshots/
        1_home.png

截图会按文件名顺序上传，因此请使用 1_、2_ 等前缀来控制它们在商店中的顺序。

图片类型

类型	用途
phoneScreenshots	手机截图（必需，2-8 张）
sevenInchScreenshots	7 英寸平板截图
tenInchScreenshots	10 英寸平板截图
tvScreenshots	Android TV 截图
wearScreenshots	Wear OS 截图
featureGraphic	Feature graphic（1024x500）
promoGraphic	Promo graphic（180x120）
icon	应用图标（512x512）
tvBanner	TV 横幅（1280x720）

Google Play 要求使用 PNG 或 JPEG 格式（推荐 PNG），每张图片最大 8 MB。

1) 上传前验证

务必先验证目录，以便在上传前发现数量、尺寸和格式问题：

# Validate all locales
gplay validate screenshots --dir ./metadata --output table

# Validate a single locale
gplay validate screenshots --dir ./metadata --locale en-US --output table

2) 上传

选项 A — 批量导入（首选）

一条命令即可导入 Fastlane 目录树中的所有图片。需要有一个已打开的编辑：

EDIT_ID=$(gplay edits create --package com.example.app | jq -r '.id')

gplay sync import-images \
  --package com.example.app \
  --edit "$EDIT_ID" \
  --dir ./metadata          # add --locale en-US to import one locale, --dry-run to preview

gplay edits validate --package com.example.app --edit "$EDIT_ID"
gplay edits commit   --package com.example.app --edit "$EDIT_ID"

选项 B — 单独上传图片

需要精细控制特定文件时使用：

EDIT_ID=$(gplay edits create --package com.example.app | jq -r '.id')

gplay images upload \
  --package com.example.app \
  --edit "$EDIT_ID" \
  --locale en-US \
  --type phoneScreenshots \
  --file ./metadata/en-US/images/phoneScreenshots/1_home.png

gplay images upload \
  --package com.example.app \
  --edit "$EDIT_ID" \
  --locale en-US \
  --type featureGraphic \
  --file ./metadata/en-US/images/featureGraphic.png

gplay edits validate --package com.example.app --edit "$EDIT_ID"
gplay edits commit   --package com.example.app --edit "$EDIT_ID"

选项 C — 随版本发布一起上传

在一次发布流程中，将截图与应用包一起上传：

gplay release \
  --package com.example.app \
  --track production \
  --bundle app-release.aab \
  --screenshots-dir ./metadata \
  --release-notes @release-notes.json

3) 替换现有截图

delete-all 会在重新上传前清空某个语言区域下的一种类型。它的 --confirm 默认值为 false，没有此参数时会拒绝执行，因此必须提供 --confirm：

EDIT_ID=$(gplay edits create --package com.example.app | jq -r '.id')

gplay images delete-all \
  --package com.example.app \
  --edit "$EDIT_ID" \
  --locale en-US \
  --type phoneScreenshots \
  --confirm

gplay images upload \
  --package com.example.app \
  --edit "$EDIT_ID" \
  --locale en-US \
  --type phoneScreenshots \
  --file ./metadata/en-US/images/phoneScreenshots/1_home.png

gplay edits validate --package com.example.app --edit "$EDIT_ID"
gplay edits commit   --package com.example.app --edit "$EDIT_ID"

4) 验证线上内容

gplay images list \
  --package com.example.app \
  --edit "$EDIT_ID" \
  --locale en-US \
  --type phoneScreenshots \
  --output table

Agent 行为

• 运行命令前，使用 --help 确认准确的标志。
• 上传前务必运行 gplay validate screenshots。
• 优先使用 gplay sync import-images，而不是多次单独调用 gplay images upload。
• 每次写入都必须经过编辑流程：创建 → 上传/导入 → 验证 → 提交。
• images delete-all 需要 --confirm；没有该参数时，命令会拒绝执行。
• 使用明确的长标志（--package、--edit、--locale、--type、--file）。
• 机器处理默认使用 JSON；供人工检查时使用 --output table。