प्रत्येक एक्सटेंशन में दस्तावेज़ होना चाहिए जो उपयोगकर्ताओं को सिखाता है कि एक्सटेंशन क्या करता है और इसका उपयोग कैसे करना है।
न्यूनतम, आवश्यक दस्तावेज़ीकरण तीन मार्कडाउन फ़ाइलों का यह सेट है:
-
PREINSTALL.md -
POSTINSTALL.md -
CHANGELOG.md
इसके अलावा, आपको निम्नलिखित के उत्पादन पर भी विचार करना चाहिए:
- एक्सटेंशन के सार्वजनिक भंडार के लिए एक
READMEफ़ाइल। - आपकी अपनी वेबसाइट पर लंबे प्रारूप वाले ट्यूटोरियल, गाइड और संदर्भ प्रकाशित किए गए हैं और आपके
PREINSTALL.mdमें लिंक किए गए हैं।
कुछ सर्वोत्तम प्रथाओं और सामान्य वाक्यांश और संरचना को सीखने के लिए, हम आधिकारिक फायरबेस एक्सटेंशन के साथ उपलब्ध फ़ाइलों की समीक्षा करने की सलाह देते हैं।
एक README बनाना
आपकी एक्सटेंशन निर्देशिका में वैकल्पिक रूप से एक README हो सकता है। ध्यान दें कि firebase ext:dev:init कमांड स्वचालित रूप से आपके लिए एक उत्पन्न नहीं करता है।
हालाँकि, फायरबेस सीएलआई, आपके extension.yaml फ़ाइल और आपकी PREINSTALL.md फ़ाइल से खींची गई सामग्री वाली README फ़ाइल को स्वतः उत्पन्न करने के लिए निम्नलिखित सुविधा कमांड का समर्थन करता है:
firebase ext:info ./path/to/extension --markdown > README.md
आधिकारिक फायरबेस एक्सटेंशन के लिए सभी README फ़ाइलें इस कमांड का उपयोग करके उत्पन्न की जाती हैं।
स्थापना जानकारी जोड़ें
रीडमी लिखने या जनरेट करने के बाद, इसमें इंस्टॉलेशन जानकारी जोड़ें। आप निम्नलिखित स्निपेट को टेम्पलेट के रूप में उपयोग कर सकते हैं:
--- ## 🧩 Install this extension ### Console [][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में जाते हैं) - किसी भी बिलिंग निहितार्थ का संक्षिप्त विवरण ( बॉयलरप्लेट टेक्स्ट से प्रारंभ करें)
यह सामग्री उपयोगकर्ता को कहां प्रदर्शित होती है?
- एक्सटेंशन.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 फ़ाइल आपके एक्सटेंशन का विस्तृत पोस्ट-इंस्टॉलेशन अनुदेशात्मक पृष्ठ है।
इस फ़ाइल में क्या सामग्री है?
- किसी भी आवश्यक पोस्ट-इंस्टॉलेशन कार्य के लिए विस्तृत निर्देश, जैसे फायरबेस सुरक्षा नियम स्थापित करना या क्लाइंट-साइड कोड जोड़ना ( उदाहरण )
- इंस्टॉल किए गए एक्सटेंशन को तुरंत आज़माने के सामान्य निर्देश (उदाहरण के लिए, "कंसोल पर जाएं, फिर ऐसा करें")
- एक्सटेंशन को ट्रिगर करने के तरीके के बारे में बुनियादी जानकारी, विशेष रूप से HTTP अनुरोध-ट्रिगर एक्सटेंशन के लिए
- स्थापित एक्सटेंशन की निगरानी कैसे करें इसके लिए संक्षिप्त निर्देश ( बॉयलरप्लेट टेक्स्ट से शुरू करें)
यह सामग्री उपयोगकर्ता को कहां प्रदर्शित होती है?
उपयोगकर्ता द्वारा आपका एक्सटेंशन इंस्टॉल करने के बाद फ़ायरबेस कंसोल में (इंस्टॉल किए गए एक्सटेंशन के विवरण कार्ड में)
- किसी वास्तविक प्रोजेक्ट में अपना एक्सटेंशन इंस्टॉल करके
POSTINSTALLसामग्री के प्रदर्शन की समीक्षा करना सुनिश्चित करें।
- किसी वास्तविक प्रोजेक्ट में अपना एक्सटेंशन इंस्टॉल करके
आपके एक्सटेंशन के लिए आपका स्रोत कोड रेपो (एक्सटेंशन निर्देशिका के अंदर)
POSTINSTALL फ़ाइलें एक्सटेंशन के लिए पैरामीटर मान और कई फ़ंक्शन-संबंधित चर तक पहुंच सकती हैं। जब POSTINSTALL सामग्री फायरबेस कंसोल में प्रदर्शित होती है, तो पैरामीटर या चर संदर्भों के बजाय वास्तविक मान प्रदर्शित होते हैं। अपनी POSTINSTALL फ़ाइल में पैरामीटर और वेरिएबल को संदर्भित करने के तरीके के बारे में नीचे और जानें।
कुछ सर्वोत्तम प्रथाएँ क्या हैं?
-
POSTINSTALLफ़ाइल की पूरी सामग्री संक्षिप्त, लेकिन वर्णनात्मक रखें। - अलग-अलग कार्यों या अवधारणाओं को अलग करने के लिए शीर्षकों का उपयोग करके सामग्री को विभाजित करें।
- अपनी वेबसाइट ( उदाहरण ) पर या एक्सटेंशन रिपॉजिटरी ( उदाहरण ) के भीतर पूरक मार्कडाउन फ़ाइलों में किसी विशिष्ट वर्कफ़्लो या कार्य के लिए विस्तृत निर्देश प्रकाशित करने पर विचार करें।
- संदर्भ पैरामीटर और फ़ंक्शन-संबंधित चर ताकि उपयोगकर्ता निर्देशों के संदर्भ में उनके कॉन्फ़िगर किए गए मान देख सकें
पैरामीटर्स और वेरिएबल्स को संदर्भित करना
इंस्टॉलेशन के बाद, फायरबेस कंसोल एक्सटेंशन की POSTINSTALL फ़ाइल की सामग्री प्रदर्शित करता है। यदि आप अपनी POSTINSTALL फ़ाइल में पैरामीटर और फ़ंक्शन-संबंधित चर (नीचे तालिका देखें) का संदर्भ देते हैं, तो कंसोल इन संदर्भों को स्थापित उदाहरण के लिए वास्तविक मानों से भर देता है।
निम्नलिखित सिंटैक्स का उपयोग करके POSTINSTALL फ़ाइल में कॉन्फ़िगर किए गए पैरामीटर मानों तक पहुंचें:${param: PARAMETER_NAME }
आप केवल अपनी POSTINSTALL फ़ाइल में निम्नलिखित फ़ंक्शन-संबंधित चर का संदर्भ भी ले सकते हैं। फायरबेस इन वेरिएबल्स का समर्थन करता है ताकि आप इंस्टॉलेशन के बाद अपने उपयोगकर्ताओं को अधिक आसानी से मार्गदर्शन प्रदान कर सकें। वे केवल POSTINSTALL फ़ाइल में उपयोग के लिए उपलब्ध हैं क्योंकि इन वेरिएबल्स के मान इंस्टॉलेशन के बाद तक उपलब्ध नहीं हैं।
इस तालिका में, function-name extension.yaml के भीतर फ़ंक्शन के संसाधन ऑब्जेक्ट में name फ़ील्ड का मान है।
| फ़ंक्शन-संबंधित चर के लिए संदर्भ | विवरण | परिवर्तनीय मान (एक्सटेंशन इंस्टॉलेशन के बाद फायरबेस द्वारा स्वचालित रूप से पॉप्युलेट किया गया) |
|---|---|---|
${function: function-name .location} | ||
| वह स्थान जहां फ़ंक्शन तैनात किया गया है | उदाहरण मान:us-central1 | |
${function: function-name .name} | ||
| अंतिम परिनियोजित फ़ंक्शन का नाम, जिसमें एक्सटेंशन की इंस्टेंस आईडी शामिल है | सामान्यीकृत प्रारूप: उदाहरण मान: | |
${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 फ़ाइल लिखने के लिए सर्वोत्तम प्रथाओं को ध्यान में रखें। इन निर्देशों को कैसे प्रदान करें, इस पर मार्गदर्शन के लिए, नीचे दिए गए अनुभाग का विस्तार करें जो आपके एक्सटेंशन पर लागू होता है।
आपके उपयोगकर्ता शामिल उत्पादों के आधार पर विभिन्न तरीकों से पृष्ठभूमि ईवेंट-ट्रिगर एक्सटेंशन को ट्रिगर कर सकते हैं।
सीधे कंसोल में परिवर्तन करें
आप अपने उपयोगकर्ताओं को सीधे फायरबेस कंसोल में एक्सटेंशन-ट्रिगरिंग परिवर्तन करने का निर्देश दे सकते हैं, विशेष रूप से आपके एक्सटेंशन के प्रारंभिक परीक्षण के लिए। उदाहरण के लिए, मान लें कि जब भी कोई नया फायरबेस प्रमाणीकरण उपयोगकर्ता बनाया जाता है तो आपका एक्सटेंशन एक नया क्लाउड फायरस्टोर दस्तावेज़ बनाता है। आप कंसोल में मैन्युअल रूप से एक नया प्रमाणीकरण उपयोगकर्ता जोड़कर अपने उपयोगकर्ताओं को अपने एक्सटेंशन के इंस्टॉल किए गए इंस्टेंस का परीक्षण करने का निर्देश दे सकते हैं। फिर वे कंसोल के क्लाउड फायरस्टोर अनुभाग में बनाए गए नए दस्तावेज़ का निरीक्षण कर सकते हैं।
क्लाइंट-साइड कोड जोड़ें
लागू होने पर, आप अपने उपयोगकर्ताओं को यह भी निर्देश दे सकते हैं कि अपने एक्सटेंशन को ट्रिगर करने के लिए क्लाइंट-साइड कोड कैसे जोड़ें। आपको उपयोगकर्ताओं को उन एपीआई के आधिकारिक दस्तावेज़ों की ओर निर्देशित करना चाहिए जिनका उन्हें उपयोग करने की आवश्यकता होगी। आप अपने उपयोगकर्ताओं को अपने ऐप में एक्सटेंशन को एकीकृत करने में मदद करने के लिए नमूना ऐप्स या संकलित क्लाइंट नमूने भी शामिल कर सकते हैं (उदाहरण के लिए डिस्ट्रीब्यूटेड काउंटर एक्सटेंशन देखें)।
ताकि आपके उपयोगकर्ता एक HTTP अनुरोध-ट्रिगर फ़ंक्शन (और इस प्रकार एक्सटेंशन) को ट्रिगर कर सकें, आपको उन्हें तैनात फ़ंक्शन का नाम या उसका यूआरएल प्रदान करना होगा।
अंतिम तैनात फ़ंक्शन का नाम उस name के समान नहीं है जिसे आपने extension.yaml के भीतर फ़ंक्शन के संसाधन ऑब्जेक्ट में निर्दिष्ट किया है। किसी प्रोजेक्ट में एक ही एक्सटेंशन के एकाधिक इंस्टॉल को समायोजित करने के लिए, फायरबेस इस प्रारूप में फ़ंक्शन का नाम बदलता है:ext- extension-instance-id - function-name ।
निम्नलिखित बुलेट्स को आपके एक्सटेंशन की POSTINSTALL फ़ाइल में शामिल करने के लिए बॉयलरप्लेट टेक्स्ट का सुझाव दिया गया है। इंस्टॉलेशन के बाद, फायरबेस कंसोल 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}`**.
चेंजलॉग फ़ाइल लिखना
इस फ़ाइल में क्या सामग्री है?
प्रत्येक एक्सटेंशन में एक 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.
यह सामग्री उपयोगकर्ता को कहां प्रदर्शित होती है?
- फायरबेस कंसोल और सीएलआई में, जब उपयोगकर्ता आपके एक्सटेंशन के नए संस्करणों में अपग्रेड करते हैं। फायरबेस कंसोल और सीएलआई केवल वे परिवर्तन प्रदर्शित करते हैं जो उपयोगकर्ता द्वारा अपग्रेड पूरा करने पर प्रभावी होंगे।
- आपके एक्सटेंशन का स्रोत कोड रेपो (एक्सटेंशन निर्देशिका के अंदर)।