Tạo tài liệu người dùng cho tiện ích của bạn

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?

Cài đặt sẵn nội dung trong bảng điều khiển của 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 trong README của tiện ích (nếu bạn sử dụng Firebase CLI --markdown > README.md cờ)

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

Văn bản tạo sẵn PREINSTALL hữu ích

Bạn nên sử dụng càng nhiều văn bản nguyên mẫu sau đây càng tốt áp dụng cho tiện ích của bạn. Chúng tôi đã cung cấp một số ví dụ, nhưng hầu hết điểm quan trọng là đảm bảo tất cả dịch vụ được lập hoá đơn của Google và không phải của Google đều trong danh sách.

Bạn có thể tham khảo các tài nguyên sau để tìm đúng thông tin về giá sản phẩm:

• Bảng giá sản phẩm Google Cloud
• Tổng quan về giá của Firebase

Đối với tất cả tiện ích, hãy thêm mục này để giúp người dùng của bạn nắm được quy trình thanh toán hệ quả:

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

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?

Nội dung sau khi cài đặt trong bảng điều khiển của Firebase

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

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

Mẹo: Đối với các giá trị có thể dài (như cơ sở dữ liệu) đường dẫn hoặc URL hàm), hãy tham chiếu tham số hoặc biến ở cuối câu và phần. Phương pháp hay nhất này giúp người dùng đọc câu dễ hơn bảng điều khiển của Firebase khi nội dung của tệp POSTINSTALL là được hiển thị với các giá trị thực 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: ext-extension-instance-id-function-name Giá trị mẫu: ext-my-awesome-extension-6m31-yourFunctionName
${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: https://deployment-location-project-id.cloudfunctions.net/name-of-final-deployed-function Giá trị mẫu: https://us-central1-project-123.cloudfunctions.net/ext-my-awesome-extension-6m31-yourFunctionName

Văn bản tạo sẵn POSTINSTALL hữu ích

Bạn nên sử dụng càng nhiều văn bản nguyên mẫu sau đây càng tốt áp dụng cho tiện ích của bạn.

Đối với tất cả các tiện ích, 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 họ đã cài đặt:

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.

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.

Tiện ích kích hoạt sự kiện trong nền

Người dùng của bạn có thể kích hoạt tiện ích kích hoạt sự kiện trong nền theo nhiều cách, tuỳ thuộc vào sản phẩm có liên quan.

Thực hiện thay đổi ngay 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 trực tiếp trong bảng điều khiển của Firebase, đặc biệt là cho quá trình thử nghiệm ban đầu đối với tiện ích của bạn. Để ví dụ: giả sử tiện ích của bạn tạo một tài liệu mới trên Cloud Firestore bất cứ khi nào Đã tạo người dùng Xác thực Firebase mới. Bạn có thể hướng dẫn người dùng thử nghiệm bản sao tiện ích đã cài đặt của bạn bằng cách thêm người dùng Xác thực mới theo cách thủ công trong bảng điều khiển. 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

Nếu được, 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 của bạn. Bạn nên hướng người dùng đến tài liệu chính thức cho các API mà họ sẽ cần dùng. Bạn cũng có thể bao gồm các ứng dụng mẫu hoặc các mẫu ứng dụng khách được 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 (tham khảo Phần mở rộng về Bộ đếm đã phân phối chẳng hạn).

Tiện ích kích hoạt yêu cầu HTTP

Để người dùng có thể kích hoạt hàm kích hoạt yêu cầu HTTP (và do đó tiện ích), bạn cần cung cấp cho chúng hàm được triển khai tên hoặc tên URL.

Tên của hàm được triển khai cuối cùng không giống với name mà bạn được chỉ định trong đối tượng tài nguyên của hàm trong extension.yaml. Người nhận hỗ trợ nhiều lượt cài đặt cùng một tiện ích trong một dự án, Firebase sẽ đổ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 tạo sẵn được đề xuất để đưa vào tệp POSTINSTALL của tiện ích. Sau khi cài đặt, bảng điều khiển của Firebase hiển thị nội dung của tệp POSTINSTALL và điền các tệp tham chiếu này có 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 hàm có tên yourFunction, bạn có thể đưa vào sau (nếu có):

• Đối với các hàm HTTP onRequest

  To 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}`**.
  

Lưu ý quan trọng: Trước khi người dùng có thể sử dụng tiện ích đã kích hoạt yêu cầu HTTP, họ cần đảm bảo các chức năng được triển khai cho tiện ích có thể truy cập công khai. Hướng dẫn chi tiết để cung cấp cho người dùng của bạn có trong văn bản tạo sẵn ví dụ nêu trê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).