Firebase is back at Google I/O on May 10! Register now

استخدام ملحق 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. إنشاء مجموعة مستندات البريد الإلكتروني.

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

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

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

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

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

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

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

  5. اختياري: قم بإعداد مجموعة قوالب.

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

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

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

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

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

    قم بتثبيت ملحق Trigger Email

  • CLI: قم بتشغيل الأمر التالي:

    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: مصفوفة تحتوي على UID للمستلم.
  • نسخة إلى: عنوان بريد إلكتروني لمستلم واحد أو مصفوفة تحتوي على عدة عناوين بريد إلكتروني للمستلمين.
  • ccUids: مصفوفة تحتوي على UIDs لمستلم CC.
  • نسخة مخفية الوجهة: عنوان بريد إلكتروني لمستلم واحد أو مصفوفة تحتوي على عدة عناوين بريد إلكتروني للمستلمين.
  • bccUids: مصفوفة تحتوي على UIDs لمستلم BCC.
  • headers: كائن لحقول رأس إضافية (على سبيل المثال {"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 المُنشأة مسبقًا (اعلم أن بريدك الإلكتروني ليس له حق الوصول إلى نظام ملفات الخادم السحابي).

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

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