إنشاء روابط إجراءات البريد الإلكتروني

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

توفر حزم Firebase Client SDK القدرة على إرسال رسائل بريد إلكتروني للمستخدمين تحتوي على روابط يمكنهم استخدامها لإعادة تعيين كلمة المرور والتحقق من عنوان البريد الإلكتروني وتسجيل الدخول عبر البريد الإلكتروني. يتم إرسال رسائل البريد الإلكتروني المستندة إلى القالب هذه بواسطة Google وتتميز بإمكانية تخصيص محدودة.

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

ويأتي هذا مع الفوائد التالية:

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

تهيئة إعدادات رمز الإجراء

قبل أن تتمكن من إنشاء رابط إجراء البريد الإلكتروني، قد تحتاج إلى تهيئة مثيل ActionCodeSettings .

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

بالنسبة للروابط التي من المفترض أن يتم فتحها عبر تطبيق جوال، ستحتاج إلى تمكين Firebase Dynamic Links وتنفيذ بعض المهام لاكتشاف هذه الروابط من تطبيق الجوال الخاص بك. راجع الإرشادات الخاصة بكيفية تكوين Firebase Dynamic Links لإجراءات البريد الإلكتروني.

لتهيئة مثيل ActionCodeSettings ، قم بتوفير البيانات التالية:

معامل يكتب وصف
url خيط

يضبط الرابط (عنوان URL للحالة/المتابعة) الذي له معاني مختلفة في سياقات مختلفة:

  • عند معالجة الارتباط في عناصر واجهة مستخدم إجراء الويب، يكون هذا هو الرابط العميق في معلمة الاستعلام continueUrl .
  • عندما تتم معالجة الارتباط في التطبيق مباشرةً، تكون هذه هي معلمة الاستعلام continueUrl في الرابط العميق للارتباط الديناميكي.
iOS ({bundleId: سلسلة}|غير محدد) يضبط معرف الحزمة. سيحاول هذا فتح الرابط في تطبيق Apple إذا كان مثبتًا. يجب تسجيل التطبيق في وحدة التحكم.
android ({اسم الحزمة: سلسلة، تثبيت التطبيق: منطقي | غير محدد، الحد الأدنى الإصدار: سلسلة | غير محدد}| غير محدد) يضبط اسم حزمة Android. سيحاول هذا فتح الرابط في تطبيق Android إذا كان مثبتًا. إذا تم تمرير installApp ، فإنه يحدد ما إذا كان سيتم تثبيت تطبيق Android إذا كان الجهاز يدعمه ولم يكن التطبيق مثبتًا بالفعل. إذا تم توفير هذا الحقل بدون packageName ، فسيظهر خطأ يوضح أنه يجب توفير packageName مع هذا الحقل. إذا تم تحديد minimumVersion ، وتم تثبيت إصدار أقدم من التطبيق، فسيتم نقل المستخدم إلى متجر Play لترقية التطبيق. يجب تسجيل تطبيق Android في وحدة التحكم.
handleCodeInApp (منطقي|غير محدد) ما إذا كان سيتم فتح رابط إجراء البريد الإلكتروني في تطبيق جوال أو رابط ويب أولاً. الافتراضي هو خطأ. عند التعيين على "صحيح"، سيتم إرسال رابط رمز الإجراء كرابط عالمي أو رابط تطبيق Android وسيتم فتحه بواسطة التطبيق إذا تم تثبيته. في الحالة الخاطئة، سيتم إرسال الرمز إلى أداة الويب أولاً وبعد ذلك ستتم إعادة التوجيه إلى التطبيق إذا كان مثبتًا.
dynamicLinkDomain (سلسلة|غير محددة) لتعيين مجال الرابط الديناميكي (أو المجال الفرعي) لاستخدامه للارتباط الحالي إذا كان سيتم فتحه باستخدام Firebase Dynamic Links. نظرًا لأنه يمكن تكوين مجالات الارتباط الديناميكي المتعددة لكل مشروع، فإن هذا الحقل يوفر القدرة على اختيار مجال واحد بشكل صريح. إذا لم يتم توفير أي مجال، فسيتم استخدام المجال الأقدم بشكل افتراضي.

يوضح المثال التالي كيفية إرسال رابط التحقق من البريد الإلكتروني الذي سيتم فتحه في تطبيق جوال أولاً كرابط ديناميكي لـ Firebase (تطبيق Apple com.example.ios أو تطبيق Android com.example.android حيث سيتم تثبيت التطبيق إذا لم يكن مثبتًا بالفعل و الحد الأدنى للإصدار هو 12). سيحتوي الرابط العميق على حمولة عنوان URL للمتابعة https://www.example.com/checkout?cartId=1234 . نطاق الارتباط الديناميكي المستخدم هو coolapp.page.link ، والذي يجب تهيئته للاستخدام مع Firebase Dynamic Links.

Node.js

const actionCodeSettings = {
  // URL you want to redirect back to. The domain (www.example.com) for
  // this URL must be whitelisted in the Firebase Console.
  url: 'https://www.example.com/checkout?cartId=1234',
  // This must be true for email link sign-in.
  handleCodeInApp: true,
  iOS: {
    bundleId: 'com.example.ios',
  },
  android: {
    packageName: 'com.example.android',
    installApp: true,
    minimumVersion: '12',
  },
  // FDL custom domain.
  dynamicLinkDomain: 'coolapp.page.link',
};

جافا

ActionCodeSettings actionCodeSettings = ActionCodeSettings.builder()
    .setUrl("https://www.example.com/checkout?cartId=1234")
    .setHandleCodeInApp(true)
    .setIosBundleId("com.example.ios")
    .setAndroidPackageName("com.example.android")
    .setAndroidInstallApp(true)
    .setAndroidMinimumVersion("12")
    .setDynamicLinkDomain("coolapp.page.link")
    .build();

بايثون

action_code_settings = auth.ActionCodeSettings(
    url='https://www.example.com/checkout?cartId=1234',
    handle_code_in_app=True,
    ios_bundle_id='com.example.ios',
    android_package_name='com.example.android',
    android_install_app=True,
    android_minimum_version='12',
    dynamic_link_domain='coolapp.page.link',
)

يذهب

actionCodeSettings := &auth.ActionCodeSettings{
	URL:                   "https://www.example.com/checkout?cartId=1234",
	HandleCodeInApp:       true,
	IOSBundleID:           "com.example.ios",
	AndroidPackageName:    "com.example.android",
	AndroidInstallApp:     true,
	AndroidMinimumVersion: "12",
	DynamicLinkDomain:     "coolapp.page.link",
}

ج #

var actionCodeSettings = new ActionCodeSettings()
{
    Url = "https://www.example.com/checkout?cartId=1234",
    HandleCodeInApp = true,
    IosBundleId = "com.example.ios",
    AndroidPackageName = "com.example.android",
    AndroidInstallApp = true,
    AndroidMinimumVersion = "12",
    DynamicLinkDomain = "coolapp.page.link",
};

لمعرفة المزيد، راجع تمرير الحالة في إجراءات البريد الإلكتروني .

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

Node.js

// Admin SDK API to generate the password reset link.
const userEmail = 'user@example.com';
getAuth()
  .generatePasswordResetLink(userEmail, actionCodeSettings)
  .then((link) => {
    // Construct password reset email template, embed the link and send
    // using custom SMTP server.
    return sendCustomPasswordResetEmail(userEmail, displayName, link);
  })
  .catch((error) => {
    // Some error occurred.
  });

جافا

String email = "user@example.com";
try {
  String link = FirebaseAuth.getInstance().generatePasswordResetLink(
      email, actionCodeSettings);
  // Construct email verification template, embed the link and send
  // using custom SMTP server.
  sendCustomEmail(email, displayName, link);
} catch (FirebaseAuthException e) {
  System.out.println("Error generating email link: " + e.getMessage());
}

بايثون

email = 'user@example.com'
link = auth.generate_password_reset_link(email, action_code_settings)
# Construct password reset email from a template embedding the link, and send
# using a custom SMTP server.
send_custom_email(email, link)

يذهب

email := "user@example.com"
link, err := client.PasswordResetLinkWithSettings(ctx, email, actionCodeSettings)
if err != nil {
	log.Fatalf("error generating email link: %v\n", err)
}

// Construct password reset template, embed the link and send
// using custom SMTP server.
sendCustomEmail(email, displayName, link)

ج #

var email = "user@example.com";
var link = await FirebaseAuth.DefaultInstance.GeneratePasswordResetLinkAsync(
    email, actionCodeSettings);
// Construct email verification template, embed the link and send
// using custom SMTP server.
SendCustomEmail(email, displayName, link);

بعد إنشاء الرابط، يمكن إدراجه في البريد الإلكتروني المخصص لإعادة تعيين كلمة المرور ثم إرساله عبر البريد الإلكتروني إلى المستخدم المقابل باستخدام خادم SMTP مخصص.

إذا كنت لا تستخدم الصفحة المقصودة الافتراضية لإعادة تعيين كلمة المرور وتقوم بإنشاء معالج مخصص خاص بك، فراجع إنشاء معالجات مخصصة لإجراءات البريد الإلكتروني .

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

Node.js

// Admin SDK API to generate the email verification link.
const useremail = 'user@example.com';
getAuth()
  .generateEmailVerificationLink(useremail, actionCodeSettings)
  .then((link) => {
    // Construct email verification template, embed the link and send
    // using custom SMTP server.
    return sendCustomVerificationEmail(useremail, displayName, link);
  })
  .catch((error) => {
    // Some error occurred.
  });

جافا

String email = "user@example.com";
try {
  String link = FirebaseAuth.getInstance().generateEmailVerificationLink(
      email, actionCodeSettings);
  // Construct email verification template, embed the link and send
  // using custom SMTP server.
  sendCustomEmail(email, displayName, link);
} catch (FirebaseAuthException e) {
  System.out.println("Error generating email link: " + e.getMessage());
}

بايثون

email = 'user@example.com'
link = auth.generate_email_verification_link(email, action_code_settings)
# Construct email from a template embedding the link, and send
# using a custom SMTP server.
send_custom_email(email, link)

يذهب

email := "user@example.com"
link, err := client.EmailVerificationLinkWithSettings(ctx, email, actionCodeSettings)
if err != nil {
	log.Fatalf("error generating email link: %v\n", err)
}

// Construct email verification template, embed the link and send
// using custom SMTP server.
sendCustomEmail(email, displayName, link)

ج #

var email = "user@example.com";
var link = await FirebaseAuth.DefaultInstance.GenerateEmailVerificationLinkAsync(
    email, actionCodeSettings);
// Construct email verification template, embed the link and send
// using custom SMTP server.
SendCustomEmail(email, displayName, link);

بعد إنشاء الرابط، يمكن إدراجه في رسالة التحقق المخصصة ثم إرساله بالبريد الإلكتروني إلى المستخدم المقابل باستخدام خادم SMTP مخصص.

إذا كنت لا تستخدم الصفحة المقصودة الافتراضية للتحقق من البريد الإلكتروني وتقوم بإنشاء معالج مخصص خاص بك، فراجع إنشاء معالجات مخصصة لإجراءات البريد الإلكتروني .

قبل أن تتمكن من مصادقة المستخدمين من خلال تسجيل الدخول عبر رابط البريد الإلكتروني، ستحتاج إلى تمكين تسجيل الدخول عبر رابط البريد الإلكتروني لمشروع Firebase الخاص بك.

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

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

Node.js

// Admin SDK API to generate the sign in with email link.
const useremail = 'user@example.com';
getAuth()
  .generateSignInWithEmailLink(useremail, actionCodeSettings)
  .then((link) => {
    // Construct sign-in with email link template, embed the link and
    // send using custom SMTP server.
    return sendSignInEmail(useremail, displayName, link);
  })
  .catch((error) => {
    // Some error occurred.
  });

جافا

String email = "user@example.com";
try {
  String link = FirebaseAuth.getInstance().generateSignInWithEmailLink(
      email, actionCodeSettings);
  // Construct email verification template, embed the link and send
  // using custom SMTP server.
  sendCustomEmail(email, displayName, link);
} catch (FirebaseAuthException e) {
  System.out.println("Error generating email link: " + e.getMessage());
}

بايثون

email = 'user@example.com'
link = auth.generate_sign_in_with_email_link(email, action_code_settings)
# Construct email from a template embedding the link, and send
# using a custom SMTP server.
send_custom_email(email, link)

يذهب

email := "user@example.com"
link, err := client.EmailSignInLink(ctx, email, actionCodeSettings)
if err != nil {
	log.Fatalf("error generating email link: %v\n", err)
}

// Construct sign-in with email link template, embed the link and send
// using custom SMTP server.
sendCustomEmail(email, displayName, link)

ج #

var email = "user@example.com";
var link = await FirebaseAuth.DefaultInstance.GenerateSignInWithEmailLinkAsync(
    email, actionCodeSettings);
// Construct email verification template, embed the link and send
// using custom SMTP server.
SendCustomEmail(email, displayName, link);

بعد إنشاء الرابط، يمكن إدراجه في البريد الإلكتروني المخصص لتسجيل الدخول ثم إرساله بالبريد الإلكتروني إلى المستخدم المقابل باستخدام خادم SMTP مخصص.

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