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

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

कम से कम, ज़रूरी दस्तावेज़ तीन मार्कडाउन फ़ाइलों का यह सेट है:

  • 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 एक्सटेंशन के लिए, रीड मी फ़ाइलें जनरेट की जाती हैं.

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

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 पर जाएं)
  • बिलिंग से जुड़े किसी भी असर के बारे में खास जानकारी (बोयलरप्लेट टेक्स्ट से शुरू करें)

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

<span class=Firebase कंसोल">
Firebase कंसोल में कॉन्टेंट पहले से इंस्टॉल करें

<span class=Firebase कंसोल">

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

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

<span class=Firebase कंसोल">
Firebase कंसोल में, ऐप्लिकेशन इंस्टॉल होने के बाद दिखने वाला कॉन्टेंट

<span class= में, इंस्टॉल के बाद दिखने वाले कॉन्टेंट की बड़ी इमेजFirebase कंसोल">

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

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

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

सबसे सही तरीके क्या हैं?

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

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

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

POSTINSTALL फ़ाइल में कॉन्फ़िगर की गई पैरामीटर वैल्यू ऐक्सेस करने के लिए, यहां दिए गए सिंटैक्स का इस्तेमाल करें: ${param:PARAMETER_NAME}

फ़ंक्शन से जुड़े इन वैरिएबल का रेफ़रंस, सिर्फ़ अपनी POSTINSTALL फ़ाइल में दिया जा सकता है. Firebase इन वैरिएबल के साथ काम करता है, ताकि आप इंस्टॉलेशन के बाद अपने उपयोगकर्ताओं को आसानी से दिशा-निर्देश दे सकें. इन्हें सिर्फ़ POSTINSTALL फ़ाइल में इस्तेमाल किया जा सकता है, क्योंकि इन वैरिएबल की वैल्यू, इंस्टॉलेशन के बाद ही उपलब्ध होती हैं.

इस टेबल में, function-name, extension.yaml में फ़ंक्शन के रिसॉर्स ऑब्जेक्ट में, name फ़ील्ड की वैल्यू है.

फ़ंक्शन से जुड़े वैरिएबल का रेफ़रंस जानकारी वैरिएबल की वैल्यू (एक्सटेंशन इंस्टॉल होने के बाद, 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

हमारा सुझाव है कि आप अपने एक्सटेंशन के लिए, यहां दिए गए बॉयलरप्लेट टेक्स्ट का ज़्यादा से ज़्यादा इस्तेमाल करें.

सभी एक्सटेंशन के लिए, यह सेक्शन शामिल करें, ताकि उपयोगकर्ता अपने इंस्टॉल किए गए एक्सटेंशन को मॉनिटर कर सकें:

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 कंसोल में जाकर, एक्सटेंशन को ट्रिगर करने वाले बदलाव करने का निर्देश दिया जा सकता है. ऐसा खास तौर पर, आपके एक्सटेंशन की शुरुआती जांच के लिए किया जा सकता है. उदाहरण के लिए, मान लें कि आपका एक्सटेंशन, जब भी कोई नया Firebase Authentication उपयोगकर्ता बनाता है, तो एक नया Cloud Firestore दस्तावेज़ बनाता है. अपने उपयोगकर्ताओं को, अपने एक्सटेंशन के इंस्टॉल किए गए इंस्टेंस को आज़माने का निर्देश दिया जा सकता है. इसके लिए, कंसोल में मैन्युअल तरीके से नया Authentication उपयोगकर्ता जोड़ें. इसके बाद, वे कंसोल के Cloud Firestore सेक्शन में बनाए गए नए दस्तावेज़ को देख सकते हैं.

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

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

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

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