अपने एक्सटेंशन के लिए उपयोगकर्ता दस्तावेज़ बनाएं

हर एक्सटेंशन के लिए, एक दस्तावेज़ होना ज़रूरी है. इसमें उपयोगकर्ताओं को यह बताया जाना चाहिए कि एक्सटेंशन क्या करता है और इसका इस्तेमाल कैसे किया जाता है.

ज़रूरी दस्तावेज़ के तौर पर, मार्कडाउन की इन तीन फ़ाइलों का सेट होना चाहिए:

• 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

Firebase के आधिकारिक Firebase एक्सटेंशन के लिए, सभी README फ़ाइलें इसी कमांड का इस्तेमाल करके जनरेट की जाती हैं.

इंस्टॉल करने से जुड़ी जानकारी जोड़ना

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 console">

Firebase Firebase कंसोल में, इंस्टॉल करने से पहले का कॉन्टेंट

Firebase console">

• extensions.dev पर, एक्सटेंशन के पेज पर.
• आपके एक्सटेंशन के लिए, सोर्स कोड रिपो (एक्सटेंशन डायरेक्ट्री में)
• एक्सटेंशन के README के हिस्से के तौर पर (अगर आपने Firebase CLI --markdown > README.md फ़्लैग का इस्तेमाल किया है)

PREINSTALL फ़ाइलें, एक्सटेंशन के पैरामीटर की वैल्यू ऐक्सेस नहीं कर सकतीं. इसलिए, आपको पैरामीटर के रेफ़रंस को असल वैल्यू के साथ रेंडर करने की उम्मीद नहीं करनी चाहिए.

सबसे सही कुछ तरीके कौनसे हैं?

• अगर मुमकिन हो, तो PREINSTALL फ़ाइल का पूरा कॉन्टेंट एक पेज से कम रखें
• इतनी जानकारी दें जो किसी एक्सटेंशन को इंस्टॉल करने से पहले, उपयोगकर्ता के लिए जानना ज़रूरी है
• 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 के सुरक्षा नियम सेट अप करना या क्लाइंट-साइड कोड जोड़ना (उदाहरण)
• इंस्टॉल किए गए एक्सटेंशन को तुरंत आज़माने के सामान्य निर्देश. जैसे, "कंसोल पर जाएं, फिर यह करें"
• एक्सटेंशन को ट्रिगर करने के तरीके के बारे में बुनियादी जानकारी. खास तौर पर, एचटीटीपी अनुरोध से ट्रिगर होने वाले एक्सटेंशन के लिए
• इंस्टॉल किए गए एक्सटेंशन की निगरानी करने के तरीके के बारे में कम शब्दों में निर्देश (बॉयलरप्लेट टेक्स्ट से शुरू करें)

यह कॉन्टेंट, उपयोगकर्ता को कहां दिखता है?

Firebase console">

Firebase Firebase कंसोल में, इंस्टॉल करने के बाद का कॉन्टेंट

Firebase console">

• उपयोगकर्ता के आपके एक्सटेंशन को इंस्टॉल करने के बाद Firebase कंसोल में (इंस्टॉल किए गए एक्सटेंशन के जानकारी वाले कार्ड में)

  • पक्का करें कि आपने किसी असल प्रोजेक्ट में अपना एक्सटेंशन इंस्टॉल करके, POSTINSTALL कॉन्टेंट के दिखने के तरीके की समीक्षा कर ली हो.

• आपके एक्सटेंशन के लिए, सोर्स कोड रिपो (एक्सटेंशन डायरेक्ट्री में)

POSTINSTALL फ़ाइलें, एक्सटेंशन के पैरामीटर की वैल्यू और फ़ंक्शन से जुड़े कई वैरिएबल ऐक्सेस कर सकती हैं. जब POSTINSTALL कॉन्टेंट Firebase कंसोल में दिखता है, तो पैरामीटर या वैरिएबल के रेफ़रंस के बजाय, असल वैल्यू दिखती हैं. अपनी POSTINSTALL फ़ाइल में पैरामीटर और वैरिएबल के रेफ़रंस देने के तरीके के बारे में ज़्यादा जानने के लिए, नीचे पढ़ें.

सबसे सही कुछ तरीके कौनसे हैं?

• POSTINSTALL फ़ाइल का पूरा कॉन्टेंट कम शब्दों में, लेकिन जानकारी देने वाला रखें.
• अलग-अलग टास्क या कॉन्सेप्ट को अलग करने के लिए, हेडिंग का इस्तेमाल करके कॉन्टेंट को सेक्शन में बांटें.
• किसी खास वर्कफ़्लो या टास्क के लिए, पूरी जानकारी वाले निर्देश अपनी वेबसाइट (उदाहरण) पर या एक्सटेंशन रिपॉज़िटरी में मौजूद सप्लीमेंट्री मार्कडाउन फ़ाइलों (उदाहरण) में पब्लिश करें.
• पैरामीटर और फ़ंक्शन से जुड़े वैरिएबल के रेफ़रंस दें, ताकि उपयोगकर्ता को निर्देशों के संदर्भ में, कॉन्फ़िगर की गई वैल्यू दिखें

पैरामीटर और वैरिएबल के रेफ़रंस देना

इंस्टॉल करने के बाद, Firebase कंसोल में एक्सटेंशन की POSTINSTALL फ़ाइल का कॉन्टेंट दिखता है. अगर आपने अपनी POSTINSTALL फ़ाइल में पैरामीटर और फ़ंक्शन से जुड़े वैरिएबल (नीचे दी गई टेबल देखें) के रेफ़रंस दिए हैं, तो कंसोल इन रेफ़रंस में, इंस्टॉल किए गए इंस्टेंस के लिए असल वैल्यू भरता है.

अहम जानकारी: ऐसी वैल्यू के लिए जो लंबी हो सकती हैं (जैसे, डेटाबेस पाथ या फ़ंक्शन का यूआरएल), वाक्यों और सेक्शन के आखिर में पैरामीटर या वैरिएबल का रेफ़रंस दें. इस सबसे सही तरीके से, 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} (यह सिर्फ़ एचटीटीपी फ़ंक्शन पर लागू होता है)
	_डिप्लॉय_ किए गए फ़ाइनल फ़ंक्शन का यूआरएल. क्लाइंट कोड इस पर एचटीटीपी अनुरोध कर सकता है	सामान्य फ़ॉर्मैट: 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 सेक्शन में बनाया गया नया दस्तावेज़ देख सकते हैं.

क्लाइंट-साइड कोड जोड़ना

अगर लागू हो, तो अपने उपयोगकर्ताओं को, आपके एक्सटेंशन को ट्रिगर करने के लिए, क्लाइंट-साइड कोड जोड़ने के तरीके के बारे में भी निर्देश दिए जा सकते हैं. आपको उपयोगकर्ताओं को उन एपीआई के आधिकारिक दस्तावेज़ों पर भेजना चाहिए जिनका उन्हें इस्तेमाल करना होगा. आपके पास, सैंपल ऐप्लिकेशन या कंपाइल किए गए क्लाइंट सैंपल शामिल करने का विकल्प भी होता है, ताकि आपके उपयोगकर्ताओं को अपने ऐप्लिकेशन में एक्सटेंशन को इंटिग्रेट करने में मदद मिल सके. उदाहरण के लिए, डिस्ट्रिब्यूटेड काउंटर एक्सटेंशन देखें.

एचटीटीपी अनुरोध से ट्रिगर होने वाले एक्सटेंशन

ताकि आपके उपयोगकर्ता, एचटीटीपी अनुरोध से ट्रिगर होने वाले फ़ंक्शन (और इस तरह एक्सटेंशन) को ट्रिगर कर सकें, आपको उन्हें डिप्लॉय किए गए फ़ंक्शन का नाम या उसका यूआरएल देना होगा.

डिप्लॉय किए गए फ़ाइनल फ़ंक्शन का नाम, उस name से अलग होता है जिसे आपने फ़ंक्शन के रिसॉर्स ऑब्जेक्ट में extension.yaml तय किया था. किसी प्रोजेक्ट में एक ही एक्सटेंशन के कई इंस्टॉलेशन को शामिल करने के लिए, Firebase फ़ंक्शन का नाम इस फ़ॉर्मैट में बदलता है: ext-extension-instance-id-function-name.

यहां दिए गए बुलेट, आपके एक्सटेंशन की POSTINSTALL फ़ाइल में शामिल करने के लिए, बॉयलरप्लेट टेक्स्ट के तौर पर सुझाए गए हैं. इंस्टॉल करने के बाद, Firebase कंसोल में POSTINSTALL फ़ाइल का कॉन्टेंट दिखता है. साथ ही, इन रेफ़रंस में, इंस्टॉल किए गए इंस्टेंस के लिए असल कॉन्फ़िगर की गई वैल्यू भरी जाती हैं. उदाहरण के लिए, अगर आपने yourFunction नाम का कोई फ़ंक्शन तय किया है, तो आपके पास इनमें से कोई भी चीज़ शामिल करने का विकल्प होता है (अगर लागू हो):

• एचटीटीपी onRequest फ़ंक्शन के लिए

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

• एचटीटीपी कॉल किए जा सकने वाले (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 हेडर (##) के तहत रखें. इसके अलावा, आपके पास मार्कडाउन फ़ॉर्मैटिंग का इस्तेमाल करने का विकल्प होता है.

यहां दिया गया उदाहरण, आधिकारिक एक्सटेंशन में से एक का अंश है:

## 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 कंसोल और सीएलआई में, जब उपयोगकर्ता आपके एक्सटेंशन के नए वर्शन पर अपग्रेड करते हैं. Firebase कंसोल और सीएलआई में सिर्फ़ वे बदलाव दिखते हैं जो अपग्रेड पूरा करने पर लागू होंगे.
• आपके एक्सटेंशन का सोर्स कोड रिपो (एक्सटेंशन डायरेक्ट्री में).