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 về chức năng của tiện ích và cách sử dụng tiện ích.

Tài liệu tối thiểu, bắt buộc là bộ ba tệp markdown sau:

  • 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.
  • Các hướng dẫn, tài liệu tham khảo và hướng dẫn 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 phổ biến, bạn nên xem lại các tệp có sẵn với 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 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 tệp cho bạn.

Tuy nhiên, CLI Firebase hỗ trợ lệnh tiện lợi 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ả tệp README cho các tiện ích Firebase chính thức đều đượ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 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 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 tệp PREINSTALL

Tệp PREINSTALL là thông tin tổng quan về tiện ích, một loại trang "tiếp thị".

Tệp này có nội dung gì?

  • Nội dung mô tả toàn diện 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 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 tác vụ 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 vấn đề liên quan đến việc thanh toán (bắt đầu bằng văn bản mẫu)

Nội dung này hiển thị cho người dùng ở đâu?

Hình ảnh nội dung cài đặt trước trong <span class=Bảng điều khiển của Firebase">
Tải trước nội dung trong bảng điều khiển Firebase

Hình ảnh lớn về nội dung cài đặt trước trong <span class=Bảng điều khiển Firebase">

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 tệp tham chiếu tham số hiển thị bằng 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 PREINSTALL trong một trang, nếu có thể
  • Cung cấp mức độ chi tiết mà người dùng cuối 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 các tệp bổ sung khác
  • Giới thiệu 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 này

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, miễn là áp dụng được cho tiện ích của bạn. Chúng tôi đã cung cấp một số ví dụ, nhưng điều quan trọng nhất là đảm bảo tất cả các dịch vụ do Google và bên không phải Google tính phí đều được liệt kê.

Bạn có thể sử dụng các tài nguyên sau đây để tìm thông tin chi tiết chính xác về giá sản phẩm:

Đối với tất cả tiện ích, hãy thêm phần này để giúp người dùng hiểu rõ các vấn đề liên quan đến việc 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>.

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 về mọi tác vụ bắt buộc sau khi cài đặt, chẳng hạn 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 đã cài đặt (ví dụ: "chuyển đến bảng điều khiển, sau đó làm như sau")
  • Thông tin cơ bản về cách kích hoạt tiện ích, đặc biệt là đối với các 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 theo dõi phần mở rộng đã cài đặt (bắt đầu bằng văn bản nguyên mẫu)

Nội dung này hiển thị cho người dùng ở đâu?

Hình ảnh nội dung sau khi cài đặt trong <span class=Bảng điều khiển Firebase">
Nội dung sau khi cài đặt trong bảng điều khiển Firebase

Hình ảnh lớn về nội dung sau khi cài đặt trong <span class=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)

  • Kho lưu trữ mã nguồn của tiện ích (bên trong thư mục tiện ích)

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 hiển thị trong bảng điều khiển Firebase, giá trị thực tế sẽ hiển thị thay vì tham số hoặc tệp tham chiếu 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.

Một số phương pháp hay nhất là gì?

  • Nội dung đầy đủ của tệp POSTINSTALL phải súc tích nhưng mang tính mô tả.
  • Phân chia nội dung bằng cách sử dụng tiêu đề để tách các nhiệm vụ hoặc khái niệm riêng biệt.
  • Hãy cân nhắc việc phát hành hướng dẫn chi tiết về 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 markdown bổ sung trong kho lưu trữ tiện ích (ví dụ).
  • Tham số tham chiếu và biến liên quan đến hàm để người dùng thấy các giá trị đã định cấu hình trong ngữ cảnh của hướng dẫn

Tham chiếu tham số và biến

Sau khi cài đặt, bảng điều khiển 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à 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 giá trị thực tế cho thực thể đã cài đặt.

Truy cập vào các giá trị thông 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 sau chỉ trong 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. Bạn chỉ có thể sử dụng các biến này trong tệp POSTINSTALL vì các giá trị cho các biến này sẽ 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 (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 hàm đã triển khai cuối cùng, bao gồm cả ID thực thể của tiện ích

Định dạng tổng quát:
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 đã triển khai cuối cùng mà mã ứng dụng có thể thực hiện yêu cầu HTTP

Định dạng tổng quát:
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

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, miễn là áp dụng được cho tiện ích của bạn.

Đối với tất cả tiện ích, hãy thêm phần sau đây để giúp người dùng theo dõi tiện ích đã 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 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ể làm theo hướng dẫn này một cách chi tiết nếu cần, nhưng hãy lưu ý đến các phương pháp hay nhất để viết tệp POSTINSTALL. Để biết hướng dẫn về cách cung cấp các 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.

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

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 ngay trong bảng điều khiển Firebase, đặc biệt là khi họ kiểm thử ban đầu 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 Cloud Firestore mới mỗi khi tạo một người dùng Firebase Authentication mới. Bạn có thể hướng dẫn người dùng kiểm thử một phiên bản đã cài đặt của tiện ích bằng cách thêm người dùng Authentication 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 của mình. Bạn nên hướng người dùng đến tài liệu chính thức về các API mà họ cần sử dụng. Bạn cũng có thể đưa vào các ứng dụng mẫu hoặc mẫu ứng dụng khách đã biên dịch để giúp người dùng tích hợp tiện ích vào ứng dụng của họ (tham khảo ví dụ về tiện ích Bộ đếm phân tán).

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

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. Để 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 này: ext-extension-instance-id-function-name.

Các dấu đầu dòng sau đây là văn bản nguyên mẫu đượ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 Firebase sẽ hiển thị nội dung của tệp POSTINSTALL và điền các tệp tham chiếu này bằng các giá trị được định cấu hình thực tế cho thực thể đã cài đặt. Ví dụ: nếu đã xác định một hàm có tên là yourFunction, bạn có thể thêm các nội dung sau (nếu có):

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

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

Ghi tệp CHANGELOG

Tệp này có nội dung gì?

Mỗi tiện ích phải có một tệp CHANGELOG.md ghi lại các thay đổi trong mỗi phiên bản mới của tiện ích mà bạn phát hành. Đặt mỗi phiên bản vào một 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.

Nội dung này hiển thị cho người dùng ở đâ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).