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

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

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

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

في ما يلي مزايا ذلك:

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

إعداد ActionCodeSettings

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

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

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

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

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

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

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

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

متابعة

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)

متابعة

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