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

تسمح لك إضافة 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.',
  },
})

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

الإعداد المسبق

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

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

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

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

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

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

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

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

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

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

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

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

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

    راجِع استخدام نماذج المقايضات مع إضافة Trigger Email (عنوان البريد الإلكتروني المشغِّل). لمزيد من التفاصيل.

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

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

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

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

حقل الرسالة

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

في ما يلي السمات المتوفّرة للحقل message:

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

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

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