Firebase एक्सटेंशन इंस्टॉल करना

Firebase कंसोल, Firebase सीएलआई (कमांड-लाइन इंटरफ़ेस) या अपने-आप जनरेट होने वाले एसडीके का इस्तेमाल करके, किसी भी आधिकारिक Firebase एक्सटेंशन को इंस्टॉल (और मैनेज) किया जा सकता है.

यह ज़रूर देखें कि हर इंस्टॉलेशन के तरीके के लिए, कौन-कौनसी कार्रवाइयां की जा सकती हैं. इसके लिए, इन कार्रवाइयों के बीच का अंतर देखें.


अपने-आप जनरेट होने वाले एसडीके का इस्तेमाल करके एक्सटेंशन इंस्टॉल करना और उन्हें मैनेज करना, एक नया विकल्प है. इस विकल्प की मदद से, किसी एक्सटेंशन के वर्शन के लिए Node SDK अपने-आप जनरेट करने के लिए, सीएलआई का इस्तेमाल किया जाता है. इसे JavaScript या TypeScript Cloud Functions में सामान्य डिपेंडेंसी के तौर पर इंपोर्ट किया जा सकता है.

अपने-आप जनरेट होने वाले इस एसडीके में यह शामिल है:

  • यह इंटरफ़ेस, एक्सटेंशन के पैरामीटर और ज़्यादातर नॉन-प्रिमिटिव पैरामीटर टाइप के लिए टाइप डिक्लेरेशन दिखाता है.
  • कंस्ट्रक्टर फ़ंक्शन, जो एक्सटेंशन के इंस्टेंस को शुरू करता है
  • यह एक एक्सटेंशन क्लास है. इसमें एक्सटेंशन से ट्रिगर होने वाले सभी इवेंट के लिए Eventarc ट्रिगर होते हैं.

एक्सटेंशन SDK जनरेट करने के बाद, एक्सटेंशन का पूरा कॉन्फ़िगरेशन कोड में होता है.

इंस्टॉल करने के इस विकल्प का इस्तेमाल करके, एक से ज़्यादा एक्सटेंशन इंस्टेंस को आसानी से मैनेज किया जा सकता है. खास तौर पर, उन प्रोजेक्ट में जिनमें एक्सटेंशन के बाहर Cloud फ़ंक्शन तय किए गए हैं.


एक्सटेंशन इंस्टॉल करने या उन्हें मैनेज करने के लिए, आपको इनमें से कोई एक भूमिका असाइन की जानी चाहिए: मालिक या एडिटर या Firebase एडमिन.

एक्सटेंशन इंस्टॉल करने के लिए, आपका प्रोजेक्ट Blaze (इस्तेमाल के हिसाब से शुल्क चुकाएं) प्लान पर होना चाहिए. एक्सटेंशन इंस्टॉल करने के लिए कोई शुल्क नहीं लिया जाता. हालांकि, Firebase सेवाओं या Cloud Secret Manager जैसी क्लाउड सेवाओं का इस्तेमाल करने पर आपसे शुल्क लिया जा सकता है. ऐसा तब होता है, जब आपने सेवाओं के मुफ़्त टियर में तय की गई सीमा से ज़्यादा इस्तेमाल किया हो.

शुरू करने से पहले

  1. अगर आपने पहले से ही ऐसा नहीं किया है, तो अपने प्रोजेक्ट में Firebase जोड़ें.

  2. अगर आपने पहले से ही अपने प्रोजेक्ट को Blaze (इस्तेमाल के हिसाब से शुल्क चुकाएं) प्लान में अपग्रेड नहीं किया है, तो ऐसा करें.

  3. Firebase सीएलआई का नया वर्शन इंस्टॉल करें या उसे अपडेट करें.

  4. अपने Firebase प्रोजेक्ट आईडी या पहले से कॉन्फ़िगर किए गए प्रोजेक्ट के उपनाम को नोट करें.

पहला चरण: किसी एक्सटेंशन के बारे में ज़्यादा जानकारी देखना

यह चरण ज़रूरी नहीं है, लेकिन इसका सुझाव दिया जाता है.

हमारा सुझाव है कि Firebase Extension इंस्टॉल करने से पहले, एक्सटेंशन के बारे में पूरी जानकारी देखें. जैसे:

  • एक्सटेंशन कैसे काम करता है, इंस्टॉल करने से पहले किए जाने वाले टास्क, और एक्सटेंशन के बारे में जानकारी
  • पहचान ज़ाहिर करने वाली सामान्य जानकारी और ब्यौरा
  • एक्सटेंशन के टास्क के लिए बिलिंग खाते की ज़रूरत है या नहीं
  • Google की सेवाएं (एपीआई) और ऐक्सेस की भूमिकाएं
  • एक्सटेंशन के लिए बनाए गए संसाधन (जैसे कि फ़ंक्शन)
  • उपयोगकर्ता के हिसाब से कॉन्फ़िगर किए जा सकने वाले पैरामीटर की जानकारी

किसी एक्सटेंशन की पूरी जानकारी देखने के लिए:

  1. पक्का करें कि आपने अपना एनवायरमेंट सेट अप कर लिया हो और कोई एक्सटेंशन चुन लिया हो.

  2. अपने कंप्यूटर पर कहीं से भी, extension-info कमांड चलाएं:

    firebase ext:info publisher-id/extension-id

    publisher-id और extension-id आर्ग्युमेंट ज़रूरी हैं. ये एक्सटेंशन की प्रीइंस्टॉल जानकारी वाले पेज पर मिल सकते हैं.

दूसरा चरण: एक्सटेंशन इंस्टॉल करना

इंस्टॉल करने से पहले, एक्सटेंशन की बुनियादी खासियतों की समीक्षा करें. जैसे, चालू किए गए एपीआई, बनाए गए संसाधन, दिया गया ऐक्सेस वगैरह. साथ ही, बिलिंग से जुड़ी ज़रूरी शर्तों की समीक्षा करें.

आगे बढ़ने से पहले, पक्का करें कि आपने अपना एनवायरमेंट सेट अप कर लिया हो और कोई एक्सटेंशन चुना हो.

Firebase के लिए Cloud Functions को चालू करना

अगर आपको नया प्रोजेक्ट शुरू करना है या आपका प्रोजेक्ट पहले से Cloud Functions for Firebase का इस्तेमाल नहीं करता है, तो init functions चलाएं:

cd your-project
firebase init functions

फ़ंक्शन की भाषा के तौर पर, TypeScript या JavaScript चुनें.

अगर आपके प्रोजेक्ट में Cloud Functions पहले से ही चालू है, तो पक्का करें कि firebase-functions पैकेज के 5.1.0 या इसके बाद वाले वर्शन का इस्तेमाल किया जा रहा हो:

cd your-project/functions
npm upgrade --save firebase-functions

अगर ESLint का इस्तेमाल किया जाता है, तो जनरेट किए गए एसडीके को अपने कॉन्फ़िगरेशन (.eslintrc.js) से भी हटाया जा सकता है:

ignorePatterns: [
  "/generated/**/*", // Ignore generated files.
  // ...
],

एक्सटेंशन एसडीके जनरेट करना

अपनी लोकल Firebase डायरेक्ट्री से, ext:sdk:install कमांड चलाएं.

firebase ext:sdk:install publisher-id/extension-id@version

उदाहरण के लिए, firestore-send-email एक्सटेंशन का वर्शन 0.1.34 इंस्टॉल करने के लिए:

firebase ext:sdk:install firebase/firestore-send-email@0.1.34

publisher-id और extension-id ज़रूरी हैं. इन्हें extensions.dev पर जाकर, एक्सटेंशन के प्रीइंस्टॉल पेज पर देखा जा सकता है. @version वाला हिस्सा ज़रूरी नहीं है. अगर इसे छोड़ दिया जाता है, तो टूल सबसे नया वर्शन इंस्टॉल करता है.

आपके पास दो विकल्प हैं:

  • --force: बिना किसी और पुष्टि के, ये सभी काम करो:

    • SDK को अपने-आप जनरेट होने दें. भले ही, उसी एक्सटेंशन और वर्शन के लिए पहले ही कोई SDK जनरेट हो चुका हो.
    • Cloud Functions Node प्रोजेक्ट में, अपने-आप जनरेट होने वाला SDK पैकेज इंस्टॉल करें.

  • --codebase: एसडीके को जोड़ने के लिए कोडबेस का नाम. अगर यह विकल्प नहीं दिया जाता है, तो कमांड SDK टूल को डिफ़ॉल्ट कोडबेस, functions में जोड़ देती है.

इस कमांड से, एक्सटेंशन के लिए अपने-आप जनरेट होने वाला SDK टूल शामिल करने वाला एक नोड पैकेज बनता है. साथ ही, इसे आपके प्रोजेक्ट के Cloud Functions कोडबेस में से किसी एक में जोड़ दिया जाता है. डिफ़ॉल्ट कोडबेस (functions) में, एसडीके को इस जगह पर सेव किया जाता है: 

functions/generated/extensions/publisher-id/extension-id/version

एसडीके जनरेट करने के बाद, कमांड आपसे पूछेगी कि क्या आपको एसडीके को अपने Cloud Functions Node प्रोजेक्ट में भी इंस्टॉल करना है. इस प्रॉम्प्ट का जवाब हां में दें.

एक्सटेंशन इंस्टेंस कॉन्फ़िगर करना

एक्सटेंशन को कॉन्फ़िगर करने के लिए, एसडीके इंपोर्ट करें. इसके बाद, आपको जिस एक्सटेंशन इंस्टेंस को इंस्टॉल करना है उसके लिए कंस्ट्रक्टर फ़ंक्शन को कॉल करें. साथ ही, उसे प्रोजेक्ट के लिए यूनीक इंस्टेंस आईडी और एक्सटेंशन के लिए ज़रूरी कॉन्फ़िगरेशन पैरामीटर पास करें.

  1. अपने Cloud Functions सोर्स में, ext:sdk:install कमांड से प्रिंट किए गए स्टेटमेंट का इस्तेमाल करके, कंस्ट्रक्टर को इंपोर्ट करें.

    TypeScript

    उदाहरण के लिए, अगर आपने firestore-send-email एक्सटेंशन के लिए एसडीके जनरेट किया है, तो import स्टेटमेंट कुछ इस तरह दिखेगा:

    import { firestoreSendEmail } from "@firebase-extensions/firebase-firestore-send-email-sdk";

    अगर एक्सटेंशन को पासवर्ड जैसी किसी सीक्रेट वैल्यू की ज़रूरत है, तो आपको Cloud Functions SDK से defineSecret फ़ंक्शन की भी ज़रूरत होगी:

    import { defineSecret } from "firebase-functions/params";

    JavaScript

    उदाहरण के लिए, अगर आपने firestore-send-email एक्सटेंशन के लिए कोई एसडीके जनरेट किया है, तो require स्टेटमेंट कुछ इस तरह दिखेगा:

    const { firestoreSendEmail } = require("@firebase-extensions/firebase-firestore-send-email-sdk");

    अगर एक्सटेंशन को पासवर्ड जैसी किसी सीक्रेट वैल्यू की ज़रूरत है, तो आपको Cloud Functions SDK से defineSecret फ़ंक्शन की भी ज़रूरत होगी:

    const { defineSecret } = require('firebase-functions/params');

  2. आपको जिस इंस्टेंस को कॉन्फ़िगर करना है उसके लिए, कंस्ट्रक्टर फ़ंक्शन को कॉल करें और नतीजे को एक्सपोर्ट करें.

    हर इंस्टेंस को एक यूनीक आईडी दें. इसमें सिर्फ़ छोटे अक्षर, संख्याएं, और हाइफ़न शामिल होने चाहिए.

    TypeScript

    export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

    JavaScript

    exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

    ध्यान दें कि सीक्रेट वैल्यू को defineSecret फ़ंक्शन का इस्तेमाल करके तय किया जाना चाहिए.

  3. इसके बाद, कॉन्फ़िगर किए गए एक्सटेंशन को डिप्लॉय करने के लिए, यह कमांड चलाएं: 

    firebase deploy --only functions --project=projectId-or-alias

    Cloud Functions डिप्लॉयमेंट के सभी सामान्य विकल्प लागू होते हैं. उदाहरण के लिए, किसी खास कोडबेस से एक्सटेंशन का एक इंस्टेंस डिप्लॉय करने के लिए: 

    firebase deploy --only functions:codebase:extension-instance-id --project=projectId-or-alias

तीसरा चरण: इंस्टॉल करने के बाद का सेटअप पूरा करना

कुछ एक्सटेंशन का इस्तेमाल करने से पहले, आपको ज़रूरी या वैकल्पिक चरणों को पूरा करना होगा. ये निर्देश, आपको एक्सटेंशन इंस्टॉल करने के बाद दिखने वाले पेज पर मिलेंगे. यह पेज, Extensions कंसोल के Firebase डैशबोर्ड में होता है. डैशबोर्ड का लिंक, एक्सटेंशन इंस्टॉल करने के बाद टर्मिनल में दिखता है.

आपको ये निर्देश, POSTINSTALL.md एक्सटेंशन की सोर्स डायरेक्ट्री में शामिल फ़ाइल में भी मिल सकते हैं.

Firebase संसाधन बनाना

अगर आपने एक्सटेंशन को ऐसे Firebase संसाधनों (Cloud Firestore कलेक्शन, Realtime Database पाथ, Cloud Storage बकेट) का इस्तेमाल करने के लिए कॉन्फ़िगर किया है जो पहले से मौजूद नहीं हैं, तो एक्सटेंशन का इस्तेमाल करने से पहले उन्हें बनाएं.

Eventarc इवेंट हैंडलर बनाना

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

अगर आपको एक्सटेंशन से ट्रिगर होने वाले किसी भी इवेंट के लिए हैंडलर तय करने हैं, तो हर इंस्टेंस के ट्रिगर करने के तरीकों का इस्तेमाल करके ऐसा किया जा सकता है:

TypeScript

export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

export const emailErrorHandler = firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

JavaScript

exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

exports.emailErrorHandler = exports.firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

आपको एक्सटेंशन इंस्टेंस के साथ-साथ इवेंट हैंडलर को भी एक्सपोर्ट करना होगा.

इवेंट हैंडलर तय करने के बाद, और जब भी किसी इवेंट हैंडलर में बदलाव किया जाए, तो एक्सटेंशन और हैंडलर, दोनों को फिर से डिप्लॉय करें.

एक्सटेंशन के कई इंस्टेंस इंस्टॉल करना

एक ही प्रोजेक्ट में, एक ही एक्सटेंशन को एक से ज़्यादा बार इंस्टॉल किया जा सकता है. हर इंस्टॉल किए गए इंस्टेंस का अपना कस्टम कॉन्फ़िगरेशन और एक्सटेंशन रिसॉर्स हो सकते हैं. हर इंस्टॉल किए गए इंस्टेंस की पहचान करने और उसे रेफ़र करने के लिए, उसके instance ID का इस्तेमाल करें. यह आईडी, आपके प्रोजेक्ट में यूनीक होता है.

आपको जिस इंस्टेंस को इंस्टॉल और कॉन्फ़िगर करना है उसके लिए, अपने-आप जनरेट हुए एसडीके के कंस्ट्रक्टर फ़ंक्शन को एक बार कॉल करें.

अगले चरण

  • Firebase कंसोल में जाकर, इंस्टॉल किए गए एक्सटेंशन की जानकारी और कॉन्फ़िगरेशन देखें.

  • आपने जो एक्सटेंशन इंस्टॉल किया है उसकी गतिविधि को मॉनिटर करें. इसमें एक्सटेंशन की परफ़ॉर्मेंस, इस्तेमाल, और लॉग की जांच करना शामिल है.

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

  • सभी प्रोजेक्ट के लिए, यह सबसे सही तरीका है कि आप अपने प्रोजेक्ट के लिए बजट से जुड़ी सूचनाएं सेट अप करें. साथ ही, Firebase कंसोल में इस्तेमाल और बिलिंग डैशबोर्ड पर नज़र रखें.