Truyền trạng thái trong các thao tác trên email

Bạn có thể truyền trạng thái thông qua URL tiếp nối khi gửi các hành động qua email để đặt lại mật khẩu hoặc xác minh email của người dùng. Điều này 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 có xử lý đường liên kết hành động qua email trực tiếp từ một ứng dụng di động khi ứng dụng đó được cài đặt hay không, thay vì xử lý từ một trang web.

Điều này có thể cực kỳ hữu ích trong các trường hợp phổ biến sau:

  • Một người dùng chưa đăng nhập có thể đang cố gắng truy cập vào nội dung yêu cầu người dùng phải đăng nhập. Tuy nhiên, người dùng có thể đã quên mật khẩu và do đó kích hoạt quy trình đặt lại mật khẩu. Khi kết thúc quy trình, người dùng mong muốn quay lại phần của ứng dụng mà họ đang cố gắng truy cập.

  • Một ứng dụng chỉ có thể cho phép truy cập vào các tài khoản đã xác minh. Ví dụ: một ứng dụng bản tin có thể yêu cầu người dùng xác minh email của họ trước khi đăng ký. Người dùng sẽ trải qua quy trình xác minh email và mong muốn được quay lại ứng dụng để hoàn tất việc đăng ký.

  • Nói chung, khi người dùng bắt đầu quy trình đặt lại mật khẩu hoặc xác minh email trên một ứng dụng của Apple, họ mong muốn hoàn tất quy trình trong ứng dụng đó. Khả năng truyền trạng thái thông qua URL tiếp nối giúp thực hiện được điều này.

Khả năng truyền trạng thái thông qua URL tiếp nối là một tính năng mạnh mẽ mà Firebase Xác thực cung cấp và có thể cải thiện đáng kể trải nghiệm người dùng.

Truyền trạng thái/URL tiếp nối trong các hành động qua email

Để truyền URL tiếp nối một cách an toàn, bạn cần đưa miền cho URL đó vào danh sách cho phép trong bảng điều khiển của Firebase. Bạn có thể thực hiện việc này trong phần Xác thực bằng cách thêm miền này vào danh sách Miền được uỷ quyền trong thẻ Phương thức đăng nhập nếu miền đó chưa có trong danh sách.

Bạn cần cung cấp một thực thể ActionCodeSettings khi gửi email đặt lại mật khẩu hoặc email xác minh. Giao diện này có các tham số sau:

Tham số Loại Mô tả
url Chuỗi

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

  • Khi đường liên kết được xử lý trong các 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.
iOSBundleId Chuỗi Đặt mã nhận dạng gói. Hệ thống sẽ cố gắng mở đường liên kết trong một ứng dụng của Apple nếu ứng dụng đó được cài đặt. Ứng dụng cần được đăng ký trong Play Console. Nếu không có Mã nhận dạng gói nào được cung cấp, thì giá trị của trường này sẽ được đặt thành mã nhận dạng gói của gói chính của Ứng dụng.
androidPackageName Chuỗi Đặt tên gói Android. Hệ thống sẽ cố gắng mở đường liên kết trong một ứng dụng Android nếu ứng dụng đó được cài đặt.
androidInstallApp bool Chỉ định có cài đặt ứng dụng Android hay không nếu thiết bị hỗ trợ và ứng dụng chưa được cài đặt. Nếu trường này được cung cấp mà không có packageName, thì một lỗi sẽ được gửi đi để giải thích rằng bạn phải cung cấp packageName cùng với trường này.
androidMinimumVersion Chuỗi Phiên bản tối thiểu của ứng dụng được hỗ trợ trong quy trình này. Nếu bạn chỉ định minimumVersion và cài đặt một phiên bản cũ hơn của ứng dụng, thì người dùng sẽ được đưa đến Cửa hàng Play để nâng cấp ứng dụng. Ứng dụng Android cần được đăng ký trong Play Console.
handleCodeInApp bool Đường liên kết hành động qua email sẽ được mở trong ứng dụng di động hay đường liên kết web trước tiên. Giá trị mặc định là "false". Khi được đặt thành true, đườ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 trong ứng dụng Android và sẽ được ứng dụng mở nếu được cài đặt. Trong trường hợp giá trị là false, mã sẽ được gửi đến tiện ích web trước tiên, sau đó khi tiếp tục, mã sẽ chuyển hướng đến ứng dụng nếu được cài đặt.
dynamicLinkDomain Chuỗi (Không dùng nữa, hãy sử dụng `linkDomain`) Đặt miền (hoặc miền con) của đường liên kết động để 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ì bạn có thể định cấu hình nhiều miền của đường 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 không có miền nào được cung cấp, thì miền đầu tiên được sử dụng theo mặc định. linkDomain Chuỗi Miền tuỳ chỉnh tuỳ chọn của Lưu trữ Firebase để sử dụng khi đường liên kết được mở thông qua một ứng dụng di động được chỉ định. Miền này phải được định cấu hình trong Lưu trữ Firebase và thuộc sở hữu của dự án. Đây không thể là miền Hosting mặc định (`web.app` hoặc `firebaseapp.com`). Miền này thay thế chế độ cài đặt `dynamicLinkDomain` không dùng nữa.

Ví dụ sau đây minh hoạ cách gửi một liên kết xác minh email sẽ mở trong một ứng dụng di động trước tiên dưới dạng Đường liên kết động của Firebase bằng miền tuỳ chỉnh của liên kết động example.page.link (ứng dụng iOS 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). Liên kết sâu sẽ chứa tải trọng URL tiếp nối https://www.example.com/?email=user@example.com.

final user = FirebaseAuth.instance.currentUser;

final actionCodeSettings = ActionCodeSettings(
  url: "http://www.example.com/verify?email=${user?.email}",
  iOSBundleId: "com.example.ios",
  androidPackageName: "com.example.android",
);

await user?.sendEmailVerification(actionCodeSettings);

Firebase Auth sử dụng Đường liên kết động của Firebase khi gửi một đường liên kết được dùng để mở trong một ứng dụng di động. Để sử dụng tính năng này, bạn cần định cấu hình Đường liên kết động trong bảng điều khiển Firebase.

  1. Bật Đường liên kết động của Firebase:

    1. Trong bảng điều khiển của Firebase, hãy mở phần Đường liên kết động.

    2. Nếu bạn chưa chấp nhận các điều khoản của Đường liên kết động và tạo miền của Đường liên kết động, hãy thực hiện ngay.

    3. Nếu bạn đã tạo một miền của Liên kết động, hãy lưu ý miền đó. Một miền của Đường liên kết động thường có dạng như ví dụ sau: 

      example.page.link

    4. Bạn sẽ cần giá trị này khi định cấu hình ứng dụng Apple hoặc Android để chặn đường liên kết đến.

  2. Định cấu hình ứng dụng Android:

    1. Nếu bạn dự định xử lý các đường liên kết này từ ứng dụng Android, thì bạn cần chỉ định tên gói Android trong phần cài đặt dự án của bảng điều khiển Firebase. Ngoài ra, bạn cần cung cấp SHA-1 và SHA-256 của chứng chỉ ứng dụng.
    2. Bạn cũng cần định cấu hình bộ lọc ý định cho đường liên kết sâu trong tệp AndroidManifest.xml.
    3. Để biết thêm thông tin về vấn đề này, hãy tham khảo hướng dẫn Nhận Đường liên kết động của Android.

  3. Định cấu hình ứng dụng Apple:

    1. Nếu bạn dự định xử lý các đường liên kết này từ ứng dụng, thì bạn cần chỉ định mã nhận dạng gói trong phần cài đặt dự án của bảng điều khiển Firebase. Ngoài ra, bạn cũng cần chỉ định mã nhận dạng trên App Store và mã nhóm nhà phát triển Apple.
    2. Bạn cũng cần định cấu hình miền của đường liên kết phổ quát FDL dưới dạng Miền được liên kết trong các chức năng của ứng dụng.
    3. Nếu bạn dự định phân phối ứng dụng của mình cho các phiên bản iOS 8 trở xuống, thì bạn cần đặt mã nhận dạng gói làm lược đồ tuỳ chỉnh cho các URL đến.
    4. Để biết thêm thông tin về vấn đề này, hãy tham khảo hướng dẫn Nhận Đường liên kết động của nền tảng Apple.

Xử lý các hành động qua email trong một ứng dụng web

Bạn có thể chỉ định có muốn xử lý đường liên kết mã hành động từ một ứng dụng web trước tiên hay không, sau đó chuyển hướng đến một trang web hoặc ứng dụng di động khác sau khi hoàn tất thành công, miễn là ứng dụng di động đó có sẵn. Bạn có thể thực hiện việc này bằng cách đặt handleCodeInApp thành false trong đối tượng ActionCodeSettings. Mặc dù không bắt buộc phải có mã nhận dạng gói hoặc tên gói Android, nhưng việc cung cấp các thông tin này sẽ cho phép người dùng chuyển hướng trở lại ứng dụng được chỉ định khi hoàn tất mã hành động qua email.

URL web được sử dụng ở đây là URL được định cấu hình trong phần mẫu hành động qua email. Một URL mặc định được cung cấp cho tất cả các dự án. Tham khảo bài viết Tuỳ chỉnh trình xử lý email để tìm hiểu thêm về cách tuỳ chỉnh trình xử lý hành động qua email.

Trong trường hợp này, đường liên kết trong tham số truy vấn continueURL sẽ là một đường liên kết FDL có tải trọng là URL được chỉ định trong đối tượng ActionCodeSettings. Mặc dù bạn có thể chặn và xử lý đường liên kết đến từ ứng dụng của mình mà không cần thêm bất kỳ phần phụ thuộc nào, nhưng bạn nên sử dụng thư viện ứng dụng FDL để phân tích cú pháp đường liên kết sâu cho bạn.

Khi xử lý các hành động qua email, chẳng hạn như xác minh email, bạn cần phân tích cú pháp mã hành động từ tham số truy vấn oobCode của đường liên kết sâu, sau đó áp dụng thông qua applyActionCode để thay đổi có hiệu lực, tức là email cần được xác minh.

Xử lý các hành động qua email trong một ứng dụng di động

Bạn có thể chỉ định có muốn xử lý đường liên kết mã hành động trong ứng dụng di động trước tiên hay không, miễn là ứng dụng đó được cài đặt. Đối với các ứng dụng Android, bạn cũng có thể chỉ định thông qua androidInstallApp rằng ứng dụng sẽ được cài đặt nếu thiết bị hỗ trợ và ứng dụng chưa được cài đặt. Nếu người dùng nhấp vào đường liên kết từ một thiết bị không hỗ trợ ứng dụng di động, thì đường liên kết đó sẽ được mở từ một trang web. Bạn có thể thực hiện việc này bằng cách đặt handleCodeInApp thành true trong đối tượng ActionCodeSettings. Bạn cũng cần chỉ định tên gói Android hoặc mã nhận dạng gói của ứng dụng di động.URL web dự phòng được sử dụng ở đây, khi không có ứng dụng di động nào, là URL được định cấu hình trong phần mẫu hành động qua email. Một URL mặc định được cung cấp cho tất cả các dự án. Tham khảo bài viết Tuỳ chỉnh trình xử lý email để tìm hiểu thêm về cách tuỳ chỉnh trình xử lý hành động qua email.

Trong trường hợp này, đường liên kết ứng dụng di động được gửi đến người dùng sẽ là một đường liên kết FDL có tải trọng là URL mã hành động, được định cấu hình trong Play Console, với các tham số truy vấn oobCode, mode, apiKey và continueUrl. Tham số sau sẽ là URL ban đầu được chỉ định trong đối tượng ActionCodeSettings. Mặc dù bạn có thể chặn và xử lý đường liên kết đến từ ứng dụng của mình mà không cần thêm bất kỳ phần phụ thuộc nào, nhưng bạn nên sử dụng thư viện ứng dụng FDL để phân tích cú pháp đường liên kết sâu cho bạn. Bạn có thể áp dụng mã hành động trực tiếp từ một ứng dụng di động tương tự như cách xử lý mã hành động từ quy trình web được mô tả trong phần tuỳ chỉnh trình xử lý email.

Khi xử lý các hành động qua email, chẳng hạn như xác minh email, bạn cần phân tích cú pháp mã hành động từ tham số truy vấn oobCode của đường liên kết sâu, sau đó áp dụng thông qua applyActionCode để thay đổi có hiệu lực, tức là email cần được xác minh.