ส่วนขยายทุกรายการจะต้องมีเอกสารที่สอนผู้ใช้ว่าส่วนขยายนี้ทำอะไรและใช้งานอย่างไร
เอกสารขั้นต่ำที่จำเป็นคือชุดไฟล์มาร์กดาวน์สามไฟล์นี้:
-
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
) - คำอธิบายโดยย่อเกี่ยวกับผลกระทบในการเรียกเก็บเงิน (เริ่มต้นด้วย ข้อความสำเร็จรูป )
เนื้อหานี้แสดงต่อผู้ใช้ที่ไหน?
- ในหน้าส่วนขยายบน extensions.dev
- ที่เก็บซอร์สโค้ดของคุณสำหรับส่วนขยายของคุณ (ภายในไดเร็กทอรีส่วนขยาย)
- เป็นส่วนหนึ่งของ README ของส่วนขยาย (หากคุณใช้ Firebase CLI
)--markdown > README.md
ไฟล์ PREINSTALL
ไม่สามารถเข้าถึงค่าพารามิเตอร์สำหรับส่วนขยายได้ ดังนั้นคุณไม่ควรคาดหวังให้การอ้างอิงพารามิเตอร์แสดงผลด้วยค่าจริง
แนวทางปฏิบัติที่ดีที่สุดมีอะไรบ้าง?
- เก็บเนื้อหาทั้งหมดของไฟล์
PREINSTALL
ไว้ ใต้หน้าเดียว หากเป็นไปได้ - ระบุระดับรายละเอียดที่ผู้ใช้จำเป็นต้องทราบก่อนติดตั้งส่วนขยาย
- ใส่คำแนะนำโดยละเอียดในไฟล์
POSTINSTALL
หรือไฟล์เสริมอื่นๆ - กล่าวถึงสั้นๆ หากคุณมีเครื่องมือหรือสคริปต์อื่นๆ เพื่อรองรับส่วนขยาย
เราขอแนะนำให้ใช้ข้อความสำเร็จรูปต่อไปนี้ให้มากที่สุดเท่าที่จะทำได้ สำหรับส่วนขยายของคุณ เราได้ยกตัวอย่างบางส่วนไว้แล้ว แต่จุดที่สำคัญที่สุดคือต้องแน่ใจว่าบริการที่เรียกเก็บเงินของ Google และที่ไม่ใช่ของ Google ทั้งหมดอยู่ในรายการ
คุณสามารถใช้แหล่งข้อมูลต่อไปนี้เพื่อค้นหารายละเอียดการกำหนดราคาผลิตภัณฑ์ที่ถูกต้อง:
สำหรับส่วนขยายทั้งหมด ให้รวมส่วนนี้เพื่อช่วยให้ผู้ใช้ของคุณเข้าใจผลกระทบในการเรียกเก็บเงิน:
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 หลังจากที่ผู้ใช้ติดตั้งส่วนขยายของคุณ (ในการ์ดรายละเอียดของส่วนขยายที่ติดตั้ง)
- ตรวจสอบให้แน่ใจว่าได้ตรวจสอบการแสดงเนื้อหา
POSTINSTALL
โดย การติดตั้งส่วนขยายของคุณในโครงการจริง
- ตรวจสอบให้แน่ใจว่าได้ตรวจสอบการแสดงเนื้อหา
ที่เก็บซอร์สโค้ดของคุณสำหรับส่วนขยายของคุณ (ภายในไดเร็กทอรีส่วนขยาย)
ไฟล์ POSTINSTALL
สามารถเข้าถึงค่าพารามิเตอร์และตัวแปรที่เกี่ยวข้องกับฟังก์ชันต่างๆ สำหรับส่วนขยาย เมื่อเนื้อหา POSTINSTALL
แสดงในคอนโซล Firebase ค่าจริง จะแสดงแทนพารามิเตอร์หรือการอ้างอิงตัวแปร เรียนรู้เพิ่มเติมด้านล่างเกี่ยวกับวิธีการ อ้างอิงพารามิเตอร์และตัวแปร ในไฟล์ POSTINSTALL
ของคุณ
แนวทางปฏิบัติที่ดีที่สุดมีอะไรบ้าง?
- เก็บเนื้อหาทั้งหมดของไฟล์
POSTINSTALL
ให้กระชับ แต่สื่อความหมายได้ - แบ่งเนื้อหาโดยใช้ส่วนหัวเพื่อแยกงานหรือแนวคิดที่แตกต่างกันออกไป
- ลองเผยแพร่คำแนะนำโดยละเอียดสำหรับเวิร์กโฟลว์หรืองานเฉพาะบนเว็บไซต์ของคุณ ( ตัวอย่าง ) หรือในไฟล์มาร์กดาวน์เสริมภายในที่เก็บส่วนขยาย ( ตัวอย่าง )
- พารามิเตอร์อ้างอิงและตัวแปรที่เกี่ยวข้องกับฟังก์ชัน เพื่อให้ผู้ใช้เห็นค่าที่กำหนดค่าไว้ในบริบทของคำแนะนำ
การอ้างอิงพารามิเตอร์และตัวแปร
หลังการติดตั้ง คอนโซล Firebase จะแสดงเนื้อหาของไฟล์ POSTINSTALL
ของส่วนขยาย หากคุณอ้างอิงพารามิเตอร์และตัวแปรที่เกี่ยวข้องกับฟังก์ชัน (ดูตารางด้านล่าง) ในไฟล์ POSTINSTALL
ของคุณ คอนโซลจะเติมข้อมูลอ้างอิงเหล่านี้ด้วยค่า จริง สำหรับอินสแตนซ์ที่ติดตั้ง
เข้าถึงค่า พารามิเตอร์ ที่กำหนดค่าไว้ในไฟล์ POSTINSTALL
โดยใช้ไวยากรณ์ต่อไปนี้:${param: PARAMETER_NAME }
คุณยังสามารถอ้างอิงตัวแปรที่เกี่ยวข้องกับฟังก์ชันต่อไปนี้ ในไฟล์ POSTINSTALL
ของคุณเท่านั้น Firebase รองรับตัวแปรเหล่านี้เพื่อให้คุณให้คำแนะนำแก่ผู้ใช้หลังการติดตั้งได้ง่ายขึ้น ใช้ได้เฉพาะในไฟล์ POSTINSTALL
เท่านั้น เนื่องจากค่าสำหรับตัวแปรเหล่านี้จะไม่สามารถใช้ได้จนกว่าจะติดตั้งเสร็จ
ในตารางนี้ function-name คือค่าของช่อง name
ในออบเจ็กต์ทรัพยากรของฟังก์ชันภายใน extension.yaml
การอ้างอิงสำหรับตัวแปรที่เกี่ยวข้องกับฟังก์ชัน | คำอธิบาย | ค่าตัวแปร (เติมอัตโนมัติโดย Firebase หลังการติดตั้งส่วนขยาย) |
---|---|---|
${function: function-name .location} | ||
ตำแหน่ง ที่ฟังก์ชันถูกปรับใช้ | ค่าตัวอย่าง:us-central1 | |
${function: function-name .name} | ||
ชื่อของฟังก์ชัน ที่ใช้งาน ขั้นสุดท้าย ซึ่งรวมถึง ID อินสแตนซ์ของส่วนขยาย | รูปแบบทั่วไป: ค่าตัวอย่าง: | |
${function: function-name .url} (ใช้ได้กับฟังก์ชัน HTTP เท่านั้น) | ||
URL ของฟังก์ชัน ที่ใช้งาน ขั้นสุดท้าย ซึ่งโค้ดไคลเอ็นต์สามารถสร้างคำขอ HTTP ได้ | รูปแบบทั่วไป: ค่าตัวอย่าง: |
เราขอแนะนำให้ใช้ข้อความสำเร็จรูปต่อไปนี้ให้มากที่สุดเท่าที่จะทำได้ สำหรับส่วนขยายของคุณ
สำหรับส่วนขยายทั้งหมด ให้รวมส่วนต่อไปนี้เพื่อช่วยให้ผู้ใช้ของคุณตรวจสอบส่วนขยายที่ติดตั้ง:
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 ใหม่ คุณสามารถแนะนำให้ผู้ใช้ทดสอบอินสแตนซ์ที่ติดตั้งของส่วนขยายของคุณได้โดยเพิ่มผู้ใช้การตรวจสอบสิทธิ์รายใหม่ด้วยตนเองในคอนโซล จากนั้นพวกเขาสามารถสังเกตเอกสารใหม่ที่สร้างขึ้นในส่วน Cloud Firestore ของคอนโซล
เพิ่มโค้ดฝั่งไคลเอ็นต์
เมื่อเป็นไปได้ คุณยังสามารถแนะนำผู้ใช้ของคุณเกี่ยวกับวิธีเพิ่มโค้ดฝั่งไคลเอ็นต์เพื่อทริกเกอร์ส่วนขยายของคุณได้ คุณควรนำผู้ใช้ไปยังเอกสารอย่างเป็นทางการสำหรับ API ที่พวกเขาจำเป็นต้องใช้ คุณยังสามารถรวมแอปตัวอย่างหรือตัวอย่างไคลเอ็นต์ที่คอมไพล์เพื่อช่วยให้ผู้ใช้ของคุณรวมส่วนขยายเข้ากับแอปของพวกเขาได้ (ดูตัวอย่าง ส่วนขยาย Distributed Counter )
เพื่อให้ผู้ใช้ของคุณสามารถทริกเกอร์ฟังก์ชันที่เรียกใช้คำขอ 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 callable (
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}`**.
กำลังเขียนไฟล์ 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 จะแสดงเฉพาะการเปลี่ยนแปลงที่จะมีผลหากผู้ใช้ทำการอัปเกรดให้เสร็จสิ้น
- ที่เก็บซอร์สโค้ดของส่วนขยายของคุณ (ภายในไดเร็กทอรีส่วนขยาย)