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 của Firebase có khả năng gửi cho người dùng email chứa các đường liên kết mà họ có thể sử dụng để đặt lại mật khẩu, xác minh địa chỉ email và đăng nhập bằng email. Những email dựa trên mẫu này do Google gửi và có khả năng tuỳ chỉnh 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, trang này sẽ giải thích cách sử dụng SDK quản trị Firebase để tạo các đường liên kết hành động cho các luồng 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 các lợi ích sau:

  • Tuỳ chỉnh mẫu email. Điều này bao gồm khả năng thêm kiểu mới và thương hiệu tuỳ chỉnh, thay đổi nội dung và biểu trưng, gọi người dùng theo tên thay vì tên đầy đủ, v.v.
  • Áp dụng các mẫu khác nhau tuỳ thuộc vào ngữ 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 ngữ 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 chính người dùng kích hoạt hoặc dưới dạng lời mời của một người dùng khác. Bạn cần thêm ngữ 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êm thông tin trạng thái, v.v.
  • Khả năng tuỳ chỉnh miền đường liên kết động dùng cho luồng ứng dụng di động khi tạo đường liên kết hành động trong email, thậm chí chỉ định một miền đường liên kết động khác tuỳ thuộc vào ngữ cảnh hoặc ứng dụng di động.

Khởi chạy ActionCodeSettings

Trước khi có thể tạo đường liên kết hành động trong 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 việc xử lý đường liên kết hành động trong email ngay từ ứng dụng di động khi ứng dụng đó được cài đặt hoặc từ trình duyệt.

Đối với các đường liên kết được mở qua ứng dụng di động, bạn cần bật Đường liên kết động của Firebase và thực hiện một số thao tác để phát hiện các đường liên kết này từ ứ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 động của Firebase cho các hành động trong 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 (trạng thái/tiếp tục URL) có ý nghĩa khác nhau trong các ngữ cảnh:

  • Khi đường liên kết được xử lý trong tiện ích hành động 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 động.
iOS ({bundleId: string}|undefined) Đặt mã nhận dạng gói. Thao tác này sẽ cố gắng mở đường liên kết trong một ứng dụng của Apple nếu bạn đã cài đặt ứng dụng đó. Ứng dụng cần được đăng ký trong Console.
android ({packageName: string, installApp:boolean|undefined, minimumVersion: string|undefined}|undefined) Đặt tên gói Android. Thao tác này sẽ cố gắng mở đường liên kết trong một ứng dụng Android nếu bạn đã cài đặt ứng dụng đó. Nếu installApp được truyền, thì giá trị này sẽ chỉ định xem có cài đặt ứng dụng Android hay không nếu thiết bị hỗ trợ ứng dụng đó và ứng dụng chưa được cài đặt. Nếu bạn cung cấp trường này mà không có packageName, hệ thống sẽ gửi một lỗi giải thích rằng bạn phải cung cấp packageName cùng với trường này. Nếu bạn chỉ định minimumVersion và cài đặt phiên bản cũ của ứng dụng, người dùng sẽ được chuyển đến Cửa hàng Play để nâng cấp ứng dụng. Bạn cần đăng ký ứng dụng Android trong Console.
handleCodeInApp (boolean|undefined) Liệu đường liên kết hành động trong email sẽ được mở trong ứng dụng dành cho thiết bị di động hay đường liên kết web trước. Giá trị mặc định là false. Khi được đặt thành đúng, đường liên kết mã hành động sẽ được gửi dưới dạng Đường liên kết phổ quát hoặc Đường liên kết ứng dụng Android và sẽ được ứng dụng mở nếu được cài đặt. Trong trường hợp sai, mã sẽ được gửi đến tiện ích web trước, sau đó tiếp tục sẽ chuyển hướng đến ứng dụng nếu đã cài đặt.
dynamicLinkDomain (string|undefined) Đặt miền liên kết động (hoặc miền con) để sử dụng cho đường liên kết hiện tại nếu đường liên kết đó được mở bằng Đường liên kết động của Firebase. Vì có thể định cấu hình nhiều miền liên kết động cho mỗi dự án, nên trường này cho phép bạn chọn một miền một cách rõ ràng. Nếu bạn không cung cấp miền nào, thì miền cũ nhất sẽ được sử dụng theo mặc định.

Ví dụ sau đây minh hoạ cách gửi một đường liên kết xác minh qua email. Trước tiên, đường liên kết này sẽ mở trong ứng dụng di động dưới dạng Đường liên kết động Firebase (ứng dụng Apple com.example.ios hoặc ứng dụng Android com.example.android, trong đó ứng dụng sẽ cài đặt nếu chưa được cài đặt và phiên bản tối thiểu là 12). Đườ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 động được sử dụng là coolapp.page.link. Bạn phải định cấu hình miền này để sử dụng với Đường liên kết động của 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',
)

Tiến hành

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 Chuyển trạng thái trong Hành động 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ẽ được giải quyết bằng đường liên kết hành động trong email. Email được dùng phải thuộc về một người dùng hiện tại.

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)

Tiến hành

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 tạo, bạn có thể chèn đường liên kết này vào email đặt lại mật khẩu tuỳ chỉnh, sau đó gửi email đế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à 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 email tuỳ chỉnh.

Để tạo đường liên kết xác minh qua 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ẽ được phân giải bằng đường liên kết đến hành động gửi email. Email được dùng phải thuộc về một người dùng hiện tại.

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)

Tiến hành

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 tạo, bạn có thể chèn đường liên kết vào email xác minh tuỳ chỉnh, sau đó gửi email đế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 xác minh email mặc định và 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 email tuỳ chỉnh.

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 trong email, bạn cần phải bật tính năng đăng nhập bằng đường liên kết trong 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à đối tượng ActionCodeSettings. Đối tượng ActionCodeSettings là bắt buộc trong trường hợp này để cung cấp thông tin về nơi trả về người dùng sau khi nhấp vào đường liên kết để hoàn tất quy trình đăng nhập. Thao tác này sẽ phân giải bằng đường liên kết đến hành động qua email.

Không giống như tính năng đặt lại mật khẩu và xác minh email, email được sử 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ể được 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 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)

Tiến hành

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 tạo, bạn có thể chèn đường liên kết vào email đăng nhập tuỳ chỉnh rồi gửi email đến 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 trong 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.