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

تتيح لك إضافة "الرسالة الإلكترونية المشغِّلة" (firestore-send-email) إرسال رسائل إلكترونية تلقائيًا استنادًا إلى المستندات في مجموعة Cloud Firestore. تؤدي إضافة مستند إلى المجموعة إلى تنشيط هذه الإضافة لإرسال رسالة إلكترونية تم إنشاؤها من ملفّات المستند. تحدِّد حقول المستوى الأعلى في المستند مُرسِل الرسالة الإلكترونية و مستلميها، بما في ذلك خيارات to وcc وbcc (كلّ منها يتيح أرقام التعريف الفريد). يحدِّد حقل 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. إعداد خدمة البريد الصادر

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

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

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

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

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

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

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

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

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

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

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

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

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

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

عند تثبيت الإضافة، سيُطلب منك تحديد معلومات اتصال 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.',
}

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

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

  • من: عنوان البريد الإلكتروني للمُرسِل. في حال عدم تحديدها في المستند، يتم استخدام المَعلمة "عنوان المُرسِل التلقائي" التي تم ضبطها.
  • replyTo: عنوان البريد الإلكتروني المخصّص للردّ. في حال عدم تحديدها في المستند، يتم استخدام المَعلمة "عنوان REPLY-TO التلقائي" التي تم ضبطها.
  • إلى: عنوان بريد إلكتروني واحد للمستلِم أو صفيف يحتوي على عناوين بريد إلكتروني متعددة للمستلِمين.
  • toUids: صفيف يحتوي على معرّفات مستخدمي المستلمين
  • cc: عنوان بريد إلكتروني واحد للمستلِم أو صفيف يحتوي على عناوين بريد إلكتروني متعددة للمستلِمين
  • ‫ccUids: صفيف يحتوي على أرقام تعريف المستلمين في الحقل "نسخة إلى"
  • bcc: عنوان بريد إلكتروني واحد للمستلِم أو صفيف يحتوي على عناوين بريد إلكتروني متعددة للمستلِمين
  • 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 للرسالة الإلكترونية.
  • attachments: صفيف يحتوي على مرفقات. خيارات Nodemailer المتوافقة: سلسلة utf-8 ونوع محتوى مخصّص وعنوان URL وسلسلة مُشفَّرة ومعرّف موارد منتظم(URI) للبيانات وعقدة MIME تم إنشاؤها مسبقًا (يُرجى العِلم أنّ بريدك الإلكتروني لا يمكنه الوصول إلى نظام ملفات خادم السحابة الإلكترونية).

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

تعرَّف على مزيد من المعلومات عن الاستخدامات المتقدّمة لهذه الإضافة: