قلاب های کاربر را به یک برنامه افزودنی اضافه کنید

شما می‌توانید به کاربرانی که افزونه شما را نصب می‌کنند، این امکان را بدهید که منطق سفارشی خود را در اجرای افزونه شما وارد کنند. دو راه برای انجام این کار وجود دارد:

• رویدادهای Eventarc : برای اینکه کاربران بتوانند به صورت غیرهمزمان به رویدادها واکنش نشان دهند، می‌توانید آن‌ها را در Eventarc منتشر کنید. کاربران می‌توانند توابع مدیریت رویداد را پیاده‌سازی کنند که مثلاً پس از اتمام وظایف طولانی مدت، اعلان ارسال می‌کنند، یا می‌توانند توابع پس پردازش خود را تعریف کنند.

• قلاب‌های همگام : برای اینکه به کاربران راهی برای اضافه کردن منطق مسدودکننده به افزونه‌تان بدهید، می‌توانید قلاب‌های همگام را در نقاط از پیش تعریف‌شده در عملیات افزونه اضافه کنید. در این نقاط، یک تابع ارائه‌دهنده کاربر را اجرا می‌کنید و فقط پس از اتمام آن ادامه می‌دهید. وظایف پیش‌پردازش اغلب در این دسته قرار می‌گیرند.

یک افزونه می‌تواند از یک یا هر دو روش استفاده کند.

رویدادهای ایونتارک

برای انتشار رویدادها از یک افزونه:

1. انواع رویدادهایی را که می‌خواهید در فایل extension.yaml منتشر کنید، تعریف کنید:

   events:
     - type: publisher-id.extension-name.version.event-name
       description: event-description
     - type: publisher-id.extension-name.version.another-event-name
       description: another-event-description
   

   شناسه type از چندین فیلد جدا شده با نقطه تشکیل شده است. فیلدهای شناسه ناشر ، نام افزونه و نام رویداد الزامی هستند. فیلد نسخه توصیه می‌شود. برای هر نوع رویدادی که منتشر می‌کنید، یک نام رویداد منحصر به فرد و توصیفی انتخاب کنید.

   برای مثال، افزونه‌ی storage-resize-images یک نوع رویداد واحد را تعریف می‌کند:

   events:
     - type: firebase.extensions.storage-resize-images.v1.complete
       description: |
         Occurs when image resizing completes. The event will contain further
         details about specific formats and sizes.
   

   کاربران می‌توانند هنگام نصب این افزونه، رویدادهایی را که می‌خواهند در آنها مشترک شوند، انتخاب کنند.

2. در توابع افزونه خود، API مربوط به Eventarc را از Admin SDK وارد کنید و با استفاده از تنظیمات نصب کاربر، یک کانال رویداد را راه‌اندازی کنید. این تنظیمات با استفاده از متغیرهای محیطی زیر نمایش داده می‌شوند:

   • EVENTARC_CHANNEL : نام کامل کانال Eventarc که کاربر برای انتشار رویدادها انتخاب کرده است.
   • EXT_SELECTED_EVENTS : فهرستی از انواع رویدادهایی که کاربر برای انتشار انتخاب کرده است و با کاما از هم جدا شده‌اند. وقتی کانالی را با این مقدار مقداردهی اولیه می‌کنید، Admin SDK به طور خودکار رویدادهایی را که کاربر انتخاب نکرده است، فیلتر می‌کند.
   • EVENTARC_CLOUD_EVENT_SOURCE : شناسه منبع رویداد ابری. SDK مدیریت به طور خودکار این مقدار را در فیلد source رویدادهای منتشر شده ارسال می‌کند. معمولاً نیازی به استفاده صریح از این متغیر نیست.

   اگر رویدادها در هنگام نصب فعال نشده باشند، این متغیرها تعریف نشده خواهند بود. می‌توانید از این واقعیت برای مقداردهی اولیه یک کانال رویداد فقط زمانی که رویدادها فعال هستند استفاده کنید:

   import * as admin from "firebase-admin";
   import {getEventarc} from 'firebase-admin/eventarc';
   
   admin.initializeApp();
   
   // Set eventChannel to a newly-initialized channel, or `undefined` if events
   // aren't enabled.
   const eventChannel =
     process.env.EVENTARC_CHANNEL &&
     getEventarc().channel(process.env.EVENTARC_CHANNEL, {
       allowedEventTypes: process.env.EXT_SELECTED_EVENTS,
     });
   

3. رویدادها را در کانال در نقاطی از افزونه خود که می‌خواهید در معرض دید کاربران قرار دهید، منتشر کنید. برای مثال:

   // If events are enabled, publish a `complete` event to the configured
   // channel.
   eventChannel && eventChannel.publish({
       type: 'firebase.extensions.storage-resize-images.v1.complete',
       subject: filename,  // the name of the original file
       data: {
         // ...
       }
   });
   

4. رویدادهایی را که منتشر می‌کنید، در فایل PREINSTALL یا POSTINSTALL مستند کنید.

   برای هر رویداد، موارد زیر را مستند کنید:

   • هدف مورد نظر آن
   • نکته‌ای که در منطق افزونه‌ی شما وجود دارد و اجرا می‌شود
   • داده‌های خروجی که شامل می‌شود
   • شرایط اجرای آن

   علاوه بر این، به کاربران هشدار دهید که هیچ عملی را در کنترل‌کننده‌های رویداد خود انجام ندهند که ممکن است همان افزونه را فعال کند و منجر به یک حلقه بی‌نهایت شود.

وقتی رویدادهایی را از یک افزونه منتشر می‌کنید، کاربران می‌توانند کنترل‌کننده‌های رویداد را برای پاسخ با منطق سفارشی مستقر کنند.

برای مثال، مثال زیر تصویر اصلی را پس از تغییر اندازه حذف می‌کند. توجه داشته باشید که این کنترل‌کننده‌ی مثال از ویژگی subject رویداد استفاده می‌کند که در این مورد، نام فایل اصلی تصویر است.

exports.onimageresized = onCustomEventPublished(
    "firebase.extensions.storage-resize-images.v1.complete",
    (event) => {
      logger.info("Received image resize completed event", event);
      // For example, delete the original.
      return admin.storage()
          .bucket("my-project.firebasestorage.app")
          .file(event.subject)
          .delete();
    });

برای اطلاعات بیشتر به محرک‌های رویداد سفارشی مراجعه کنید.

مثال

افزونه رسمی تغییر اندازه تصاویر (Resize Images) با انتشار در Eventarc پس از تغییر اندازه تصویر، یک قلاب ناهمزمان (asynchronous hook) ارائه می‌دهد.

قلاب‌های همزمان

وقتی می‌خواهید به کاربران قلابی ارائه دهید که برای عملکرد یکی از توابع افزونه شما باید با موفقیت تکمیل شود، از قلاب‌های همزمان استفاده کنید.

یک هوک همزمان، یک تابع ابری قابل فراخوانی HTTPS تعریف شده توسط کاربر را فراخوانی می‌کند و قبل از ادامه، منتظر تکمیل (احتمالاً با یک مقدار برگشتی) می‌ماند. خطایی در تابع ارائه شده توسط کاربر منجر به خطا در تابع افزونه می‌شود.

برای نمایش یک هوک همگام:

1. پارامتری به افزونه خود اضافه کنید که به کاربران اجازه دهد افزونه را با URL به تابع ابری سفارشی خود پیکربندی کنند. برای مثال:

   - param: PREPROCESSING_FUNCTION
     label: Pre-processing function URL
     description: >
       An HTTPS callable function that will be called to transform the input data
       before it is processed by this function.
     type: string
     example: https://us-west1-my-project-id.cloudfunctions.net/preprocessData
     required: false
   

2. در نقطه‌ای از افزونه که می‌خواهید هوک را نمایش دهید، تابع را با استفاده از URL آن فراخوانی کنید. برای مثال:

   const functions = require('firebase-functions/v1');
   const fetch = require('node-fetch');
   
   const preprocessFunctionURL = process.env.PREPROCESSING_FUNCTION;
   
   exports.yourFunctionName = functions.firestore.document("collection/{doc_id}")
       .onWrite((change, context) => {
         // PREPROCESSING_FUNCTION hook begins here.
         // If a preprocessing function is defined, call it before continuing.
         if (preprocessFunctionURL) {
           try {
             await fetch(preprocessFunctionURL); // Could also be a POST request if you want to send data.
           } catch (e) {
             // Preprocessing failure causes the function to fail.
             functions.logger.error("Preprocessor error:", e);
             return;
           }
         }
         // End of PREPROCESSING_FUNCTION hook.
   
         // Main function logic follows.
         // ...
       });
   

3. هر هوک (hook) که در فایل PREINSTALL یا POSTINSTALL در دسترس قرار می‌دهید را مستندسازی کنید.

   برای هر قلاب، موارد زیر را مستند کنید:

   • هدف مورد نظر آن
   • نکته‌ای که در منطق افزونه‌ی شما وجود دارد و اجرا می‌شود
   • ورودی‌ها و خروجی‌های مورد انتظار آن
   • شرایط (یا گزینه‌های) اجرای آن

   علاوه بر این، به کاربران هشدار دهید که هیچ عملی را در تابع هوک انجام ندهند که ممکن است همان افزونه را فعال کند و منجر به یک حلقه بی‌نهایت شود.

مثال

افزونه‌ی Algolia Search یک هوک همزمان برای فراخوانی تابع تبدیل ارائه شده توسط کاربر قبل از نوشتن در Algolia فراهم می‌کند.