إضافة عناصر الجذب للمستخدمين إلى إضافة

يمكنك منح المستخدمين الذين يثبّتون إضافتك إمكانية إدراج منطقهم المخصّص في تنفيذ إضافتك. هناك طريقتان للقيام بذلك:

• أحداث Eventarc: لمنح المستخدمين طريقة للتفاعل بشكل غير متزامن مع الأحداث، يمكنك النشر على 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. في وظائف الإضافة، استورِد Eventarc API من Admin SDK وأعِد ضبط قناة أحداث باستخدام إعدادات التثبيت الخاصة بالمستخدم. يتم عرض هذه الإعدادات باستخدام متغيّرات البيئة التالية:

   • EVENTARC_CHANNEL: الاسم المؤهَّل بالكامل لقناة Eventarc التي اختَارها المستخدِم لنشر الأحداث فيها.
   • ‫EXT_SELECTED_EVENTS: قائمة مفصولة بفواصل لأنواع الأحداث التي اختار المستخدم نشرها عند إعداد قناة باستخدام هذه القيمة، تعمل "حزمة تطوير البرامج (SDK) للمشرف" على فلترة الأحداث التي لم يختارها المستخدم تلقائيًا.
   • EVENTARC_CLOUD_EVENT_SOURCE: معرّف مصدر حدث Cloud تُرسِل IDE 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.appspot.com")
          .file(event.subject)
          .delete();
    });

اطّلِع على عوامل تشغيل الأحداث المخصّصة للحصول على مزيد من المعلومات.

مثال

توفّر إضافة Resize Images الرسمية خطافًا غير متزامن من خلال النشر في Eventarc بعد تغيير حجم الصورة.

علامات الربط المتزامنة

عندما تريد تزويد المستخدمين بخطاف يجب إكماله بنجاح لكي تعمل إحدى وظائف الإضافة، استخدِم المخطّطات المتزامنة.

تستدعي ميزة الربط المتزامن دالة سحابة قابلة للاتّصال عبر بروتوكول HTTPS يحدّدها المستخدم وتنتظر اكتمالها (ربما مع قيمة معروضة) قبل المتابعة. يؤدي الخطأ في الدالة المقدَّمة من المستخدِم إلى حدوث خطأ في دالة الإضافة.

لعرض ربط متزامن:

1. أضِف مَعلمة إلى إضافتك تسمح للمستخدمين بضبط الإضافة باستخدام عنوان URL لوظيفتهم المخصّصة في Cloud. على سبيل المثال:

   - 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. سجِّل أيّ أدوات ربط لديك في ملف PREINSTALL أوملف POSTINSTALL.

   بالنسبة إلى كلّ ربط، سجِّل ما يلي:

   • الغرض المقصود
   • النقطة في منطق الإضافة التي يتم فيها تشغيلها
   • المدخلات والمخرجات المتوقّعة
   • شروط (أو خيارات) تنفيذها

   بالإضافة إلى ذلك، يجب تحذير المستخدمين من عدم اتّخاذ أي إجراءات في وظيفة الربط قد تؤدي إلى تشغيل الإضافة نفسها، ما يؤدي إلى حلقة لانهائية.

مثال

توفّر إضافة Algolia Search خطافًا متزامنًا للاتّصال بوظيفة تحويل يقدّمها المستخدم قبل الكتابة إلى Algolia.