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

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

توفّر حِزم تطوير البرامج (SDK) الخاصة بالعميل في Firebase إمكانية إرسال رسائل إلكترونية إلى المستخدمين تتضمّن روابط يمكنهم استخدامها لإعادة ضبط كلمات المرور وإثبات ملكية عناوين البريد الإلكتروني وتسجيل الدخول باستخدام البريد الإلكتروني. ترسل Google هذه الرسائل الإلكترونية المستندة إلى نماذج، ولا يمكن تخصيصها إلا بشكل محدود.

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

وتتضمّن هذه الميزة المزايا التالية:

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

إعداد ActionCodeSettings

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

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

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

لإعداد مثيل ActionCodeSettings، قدِّم البيانات التالية:

المَعلمة النوع الوصف
url سلسلة

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

  • عندما تتم معالجة الرابط في أدوات الويب، يكون هذا هو الرابط لصفحة في التطبيق ضمن مَعلمة طلب البحث continueUrl.
  • عندما تتم معالجة الرابط في التطبيق مباشرةً، تكون هذه هي continueUrl مَعلمة طلب البحث في الرابط لصفحة معيّنة Hosting.
iOS ({bundleId: string}|undefined) تضبط هذه السمة معرّف حزمة iOS للمساعدة في تحديد ما إذا كان يجب إنشاء رابط مخصّص للويب فقط أو رابط متوافق مع الأجهزة الجوّالة يتم فتحه على جهاز Apple.Firebase Authentication
android ({packageName: string, installApp:boolean|undefined, minimumVersion: string|undefined}|undefined) تضبط هذه السمة اسم حزمة Android لمساعدة Firebase Authentication في تحديد ما إذا كان يجب إنشاء رابط مخصّص للويب فقط أو رابط متوافق مع الأجهزة الجوّالة يتم فتحه على جهاز Android.
handleCodeInApp (boolean|undefined) تحديد ما إذا كان سيتم فتح رابط إجراء الرسالة الإلكترونية في تطبيق على الجهاز الجوّال أو رابط ويب أولاً القيمة التلقائية هي "خطأ". عند ضبط هذه السمة على "صحيح"، سيتم إرسال رابط رمز الإجراء كرابط عام أو رابط تطبيق Android وسيتم فتحه من خلال التطبيق إذا كان مثبّتًا. في الحالة غير الصحيحة، سيتم إرسال الرمز إلى التطبيق المصغّر على الويب أولاً، ثم ستتم إعادة التوجيه إلى التطبيق عند المتابعة إذا كان مثبّتًا.
linkDomain (string|undefined) عند تحديد نطاقات مخصّصة لروابط الاستضافة في أحد المشاريع، حدِّد النطاق الذي تريد استخدامه عندما يفتح تطبيق جوّال محدّد الرابط، وإلا سيتم تلقائيًا اختيار النطاق التلقائي (مثلاً، PROJECT_ID.firebaseapp.com).
dynamicLinkDomain (string|undefined) تمّ الإيقاف. لا تحدّد هذه المَعلمة.

يوضّح المثال التالي كيفية إرسال رابط تأكيد عنوان البريد الإلكتروني الذي سيتم فتحه أولاً في تطبيق على الجهاز الجوّال. سيحتوي الرابط لصفحة معيّنة في التطبيق على حمولة https://www.example.com/checkout?cartId=1234 الخاصة بعنوان URL للمتابعة. نطاق رابط Hosting المخصّص المستخدَم هو custom-domain.com، ويجب إعداده لاستخدامه مع Firebase Hosting.

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',
  },
  // The domain must be configured in Firebase Hosting and owned by the project.
  linkDomain: 'custom-domain.com',
};

Java

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();

Python

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',
)

Go

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",
}

#C

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.
  });

Java

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());
}

Python

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)

Go

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)

#C

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.
  });

Java

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());
}

Python

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)

Go

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)

#C

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.
  });

Java

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());
}

Python

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)

Go

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)

#C

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 من خلال روابط الرسائل الإلكترونية سيساعد ذلك في تقديم معلومات حول كيفية إكمال عملية تسجيل الدخول بعد أن ينقر المستخدم على الرابط وتتم إعادة توجيهه إلى التطبيق.