Mỗi tiện ích phải có tài liệu hướng dẫn người dùng về chức năng và cách sử dụng tiện ích đó.
Tài liệu tối thiểu, bắt buộc là bộ gồm 3 tệp đánh dấu này:
PREINSTALL.mdPOSTINSTALL.mdCHANGELOG.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 khai của tiện ích. - Các bài viết hướng dẫn, chỉ dẫn và tài liệu tham khảo 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.md.
Để tìm hiểu một số phương pháp hay nhất cũng như cách diễn đạt và cấu trúc thường gặp, bạn nên xem xét các tệp có trong tiện ích Firebase chính thức.
Tạo tệp README
Thư mục tiện ích của bạn có thể chứa một tệp README (nếu muốn). Xin 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, CLI Firebase có hỗ trợ lệnh thuận tiện sau đây để tự động tạo tệp README chứa nội dung được lấy từ tệp extension.yaml và tệp PREINSTALL.md:
firebase ext:info ./path/to/extension --markdown > README.md
Tất cả các tệp README cho các tiện ích Firebasechính thức đều được tạo bằng lệnh này.
Thêm thông tin lắp đặt
Sau khi bạn viết hoặc tạo một tệp README, hãy thêm thông tin cài đặt vào tệp đó. 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) ---
Ghi tệp PREINSTALL
Tệp PREINSTALL là thông tin tổng quan về tiện ích của bạn, một loại trang "tiếp thị".
Tệp này có nội dung gì?
- Nội dung mô tả đầy đủ về chức năng của tiện ích
- 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 quyền truy cập vào một dịch vụ không phải của Google (ví dụ)
- Nội dung mô tả ngắn gọn về mọi tác vụ trước khi cài đặt và hướng dẫn thực hiện các tác vụ đó
- Nội dung mô tả ngắn gọn về mọi việc cần làm sau khi cài đặt
(ví dụ)
(hướng dẫn chi tiết nằm trong
POSTINSTALL) - Nội dung mô tả ngắn gọn về mọi tác động đến việc thanh toán (bắt đầu bằng văn bản mẫu)
Người dùng nhìn thấy nội dung này ở đâu?
Bảng điều khiển của Firebase">
Bảng điều khiển Firebase">
- Trên trang của tiện ích trên extensions.dev.
- Kho lưu trữ mã nguồn cho tiện ích của bạn (bên trong thư mục tiện ích)
- Là một phần của tệp README của tiện ích (nếu bạn sử dụng cờ Firebase CLI
--markdown > README.md
Các tệp PREINSTALL không thể truy cập vào các giá trị tham số cho tiện ích, vì vậy bạn không nên mong đợi các giá trị tham số sẽ hiển thị bằng các giá trị thực tế.
Đâu là một số phương pháp hay nhất?
- Giữ toàn bộ nội dung của tệp
PREINSTALLtrong một trang (nếu có thể) - Cung cấp mức độ chi tiết mà người dùng cuối hoàn toàn cần biết trước khi cài đặt tiện ích
- Đưa hướng dẫn chi tiết vào tệp
POSTINSTALLhoặc các tệp 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
Ghi tệp POSTINSTALL
Tệp POSTINSTALL là trang hướng dẫn chi tiết sau khi cài đặt của tiện ích.
Tệp này có nội dung gì?
- Hướng dẫn chi tiết cho mọi tác vụ bắt buộc sau khi cài đặt, chẳng hạn như thiết lập các quy tắc bảo mật của 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 đã cài đặt (ví dụ: "chuyển đến bảng điều khiển, sau đó làm việc này")
- Thông tin cơ bản về cách kích hoạt tiện ích, đặc biệt là đối với tiện ích được kích hoạt bằng yêu cầu HTTP
- Hướng dẫn ngắn gọn về cách giám sát tiện ích đã cài đặt (bắt đầu bằng văn bản mẫu)
Người dùng nhìn thấy nội dung này ở đâu?
Bảng điều khiển của Firebase">
Bảng điều khiển Firebase">
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)
- Hãy nhớ xem xét cách hiển thị nội dung
POSTINSTALLbằng cách cài đặt tiện ích trong một dự án thực tế.
- Hãy nhớ xem xét cách hiển thị nội dung
Kho lưu trữ mã nguồn cho tiện ích của bạn (bên trong thư mục tiện ích)
Các tệp POSTINSTALL có thể truy cập vào các giá trị tham số và một số biến liên quan đến hàm cho tiện ích. Khi nội dung POSTINSTALL xuất hiện trong bảng điều khiển Firebase, giá trị thực tế sẽ xuất hiện thay vì các tham số hoặc biến tham chiếu. 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.
Đâu là một số phương pháp hay nhất?
- Nội dung đầy đủ của tệp
POSTINSTALLphải súc tích nhưng có tính mô tả. - Chia nội dung thành các phần bằng cách sử dụng tiêu đề để tách biệt 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 hướng dẫn chi tiết cho một quy trình hoặc nhiệm vụ cụ thể trên trang web của bạn (ví dụ) hoặc trong các tệp markdown bổ sung trong kho lưu trữ tiện ích (ví dụ).
- Tham số tham chiếu và các biến liên quan đến hàm để người dùng thấy các giá trị đã định cấu hình trong bối cảnh của hướng dẫn
Tham số và biến tham chiếu
Sau khi cài đặt, bảng điều khiển Firebase sẽ hiển thị nội dung của tệp POSTINSTALL trong tiện ích. 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 sẵn các giá trị thực tế cho thực thể đã cài đặt vào các tham chiếu này.
Truy cập vào các giá trị tham số đã đị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 chỉ trong tệp POSTINSTALL. Firebase hỗ trợ những biến này để bạn có thể dễ dàng hướng dẫn người dùng sau khi cài đặt. Bạn chỉ có thể sử dụng các biến này trong tệp POSTINSTALL vì các giá trị cho những biến này chỉ có 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.
| Thông tin tham khảo về biến liên quan đến hàm | Nội dung mô tả | Giá trị biến (Firebase tự động điền sau khi bạn cài đặt tiện ích) |
|---|---|---|
${function:function-name.location}
|
||
| Vị trí nơi triển khai hàm |
Giá trị mẫu:us-central1
|
|
${function:function-name.name}
|
||
| Tên của hàm được triển khai cuối cùng, bao gồm cả mã nhận dạng phiên bản của tiện ích |
Định dạng tổng quát:
Giá trị mẫu: |
|
${function:function-name.url}
(chỉ áp dụng cho các hàm HTTP)
|
||
| URL của hàm đã triển khai cuối cùng mà mã ứng dụng có thể thực hiện các yêu cầu HTTP |
Định dạng tổng quát:
Giá trị mẫu: |
|
Tài liệu về cách kích hoạt một tiện ích
Trong tài liệu người dùng của tiện ích, bạn cần hướng dẫn người dùng về cách kích hoạt tiện ích. Bạn có thể đưa ra hướng dẫn chi tiết đến mức cần thiết, nhưng hãy nhớ các phương pháp hay nhất để viết tệp POSTINSTALL.
Để xem hướng dẫn về cách cung cấp các chỉ dẫn này, hãy mở rộng phần bên dưới áp dụng cho tiện ích của bạn.
Viết tệp NHẬT KÝ THAY ĐỔI
Tệp này có nội dung gì?
Mỗi tiện ích đều phải có một tệp CHANGELOG.md ghi lại những thay đổi có trong mỗi phiên bản mới của tiện ích mà bạn xuất bản. Đặt mỗi phiên bản trong 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 muốn.
Ví dụ sau đây là một đoạn trích từ một trong các tiện ích 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.
Người dùng nhìn thấy nội dung này ở đâu?
- Trong bảng điều khiển Firebase và CLI, khi người dùng nâng cấp lên các phiên bản mới của tiện ích. 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 quá trình nâng cấp.
- Kho lưu trữ mã nguồn của tiện ích (bên trong thư mục tiện ích).