產生電子郵件動作連結

行動應用程式有時需要與使用者互動，並透過電子郵件提示使用者採取特定動作。

Firebase 用戶端 SDK 可讓您傳送電子郵件給使用者，內含可用於重設密碼、驗證電子郵件地址，以及以電子郵件登入的連結。這些範本電子郵件由 Google 傳送，自訂功能有限。

如果您想改用自家的電子郵件範本和電子郵件傳送服務，請參閱本頁面，瞭解如何使用 Firebase Admin SDK，以程式輔助方式產生上述流程的動作連結，並將連結納入寄給使用者的電子郵件中。

這項做法具備下列優點：

• 自訂電子郵件範本。包括新增樣式和自訂品牌、變更文字和標誌、以使用者名字而非全名稱呼使用者等等。
• 根據內容套用不同的範本。舉例來說，如果使用者要驗證電子郵件地址才能訂閱電子報，您可能需要在電子郵件內容中提供相關資訊。另一個例子是電子郵件連結登入：在某種情況下，這可能會由同一位使用者觸發，或由其他使用者發出邀請。電子郵件中必須包含背景資訊。
• 將自訂電子郵件範本本地化。
• 能夠在安全的伺服器環境中產生連結。
• 能夠自訂連結的開啟方式 (透過行動應用程式或瀏覽器)，以及如何傳遞其他狀態資訊等。
• 在建構電子郵件動作連結時，能夠自訂用於行動應用程式流程的動態連結網域，甚至可以根據情境或行動應用程式指定不同的動態連結網域。

初始化 ActionCodeSettings

您可能需要先初始化 ActionCodeSettings 執行個體，才能產生電子郵件動作連結。

ActionCodeSettings 可讓您透過繼續網址傳遞其他狀態，使用者只要點選電子郵件連結，即可存取該網址。這也讓使用者可以在動作完成後返回應用程式。此外，您可以指定是否要直接從已安裝的行動應用程式或瀏覽器處理電子郵件動作連結。

如果是透過行動應用程式開啟的連結，您必須啟用 Firebase Dynamic Links，並執行一些任務，才能在行動應用程式中偵測這些連結。請參閱如何設定 Firebase Dynamic Links 的操作說明，瞭解如何處理電子郵件動作。

如要初始化 ActionCodeSettings 例項，請提供下列資料：

參數	類型	說明
url	字串	設定在不同情境中具有不同意義的連結 (狀態/繼續網址)： 如果連結是在網頁動作小工具中處理，則這是 continueUrl 查詢參數中的深層連結。 如果連結是直接在應用程式中處理，則這是動態連結深層連結中的 continueUrl 查詢參數。
iOS	({bundleId: string}|undefined)	設定軟體包 ID。系統會嘗試在已安裝的 Apple 應用程式中開啟連結。應用程式必須在控制台中註冊。
android	({packageName: string, installApp:boolean|undefined, minimumVersion: string|undefined}|undefined)	設定 Android 套件名稱。系統會嘗試在已安裝的 Android 應用程式中開啟連結。如果傳遞 installApp，則會在裝置支援 Android 應用程式且尚未安裝時，指定是否要安裝該應用程式。如果您在提供這個欄位時未附上 packageName，系統會擲回錯誤，說明必須與此欄位一併提供 packageName。如果指定 minimumVersion，且安裝舊版應用程式，使用者會被帶往 Play 商店升級應用程式。Android 應用程式必須在管理中心註冊。
handleCodeInApp	(布林值|未定義)	電子郵件動作連結是否會先在行動應用程式或網頁連結中開啟。預設值為 false。如果設為 True，系統會以通用連結或 Android 應用程式連結傳送動作碼連結，並在應用程式安裝後由應用程式開啟。在 false 的情況下，系統會先將程式碼傳送至網頁小工具，然後在繼續時會將您重新導向至已安裝的應用程式。
dynamicLinkDomain	(字串|未定義)	如果要使用 Firebase 動態連結開啟目前連結，則可設定要使用的動態連結網域 (或子網域)。每個專案可設定多個動態連結網域，因此這個欄位可讓您明確選擇其中一個網域。如果未提供任何網域，系統會預設使用最久的網域。

以下範例說明如何傳送電子郵件驗證連結，讓使用者先在行動應用程式中以 Firebase 動態連結的形式開啟 (Apple 應用程式 com.example.ios 或 Android 應用程式 com.example.android，如果應用程式尚未安裝，系統會安裝該應用程式，且最低版本為 12)。深層連結會包含繼續網址酬載 https://www.example.com/checkout?cartId=1234。使用的動態連結網域為 coolapp.page.link，必須設定為搭配 Firebase Dynamic Links 使用。

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

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",
    DynamicLinkDomain = "coolapp.page.link",
};

詳情請參閱「在電子郵件動作中傳遞狀態」。

產生密碼重設電子郵件連結

如要產生密碼重設連結，請提供現有使用者的電子郵件地址和選用的 ActionCodeSettings 物件。這項作業會透過電子郵件動作連結解決。使用的電子郵件必須屬於現有使用者。

Node.js

// Admin SDK API to generate the password reset link.
const userEmail = '[e-mail]';
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 = "[e-mail]";
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 = '[e-mail]'
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)

Go

email := "[e-mail]"
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 = "[e-mail]";
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 = '[e-mail]';
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 = "[e-mail]";
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 = '[e-mail]'
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 := "[e-mail]"
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 = "[e-mail]";
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 = '[e-mail]';
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 = "[e-mail]";
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 = '[e-mail]'
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)

Go

email := "[e-mail]"
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 = "[e-mail]";
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 驗證使用者。這有助於在使用者點選連結並重新導向至應用程式後，提供如何完成登入的相關資訊。