استخدام ملحق 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.',
  },
})

يمكنك أيضًا تكوين هذا الامتداد اختياريًا لعرض رسائل البريد الإلكتروني باستخدام قوالب Handlebars .

إعداد ما قبل التثبيت

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

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

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

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

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

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

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

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

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

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

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

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

    راجع استخدام قوالب المقاود مع ملحق Trigger Email للحصول على التفاصيل.

قم بتثبيت الامتداد

لتثبيت الملحق، اتبع الخطوات الموجودة في صفحة تثبيت ملحق Firebase . باختصار، قم بأحد الإجراءات التالية:

  • وحدة تحكم 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.',
}

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

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

  • من: عنوان البريد الإلكتروني للمرسل. إذا لم يتم تحديده في المستند، فسيتم استخدام معلمة "العنوان الافتراضي من" التي تم تكوينها.
  • ResponseTo: عنوان البريد الإلكتروني للرد. إذا لم يتم تحديده في المستند، فسيتم استخدام معلمة "عنوان الرد الافتراضي" التي تم تكوينها.
  • إلى: عنوان بريد إلكتروني لمستلم واحد أو مصفوفة تحتوي على عناوين بريد إلكتروني متعددة للمستلمين.
  • toUids: مصفوفة تحتوي على UIDs للمستلم.
  • نسخة إلى: عنوان بريد إلكتروني لمستلم واحد أو مصفوفة تحتوي على عناوين بريد إلكتروني متعددة للمستلمين.
  • ccUids: مصفوفة تحتوي على UIDs لمستلم CC.
  • نسخة مخفية الوجهة: عنوان بريد إلكتروني لمستلم واحد أو مصفوفة تحتوي على عناوين بريد إلكتروني متعددة للمستلمين.
  • bccUids: صفيف يحتوي على UIDs لمستلم BCC.
  • الرؤوس: كائن من حقول الرأس الإضافية (على سبيل المثال {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"} ).

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

حقل الرسالة

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

الخصائص المتوفرة لحقل message هي:

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

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

تعرف على المزيد من الاستخدام المتقدم لهذا الامتداد: