Xuất bản tiện ích của bạn

Trang này giải thích cách phát hành tiện ích trên Trung tâm tiện ích.

Trước khi bắt đầu

Để phát hành một tiện ích, trước tiên, bạn cần đăng ký làm nhà xuất bản tiện ích.

Nguồn đáng tin cậy

Tất cả các tiện ích được xuất bản trên Trung tâm tiện ích phải có nguồn có thể xác minh công khai. Thay vì tải mã nguồn tiện ích trực tiếp lên Trung tâm tiện ích, bạn hãy chỉ định vị trí nguồn và Trung tâm tiện ích sẽ tải mã nguồn đó xuống và tạo mã nguồn từ đó.

Hiện tại, việc này có nghĩa là cung cấp mã nguồn tiện ích của bạn trên một kho lưu trữ GitHub công khai.

Việc tải lên từ một nguồn có thể xác minh được mang lại một số lợi ích:

• Người dùng có thể kiểm tra mã nguồn của bản sửa đổi cụ thể của tiện ích sẽ được cài đặt.
• Bạn có thể đảm bảo rằng bạn chỉ tải những nội dung mà bạn dự định tải lên, chẳng hạn như công việc đang tiến hành hoặc các tệp lạc lõng còn lại từ quá trình phát triển.

Lưu ý: Bạn có thể tải các phiên bản phát hành trước của một tiện ích lên từ nguồn cục bộ. Những bản phát hành này sẽ không được liệt kê trên Trung tâm tiện ích.

Chu kỳ phát triển được đề xuất

Các công cụ phát triển Tiện ích Firebase hỗ trợ tải các phiên bản trước khi phát hành của tiện ích lên, giúp bạn dễ dàng kiểm thử tiện ích và quy trình cài đặt tiện ích trong cùng một môi trường mà cuối cùng các tiện ích đó sẽ được phát hành.

Khả năng này giúp bạn có thể thực hiện một chu kỳ phát triển như sau:

1. Phát triển và lặp lại nhanh chóng tiện ích của bạn bằng cách sử dụng Bộ trình mô phỏng Firebase.

2. Kiểm thử tiện ích trong một dự án thực bằng cách cài đặt tiện ích đó từ nguồn cục bộ:

   firebase ext:install /path/to/extension
   firebase deploy --only extensions

3. Tải phiên bản phát hành trước lên Trung tâm tiện ích (xem bên dưới). Phân phối đường liên kết cài đặt để thử nghiệm rộng rãi hơn và lặp lại bằng cách tải thêm các phiên bản phát hành trước lên nếu cần.

4. Tải phiên bản hoàn chỉnh, ổn định lên Trung tâm tiện ích (xem bên dưới) và gửi phiên bản này đi xem xét. Nếu tiện ích vượt qua quy trình xem xét, tiện ích đó sẽ được xuất bản trên Trung tâm tiện ích.

5. Tăng số phiên bản trong extension.yaml và lặp lại chu kỳ này cho phiên bản tiếp theo của tiện ích.

Tải tiện ích mới lên

Cách tải một tiện ích lên lần đầu tiên:

1. Không bắt buộc: Gửi mã của bạn vào kho lưu trữ GitHub công khai.

2. Chạy lệnh ext:dev:upload của Firebase CLI:

   GitHub

   firebase ext:dev:upload your_publisher_id/your_extension_id

   Nguồn cục bộ

   cd /path/to/extension
   firebase ext:dev:upload your_publisher_id/your_extension_id --local

   Trong lệnh gọi lệnh, bạn cần chỉ định nội dung sau:

   • Mã nhà xuất bản mà bạn đã đăng ký.

   • Chuỗi mã nhận dạng sẽ xác định tiện ích. Đặt tên cho tiện ích theo định dạng sau: firebase-product-description-of-tasks-performed. Ví dụ: firestore-bigquery-export

   Lệnh này sẽ nhắc bạn cung cấp thêm thông tin:

   • Nếu bạn tải lên từ GitHub:

     • URL đến kho lưu trữ của tiện ích trong GitHub. Xin lưu ý rằng một kho lưu trữ có thể chứa nhiều phần mở rộng, miễn là mỗi phần mở rộng có một thư mục gốc riêng biệt.

       Khi bạn tải một tiện ích mới lên lần đầu tiên, kho lưu trữ sẽ được đăng ký làm nguồn chuẩn cho tiện ích của bạn.

     • Thư mục trong kho lưu trữ chứa phần mở rộng của bạn.

     • Tài liệu tham khảo Git của cam kết mà bạn muốn dùng để tạo nguồn phiên bản tiện ích. Đây có thể là hàm băm cam kết, thẻ hoặc tên nhánh.

   • Giai đoạn phát hành của phiên bản bạn đang tải lên.

     Các giai đoạn alpha, beta và rc (bản phát hành dùng thử) dùng để tải các phiên bản phát hành trước lên để người kiểm thử cài đặt. Hãy sử dụng một trong các giai đoạn này để tải phần mở rộng mới lên lần đầu.

     Giai đoạn stable được dùng cho các bản phát hành công khai sẽ được xuất bản trên Trung tâm tiện ích. Việc tải bản phát hành stable lên sẽ tự động bắt đầu quy trình xem xét và nếu vượt qua, thì tiện ích sẽ được xuất bản.

   Lưu ý rằng bạn không chỉ định số phiên bản – giá trị này đến từ tệp extension.yaml. Khi bạn tải một phiên bản tiện ích phát hành trước lên, giai đoạn và số lượt tải lên sẽ được thêm vào phiên bản đó. Ví dụ: nếu extension.yaml chỉ định phiên bản 1.0.1 và bạn tải một bản phát hành đề xuất lên, thì phiên bản này sẽ là 1.0.1-rc.0; việc tải một bản phát hành đề xuất khác của cùng phiên bản lên sẽ tự động tăng số lượng, dẫn đến 1.0.1-rc.1, v.v.

Giờ đây, khi đã tải phiên bản phát hành trước của tiện ích lên, bạn có thể chia sẻ phiên bản đó với người khác để thử nghiệm. Người dùng có thể cài đặt tiện ích của bạn theo một trong hai cách sau:

• Bằng bảng điều khiển: Người dùng có thể cài đặt tiện ích bằng cách nhấp vào một đường liên kết có định dạng sau:

  https://console.firebase.google.com/project/_/extensions/install?ref=your_publisher_id/your_extension_id@version

  Bạn có thể chia sẻ đường liên kết trực tiếp với người kiểm thử.

• Bằng CLI: Người dùng có thể cài đặt tiện ích bằng cách truyền chuỗi mã nhận dạng tiện ích đến lệnh ext:install:

  firebase ext:install your_publisher_id/your_extension_id@version \
      --project=destination_project_id
  

Tải phiên bản đã cập nhật lên

Sau khi tải phiên bản đầu tiên của một tiện ích lên, bạn có thể tải bản cập nhật lên để khắc phục sự cố, thêm tính năng hoặc chuyển sang giai đoạn phát hành. Khi bạn tải một phiên bản mới lên, những người dùng đã cài đặt phiên bản cũ của tiện ích sẽ được nhắc nâng cấp trong bảng điều khiển Firebase.

Cách tải nội dung cập nhật lên:

1. Không bắt buộc: Gửi mã của bạn vào kho lưu trữ Git công khai.

2. Chạy lệnh ext:dev:upload của Firebase CLI:

   GitHub

   firebase ext:dev:upload your_publisher_id/your_extension_id

   Lần này, bạn sẽ không được nhắc chỉ định kho lưu trữ GitHub hoặc thư mục gốc của tiện ích vì những kho lưu trữ này đã được định cấu hình cho tiện ích của bạn. Nếu đã tái cấu trúc cấu trúc kho lưu trữ hoặc di chuyển sang kho lưu trữ mới, bạn có thể thay đổi các cấu trúc đó bằng đối số lệnh --root và --repo.

   Nguồn cục bộ

   cd /path/to/extension
   firebase ext:dev:upload your_publisher_id/your_extension_id --local

Gửi phần mở rộng để xuất bản

Khi bạn đã sẵn sàng phát hành công khai tiện ích của mình:

1. Gửi mã của bạn vào kho lưu trữ Git công khai. (Bắt buộc đối với bản phát hành công khai.)

2. Chạy lệnh ext:dev:upload của Firebase CLI, chỉ định stable làm giai đoạn phát hành:

   firebase ext:dev:upload your_publisher_id/your_extension_id

3. Nếu trước đây bạn đã phát hành một phiên bản tiện ích, thì việc tải một bản phát hành ổn định mới lên sẽ tự động gửi tiện ích đó để xem xét.

   Nếu bạn đã tải bản phát hành ổn định đầu tiên của tiện ích lên, hãy tìm tiện ích đó trên trang tổng quan dành cho nhà xuất bản rồi nhấp vào Xuất bản lên Trung tâm tiện ích.

Sau khi bạn gửi, quy trình xem xét có thể mất vài ngày. Nếu được chấp nhận, tiện ích sẽ được phát hành lên Trung tâm tiện ích. Nếu bị từ chối, bạn sẽ nhận được thông báo giải thích lý do. Sau đó, bạn có thể giải quyết các vấn đề được báo cáo rồi gửi lại để được xem xét.

Để đẩy nhanh quá trình xem xét và tăng cơ hội vượt qua lần thử đầu tiên, trước khi gửi, hãy kiểm tra kỹ những thông tin sau:

• Bạn đã kiểm thử kỹ lưỡng tiện ích và quy trình cài đặt.
• Tài liệu của bạn đầy đủ và chính xác, đồng thời hiển thị tốt trong bảng điều khiển Firebase.
• Tên nhà xuất bản và thương hiệu của bạn phải xác định rõ ràng và chính xác bạn là nhà xuất bản.
• Tên, nội dung mô tả và biểu tượng của tiện ích thể hiện rõ ràng và chính xác mục đích của tiện ích.
• Bạn đã áp dụng các thẻ hữu ích và chính xác.
• Trong extension.yaml, bạn đã khai báo mọi API của Google và không phải của Google mà bạn sử dụng cũng như mọi loại sự kiện mà tiện ích của bạn phát ra.
• Bạn đang yêu cầu chỉ cấp quyền truy cập vào các vai trò cần thiết để tiện ích hoạt động, đồng thời bạn đã giải thích rõ ràng cho người dùng lý do bạn cần quyền truy cập đó.
• Các tệp nguồn của bạn được cấp phép rõ ràng theo các điều khoản của Apache-2.0.

Quản lý các tiện ích đã tải lên và đã xuất bản

Liệt kê các tiện ích đã tải lên

Để liệt kê các tiện ích bạn đã tải lên theo mã nhà xuất bản, hãy làm theo một trong các cách sau:

Trang tổng quan dành cho nhà xuất bản

Xem các yêu cầu đó trên trang tổng quan dành cho nhà xuất bản.

Giao diện dòng lệnh (CLI) của Firebase

Chạy lệnh ext:dev:list:

firebase ext:dev:list your_publisher_id

Xem mức sử dụng của các tiện ích bạn đã tải lên

Để xem mức sử dụng của các tiện ích bạn đã tải lên theo mã nhà xuất bản, hãy làm theo một trong những cách sau:

Trang tổng quan dành cho nhà xuất bản

Trang tổng quan dành cho nhà xuất bản có các chỉ số về mức sử dụng tích luỹ cho tất cả các tiện ích và các chỉ số riêng lẻ cho từng tiện ích.

Giao diện dòng lệnh (CLI) của Firebase

Chạy lệnh ext:dev:usage:

firebase ext:dev:usage your_publisher_id

Ngừng sử dụng phiên bản của một tiện ích

Vào một lúc nào đó, bạn có thể muốn không dùng phiên bản tiện ích cũ nữa. Ví dụ: nếu bạn phát hành một phiên bản mới khắc phục lỗi nghiêm trọng hoặc cập nhật một phần phụ thuộc bằng một bản cập nhật bảo mật quan trọng, thì điều quan trọng là bạn phải ngăn người dùng mới cài đặt phiên bản cũ và khuyến khích người dùng hiện tại nâng cấp.

Để ngừng sử dụng một phiên bản của tiện ích, hãy làm theo một trong những cách sau:

Trang tổng quan dành cho nhà xuất bản

1. Trên trang tổng quan của nhà xuất bản, hãy nhấp vào tiện ích để mở chế độ xem chi tiết của tiện ích đó.
2. Chọn phiên bản bạn muốn ngừng sử dụng.
3. Nhấp vào Ngừng sử dụng phiên bản.

Giao diện dòng lệnh (CLI) của Firebase

Chạy lệnh ext:dev:deprecate:

firebase ext:dev:deprecate your_publisher_id/your_extension_id versions \
    [--message "deprecation_message"]

Bạn có thể chỉ định một phiên bản hoặc một phạm vi phiên bản. Ví dụ:

• 1.0.2
• 1.1.0-1.1.7
• <1.2.0
• 1.1.*

Các phiên bản không dùng nữa của tiện ích sẽ không được liệt kê trên Trung tâm tiện ích và không thể cài đặt. Những người dùng có dự án đã cài đặt phiên bản không dùng nữa sẽ thấy một thông báo khuyến khích họ nâng cấp; trong thời gian chờ đợi, họ vẫn có thể sử dụng và định cấu hình lại tiện ích.

Nếu mọi phiên bản của một tiện ích đều không được dùng nữa, thì tiện ích đó sẽ được coi là không được dùng nữa và sẽ bị xoá khỏi Trung tâm tiện ích. Việc tải phiên bản mới của một tiện ích không dùng nữa lên sẽ tự động bắt đầu quy trình xem xét và sau khi được chấp nhận, bạn có thể xuất bản lại tiện ích đó trên Trung tâm tiện ích.

Để đảo ngược một phiên bản ngừng sử dụng, hãy sử dụng trang tổng quan của nhà xuất bản hoặc chạy lệnh ext:dev:undeprecate của Firebase CLI:

firebase ext:dev:undeprecate your_publisher_id/your_extension_id versions

Phụ lục: Khắc phục lỗi bản dựng

Khi bạn tải tiện ích lên, trước tiên, phần phụ trợ sẽ tạo mã nguồn của bạn bằng quy trình sau:

1. Sao chép kho lưu trữ GitHub và kiểm tra tệp đối chiếu nguồn được chỉ định.

2. Cài đặt các phần phụ thuộc NPM bằng cách chạy npm clean-install trong mọi thư mục nguồn hàm được chỉ định trong extension.yaml (xem sourceDirectory trong tài nguyên của Hàm trên đám mây).

   Lưu ý những điều sau:

   • Mỗi tệp package.json phải có một tệp package-lock.json tương ứng. Để biết thêm thông tin, hãy xem npm-ci.

   • Các tập lệnh sau khi cài đặt sẽ không chạy trong quá trình cài đặt phần phụ thuộc. Nếu bản dựng mã nguồn của bạn dựa vào các tập lệnh sau khi cài đặt, hãy tái cấu trúc bản dựng đó trước khi tải lên.

3. Tạo mã bằng cách chạy npm run build trong mọi thư mục nguồn hàm được chỉ định trong extension.yaml.

Chỉ thư mục gốc của tiện ích mới được lưu trong gói tiện ích cuối cùng sẽ được chia sẻ.

Nếu bạn gặp lỗi bản dựng trong khi tải phần mở rộng lên, hãy sao chép các bước tạo bản dựng ở trên trên máy trong một thư mục mới cho đến khi không còn lỗi, sau đó thử tải lên lại.