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

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

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

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

يوفّر لك ذلك المزايا التالية:

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

إعداد ActionCodeSettings

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

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

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

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

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

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

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

جافا

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

انتقال

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

جافا

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)

انتقال

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

جافا

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)

انتقال

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

جافا

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)

انتقال

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