استخدام إضافة Trigger Email

يتيح لك إضافة Trigger Email (firestore-send-email) إرسال رسائل إلكترونية تلقائيًا استنادًا إلى المستندات في مجموعة Cloud Firestore. تؤدي إضافة مستند إلى المجموعة إلى تفعيل هذه الإضافة لإرسال رسالة إلكترونية تم إنشاؤها من حقول المستند. تحدّد الحقول ذات المستوى الأعلى في المستند مُرسِل الرسالة الإلكترونية والمستلِمين، بما في ذلك الخيارات to وcc وbcc (يدعم كل منها معرّفات UID). يحدّد الحقل message في المستند عناصر البريد الإلكتروني الأخرى، مثل سطر الموضوع ونص الرسالة (إما نص عادي أو HTML).

في ما يلي مثال أساسي على كتابة مستند يؤدي إلى تشغيل هذه الإضافة:

admin.firestore().collection('mail').add({
  to: 'someone@example.com',
  message: {
    subject: 'Hello from Firebase!',
    html: 'This is an <code>HTML</code> email body.',
  },
})

يمكنك أيضًا ضبط هذه الإضافة لعرض الرسائل الإلكترونية باستخدام نماذج Handlebars، إذا أردت ذلك.

إعدادات التثبيت المُسبَق

قبل تثبيت الإضافة، أكمِل الخطوات التالية:

  1. إعداد خدمة البريد الصادر

    عند تثبيت إضافة Trigger Email، عليك تحديد تفاصيل الاتصال والمصادقة الخاصة بخادم SMTP الذي تستخدمه الإضافة لإرسال الرسائل الإلكترونية. يتم توفير ذلك عادةً من خلال خدمة لتسليم الرسائل الإلكترونية، مثل Sendgrid أو Mailgun أو Mailchimp Transactional Email، ولكن يمكن أن يكون أيضًا خادمًا تديره بنفسك.

  2. إنشاء مجموعة مستندات للرسائل الإلكترونية

    تستمع إضافة "إرسال رسالة إلكترونية عند تشغيل حدث" إلى المستندات الجديدة في Cloud FirestoreمجموعةCloud Firestore تحدّدها. عندما تعثر الإضافة على مستند جديد، ترسل رسالة إلكترونية استنادًا إلى حقول المستند. يمكنك استخدام أي مجموعة Cloud Firestore لهذا الغرض، وتستخدِم الأمثلة الواردة في هذه الصفحة مجموعة باسم email.

  3. إعداد قواعد الأمان لمجموعة مستندات البريد الإلكتروني

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

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

  4. اختياري: إعداد مجموعة مستخدمين

    ضمن الاستخدام الأساسي لهذه الإضافة، يمكنك تحديد مستلمي رسالة إلكترونية من خلال تحديد عناوين بريدهم الإلكتروني في الحقول to وcc وbcc في مستند الرسالة. كحلّ بديل، إذا كان لديك قاعدة بيانات مستخدمين في Cloud Firestore، يمكنك تحديد المستلِمين باستخدام أرقام التعريف الفريدة للمستخدمين. لكي تنجح هذه العملية، يجب أن تستوفي مجموعة المستخدمين المعايير التالية:

    • يجب أن تستند عملية الجمع إلى أرقام تعريف المستخدمين. أي أنّ معرّف المستند لكل مستند مستخدم في المجموعة يجب أن يكون Firebase Authenticationمعرّف المستخدم الفريد.
    • يجب أن يتضمّن مستند كل مستخدم الحقل email الذي يحتوي على عنوان البريد الإلكتروني للمستخدم.

  5. اختياري: إعداد مجموعة نماذج

    يمكنك عرض الرسائل الإلكترونية باستخدام نماذج Handlebars. لإجراء ذلك، ستحتاج إلى مجموعة Cloud Firestore تحتوي على النماذج.

    راجِع استخدام نماذج Handlebars مع إضافة Trigger Email للحصول على التفاصيل.

تثبيت الإضافة

لتثبيت الإضافة، اتّبِع الخطوات الواردة في صفحة تثبيت Firebase Extension. باختصار، نفِّذ أحد الإجراءات التالية:

  • Firebase وحدة التحكّم: انقر على الزرّ التالي:

    تثبيت إضافة Trigger Email

  • واجهة سطر الأوامر: نفِّذ الأمر التالي: 

    firebase ext:install firebase/firestore-send-email --project=projectId-or-alias

عند تثبيت الإضافة، سيُطلب منك تحديد معلومات اتصال SMTP ومجموعات Cloud Firestore التي أعددتها سابقًا.

استخدام الإضافة

بعد التثبيت، تراقب هذه الإضافة جميع عمليات الكتابة في المستندات إلى المجموعة التي أعددتها. يتم تسليم الرسالة الإلكترونية استنادًا إلى محتوى حقول المستند. تحدّد الحقول ذات المستوى الأعلى المُرسِلين والمستلِمين للرسالة الإلكترونية. يحتوي الحقل message على تفاصيل الرسالة الإلكترونية التي سيتم تسليمها، بما في ذلك نص الرسالة الإلكترونية.

مثال: إرسال رسالة إلكترونية

لإرسال رسالة بسيطة، أضِف مستندًا إلى مجموعة الرسائل يتضمّن الحقل to والحقل message مع المحتوى التالي:

to: ['someone@example.com'],
message: {
  subject: 'Hello from Firebase!',
  text: 'This is the plaintext section of the email body.',
  html: 'This is the <code>HTML</code> section of the email body.',
}

حقول المُرسِل والمستلِم

توفّر الحقول ذات المستوى الأعلى في المستند معلومات عن مُرسِل الرسالة الإلكترونية ومُستلِمها. الحقول المتاحة هي:

  • من: عنوان البريد الإلكتروني للمُرسِل في حال عدم تحديدها في المستند، يتم استخدام المَعلمة "عنوان FROM التلقائي" التي تم ضبطها.
  • replyTo: عنوان البريد الإلكتروني للردّ في حال عدم تحديدها في المستند، يتم استخدام المَعلمة "عنوان REPLY-TO التلقائي" التي تم ضبطها.
  • إلى: عنوان بريد إلكتروني واحد للمستلِم أو مصفوفة تحتوي على عدة عناوين بريد إلكتروني للمستلِمين
  • toUids: مصفوفة تحتوي على المعرّفات الفريدة للمستلِمين.
  • cc: عنوان بريد إلكتروني لمستلِم واحد أو مصفوفة تحتوي على عناوين بريد إلكتروني لعدة مستلمين
  • ccUids: مصفوفة تحتوي على معرّفات المستخدمين الفريدة للمستلمين في الحقل "نسخة إلى".
  • نسخة مخفية الوجهة: عنوان بريد إلكتروني لمستلم واحد أو مصفوفة تحتوي على عناوين بريد إلكتروني لعدة مستلمين
  • bccUids: مصفوفة تحتوي على معرّفات المستخدمين الفريدة لمستلمي النسخة المخفية الوجهة.
  • headers: كائن يتضمّن حقول رؤوس إضافية (على سبيل المثال، {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"}).

ملاحظة: تقدّم الخيارات toUids وccUids وbccUids رسائل إلكترونية استنادًا إلى معرّفات المستخدمين الفريدة المرتبطة بعناوين البريد الإلكتروني ضِمن مستند Cloud Firestore. لاستخدام خيارات المستلِمين هذه، عليك تحديد مجموعة Cloud Firestore لمعلَمة "مجموعة المستخدمين" الخاصة بالإضافة. يمكن للإضافة بعد ذلك قراءة الحقل email لكل معرّف فريد محدّد في الحقول toUids و/أو ccUids و/أو bccUids.

حقل الرسالة

يحتوي الحقل message في المستند على معلومات التسليم الأولية للرسالة الإلكترونية. يجب بشكل عام أن يملأ هذا الحقل رمز موثوق به فقط يتم تشغيله على خوادمك أو في Cloud Functions (يُرجى الرجوع إلى قسم "قواعد الأمان وإرسال الرسائل الإلكترونية" أدناه).

السمات المتاحة للحقل message هي:

  • ‫messageId: عنوان معرّف الرسالة للبريد الإلكتروني، إذا كان متوفّرًا.
  • subject: موضوع الرسالة الإلكترونية.
  • text: محتوى الرسالة الإلكترونية بنص عادي.
  • html: محتوى HTML للرسالة الإلكترونية
  • amp: محتوى البريد الإلكتروني AMP4EMAIL
  • المرفقات: مصفوفة تحتوي على مرفقات. خيارات Nodemailer المتاحة: سلسلة utf-8، ونوع محتوى مخصّص، وعنوان URL، وسلسلة مرمّزة، ومعرّف موارد منتظم(URI) للبيانات، وعقدة MIME مُنشأة مسبقًا (يُرجى العِلم بأنّ بريدك الإلكتروني لا يمكنه الوصول إلى نظام ملفات خادم السحابة الإلكترونية).

الاستخدام المتقدّم

في ما يلي معلومات عن الاستخدام الأكثر تقدّمًا لهذه الإضافة: