Mỗi tiện ích phải có tài liệu hướng dẫn người dùng biết tiện ích đó tính năng và cách sử dụng chúng.
Tài liệu tối thiểu và bắt buộc là bộ ba tệp Markdown này:
PREINSTALL.md
POSTINSTALL.md
CHANGELOG.md
Ngoài ra, bạn cũng nên cân nhắc việc tạo:
- Tệp
README
cho kho lưu trữ công khai của tiện ích. - Bài hướng dẫn, tài liệu tham khảo và tài liệu tham khảo có thời lượng dài hơn xuất bản trên trang web của riêng bạn và
được liên kết trong
PREINSTALL.md
của bạn.
Để 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 phổ biến, bạn nên xem lại các tệp có sẵn bằng tiện ích chính thức của Firebase.
Tạo một tệp README
Thư mục tiện ích của bạn có thể chứa một tệp README (không bắt buộc). 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 của Firebase hỗ trợ lệnh tiện lợi sau để
tự động tạo một tệp README
chứa nội dung được lấy từ
Tệp 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 phần tử tiện ích chính thức của Firebase đượ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 một 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 this extension in your Firebase project](https://www.gstatic.com/mobilesdk/210513_mobilesdk/install-extension.png "Install this extension in your Firebase project")][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 một tệp PREINSTALL
Tệp PREINSTALL
là thông tin tổng quan về tiện ích, một loại nội dung "tiếp thị" .
Nội dung nào trong tệp này?
- Mô tả toàn diện về chức năng của tiện ích
- Danh sách đ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 quyền truy cập không phải của Google dịch vụ (ví dụ)
- Nội dung mô tả ngắn gọn về mọi thao tác trước khi cài đặt và hướng dẫn tương ứng
- Nội dung mô tả ngắn gọn về mọi thao tác sau khi cài đặt
(ví dụ)
(xem hướng dẫn chi tiết có trong
POSTINSTALL
) - Mô tả ngắn gọn về mọi vấn đề liên quan đến việc thanh toán (bắt đầu bằng văn bản tạo sẵn)
Nội dung này hiển thị cho người dùng ở đâu?
- 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 trong README của tiện ích (nếu bạn sử dụng Firebase CLI
cờ)--markdown > README.md
Tệp PREINSTALL
không thể truy cập các giá trị tham số cho tiện ích, vì vậy, bạn
không nên mong đợi các tham chiếu tham số hiển thị với 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
PREINSTALL
ở mức dướ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
- Đặt hướng dẫn chi tiết trong tệp
POSTINSTALL
hoặc tệp khác tệp bổ sung - Đề cập ngắn gọn đến việc bạn có cung cấp các công cụ hoặc tập lệnh khác để hỗ trợ tiện ích
Ghi một tệp POSTINSTALL
Tệp POSTINSTALL
là thông tin chi tiết sau cài đặt tiện ích của bạn
trang hướng dẫn.
Nội dung nào trong tệp này?
- Hướng dẫn chi tiết cho mọi thao tác bắt buộc sau khi cài đặt, như thiết lập 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ụ: "truy cập vào bảng điều khiển, sau đó thực hiện thao tác này")
- Thông tin cơ bản về cách kích hoạt tiện ích, đặc biệt đối với Tiện ích 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 đã cài đặt (bắt đầu bằng văn bản tạo sẵn)
Nội dung này hiển thị cho người dùng ở đâu?
Trong bảng điều khiển của 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 lại cách hiển thị nội dung
POSTINSTALL
muộn nhất vào ngày việc cài đặt tiện ích trong phiên bản dự án.
- Hãy nhớ xem lại 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)
Tệp POSTINSTALL
có thể truy cập các giá trị tham số và một số liên quan đến hàm
các biến cho tiện ích. Khi nội dung POSTINSTALL
được hiển thị trong
bảng điều khiển của Firebase, giá trị thực tế sẽ hiển thị thay vì thông số
hoặc tham chiếu biến. Tìm hiểu thêm về cách tham chiếu các thông số và
biến trong tệp POSTINSTALL
.
Một số phương pháp hay nhất là gì?
- Giữ cho toàn bộ nội dung của tệp
POSTINSTALL
ngắn gọn nhưng có tính mô tả. - Chia nhỏ nội dung thành các phần riêng biệt bằng cách sử dụng tiêu đề để tách riêng các nhiệm vụ hoặc các khái niệm khác nhau.
- Cân nhắc xuất bản hướng dẫn chi tiết cho một quy trình công việc hoặc công việc 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à liên quan đến chức năng biến để người dùng thấy các giá trị được định cấu hình của họ 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 của Firebase sẽ hiển thị nội dung của
tệp POSTINSTALL
của tiện ích. Nếu bạn tham chiếu các tham số và hàm liên quan đến hàm
các biến (xem bảng bên dưới) trong tệp POSTINSTALL
, sau đó là 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 thực thể đã cài đặt.
Truy cập các giá trị tham số đã định cấu hình trong tệp POSTINSTALL
bằng cách sử dụng
cú pháp sau: ${param:PARAMETER_NAME}
Bạn cũng có thể tham khảo các biến liên quan đến hàm sau trong
POSTINSTALL
chỉ có thể sử dụng cho tệp POSTINSTALL
. 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
chưa có cho đến khi cài đặt xong.
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
.
Tài liệu tham khảo cho biến liên quan đến hàm | Nội dung mô tả | Giá trị biến (do Firebase tự động điền sau khi 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 chức năng được triển khai cuối cùng, bao gồm mã bản sao của tiện ích |
Định dạng chung:
Giá trị mẫu: |
|
${function:function-name.url}
(chỉ áp dụng cho các hàm HTTP)
|
||
URL của hàm được 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 chung:
Giá trị mẫu: |
Ghi lại 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 của bạn. Các hướng dẫn này có thể chi tiết như bạn
nghĩ là cần thiết, nhưng hãy lưu ý các phương pháp hay nhất để viết
POSTINSTALL
.
Để xem 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 dưới đây
áp dụng cho tiện ích của bạn.
Viết tệp CHANGELOG
Nội dung nào trong tệp này?
Mỗi tiện ích phải có một 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à bạn xuất bản. Đặt từng phiên bản
dưới tiêu đề cấp 2 (##
); nếu không, bạn có thể dùng mọi Markdown
mà bạn muốn.
Ví dụ sau đây là phần trích dẫn 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.
Nội dung này hiển thị cho người dùng ở đâu?
- Trong bảng điều khiển của 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 của Firebase và CLI chỉ hiển thị các 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 của bạn (bên trong thư mục tiện ích).