Cập nhật gian hàng Play Store bằng Google Play Developer API

Google Play Developer API (tên chính thức là Android Publisher API) cho phép bạn thay đổi gian hàng — tiêu đề, mô tả, ảnh chụp màn hình, ảnh bìa tính năng — mà không cần mở Play Console. Đây chính là thứ bạn cần nếu đang đẩy nội dung đã bản địa hóa từ một CMS, đồng bộ ảnh chụp màn hình từ pipeline build, hoặc cập nhật hàng chục gian hàng ngôn ngữ cùng lúc. Đây là quy trình đầy đủ để làm đúng, kể cả những phần mà tài liệu tham khảo hay giấu đi.

Một edit là một giao dịch, không phải các lần ghi trực tiếp

Mô hình tư duy giúp bạn đỡ đau đầu nhất: bạn không bao giờ sửa trực tiếp gian hàng đang hoạt động. Bạn mở một edit, đây là một bản sao lưu trữ riêng tư của trạng thái đã triển khai hiện tại của app — gian hàng, ảnh, track, tất cả đều được sao chép vào đó. Bạn thực hiện mọi thay đổi trên bản sao đó. Sau đó bạn commit toàn bộ cùng một lúc, hoặc bỏ nó đi và coi như chưa từng xảy ra.

Chính Google cũng nói thẳng: "Changes made within an edit are not live until the edit is committed." (Các thay đổi trong một edit chưa hoạt động cho đến khi edit được commit). Khi commit, nếu không có lỗi xác thực, mọi thay đổi trong edit sẽ đồng loạt lên trực tiếp, thay thế trạng thái hiện tại. Nếu xác thực thất bại, API sẽ báo lỗi và gian hàng đang hoạt động không bị đụng chạm. Vậy vòng đời chỉ gồm đúng bốn bước:

• edits.insert — tạo edit, nhận về một editId.
• chỉnh sửa — edits.listings.update cho nội dung theo từng ngôn ngữ, edits.images.upload / deleteall cho ảnh chụp màn hình và ảnh đồ họa.
• edits.commit — xác thực toàn bộ, rồi xuất bản tất cả cùng một lúc.
• edits.abandon — bỏ bản nháp, gian hàng đang hoạt động không đổi.

Một ràng buộc cứng cần thiết kế xoay quanh: một tài khoản chỉ được có một edit đang mở tại một thời điểm, và nếu ai đó commit một edit hoặc sửa app qua giao diện Play Console, mọi edit khác đang mở của app đó sẽ bị vô hiệu. Hãy coi một edit là ngắn hạn — mở nó, ghi nó, commit nó. Đừng để nó mở hàng giờ trong khi có người thao tác thủ công trong console.

Xác thực: một service account, cộng với lời mời mà ai cũng quên

Với một công cụ cập nhật tự động, bạn cần một service account, không phải OAuth người dùng. Có hai hệ thống liên quan, và chúng thực sự tách biệt:

1. Google Cloud. Tạo một service account, bật Google Play Android Developer API trên dự án, và tải khóa JSON về. Phạm vi (scope) duy nhất bạn cần là https://www.googleapis.com/auth/androidpublisher.
2. Play Console. Vào Users & permissions, nhấn Invite new users, dán email của service account (địa chỉ dạng ...@...iam.gserviceaccount.com), và cấp quyền truy cập app cho nó. Chỉ khi đó khóa này mới có thể chạm vào gian hàng của bạn.

Một điều kiện tiên quyết nữa: app phải đã tồn tại và có ít nhất một bản phát hành (ít nhất một APK/AAB đã được tải lên qua console). Bạn không thể khởi tạo một app hoàn toàn mới chỉ bằng API.

Bốn lệnh gọi, dưới dạng REST

Cập nhật nội dung gian hàng

edits.listings.update là một PUT — thay thế toàn bộ nội dung của ngôn ngữ đó. Bất cứ thứ gì bạn gửi sẽ trở thành nội dung gian hàng; những trường bạn bỏ sót sẽ bị xóa, không được giữ lại. Vì vậy nếu chỉ muốn thay đổi mô tả ngắn, bạn vẫn phải gửi kèm tiêu đề và mô tả đầy đủ, nếu không sẽ xóa mất chúng. Khi bạn thực sự muốn thay đổi một phần, có một lệnh riêng edits.listings.patch chỉ hợp nhất những trường bạn cung cấp. Với hầu hết pipeline, PUT đầy đủ gọn gàng hơn — dù sao bạn cũng đang render toàn bộ nội dung từ nguồn dữ liệu gốc của mình, nên thay thế toàn bộ là chính xác.

Ba trường văn bản và giới hạn của chúng: title tối đa 30 ký tự, shortDescription tối đa 80, fullDescription tối đa 4000. Mỗi resource nội dung ứng với một ngôn ngữ, được đánh khóa theo mã ngôn ngữ BCP-47 trong URL (en-US, de-DE, ja-JP, v.v.). Để cập nhật mười ngôn ngữ, bạn thực hiện mười lệnh gọi listings.update bên trong cùng một edit — rồi một lần commit sẽ xuất bản chúng cùng lúc.

Tải ảnh chụp màn hình và ảnh bìa tính năng

Ảnh được gắn theo từng ngôn ngữ và từng loại ảnh. Loại ảnh là một enum, và mỗi vị trí tài sản trong gian hàng ứng với một trong các giá trị sau:

• phoneScreenshots, sevenInchScreenshots, tenInchScreenshots — bộ ảnh chụp màn hình cho điện thoại và máy tính bảng.
• tvScreenshots, wearScreenshots — Android TV và Wear OS.
• featureGraphic — banner 1024×500 hiển thị ở đầu gian hàng.
• icon, tvBanner — biểu tượng app và banner TV.

edits.images.upload thêm một ảnh của một ngôn ngữ và loại nhất định vào edit. Không có lệnh gọi "đặt cả mảng" nào, nên mẫu đáng tin cậy để thay ảnh chụp màn hình là gọi edits.images.deleteall cho ngôn ngữ và loại ảnh đó trước, rồi tải bộ ảnh mới lên theo đúng thứ tự bạn muốn hiển thị. edits.images.list đọc những gì hiện có trong edit, và edits.images.delete xóa một ảnh đơn lẻ theo id nếu bạn cần chỉnh sửa chính xác. Tất cả vẫn nằm trong edit cho đến khi bạn commit.

Commit — và "hoạt động" thực sự nghĩa là gì

Có vài điều đáng lưu ý chính xác, vì chúng khiến người ta bất ngờ:

• Không cần bản build mới. Commit một edit chỉ sửa nội dung gian hàng không cần APK/AAB mới. Văn bản và ảnh là metadata; bạn có thể cập nhật chúng bao nhiêu lần tùy ý dựa trên bản phát hành hiện có. (App chỉ cần đã có một bản phát hành trước đó.)
• Commit xác thực, rồi mới xuất bản. Nếu một ảnh chụp màn hình sai kích thước hoặc một trường quá dài, commit sẽ thất bại và gian hàng đang hoạt động không bao giờ thay đổi — bạn sửa rồi commit lại.
• Không tức thì. Sau khi commit thành công, thay đổi có thể mất đến vài giờ để hiển thị, giống như khi sửa thủ công trong Play Console. Đừng coi mã 200 khi commit là "đã hiển thị cho người dùng ngay".
• Bỏ (abandon) là miễn phí. Nếu một lần chạy thử trông không ổn, edits.abandon sẽ hủy bản nháp mà không ảnh hưởng gì đến gian hàng đang hoạt động. Rất hữu ích để kiểm chứng một pipeline mà không có rủi ro.

Con đường không cần code: thiết kế, dịch, xuất bản

API ở trên là công cụ đúng đắn nếu bạn có thời gian kỹ thuật để đầu tư và một nguồn dữ liệu gốc để đồng bộ. Điều nó không làm là tạo ra các tài sản. Bạn vẫn phải thiết kế ảnh chụp màn hình, viết tiêu đề và cả hai bản mô tả, và tạo ra tất cả những thứ đó cho từng ngôn ngữ — API chỉ đẩy đi những gì bạn đưa cho nó.

Đó chính là phần Mokbi đảm nhận. Bạn thiết kế ảnh chụp màn hình ngay trên trình duyệt, soạn tiêu đề, mô tả ngắn và mô tả đầy đủ song song với chúng, và dịch toàn bộ nội dung gian hàng sang 50 ngôn ngữ trong một lần — để mười lệnh gọi listings.update ở trên có nội dung thật, đã bản địa hóa để gửi thay vì văn bản giữ chỗ.

Còn bản thân việc xuất bản? Mokbi cũng làm luôn. Với Google Play, nó chạy chính xác quy trình này ở phía sau (edits.insert → listings.update → tải ảnh lên → commit), nên gian hàng đã bản địa hóa cùng các tài sản của bạn được công khai mà không cần bạn viết một dòng code nào ở trên. Với App Store, nó chuẩn bị sẵn phiên bản trong App Store Connect, điền đầy đủ và sẵn sàng gửi duyệt, vì Apple yêu cầu bạn phải tự nhấn Submit cuối cùng và trải qua kiểm duyệt. Thiết kế ảnh chụp màn hình và ảnh bìa tính năng, viết nội dung gian hàng, dịch sang 50 ngôn ngữ, và đưa lên trực tuyến là một chuỗi liền mạch.

Đọc tiếp

• Cập nhật gian hàng Play mà không cần phát hành bản build mới
• Yêu cầu gian hàng Play và checklist tài sản
• Phiên bản tương đương của App Store Connect API, cho iOS

Mở trình chỉnh sửa →