Đăng ký tên gói bằng Android Developer Console API

Android Developer Console API là một giao diện công khai được thiết kế để cho phép các nhà phân phối ứng dụng và nhà phát triển cá nhân đăng ký tên gói theo phương thức lập trình trong Android Developer Console.

Khả năng tích hợp máy chủ đến máy chủ của bạn với tư cách là:

App Distribution Nhà phát triển cá nhân
Đăng ký tên gói – khoá thay mặt cho nhà phát triển đang phát hành ứng dụng lên cửa hàng. Đăng ký tên gói bằng khoá do cửa hàng quản lý. Chứng minh quyền sở hữu khoá liên kết với tên gói. Đăng ký một khoá tên gói trong quy trình triển khai liên tục. Chứng minh quyền sở hữu khoá liên kết với tên gói.

Trước khi bắt đầu

Trước khi bắt đầu, bạn cần có:

  1. Quyền quản trị đối với một dự án trên đám mây của Google Cloud.
  2. Hiểu biết cơ bản về:

Bạn cũng cần nắm rõ các thuật ngữ sau:

Thuật ngữ Định nghĩa
Tài khoản nhà phát triển Đại diện cho một tài khoản Android Developer Console có thể sở hữu một hoặc nhiều tên gói. Trạng thái này chứa trạng thái xác minh (NOT_VERIFIED hoặc VERIFIED).
Tên gói Một tên gói Android cụ thể (ví dụ: com.example.app) trong tài khoản nhà phát triển, có thể liên kết với một hoặc nhiều khoá. Trạng thái này chứa trạng thái đăng ký (DRAFT, IN_REVIEW, REGISTERED hoặc PENDING_TRANSFER).
Khoá Chứng chỉ/khoá công khai cụ thể dùng để ký tên gói Android. Bao gồm hàm băm SHA-256 và trạng thái đăng ký hiện tại (DRAFT, OWNERSHIP_VERIFIED, IN_REVIEW, REGISTERED hoặc PENDING_TRANSFER).

Bắt đầu

Hãy hoàn tất các bước sau để truy cập vào Android Developer Console API:

Tạo một dự án trên Google Cloud

  1. Tạo tài khoản Google Cloud nếu bạn chưa có tài khoản.
  2. Mở Google Cloud Console.
  3. Tạo một dự án trên Google Cloud.

Bật API trong dự án trên đám mây của bạn

  1. Mở Google Cloud Console.
  2. Trong trình đơn điều hướng (☰), hãy chọn API và Dịch vụ > Thư viện.
  3. Chọn dự án Google Cloud mà bạn muốn bật API trong trình đơn thả xuống của dự án.
  4. Sử dụng thanh tìm kiếm API & Services (API và dịch vụ) để chọn Android Developer Console API.
  5. Bật API:
    1. Chuyển đến trang tổng quan của API bằng cách chọn API đó trong kết quả tìm kiếm.
    2. Nhấp vào nút Bật màu xanh dương. Google Cloud sẽ kích hoạt API cho dự án bạn đã chọn. Quá trình này thường chỉ mất một chút thời gian. Sau khi bật, bạn có thể bắt đầu sử dụng.

Xác thực API

Để thực hiện lệnh gọi đến Android Developer Console API, bạn phải xác thực yêu cầu của mình bằng OAuth 2.0.

Xác thực bằng OAuth 2.0

API Android Developer Console yêu cầu xác thực OAuth 2.0 để cho phép truy cập vào tài nguyên tài khoản nhà phát triển và tên gói. Vì dữ liệu tài khoản nhà phát triển được liên kết với Tài khoản Google của người dùng chứ không phải dự án Google Cloud, nên bạn không thể sử dụng Tài khoản dịch vụ, Workload Identity và khoá API để xác thực yêu cầu API.

Phạm vi OAuth 2.0

Phạm vi sau đây là bắt buộc đối với tất cả các thao tác:

Phạm vi OAuth 2.0 Mô tả
https://www.googleapis.com/auth/androiddeveloperconsole Xem và quản lý tên gói và dữ liệu trong tài khoản Android Developer Console của bạn

Triển khai quy trình OAuth 2.0 cho máy chủ web

Để tích hợp với Android Developer Console API, các ứng dụng phải sử dụng quy trình OAuth 2.0 cho máy chủ web. Tuỳ thuộc vào loại ứng dụng và nhu cầu tự động hoá, bạn có thể chọn một trong hai chiến lược quản lý thông tin xác thực chính:

Cách A (Nên dùng): Truy cập ngoại tuyến / tự động (tích hợp CI/CD và máy chủ) Cách B: Quyền truy cập tạm thời / tương tác
Chiến lược này cho phép các quy trình tự động (như quy trình CI/CD) chạy ở chế độ nền mà không cần con người can thiệp:

Thiết lập sự đồng ý của người dùng một lần: Trong quá trình thiết lập ban đầu, nhà phát triển hoặc chủ sở hữu tài khoản sẽ hoàn tất quy trình đồng ý một lần trong trình duyệt của họ. Ứng dụng của bạn yêu cầu quyền xem không cần mạng (access_type=offline) cùng với phạm vi API. Google sẽ trả về một mã uỷ quyền. Ứng dụng của bạn sẽ đổi mã này lấy một mã truy cập ban đầu và một mã làm mới dài hạn.

Thực thi trong nền: Lưu trữ refresh_token một cách an toàn trong môi trường triển khai hoặc trình quản lý bí mật (ví dụ: GitHub Actions Secrets, Google Secret Manager). Đối với các lệnh gọi API tiếp theo, quy trình tự động của bạn sẽ sử dụng mã làm mới được lưu trữ để lấy mã truy cập ngắn hạn mới theo yêu cầu, bỏ qua mọi lời nhắc đăng nhập thủ công hoặc 2FA. 		Nếu bạn không muốn lưu trữ mã làm mới dài hạn trong môi trường của mình hoặc nếu ứng dụng của bạn chạy trong bối cảnh người dùng tương tác:

Nhắc khi thực thi: Đừng yêu cầu quyền truy cập khi không có mạng hoặc lưu trữ mã làm mới. Mỗi khi công cụ hoặc ứng dụng được thực thi, hãy nhắc người dùng xác thực bằng cách chuyển hướng họ đến trang đồng ý của Google OAuth trong trình duyệt của họ.

Quyền truy cập ngắn hạn: Người dùng đăng nhập và đồng ý, còn ứng dụng trực tiếp nhận được mã truy cập ngắn hạn (hoặc sử dụng quy trình trao đổi mã uỷ quyền). Mã truy cập này được dùng để thực hiện lệnh gọi API và bị loại bỏ sau khi thực thi. Người dùng cần xác thực lại trong những lần chạy sau này.

Đăng ký tên gói

Đăng ký tên gói là quy trình liên kết một khoá với một tên gói. Cách đăng ký khoá phụ thuộc vào việc bạn đăng ký khoá cho tên gói mới hay tên gói hiện có trong Android.

Đăng ký tên gói mới

Đối với một tên gói mới chưa từng xuất hiện trên Android, bạn có thể cung cấp chứng chỉ khoá công khai từ cặp khoá ký của ứng dụng.

Đăng ký tên gói hiện có

Để đăng ký một tên gói hiện có, bạn phải chứng minh quyền sở hữu một khoá ký riêng tư đã biết. Không giống như quy trình đăng ký mới, API này trả về danh sách dấu vân tay chứng chỉ công khai đã biết đủ điều kiện đăng ký. Bạn có thể dùng các khoá này để đăng ký trực tiếp.

Nếu khoá bạn đang đăng ký được liệt kê là "cần có lý do", thì bạn vẫn có thể đăng ký khoá đó. Tuy nhiên, ngoài việc hoàn tất bằng chứng chứng minh quyền sở hữu, nhà phát triển cũng phải gửi lý do sử dụng tên gói.

Các quy tắc chính về điều kiện sử dụng

Danh sách các khoá đủ điều kiện được xác định theo các quy tắc về điều kiện đăng ký tên gói nhằm giảm thiểu vấn đề dùng chung tên gói (được giới thiệu trong quy trình xác minh nhà phát triển Android).

Trong trường hợp một tên gói được nhiều nhà phát triển sử dụng hoặc có nhiều khoá ký, điều kiện đăng ký sẽ được xác định như sau:

Trường hợp Quy tắc đăng ký trực tiếp Quy tắc dành cho các nhà phát triển khác
Người nắm giữ khoá chính Khoá chiếm hơn 50% tổng số lượt cài đặt đã biết sẽ được ưu tiên. Tất cả nhà phát triển khác đều phải đưa ra lý do chính đáng.
Hơn 50 lượt cài đặt. Nếu không có khoá nào có hơn 50% lượt cài đặt, thì tất cả các khoá có từ 50 lượt cài đặt trở lên đều đủ điều kiện. Những nhà phát triển có khoá có ít hơn 50 lượt cài đặt đều phải đưa ra lý do.
Chưa đến 50 lượt cài đặt Nếu không có khoá nào đáp ứng ngưỡng 50 lượt cài đặt, thì mọi khoá đều có thể được sử dụng theo nguyên tắc ưu tiên người đến trước Khi có một nhà phát triển đăng ký, các nhà phát triển khác đều phải đưa ra lý do chính đáng.

Xác minh quyền sở hữu khoá

Để hoàn tất quy trình xác minh cho tên gói hiện có, API sẽ cung cấp một chuỗi xác minh. Chuỗi xác minh này cần được đưa vào một tệp mới có tên là adi-registration.properties trong thư mục thành phần của ứng dụng. Sau đó, bạn phải ký và tải tệp APK lên bằng khoá riêng tư tương ứng với khoá công khai mà bạn đang đăng ký.

Giải thích lý do đăng ký khoá

Nếu việc đăng ký khoá yêu cầu phải có lý do, thì nhà phát triển phải gửi lý do kinh doanh chi tiết. Google sẽ xem xét lý do này và quá trình phê duyệt đăng ký tên gói có thể mất đến 24 giờ.

Các phương pháp hay nhất về trải nghiệm người dùng

Bạn nên sử dụng các mẫu này cho những ứng dụng dùng Android Developer Console API để đảm bảo quá trình tích hợp liền mạch diễn ra suôn sẻ.

Thiết lập bối cảnh uỷ quyền OAuth rõ ràng

Việc cung cấp bối cảnh rõ ràng trước khi yêu cầu uỷ quyền OAuth giúp nhà phát triển hiểu được lý do cần có quyền truy cập vào tài khoản. Để hướng dẫn người dùng một cách hiệu quả, hãy giải thích rõ ràng về chức năng dự kiến trước khi chạy màn hình xin phép bằng OAuth.

Cấu trúc bối cảnh uỷ quyền theo định dạng sau:

  • Tiêu đề: "Liên kết tài khoản Android Developer Console"
  • Tóm tắt: "Quản lý việc đăng ký tên gói để xác minh nhà phát triển Android trong [application-name]"
  • Nút hành động: Nút "Tiếp tục bằng Google" hoặc "Đăng nhập bằng Google"
Hộp thoại minh hoạ bối cảnh uỷ quyền OAuth để liên kết tài khoản.
Hình 1. Liên kết tài khoản Android Developer Console.

Xác định tài khoản nhà phát triển

  1. Tích hợp với phương thức API ListDeveloperAccounts để truy xuất và liệt kê tất cả tài khoản nhà phát triển đã được cấp quyền truy cập.
  2. Cung cấp bộ chọn tài khoản để cho phép nhà phát triển chọn tài khoản nhà phát triển mà họ muốn.
  3. Làm nổi bật tài khoản displayName, sử dụng số tài khoản trong trường name làm thông tin phụ.
  4. Hiển thị trạng thái xác minh tài khoản (verificationState):
    • VERIFIED: Xác nhận danh tính nhà phát triển đã xác minh bằng một dấu hiệu trực quan tích cực (ví dụ: dấu kiểm màu xanh lục).
    • NOT_VERIFIED: Cho biết quy trình xác minh chưa hoàn tất và hạn chế việc đăng ký gói cho tài khoản. Nếu muốn, bạn có thể cung cấp một nút kêu gọi hành động chính để đưa nhà phát triển đến Android Developer Console khi họ chọn tài khoản.
Bộ chọn tài khoản cho thấy tên tài khoản nhà phát triển và trạng thái xác minh.
Hình 2. Bộ chọn tài khoản cho thấy các tài khoản nhà phát triển và trạng thái xác minh.

Nếu nhận được phản hồi trống do không có tài khoản nhà phát triển nào được liên kết với Tài khoản Google, hãy hướng dẫn nhà phát triển đến Android Developer Console bằng nút kêu gọi hành động chính.

Quản lý tên gói

  1. Tích hợp với điểm cuối API ListAndroidPackages để truy xuất tất cả tên gói liên kết với tài khoản nhà phát triển. Cung cấp cho nhà phát triển một giao diện tập trung, chẳng hạn như danh sách hoặc bảng, để theo dõi trạng thái gói một cách hiệu quả.
  2. Hiển thị packageName cùng với trạng thái đăng ký hiện tại (DRAFT, IN_REVIEW, REGISTERED hoặc PENDING_TRANSFER), áp dụng các chỉ báo hình ảnh riêng biệt cho từng trạng thái. Nếu đã cung cấp và lưu "tên thân thiện" trong quá trình tạo, bạn có thể tuỳ ý đưa tên đó vào màn hình.
Giao diện hiển thị tên gói đã đăng ký và trạng thái của các gói đó.
Hình 3. Giao diện để quản lý tên gói và trạng thái đăng ký.

Quản lý khoá

  1. Gọi điểm cuối API ListAndroidPackageKeys để tìm nạp tất cả khoá liên kết với một tên gói, cung cấp cho nhà phát triển thông tin tổng quan có cấu trúc (chẳng hạn như bảng hoặc danh sách) để theo dõi trạng thái đăng ký của họ.
  2. Trình bày certificateFingerprintSha256 cho mọi khoá cùng với trạng thái đăng ký (DRAFT, OWNERSHIP_VERIFIED, IN_REVIEW, REGISTERED_ACTIVE hoặc PENDING_TRANSFER), sử dụng các chỉ báo hình ảnh riêng biệt để phân biệt giữa các trạng thái.
Danh sách dấu vân tay chứng chỉ và trạng thái đăng ký khoá.
Hình 4. Tổng quan về các khoá và trạng thái đăng ký của khoá.
  1. Cho phép nhà phát triển đăng ký thêm khoá trong tên gói hiện có bằng cách tích hợp với phương thức API CreateAndroidPackageKey.

Đăng ký tên gói

  1. Sử dụng bố cục dựa trên biểu mẫu, trong đó nhà phát triển nhập tên gói của họ vào một trường văn bản, miễn là thông tin này chưa được ứng dụng của bạn thu thập (ví dụ: thông qua lời nhắc trước đó).
  2. Gọi phương thức API CreateAndroidPackage để đăng ký tên gói trong tài khoản nhà phát triển và gọi phương thức API GetAndroidPackageRegistrationPolicy để xác định quy tắc về điều kiện đăng ký khoá hiện hành.
  3. Dựa trên keySelectionStrategy được chỉ định cho tên gói, hãy nhắc nhà phát triển thực hiện một trong những thao tác sau:
    • Nếu keySelectionStrategy được đặt thành SELECT_KEY_FROM_LIST: Hãy yêu cầu nhà phát triển chọn một khoá để đăng ký trong danh sách knownKeys được cung cấp (chứa dấu vân tay chứng chỉ SHA-256), chẳng hạn như sử dụng nút chọn. Quy trình này yêu cầu xác minh quyền sở hữu khoá (tham khảo phần Xác minh quyền sở hữu khoá bên dưới).
    • Nếu keySelectionStrategy được đặt thành USE_ANY_KEY: Nhắc nhà phát triển cung cấp khoá trực tiếp. Bạn không cần xác minh quyền sở hữu khoá trong trường hợp này.
  4. Gọi phương thức API CreateAndroidPackageKey để liên kết khoá đã chọn với tên gói mới.
Biểu mẫu đăng ký tên gói và chọn khoá ký.
Hình 5. Quy trình đăng ký tên gói và chọn khoá.

Ngoài ra, ứng dụng của bạn có thể tự động phát hiện và trích xuất tên gói hoặc khoá ngay từ một ứng dụng đã tải lên.

Xác minh quyền sở hữu khoá

Khi keySelectionStrategy được đặt thành SELECT_KEY_FROM_LIST, nhà phát triển phải chứng minh quyền sở hữu khoá ký riêng tư của họ. Để chứng minh quyền sở hữu, bạn cần gửi một tệp APK đã ký có chứa verificationToken do API tạo.

Để hỗ trợ quy trình xác minh quyền sở hữu khoá, hãy tích hợp phương thức API VerifyAndroidPackageKeyOwnership và xây dựng các thành phần giao diện người dùng sau:

  • Thành phần hiển thị mã thông báo: Hiển thị verificationToken nổi bật bên trong một khối đoạn mã, bao gồm cả nút "Sao chép vào bảng nhớ tạm" tiện lợi.
  • Hướng dẫn thiết lập cho nhà phát triển: Cung cấp hướng dẫn chi tiết để nhà phát triển đặt tệp adi-registration.properties chứa verificationToken vào thư mục tài sản của ứng dụng.
  • Khu vực thả để gửi tệp APK: Cung cấp một khu vực thả tệp tải lên chuyên dụng để nhận tệp APK đã ký.
Vùng thả và màn hình hiển thị mã thông báo để xác minh quyền sở hữu khoá.
Hình 6. Các thành phần giao diện người dùng để xác minh quyền sở hữu khoá bằng cách tải tệp APK đã ký lên.

Giải thích lý do đăng ký khoá

Khi một khoá đã biết có trường justificationRequired được đặt thành REQUIRED, việc đăng ký khoá đó cùng với tên gói yêu cầu nhà phát triển phải gửi lý do kinh doanh đầy đủ.

Gửi lý do này bằng cách gọi phương thức API JustifyAndroidPackageKeyRegistration. Đảm bảo giao diện người dùng của ứng dụng có một vùng nhập văn bản riêng để thu thập lý do của nhà phát triển và thông báo cho họ biết rằng họ phải cung cấp lý do trước khi gửi yêu cầu đăng ký khoá. Google sẽ xem xét lý do bạn gửi. Quá trình này có thể mất đến 24 giờ để phê duyệt trước khi hoàn tất việc đăng ký tên gói.

Tự động hoá quy trình xác minh khoá cho các khoá được quản lý

Nếu ứng dụng của bạn quản lý khoá ký của nhà phát triển, thì nhà phát triển không thể ký tệp APK theo cách thủ công để xác minh quyền sở hữu. Thay vào đó, bạn phải tự động thực hiện lệnh gọi API VerifyAndroidPackageKeyOwnership thay mặt họ.

Bằng cách tự động xử lý quy trình thêm mã thông báo và tải tệp APK lên, ứng dụng của bạn sẽ loại bỏ các bước thủ công này. Hãy nhớ thông báo cho nhà phát triển rằng quy trình xác minh quyền sở hữu khoá được ứng dụng của bạn quản lý liền mạch bằng khoá được lưu trữ trong hệ thống của bạn.

Tuân thủ nguyên tắc trình bày thương hiệu

Để duy trì lòng tin của người dùng và đảm bảo tính minh bạch, tất cả ứng dụng tích hợp với Android Developer Console API đều phải tuân thủ các nguyên tắc trình bày thương hiệu sau đây.

Thuật ngữ và cách viết hoa

Khi đề cập đến sản phẩm trong tài liệu hoặc tài liệu dành cho người dùng, hãy luôn sử dụng tên đầy đủ là Android Developer Console. Đừng sử dụng từ viết tắt "ADC".

Chương trình này phải được gọi là chương trình xác minh nhà phát triển Android. Hãy tuân thủ chính xác cách viết hoa và chính tả này trong mọi bối cảnh.

Để tránh nhầm lẫn với tệp APK hoặc AAB, hãy sử dụng cụ thể thuật ngữ "tên gói" thay vì chỉ dùng "gói".

Khi mô tả quy trình thêm tên gói, hãy sử dụng cụm từ "đăng ký tên gói" thay vì "xác nhận quyền sở hữu tên gói".

Sử dụng lời kêu gọi hành động "Đăng nhập"

Phương thức xác thực OAuth 2.0 với Android Developer Console dựa vào Dịch vụ nhận dạng của Google. Để luôn tuân thủ nguyên tắc sử dụng thương hiệu của Dịch vụ nhận dạng của Google, bạn phải sử dụng lời kêu gọi hành động "Tiếp tục bằng Google" hoặc "Đăng nhập bằng Google" trên nút uỷ quyền. Văn bản này là bắt buộc và không thể sửa đổi, vì văn bản này đảm bảo người dùng hiểu rằng họ đang sử dụng thông tin đăng nhập của Google để cho phép ứng dụng của bạn truy cập vào Tài khoản Google của họ.

Duy trì bản sắc thương hiệu và tính toàn vẹn

Khi tích hợp biểu trưng của Android Developer Console vào giao diện ứng dụng, bạn phải tuân thủ các thông số kỹ thuật sau để duy trì bản sắc hình ảnh và tính toàn vẹn của thương hiệu:

  • Vị trí và hệ thống phân cấp biểu trưng: Chỉ sử dụng biểu trưng chính thức, được phê duyệt của Android Developer Console. Biểu trưng này phải luôn là thành phần phụ so với các thành phần thương hiệu chính của ứng dụng để tránh gây hiểu lầm rằng ứng dụng này là một sản phẩm chính thức của Google.
Biểu trưng chính thức của Android Developer Console. Nhấp để lưu tệp.
Hình 7. Biểu trưng chính thức của Android Developer Console. Nhấp vào hình ảnh để lưu tệp.
  • Kiểu hình ảnh và độ méo: Thành phần phải luôn được hiển thị với tỷ lệ khung hình hoàn toàn bị ràng buộc. Bạn không được bóp méo, kéo giãn, làm lệch, cắt, lật hoặc sửa đổi các thành phần của biểu trưng. Đừng thay đổi bảng màu chính thức, hoán đổi màu nền trước hoặc màu nền, hoặc áp dụng hiệu ứng đổ bóng, hiệu ứng phát sáng hoặc dải màu trang trí.
  • Quy định hạn chế về việc sử dụng: Không được đưa bất kỳ thành phần thương hiệu nào thuộc sở hữu của Google vào thành phần ứng dụng của riêng bạn. Bạn chỉ có thể sử dụng thành phần biểu trưng Android Developer Console trong bối cảnh bố cục ứng dụng để biểu thị rõ ràng một hoạt động tích hợp đang hoạt động.

Tài nguyên khác