Tạo đường liên kết hành động trong email

Đôi khi, ứng dụng di động cần tương tác với người dùng và nhắc họ thực hiện một số hành động nhất định bằng cách gửi email.

SDK ứng dụng Firebase cung cấp khả năng gửi email cho người dùng có chứa các đường liên kết mà họ có thể dùng để đặt lại mật khẩu, xác minh địa chỉ email và đăng nhập dựa trên email. Google gửi những email dựa trên mẫu này và bạn chỉ có thể tuỳ chỉnh ở mức độ hạn chế.

Nếu bạn muốn sử dụng mẫu email và dịch vụ gửi email của riêng mình, thì trang này sẽ giải thích cách sử dụng Firebase Admin SDK để tạo các đường liên kết đến hành động cho các quy trình trên theo phương thức lập trình. Bạn có thể đưa các đường liên kết này vào email gửi cho người dùng.

Điều này mang lại những lợi ích sau:

  • Tuỳ chỉnh mẫu email. Ví dụ: bạn có thể thêm kiểu mới và thương hiệu tuỳ chỉnh, thay đổi từ ngữ và biểu trưng, gọi người dùng bằng tên thay vì tên đầy đủ, v.v.
  • Áp dụng các mẫu khác nhau tuỳ thuộc vào bối cảnh. Ví dụ: nếu người dùng đang xác minh email để đăng ký nhận bản tin, thì bạn có thể cần cung cấp bối cảnh trong nội dung email. Một ví dụ khác là đăng nhập bằng đường liên kết trong email: trong một trường hợp, thao tác này có thể do cùng một người dùng kích hoạt hoặc do một người dùng khác mời. Bạn cần phải thêm bối cảnh vào email.
  • Bản địa hoá mẫu email tuỳ chỉnh.
  • Có thể tạo đường liên kết từ một môi trường máy chủ an toàn.
  • Khả năng tuỳ chỉnh cách mở đường liên kết, thông qua ứng dụng di động hoặc trình duyệt, cũng như cách truyền thông tin bổ sung về trạng thái, v.v.
  • Có thể tuỳ chỉnh miền đường liên kết trên thiết bị di động được dùng cho các luồng ứng dụng di động khi tạo đường liên kết hành động trong email.

Khởi chạy ActionCodeSettings

Trước khi có thể tạo đường liên kết đến thao tác qua email, bạn có thể cần khởi chạy một thực thể ActionCodeSettings.

ActionCodeSettings cho phép bạn truyền trạng thái bổ sung thông qua một URL tiếp tục mà người dùng có thể truy cập sau khi nhấp vào đường liên kết trong email. Điều này cũng giúp người dùng có thể quay lại ứng dụng sau khi hoàn tất hành động. Ngoài ra, bạn có thể chỉ định xem có xử lý đường liên kết thao tác qua email trực tiếp từ ứng dụng di động khi ứng dụng được cài đặt hay từ trình duyệt hay không.

Đối với những đường liên kết được mở thông qua ứng dụng di động, bạn cần thực hiện một số thao tác để phát hiện những đường liên kết này trong ứng dụng di động. Hãy tham khảo hướng dẫn về cách định cấu hình đường liên kết trên thiết bị di động cho các thao tác trên email.

Để khởi chạy một thực thể ActionCodeSettings, hãy cung cấp dữ liệu sau:

Thông số Loại Mô tả
url chuỗi

Đặt đường liên kết (URL trạng thái/tiếp tục) có ý nghĩa khác nhau trong các ngữ cảnh khác nhau:

  • Khi đường liên kết được xử lý trong các tiện ích thao tác trên web, đây là đường liên kết sâu trong tham số truy vấn continueUrl.
  • Khi đường liên kết được xử lý trực tiếp trong ứng dụng, đây là tham số truy vấn continueUrl trong đường liên kết sâu của đường liên kết Hosting.
iOS ({bundleId: string}|undefined) Đặt mã nhận dạng gói iOS để giúp Firebase Authentication xác định xem có nên tạo một đường liên kết chỉ dành cho web hay đường liên kết dành cho thiết bị di động được mở trên thiết bị Apple hay không
android ({packageName: string, installApp:boolean|undefined, minimumVersion: string|undefined}|undefined) Đặt tên gói Android để giúp Firebase Authentication xác định xem có nên tạo đường liên kết chỉ dành cho web hay đường liên kết dành cho thiết bị di động được mở trên thiết bị Android
handleCodeInApp (boolean|undefined) Đường liên kết đến thao tác trong email sẽ được mở trong ứng dụng di động hay đường liên kết trên web trước. Giá trị mặc định là false. Khi được đặt thành true, đường liên kết mã thao tác sẽ được gửi dưới dạng Đường liên kết phổ quát hoặc Đường liên kết đến ứng dụng Android và sẽ được ứng dụng mở nếu đã cài đặt. Trong trường hợp sai, mã sẽ được gửi đến tiện ích web trước, sau đó khi tiếp tục, mã sẽ chuyển hướng đến ứng dụng nếu đã cài đặt.
linkDomain (string|undefined) Khi bạn xác định các miền liên kết lưu trữ tuỳ chỉnh cho một dự án, hãy chỉ định miền nào sẽ dùng khi đường liên kết được mở bằng một ứng dụng di động cụ thể. Nếu không, miền mặc định sẽ tự động được chọn (ví dụ: PROJECT_ID.firebaseapp.com).
dynamicLinkDomain (string|undefined) Không dùng nữa. Không chỉ định tham số này.

Ví dụ sau đây minh hoạ cách gửi một đường liên kết xác minh email sẽ mở trong ứng dụng di động trước. Đường liên kết sâu sẽ chứa tải trọng URL tiếp tục https://www.example.com/checkout?cartId=1234. Miền liên kết Hosting tuỳ chỉnh được sử dụng là custom-domain.com, miền này phải được định cấu hình để sử dụng với 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',
)

Tìm

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

Để tìm hiểu thêm, hãy xem phần Truyền trạng thái trong các thao tác trên email.

Tạo đường liên kết đặt lại mật khẩu trong email

Để tạo đường liên kết đặt lại mật khẩu, hãy cung cấp email của người dùng hiện tại và một đối tượng ActionCodeSettings không bắt buộc. Thao tác này sẽ giải quyết bằng đường liên kết đến thao tác trong email. Email được dùng phải thuộc về một người dùng hiện có.

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)

Tìm

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

Sau khi được tạo, đường liên kết này có thể được chèn vào email đặt lại mật khẩu tuỳ chỉnh rồi gửi đến người dùng tương ứng bằng máy chủ SMTP tuỳ chỉnh.

Nếu bạn không sử dụng trang đích đặt lại mật khẩu mặc định và đang tạo trình xử lý tuỳ chỉnh của riêng mình, hãy xem phần tạo trình xử lý thao tác tuỳ chỉnh qua email.

Tạo đường liên kết xác minh email

Để tạo đường liên kết xác minh email, hãy cung cấp email chưa được xác minh của người dùng hiện tại và một đối tượng ActionCodeSettings không bắt buộc. Thao tác này sẽ phân giải bằng đường liên kết đến thao tác với email. Email được dùng phải thuộc về một người dùng hiện có.

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)

Tìm

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

Sau khi được tạo, đường liên kết này có thể được chèn vào email xác minh tuỳ chỉnh, sau đó được gửi qua email cho người dùng tương ứng bằng máy chủ SMTP tuỳ chỉnh.

Nếu bạn không sử dụng trang đích xác minh email mặc định và đang tạo trình xử lý tuỳ chỉnh của riêng mình, hãy xem phần tạo trình xử lý hành động tuỳ chỉnh cho email.

Tạo đường liên kết qua email để đăng nhập

Trước khi có thể xác thực người dùng bằng tính năng đăng nhập bằng đường liên kết qua email, bạn cần phải bật tính năng đăng nhập bằng đường liên kết qua email cho dự án Firebase của mình.

Để tạo đường liên kết đăng nhập, hãy cung cấp email của người dùng và một đối tượng ActionCodeSettings. Trong trường hợp này, bạn phải có đối tượng ActionCodeSettings để cung cấp thông tin về vị trí cần đưa người dùng quay lại sau khi họ nhấp vào đường liên kết để hoàn tất quá trình đăng nhập. Thao tác này sẽ phân giải bằng đường liên kết đến thao tác qua email.

Không giống như quy trình đặt lại mật khẩu và xác minh email, email được dùng không nhất thiết phải thuộc về một người dùng hiện tại, vì thao tác này có thể dùng để đăng ký người dùng mới vào ứng dụng của bạn thông qua đường liên kết trong email.

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)

Tìm

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

Sau khi được tạo, đường liên kết này có thể được chèn vào email đăng nhập tuỳ chỉnh, sau đó được gửi qua email cho người dùng tương ứng bằng máy chủ SMTP tuỳ chỉnh.

Tìm hiểu thêm về cách xác thực người dùng bằng Firebase thông qua đường liên kết qua email. Điều này sẽ giúp cung cấp thông tin về cách hoàn tất quy trình đăng nhập sau khi người dùng nhấp vào đường liên kết và được chuyển hướng trở lại ứng dụng.