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

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

เอกสารขั้นต่ำที่จำเป็นคือชุดไฟล์มาร์กดาวน์ 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

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

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 หลังจากที่ผู้ใช้ติดตั้งส่วนขยาย (ใน การ์ดรายละเอียดของส่วนขยายที่ติดตั้ง)

  • อย่าลืมตรวจสอบการแสดงเนื้อหา 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 ใหม่แล้ว คุณสามารถแจ้งให้ผู้ใช้ทดสอบ อินสแตนซ์ที่ติดตั้งของส่วนขยายโดยการเพิ่มผู้ใช้การตรวจสอบสิทธิ์รายใหม่ด้วยตนเอง ในคอนโซล จากนั้น ผู้ใช้จะสามารถสังเกตเอกสารใหม่ที่สร้างขึ้นใน ส่วน 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 (##); หรือไม่เช่นนั้น ให้ใช้มาร์กดาวน์ การจัดรูปแบบที่คุณต้องการ

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

## 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 แสดงเฉพาะการเปลี่ยนแปลงที่ จะมีผลถ้าผู้ใช้ทำการอัปเกรดให้เสร็จสมบูรณ์
• ที่เก็บซอร์สโค้ดของส่วนขยายของคุณ (ภายในไดเรกทอรีส่วนขยาย)