สร้างเอกสารประกอบผู้ใช้สำหรับส่วนขยายของคุณ

ส่วนขยายทุกรายการต้องมีเอกสารประกอบที่สอนผู้ใช้ว่าส่วนขยายนั้นทำอะไรและใช้งานอย่างไร

เอกสารประกอบขั้นต่ำที่จำเป็นคือชุดไฟล์มาร์กดาวน์ 3 ไฟล์ต่อไปนี้

• PREINSTALL.md
• POSTINSTALL.md
• CHANGELOG.md

นอกจากนี้ คุณควรพิจารณาสร้างเนื้อหาต่อไปนี้ด้วย

• ไฟล์ README สำหรับที่เก็บสาธารณะของส่วนขยาย
• บทแนะนำ คู่มือ และข้อมูลอ้างอิงแบบยาวที่เผยแพร่ในเว็บไซต์ของคุณเองและลิงก์ใน PREINSTALL.md

หากต้องการดูแนวทางปฏิบัติแนะนำ รวมถึงโครงสร้างและวลีที่ใช้กันโดยทั่วไป เราขอแนะนำให้อ่านไฟล์ที่มาพร้อมกับส่วนขยาย Firebase อย่างเป็นทางการ

การสร้าง README

ไดเรกทอรีส่วนขยายอาจมี README หรือไม่มีก็ได้ โปรดทราบว่าคำสั่ง firebase ext:dev:init จะไม่สร้างคีย์ให้คุณโดยอัตโนมัติ

อย่างไรก็ตาม Firebase CLI รองรับคำสั่งอำนวยความสะดวกต่อไปนี้เพื่อสร้างไฟล์ README โดยอัตโนมัติซึ่งมีเนื้อหาที่ดึงมาจากไฟล์ extension.yaml และไฟล์ PREINSTALL.md

firebase ext:info ./path/to/extension --markdown > README.md

ระบบจะสร้างไฟล์ README ทั้งหมดสำหรับส่วนขยาย Firebase อย่างเป็นทางการโดยใช้คำสั่งนี้

เพิ่มข้อมูลการติดตั้ง

หลังจากเขียนหรือสร้าง README แล้ว ให้เพิ่มข้อมูลการติดตั้งลงในไฟล์ดังกล่าว คุณใช้ข้อมูลโค้ดต่อไปนี้เป็นเทมเพลตได้

---

## 🧩 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)

---

กำลังเขียนไฟล์ PREINSTALL

ไฟล์ PREINSTALL คือภาพรวมของส่วนขยาย ซึ่งเป็นหน้า "การตลาด" ประเภทหนึ่ง

ไฟล์นี้มีเนื้อหาอะไรบ้าง

• คำอธิบายที่ครอบคลุมเกี่ยวกับฟังก์ชันการทำงานของส่วนขยาย
• รายการข้อกำหนดเบื้องต้น เช่น การตั้งค่าฐานข้อมูลหรือการเข้าถึงบริการที่ไม่ใช่ของ Google (ตัวอย่าง)
• คำอธิบายสั้นๆ เกี่ยวกับงานก่อนการติดตั้งและวิธีการ
• คำอธิบายสั้นๆ เกี่ยวกับงานหลังการติดตั้ง (ตัวอย่าง) (วิธีการโดยละเอียดจะอยู่ใน POSTINSTALL)
• คำอธิบายสั้นๆ เกี่ยวกับผลกระทบด้านการเรียกเก็บเงิน (เริ่มต้นด้วยข้อความสำเร็จรูป)

เนื้อหานี้แสดงต่อผู้ใช้ที่ใด

คอนโซล Firebase">

ติดตั้งเนื้อหาไว้ล่วงหน้าในคอนโซล Firebase

คอนโซล Firebase">

• ในหน้าของส่วนขยายบน extensions.dev
• ที่เก็บซอร์สโค้ดสำหรับส่วนขยาย (ภายในไดเรกทอรีส่วนขยาย)
• เป็นส่วนหนึ่งของ README ของส่วนขยาย (หากคุณใช้แฟล็ก Firebase CLI --markdown > README.md)

ไฟล์ PREINSTALL ไม่สามารถเข้าถึงค่าพารามิเตอร์ของส่วนขยายได้ ดังนั้นคุณจึงไม่ควรคาดหวังว่าการอ้างอิงพารามิเตอร์จะแสดงผลด้วยค่าจริง

แนวทางปฏิบัติแนะนำมีอะไรบ้าง

• เก็บเนื้อหาทั้งหมดของไฟล์ PREINSTALL ไว้ไม่เกิน 1 หน้า หากเป็นไปได้
• ระบุรายละเอียดที่ผู้ใช้ปลายทางจำเป็นต้องทราบก่อนติดตั้งส่วนขยาย
• ใส่คำแนะนำโดยละเอียดในไฟล์ POSTINSTALL หรือไฟล์เสริมอื่นๆ
• ระบุสั้นๆ หากคุณมีเครื่องมือหรือสคริปต์อื่นๆ เพื่อรองรับส่วนขยาย

ข้อความสำเร็จรูป PREINSTALL ที่เป็นประโยชน์

เราขอแนะนำให้ใช้ข้อความสำเร็จรูปต่อไปนี้ให้มากที่สุดเท่าที่จะเป็นไปได้ตามความเหมาะสมสำหรับส่วนขยายของคุณ เราได้ยกตัวอย่างไว้บางส่วน แต่ประเด็นที่สำคัญที่สุดคือการตรวจสอบว่าได้ระบุบริการทั้งหมดที่เรียกเก็บเงินโดย Google และไม่ใช่ Google

คุณสามารถใช้แหล่งข้อมูลต่อไปนี้เพื่อดูรายละเอียดราคาผลิตภัณฑ์ที่ถูกต้อง

• รายการราคาผลิตภัณฑ์ Google Cloud
• ภาพรวมราคาของ Firebase

สำหรับส่วนขยายทั้งหมด ให้ใส่ส่วนนี้เพื่อช่วยให้ผู้ใช้เข้าใจผลกระทบด้านการเรียกเก็บเงิน

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

กำลังเขียนไฟล์ POSTINSTALL

ไฟล์ POSTINSTALL คือหน้าคำแนะนำหลังการติดตั้งโดยละเอียดของส่วนขยาย

ไฟล์นี้มีเนื้อหาอะไรบ้าง

• วิธีการโดยละเอียดสำหรับงานหลังการติดตั้งที่จำเป็น เช่น การตั้งค่ากฎความปลอดภัยของ Firebase หรือการเพิ่มโค้ดฝั่งไคลเอ็นต์ (ตัวอย่าง)
• วิธีการทั่วไปเกี่ยวกับวิธีลองใช้ส่วนขยายที่ติดตั้งทันที (เช่น "ไปที่คอนโซล แล้วทำสิ่งนี้")
• ข้อมูลพื้นฐานเกี่ยวกับวิธีทริกเกอร์ส่วนขยาย โดยเฉพาะสำหรับส่วนขยายที่ทริกเกอร์ด้วยคำขอ HTTP
• คำแนะนำสั้นๆ เกี่ยวกับวิธีตรวจสอบส่วนขยายที่ติดตั้ง (เริ่มต้นด้วยข้อความสำเร็จรูป)

เนื้อหานี้แสดงต่อผู้ใช้ที่ใด

คอนโซล Firebase">

เนื้อหาหลังการติดตั้งในคอนโซล Firebase

คอนโซล Firebase">

• ในคอนโซล Firebase หลังจากที่ผู้ใช้ติดตั้งส่วนขยาย (ในการ์ดรายละเอียดของส่วนขยายที่ติดตั้ง)

  • อย่าลืมตรวจสอบการแสดงเนื้อหา POSTINSTALL โดยติดตั้งส่วนขยายในโปรเจ็กต์จริง

• ที่เก็บซอร์สโค้ดสำหรับส่วนขยาย (ภายในไดเรกทอรีส่วนขยาย)

ไฟล์ POSTINSTALL สามารถเข้าถึงค่าพารามิเตอร์และตัวแปรที่เกี่ยวข้องกับฟังก์ชันหลายรายการสำหรับส่วนขยาย เมื่อเนื้อหา POSTINSTALL แสดงในคอนโซล Firebase ค่าจริงจะแสดงแทนการอ้างอิงพารามิเตอร์หรือตัวแปร ดูข้อมูลเพิ่มเติมด้านล่างเกี่ยวกับวิธีอ้างอิงพารามิเตอร์และตัวแปรในไฟล์ POSTINSTALL

แนวทางปฏิบัติแนะนำมีอะไรบ้าง

• เขียนเนื้อหาทั้งหมดของไฟล์ POSTINSTALL ให้กระชับแต่สื่อความหมาย
• แบ่งเนื้อหาออกเป็นส่วนๆ โดยใช้ส่วนหัวเพื่อแยกงานหรือแนวคิดที่แตกต่างกัน
• ลองเผยแพร่คำแนะนำโดยละเอียดสำหรับเวิร์กโฟลว์หรือภารกิจที่เฉพาะเจาะจงในเว็บไซต์ (ตัวอย่าง) หรือในไฟล์มาร์กดาวน์เสริมภายในที่เก็บส่วนขยาย (ตัวอย่าง)
• พารามิเตอร์อ้างอิงและตัวแปรที่เกี่ยวข้องกับฟังก์ชันเพื่อให้ผู้ใช้เห็นค่าที่กำหนดค่าไว้ในบริบทของวิธีการ

การอ้างอิงพารามิเตอร์และตัวแปร

หลังจากติดตั้งแล้ว คอนโซล Firebase จะแสดงเนื้อหาของไฟล์ POSTINSTALL ของส่วนขยาย หากคุณอ้างอิงพารามิเตอร์และตัวแปรที่เกี่ยวข้องกับฟังก์ชัน (ดูตารางด้านล่าง) ในไฟล์ POSTINSTALL คอนโซลจะป้อนข้อมูลการอ้างอิงเหล่านี้ด้วยค่าจริงสำหรับอินสแตนซ์ที่ติดตั้ง

เคล็ดลับ: สำหรับค่าที่อาจมีความยาว (เช่น เส้นทางฐานข้อมูลหรือ URL ของฟังก์ชัน) ให้อ้างอิงพารามิเตอร์หรือตัวแปรที่ท้ายประโยคและส่วนต่างๆ แนวทางปฏิบัติแนะนำนี้ช่วยให้อ่านประโยคในคอนโซล Firebase ได้ง่ายขึ้นเมื่อแสดงเนื้อหาของไฟล์ POSTINSTALL ด้วยค่าจริง

เข้าถึงค่าพารามิเตอร์ที่กำหนดค่าไว้ในไฟล์ POSTINSTALL โดยใช้ไวยากรณ์ต่อไปนี้ ${param:PARAMETER_NAME}

นอกจากนี้ คุณยังอ้างอิงตัวแปรที่เกี่ยวข้องกับฟังก์ชันต่อไปนี้ในไฟล์ POSTINSTALL เท่านั้นได้ด้วย Firebase รองรับตัวแปรเหล่านี้เพื่อให้คุณสามารถให้คำแนะนำแก่ผู้ใช้หลังการติดตั้งได้ง่ายขึ้น โดยจะใช้ได้เฉพาะในไฟล์ POSTINSTALL เนื่องจากค่าของตัวแปรเหล่านี้จะใช้ได้หลังจากการติดตั้งเท่านั้น

ในตารางนี้ function-name คือค่าของช่อง name ในออบเจ็กต์ทรัพยากรของฟังก์ชันภายใน extension.yaml

ข้อมูลอ้างอิงสำหรับตัวแปรที่เกี่ยวข้องกับฟังก์ชัน	คำอธิบาย	ค่าตัวแปร (Firebase จะป้อนข้อมูลให้อัตโนมัติหลังจากติดตั้งส่วนขยาย)
${function:function-name.location}
	ตำแหน่งที่มีการติดตั้งใช้งานฟังก์ชัน	ค่าตัวอย่าง: us-central1
${function:function-name.name}
	ชื่อของฟังก์ชันสุดท้ายที่ติดตั้งใช้งาน ซึ่งรวมถึงรหัสอินสแตนซ์ของส่วนขยาย	รูปแบบทั่วไป: ext-extension-instance-id-function-name ค่าตัวอย่าง: ext-my-awesome-extension-6m31-yourFunctionName
${function:function-name.url} (ใช้ได้กับฟังก์ชัน HTTP เท่านั้น)
	URL ของฟังก์ชันที่ติดตั้งใช้งานขั้นสุดท้าย ซึ่งโค้ดไคลเอ็นต์สามารถส่งคำขอ HTTP ได้	รูปแบบทั่วไป: https://deployment-location-project-id.cloudfunctions.net/name-of-final-deployed-function ค่าตัวอย่าง: https://us-central1-project-123.cloudfunctions.net/ext-my-awesome-extension-6m31-yourFunctionName

ข้อความสำเร็จรูป POSTINSTALL ที่เป็นประโยชน์

เราขอแนะนำให้ใช้ข้อความสำเร็จรูปต่อไปนี้ให้มากที่สุดเท่าที่จะเป็นไปได้ตามความเหมาะสมสำหรับส่วนขยายของคุณ

สำหรับส่วนขยายทั้งหมด ให้ใส่ส่วนต่อไปนี้เพื่อช่วยให้ผู้ใช้ตรวจสอบส่วนขยายที่ติดตั้งไว้ได้

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.

การบันทึกวิธีเรียกใช้ส่วนขยาย

ในเอกสารประกอบสำหรับผู้ใช้ของส่วนขยาย คุณต้องแนะนำผู้ใช้เกี่ยวกับวิธีเรียกใช้ส่วนขยาย คำสั่งเหล่านี้อาจมีรายละเอียดมากเท่าที่คุณคิดว่าจำเป็น แต่โปรดคำนึงถึงแนวทางปฏิบัติแนะนำในการเขียนไฟล์ POSTINSTALL หากต้องการคำแนะนำเกี่ยวกับวิธีระบุวิธีการเหล่านี้ ให้ขยายส่วนด้านล่างที่เกี่ยวข้องกับส่วนขยายของคุณ

ส่วนขยายที่ทริกเกอร์ตามเหตุการณ์ในเบื้องหลัง

ผู้ใช้สามารถเรียกใช้ส่วนขยายที่ทริกเกอร์เหตุการณ์ในเบื้องหลังได้หลายวิธี โดยขึ้นอยู่กับผลิตภัณฑ์ที่เกี่ยวข้อง

ทำการเปลี่ยนแปลงในคอนโซลโดยตรง

คุณสามารถแนะนำให้ผู้ใช้ทำการเปลี่ยนแปลงที่ทริกเกอร์ส่วนขยายได้โดยตรงในคอนโซล Firebase โดยเฉพาะอย่างยิ่งสำหรับการทดสอบส่วนขยายครั้งแรก ตัวอย่างเช่น สมมติว่าส่วนขยายของคุณสร้างเอกสาร Cloud Firestore ใหม่ทุกครั้งที่มีการสร้างผู้ใช้ Firebase Authentication ใหม่ คุณสามารถแนะนำให้ผู้ใช้ทดสอบอินสแตนซ์ที่ติดตั้งของส่วนขยายได้โดยการเพิ่มผู้ใช้ Authentication ใหม่ด้วยตนเองในคอนโซล จากนั้นผู้ใช้จะเห็นเอกสารใหม่ที่สร้างขึ้นในส่วน Cloud Firestore ของคอนโซล

เพิ่มโค้ดฝั่งไคลเอ็นต์

หากมี คุณยังสามารถแนะนำผู้ใช้เกี่ยวกับวิธีเพิ่มโค้ดฝั่งไคลเอ็นต์เพื่อเรียกให้ส่วนขยายทำงานได้ด้วย คุณควรนำผู้ใช้ไปยังเอกสารประกอบอย่างเป็นทางการสำหรับ API ที่ผู้ใช้จำเป็นต้องใช้ นอกจากนี้ คุณยังสามารถรวมแอปตัวอย่างหรือตัวอย่างไคลเอ็นต์ที่คอมไพล์แล้วเพื่อช่วยให้ผู้ใช้ผสานรวมส่วนขยายเข้ากับแอปของตนได้ (ดูตัวอย่างได้ที่ส่วนขยาย Distributed Counter)

ส่วนขยายที่ทริกเกอร์โดยคำขอ HTTP

เพื่อให้ผู้ใช้เรียกใช้ฟังก์ชันที่ทริกเกอร์ด้วยคำขอ HTTP (และส่วนขยาย) ได้ คุณต้องระบุชื่อหรือ URL ของฟังก์ชันที่ติดตั้งใช้งานให้ผู้ใช้ทราบ

ชื่อของฟังก์ชันที่ติดตั้งใช้งานขั้นสุดท้ายไม่เหมือนกับ name ที่คุณระบุไว้ในออบเจ็กต์ทรัพยากรของฟังก์ชันภายใน extension.yaml Firebase จะเปลี่ยนชื่อฟังก์ชันในรูปแบบ ext-extension-instance-id-function-name เพื่อรองรับการติดตั้งส่วนขยายเดียวกันหลายรายการในโปรเจ็กต์

หัวข้อย่อยต่อไปนี้เป็นข้อความสำเร็จรูปที่แนะนำให้รวมไว้ในไฟล์ POSTINSTALL ของส่วนขยาย หลังการติดตั้ง คอนโซล Firebase จะแสดงเนื้อหาของไฟล์ POSTINSTALL และป้อนข้อมูลอ้างอิงเหล่านี้ ด้วยค่าที่กำหนดค่าจริงสำหรับอินสแตนซ์ที่ติดตั้ง เช่น หากคุณกำหนดฟังก์ชันชื่อ yourFunction คุณสามารถรวมรายการต่อไปนี้ (ตามความเหมาะสม)

• สําหรับฟังก์ชัน HTTP onRequest

  To trigger this extension, make a request to or visit the following URL:
  **`${function:yourFunction.url}`**.
  

• สำหรับฟังก์ชันที่เรียกใช้ได้ผ่าน 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}`**.
  

สำคัญ: ก่อนที่ผู้ใช้จะใช้ส่วนขยายที่ทริกเกอร์ด้วยคำขอ HTTP ได้ ผู้ใช้ต้องทำให้ฟังก์ชันที่ติดตั้งใช้งานสำหรับส่วนขยายนั้นเข้าถึงได้แบบสาธารณะ วิธีการโดยละเอียดที่ต้องแจ้งให้ผู้ใช้ทราบอยู่ในตัวอย่างข้อความสำเร็จรูปด้านบน

การเขียนไฟล์ CHANGELOG

ไฟล์นี้มีเนื้อหาอะไรบ้าง

ส่วนขยายทุกรายการต้องมีไฟล์ CHANGELOG.md ที่บันทึกการเปลี่ยนแปลงที่รวมอยู่ในส่วนขยายเวอร์ชันใหม่แต่ละเวอร์ชันที่คุณเผยแพร่ ใส่แต่ละเวอร์ชันไว้ใต้ส่วนหัวระดับ 2 (##) หรือจะใช้การจัดรูปแบบ Markdown ใดก็ได้ตามต้องการ

ตัวอย่างต่อไปนี้เป็นข้อความที่ตัดตอนมาจากส่วนขยายอย่างเป็นทางการรายการหนึ่ง

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

เนื้อหานี้แสดงต่อผู้ใช้ที่ใด

• ในคอนโซล Firebase และ CLI เมื่อผู้ใช้อัปเกรดส่วนขยายเป็นเวอร์ชันใหม่ คอนโซล Firebase และ CLI จะแสดงเฉพาะการเปลี่ยนแปลงที่จะมีผลหากผู้ใช้อัปเกรดเสร็จสมบูรณ์
• ที่เก็บซอร์สโค้ดของส่วนขยาย (ภายในไดเรกทอรีส่วนขยาย)