Đă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 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.

Các chức năng của cấu hình tích hợp máy chủ đến máy chủ dưới dạng:

Nhà phân phối ứng dụng 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 xuất bản ứ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 một khoá được liên kết với tên gói. Đăng ký tên gói – khoá trong quy trình triển khai liên tục. Chứng minh quyền sở hữu một khoá được 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 truy cập quản trị vào một dự án trên Google Cloud.
  2. Có kiến thức 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. Thành phần 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 một tài khoản nhà phát triển, có thể được liên kết với một hoặc nhiều khoá. Nó chứa trạng thái đăng ký (DRAFT, IN_REVIEW, REGISTERED hoặc PENDING_TRANSFER).
Khoá Khoá/chứng chỉ công khai cụ thể được 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 một tài khoản Google Cloud nếu bạn chưa có.
  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 dự án.
  4. Sử dụng thanh tìm kiếm APIs & 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 tính năng này.

Xác thực API

Để gọi Android Developer Console API, bạn phải xác thực các yêu cầu bằng OAuth 2.0.

Xác thực bằng OAuth 2.0

Android Developer Console API yêu cầu xác thực OAuth 2.0 để cho phép truy cập vào các 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ể dùng Tài khoản dịch vụ, Workload Identity Federation và khoá API để xác thực các yêu cầu API.

Phạm vi OAuth 2.0

Bạn phải có phạm vi sau đây cho 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 Máy chủ web OAuth 2.0. 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 đăng nhập chính:

Lựa chọn A (Được đề xuất): Quyền truy cập ngoại tuyến / tự động (CI/CD và tích hợp 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 (chẳng hạn như quy trình CI/CD) chạy ở chế độ nền mà không cần sự can thiệp của con người:

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 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 truy cập khi không có mạng (access_type=offline) cùng với phạm vi API. Google 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 ở chế độ 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 đã 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 có thời hạn sử dụng dài trong môi trường của mình hoặc nếu ứng dụng của bạn chạy trong ngữ cảnh người dùng tương tác:

Nhắc nhở khi thực thi: Không yêu cầu quyền truy cập ngoại tuyến 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 ý OAuth của Google trong trình duyệt.

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

Đă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ề một danh sách dấu vân tay chứng chỉ công khai đã biết và đủ đ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á mà bạn đang đăng ký được liệt kê là "cần có lý do chính đáng", bạn vẫn có thể đăng ký khoá đó. Tuy nhiên, ngoài việc hoàn tất quy trình chứng minh quyền sở hữu, nhà phát triển cũng phải gửi lý do chính đáng cho việc sử dụng tên gói.

Các quy tắc chính về điều kiện

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.
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.

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

Để hoàn tất quy trình xác minh cho một tên gói hiện có, API sẽ cung cấp một chuỗi xác minh. Bạn cần thêm chuỗi xác minh này vào một tệp mới có tên là adi-registration.properties trong thư mục tài sản của ứng dụng. Sau đó, bạn phải ký và tải 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á cần 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 yêu cầu đă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

Các ứng dụng sử dụng Android Developer Console API nên tuân theo những mẫu này để đảm bảo quá trình tích hợp liền mạch.

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 trình bày rõ ràng về chức năng dự kiến trước khi phát hành màn hình xin phép OAuth.

Cấu trúc ngữ cảnh uỷ quyền bằng cách sử dụng đị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 [tên ứng dụng]"
  • 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. Xoá bố cục hộp thoại bối cảnh uỷ quyền OAuth.

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 một 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. 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 tín 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 rằng 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. Không bắt buộc: Cung cấp một nút CTA chính để chuyển nhà phát triển đến Android Developer Console khi họ chọn tài khoản.
Trình chọn tài khoản cho biết 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 hiển thị tài khoản nhà phát triển và trạng thái xác minh.

Nếu nhận được một phản hồi trống vì 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 truy cập vào Android Developer Console bằng nút CTA 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 được 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 trực quan 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, thì bạn có thể tuỳ ý thêm 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ả các khoá được liên kết với 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. Xuất hiện 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 trực quan 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. Thông tin tổng quan về các khoá và trạng thái đăng ký của chúng.
  1. Cho phép nhà phát triển đăng ký các khoá bổ sung theo 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 vào một trường văn bản, miễn là ứng dụng của bạn chưa thu thập thông tin này (ví dụ: thông qua một 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 các quy tắc chính về điều kiện áp dụng.
  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: 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 trực tiếp một khoá. Trong trường hợp này, bạn không cần xác minh quyền sở hữu khoá.
  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á trực tiếp 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 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à tạo các thành phần giao diện người dùng sau đây:

  • Thành phần hiển thị mã thông báo: Hiển thị verificationToken một cách 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 dụng.
  • Hướng dẫn thiết lập cho nhà phát triển: Cung cấp hướng dẫn chi tiết để hướng dẫn nhà phát triển đặt một tệp adi-registration.properties chứa verificationToken vào thư mục tài sản của ứng dụng.
  • Vùng thả để gửi tệp APK: Cung cấp một vùng 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 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 từ nhà phát triển và thông báo cho họ 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 tối đa 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ý 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 thi lệnh gọi API VerifyAndroidPackageKeyOwnership thay cho họ.

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

Tuân thủ nguyên tắc sử dụng 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 sử dụng thương hiệu sau đây.

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

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

Chương trình này phải được gọi là quy 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 ngữ cảnh.

Để tránh nhầm lẫn với 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 dùng cụm từ "đăng ký tên gói" thay vì "đăng ký 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 trên Dịch vụ nhận dạng của Google. Để 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. Đây là văn bản 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 Google để uỷ quyền cho ứ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 Android Developer Console vào giao diện ứng dụng, bạn phải tuân thủ các quy cách sau để duy trì tính nhất quán về nhận diện thị giác và thương hiệu:

  • Vị trí và thứ tự ưu tiên của 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 phải luôn là yếu tố phụ so với các phần tử thương hiệu chính của ứng dụng để tránh trình bày sai ứng dụng dưới dạng 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.
  • Phong cách hình ảnh và biến dạng: Thành phần phải luôn được hiển thị với tỷ lệ khung hình bị hạn chế hoàn toàn. 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. Không được 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 hiệu ứng chuyển 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 của 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 diễn ra.

Tài nguyên khác