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

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

• أحداث Eventarc: لمنح المستخدمين طريقة للتفاعل بشكل غير متزامن مع الأحداث، يمكنك النشر على Eventarc. ويمكن للمستخدمين تفعيل وظائف معالج الأحداث التي، على سبيل المثال، إرسال الإشعارات بعد اكتمال مهام طويلة الأمد، أو يمكنهم تحديد وظائفهم الخاصة بعد المعالجة.

• العناصر المُدمجة المتزامنة: لمنح المستخدمين طريقة لإضافة منطق حظر إلى إضافتك، يمكنك إضافة عناصر مدمجة متزامنة في نقاط محدّدة مسبقًا في عمل إضافة Chrome. في هذه النقاط، يمكنك تشغيل دالة مقدّم خدمة مستخدمين ومتابعة الخطوات بعد اكتمالها فقط. تندرج مهام المعالجة المُسبَقة غالبًا ضمن هذه الفئة.

يمكن أن تستخدم الإضافة إحدى الطريقتَين أو كلتيهما.

أحداث 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: معرّف مصدر الحدث على السحابة الإلكترونية تُرسِل IDE SDK هذه القيمة تلقائيًا في حقل source من IDE events. لا تحتاج عادةً إلى استخدام هذا المتغيّر بشكل صريح.

   إذا لم يتم تفعيل الأحداث عند التثبيت، ستكون هذه المتغيّرات غير محدّدة. يمكنك استخدام هذه المعلومة لإعداد قناة حدث فقط عند تفعيل الأحداث:

   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 إلى دالة السحابة الإلكترونية المخصّصة. على سبيل المثال:

   - 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.