Mọi tiện ích mở rộng đều phải có tài liệu hướng dẫn người dùng chức năng của tiện ích mở rộng và cách sử dụng tiện ích mở rộng đó.
Tài liệu tối thiểu, bắt buộc là bộ ba tệp đánh dấu này:
-
PREINSTALL.md -
POSTINSTALL.md -
CHANGELOG.md
Ngoài ra, bạn cũng nên cân nhắc việc sản xuất:
- Tệp
READMEcho kho lưu trữ công cộng của tiện ích mở rộng. - Các hướng dẫn, hướng dẫn và tài liệu tham khảo dạng dài hơn được xuất bản trên trang web của riêng bạn và được liên kết trong
PREINSTALL.mdcủa bạn.
Để tìm hiểu một số phương pháp hay nhất cũng như cụm từ và cấu trúc phổ biến, chúng tôi khuyên bạn nên xem lại các tệp có sẵn với tiện ích mở rộng chính thức của Firebase .
Tạo README
Thư mục tiện ích mở rộng của bạn có thể tùy ý chứa README. Lưu ý rằng lệnh firebase ext:dev:init không tự động tạo một lệnh cho bạn.
Tuy nhiên, Firebase CLI hỗ trợ lệnh tiện lợi sau để tự động tạo tệp README chứa nội dung được lấy từ tệp tiện extension.yaml và tệp PREINSTALL.md của bạn:
firebase ext:info ./path/to/extension --markdown > README.md
Tất cả các tệp README cho tiện ích mở rộng Firebase chính thức được tạo bằng lệnh này.
Thêm thông tin cài đặt
Sau khi bạn viết hoặc tạo README, hãy thêm thông tin cài đặt vào đó. Bạn có thể sử dụng đoạn mã sau làm mẫu:
--- ## 🧩 Install this extension ### Console [][install-link] [install-link]: https://console.firebase.google.com/project/_/extensions/install?ref=publisher_id/extension_name ### Firebase CLI ```bash firebase ext:install publisher_id/extension_name --project=[your-project-id] ``` > Learn more about installing extensions in the Firebase Extensions documentation: > [console](https://firebase.google.com/docs/extensions/install-extensions?platform=console), > [CLI](https://firebase.google.com/docs/extensions/install-extensions?platform=cli) ---
Viết một tập tin PREINSTALL
Tệp PREINSTALL là thông tin tổng quan về tiện ích mở rộng của bạn, một loại trang "tiếp thị".
Nội dung nào có trong tập tin này?
- Mô tả đầy đủ về chức năng của tiện ích mở rộng của bạn
- Danh sách các điều kiện tiên quyết, chẳng hạn như thiết lập cơ sở dữ liệu hoặc truy cập vào dịch vụ không phải của Google ( ví dụ )
- Mô tả ngắn gọn về mọi tác vụ cài đặt sẵn và hướng dẫn thực hiện
- Mô tả ngắn gọn về mọi tác vụ sau khi cài đặt ( ví dụ ) (hướng dẫn chi tiết có trong
POSTINSTALL) - Mô tả ngắn gọn về bất kỳ ý nghĩa thanh toán nào (bắt đầu bằng văn bản soạn sẵn )
Nội dung này hiển thị ở đâu cho người dùng?
- Trên trang của tiện ích mở rộng trên Extensions.dev .
- Kho lưu trữ mã nguồn cho tiện ích mở rộng của bạn (bên trong thư mục tiện ích mở rộng)
- Là một phần của README của tiện ích mở rộng (nếu bạn sử dụng Firebase CLI
--markdown > README.md
Các tệp PREINSTALL không thể truy cập các giá trị tham số cho tiện ích mở rộng, vì vậy bạn không nên mong đợi các tham chiếu tham số sẽ hiển thị với các giá trị thực tế.
Một số phương pháp hay nhất là gì?
- Giữ toàn bộ nội dung của tệp
PREINSTALLdưới một trang , nếu có thể - Cung cấp mức độ chi tiết mà người dùng cuối thực sự cần biết trước khi cài đặt tiện ích mở rộng
- Đưa hướng dẫn chi tiết vào file
POSTINSTALLhoặc file bổ sung khác - Đề cập ngắn gọn nếu bạn cung cấp các công cụ hoặc tập lệnh khác để hỗ trợ tiện ích mở rộng
Chúng tôi khuyên bạn nên sử dụng càng nhiều văn bản soạn sẵn sau đây càng tốt, nếu có thể áp dụng cho tiện ích mở rộng của bạn. Chúng tôi đã cung cấp một số ví dụ nhưng điểm quan trọng nhất là đảm bảo tất cả các dịch vụ do Google và dịch vụ không phải của Google đều được liệt kê.
Bạn có thể sử dụng các tài nguyên sau để tìm thông tin chi tiết về giá sản phẩm chính xác:
Đối với tất cả tiện ích mở rộng, hãy bao gồm phần này để giúp người dùng của bạn hiểu ý nghĩa thanh toán:
Billing
This extension uses other Firebase or Google Cloud services which may have
associated charges:
* <list Google services / products that your extension uses>
* <list Firebase services that your extension uses>
* Cloud Secret Manager <if the extension uses secret params>
* Cloud Functions
When you use Firebase Extensions, you're only charged for the underlying
resources that you use. A paid-tier billing plan is only required if the
extension uses a service that requires a paid-tier plan, for example calling to
a Google Cloud API or making outbound network requests to non-Google services.
All Firebase services offer a no-cost tier of usage.
[Learn more about Firebase billing.](https://firebase.google.com/pricing)
<Applicable info about billing implications for non-Google services, such as:>
Usage of this extension also requires you to have a <non-Google-service> account.
You are responsible for any associated costs with your usage of <non-Google-service>.
Viết một tập tin POSTINSTALL
Tệp POSTINSTALL là trang hướng dẫn chi tiết sau khi cài đặt tiện ích mở rộng của bạn.
Nội dung nào có trong tập tin này?
- Hướng dẫn chi tiết cho mọi tác vụ bắt buộc sau khi cài đặt, như thiết lập quy tắc bảo mật Firebase hoặc thêm mã phía máy khách ( ví dụ )
- Hướng dẫn chung về cách dùng thử ngay tiện ích mở rộng đã cài đặt (ví dụ: "đi tới bảng điều khiển, sau đó thực hiện việc này")
- Thông tin cơ bản về cách kích hoạt tiện ích mở rộng, đặc biệt đối với tiện ích mở rộng kích hoạt yêu cầu HTTP
- Hướng dẫn ngắn gọn về cách giám sát tiện ích mở rộng đã cài đặt (bắt đầu bằng văn bản soạn sẵn )
Nội dung này hiển thị ở đâu cho người dùng?
Trong bảng điều khiển Firebase sau khi người dùng cài đặt tiện ích của bạn (trong thẻ chi tiết của tiện ích đã cài đặt)
- Đảm bảo xem lại việc hiển thị nội dung
POSTINSTALLbằng cách cài đặt tiện ích mở rộng của bạn trong một dự án thực tế .
- Đảm bảo xem lại việc hiển thị nội dung
Kho lưu trữ mã nguồn cho tiện ích mở rộng của bạn (bên trong thư mục tiện ích mở rộng)
Các tệp POSTINSTALL có thể truy cập các giá trị tham số và một số biến liên quan đến hàm cho tiện ích mở rộng. Khi nội dung POSTINSTALL được hiển thị trong bảng điều khiển Firebase, các giá trị thực tế sẽ hiển thị thay vì tham chiếu tham số hoặc biến. Tìm hiểu thêm bên dưới về cách tham chiếu các tham số và biến trong tệp POSTINSTALL của bạn.
Một số phương pháp hay nhất là gì?
- Giữ nội dung đầy đủ của tệp
POSTINSTALLngắn gọn nhưng mang tính mô tả. - Phân chia nội dung bằng cách sử dụng các tiêu đề để chia nhỏ các nhiệm vụ hoặc khái niệm riêng biệt.
- Hãy cân nhắc việc xuất bản các hướng dẫn chi tiết cho một quy trình công việc hoặc tác vụ cụ thể trên trang web của bạn ( ví dụ ) hoặc trong các tệp đánh dấu bổ sung trong kho lưu trữ tiện ích mở rộng ( ví dụ ).
- Các tham số tham chiếu và các biến liên quan đến hàm để người dùng nhìn thấy các giá trị được cấu hình của chúng trong ngữ cảnh của hướng dẫn
Tham chiếu các tham số và biến
Sau khi cài đặt, bảng điều khiển Firebase hiển thị nội dung của tệp POSTINSTALL của tiện ích mở rộng. Nếu bạn tham chiếu các tham số và biến liên quan đến hàm (xem bảng bên dưới) trong tệp POSTINSTALL thì bảng điều khiển sẽ điền các tham chiếu này bằng các giá trị thực tế cho phiên bản đã cài đặt.
Truy cập các giá trị tham số được định cấu hình trong tệp POSTINSTALL bằng cú pháp sau:${param: PARAMETER_NAME }
Bạn cũng có thể tham chiếu các biến liên quan đến hàm sau trong tệp POSTINSTALL của mình . Firebase hỗ trợ các biến này để bạn có thể dễ dàng cung cấp hướng dẫn cho người dùng sau khi cài đặt. Chúng chỉ có sẵn để sử dụng trong tệp POSTINSTALL vì các giá trị cho các biến này không có sẵn cho đến sau khi cài đặt.
Trong bảng này, function-name là giá trị của trường name trong đối tượng tài nguyên của hàm trong extension.yaml .
| Tham chiếu cho biến liên quan đến hàm | Sự miêu tả | Giá trị biến (được Firebase tự động điền sau khi cài đặt tiện ích mở rộng) |
|---|---|---|
${function: function-name .location} | ||
| Vị trí triển khai chức năng | Giá trị ví dụ:us-central1 | |
${function: function-name .name} | ||
| Tên của chức năng được triển khai cuối cùng, bao gồm ID phiên bản của tiện ích mở rộng | Dạng tổng quát: Giá trị ví dụ: | |
${function: function-name .url} (chỉ áp dụng cho các hàm HTTP) | ||
| URL của chức năng được triển khai cuối cùng mà mã máy khách có thể thực hiện các yêu cầu HTTP | Dạng tổng quát: Giá trị ví dụ: | |
Chúng tôi khuyên bạn nên sử dụng càng nhiều văn bản soạn sẵn sau đây càng tốt, nếu có thể áp dụng cho tiện ích mở rộng của bạn.
Đối với tất cả tiện ích mở rộng, hãy bao gồm phần sau để giúp người dùng của bạn giám sát tiện ích mở rộng đã cài đặt của họ:
Monitoring
As a best practice, you can
[monitor the activity](https://firebase.google.com/docs/extensions/manage-installed-extensions_community#monitor)
of your installed extension, including checks on its health, usage, and logs.
Tài liệu cách kích hoạt tiện ích mở rộng
Trong tài liệu dành cho người dùng tiện ích mở rộng, bạn cần hướng dẫn người dùng về cách kích hoạt tiện ích mở rộng của mình. Những hướng dẫn này có thể chi tiết đến mức bạn cho là cần thiết nhưng hãy ghi nhớ các phương pháp hay nhất để ghi tệp POSTINSTALL . Để biết hướng dẫn về cách cung cấp những hướng dẫn này, hãy mở rộng phần bên dưới áp dụng cho tiện ích mở rộng của bạn.
Người dùng của bạn có thể kích hoạt tiện ích mở rộng kích hoạt sự kiện nền theo nhiều cách khác nhau, tùy thuộc vào sản phẩm có liên quan.
Thực hiện thay đổi trực tiếp trong bảng điều khiển
Bạn có thể hướng dẫn người dùng thực hiện các thay đổi kích hoạt tiện ích mở rộng trực tiếp trong bảng điều khiển Firebase, đặc biệt là đối với thử nghiệm ban đầu của họ đối với tiện ích mở rộng của bạn. Ví dụ: giả sử tiện ích mở rộng của bạn tạo tài liệu Cloud Firestore mới bất cứ khi nào người dùng Xác thực Firebase mới được tạo. Bạn có thể hướng dẫn người dùng kiểm tra phiên bản đã cài đặt của tiện ích mở rộng bằng cách thêm người dùng Xác thực mới vào bảng điều khiển theo cách thủ công. Sau đó, họ có thể quan sát tài liệu mới được tạo trong phần Cloud Firestore của bảng điều khiển.
Thêm mã phía máy khách
Khi thích hợp, bạn cũng có thể hướng dẫn người dùng cách thêm mã phía máy khách để kích hoạt tiện ích mở rộng của mình. Bạn nên hướng người dùng tới tài liệu chính thức về các API mà họ sẽ cần sử dụng. Bạn cũng có thể bao gồm các ứng dụng mẫu hoặc mẫu ứng dụng khách đã biên soạn để giúp người dùng của bạn tích hợp tiện ích mở rộng vào ứng dụng của họ (tham khảo tiện ích mở rộng Bộ đếm phân phối để biết ví dụ).
Để người dùng của bạn có thể kích hoạt hàm được kích hoạt yêu cầu HTTP (và do đó là tiện ích mở rộng), bạn cần cung cấp cho họ tên của hàm được triển khai hoặc URL của hàm đó .
Tên của hàm được triển khai cuối cùng không giống với name mà bạn đã chỉ định trong đối tượng tài nguyên của hàm trong extension.yaml . Để đáp ứng nhiều lượt cài đặt của cùng một tiện ích mở rộng trong một dự án, Firebase đổi tên hàm theo định dạng sau:ext- extension-instance-id - function-name .
Các dấu đầu dòng sau đây là văn bản soạn sẵn được đề xuất để đưa vào tệp POSTINSTALL của tiện ích mở rộng của bạn. Sau khi cài đặt, bảng điều khiển Firebase hiển thị nội dung của tệp POSTINSTALL và điền các tham chiếu này với các giá trị được định cấu hình thực tế cho phiên bản đã cài đặt. Ví dụ: nếu bạn đã xác định một hàm có tên yourFunction , bạn có thể bao gồm các mục sau (nếu có):
Đối với các hàm HTTP
onRequestTo trigger this extension, make a request to or visit the following URL: **`${function:yourFunction.url}`**.Đối với các hàm có thể gọi HTTP (
onCall)This extension is implemented as an HTTP callable function. To call it from your client app, follow the instructions in the [callable functions documentation](https://firebase.google.com/docs/functions/callable#call_the_function). The name of the function to call is **`${function:yourFunction.name}`**, and its region is **`${function:yourFunction.location}`**.
Viết một tập tin CHANGELOG
Nội dung nào có trong tập tin này?
Mọi tiện ích mở rộng phải có tệp CHANGELOG.md ghi lại các thay đổi có trong mỗi phiên bản mới của tiện ích mở rộng mà bạn xuất bản. Đặt mỗi phiên bản dưới tiêu đề cấp 2 ( ## ); nếu không, bạn có thể sử dụng bất kỳ định dạng Markdown nào bạn thích.
Ví dụ sau đây là đoạn trích từ một trong các tiện ích mở rộng chính thức:
## Version 0.1.3 feature - Support deletion of directories (issue #148). ## Version 0.1.2 feature - Add a new param for recursively deleting subcollections in Cloud Firestore (issue #14). fixed - Fixed "cold start" errors experienced when the extension runs after a period of inactivity (issue #48). ## Version 0.1.1 Initial release of the _Delete User Data_ extension.
Nội dung này hiển thị ở đâu cho người dùng?
- Trong bảng điều khiển Firebase và CLI, khi người dùng nâng cấp lên phiên bản tiện ích mở rộng mới của bạn. Bảng điều khiển Firebase và CLI chỉ hiển thị những thay đổi sẽ có hiệu lực nếu người dùng hoàn tất nâng cấp.
- Kho lưu trữ mã nguồn của tiện ích mở rộng của bạn (bên trong thư mục tiện ích mở rộng).