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

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

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

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

ويحقق هذا الإجراء المزايا التالية:

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

إعداد ActionCodeSettings

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

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

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

لإعداد مثيل ActionCodeSettings، يُرجى تقديم البيانات التالية:

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

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

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

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

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',
};

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