Passing State in Email Actions

You can pass state via a continue URL when sending email actions for password resets or verifying a user's email. This provides the user the ability to be returned to the app after the action is completed. In addition, you can specify whether to handle the email action link directly from a mobile application when it is installed instead of a web page.

This can be extremely useful in the following common scenarios:

• A user, not currently logged in, may be trying to access content that requires the user to be signed in. However, the user might have forgotten their password and therefore trigger the reset password flow. At the end of the flow, the user expects to go back to the section of the app they were trying to access.

• An application may only offer access to verified accounts. For example, a newsletter app may require the user to verify their email before subscribing. The user would go through the email verification flow and expect to be returned to the app to complete their subscription.

• In general, when a user begins a password reset or email verification flow on an Apple app they expect to complete the flow within the app; the ability to pass state via continue URL makes this possible.

Having the ability to pass state via a continue URL is a powerful feature that Firebase Auth provides and which can significantly enhance the user experience.

Passing state/continue URL in email actions

In order to securely pass a continue URL, the domain for the URL will need to be whitelisted in the Firebase console. This is done in the Authentication section by adding this domain to the list of Authorized domains under the Sign-in method tab if it is not already there.

A FIRActionCodeSettings instance needs to be provided when sending a password reset email or a verification email. This interface takes the following parameters:

The following example illustrates how to send an email verification link that will open in a mobile app first as a Firebase Dynamic Link using the custom dynamic link domain example.page.link (iOS app com.example.ios or Android app com.example.android where the app will install if not already installed and the minimum version is 12). The deep link will contain the continue URL payload https://www.example.com/?email=user@example.com.

var actionCodeSettings =  ActionCodeSettings.init()
actionCodeSettings.canHandleInApp = true
let user = Auth.auth().currentUser()
actionCodeSettings.URL =
    String(format: "https://www.example.com/?email=%@", user.email)
actionCodeSettings.iOSbundleID = Bundle.main.bundleIdentifier!
actionCodeSettings.setAndroidPakageName("com.example.android",
                                         installIfNotAvailable:true,
                                         minimumVersion:"12")
// When multiple custom dynamic link domains are defined, specify which one to use.
actionCodeSettings.dynamicLinkDomain = "example.page.link"
user.sendEmailVerification(withActionCodeSettings:actionCodeSettings { error in
  if error {
    // Error occurred. Inspect error.code and handle error.
    return
  }
  // Email verification sent.
})

 FIRActionCodeSettings *actionCodeSettings = [[FIRActionCodeSettings alloc] init];
 actionCodeSettings.handleCodeInApp = YES;
 FIRUser *user = [FIRAuth auth].currentUser;
 NSString *urlString =
     [NSString stringWithFormat:@"https://www.example.com/?email=%@", user.email];
 actionCodeSettings.URL = [NSURL URLWithString:urlString];
 actionCodeSettings.iOSBundleID = [NSBundle mainBundle].bundleIdentifier;
 // When multiple custom dynamic link domains are defined, specify which one to use.
 actionCodeSettings.dynamicLinkDomain = @"example.page.link";
 [actionCodeSettings setAndroidPackageName:@"com.example.android"
                     installIfNotAvailable:YES
                            minimumVersion:'12'];
 [user sendEmailVerificationWithActionCodeSettings:actionCodeSettings
                                        completion:^(NSError *_Nullable error) {
   if (error) {
     // Error occurred. Inspect error.code and handle error.
     return;
   }
   // Email verification sent.
 }];

Configuring Firebase Dynamic Links

Firebase Auth uses Firebase Dynamic Links when sending a link that is meant to be opened in a mobile application. In order to use this feature, Dynamic Links need to be configured in the Firebase Console.

1. Enable Firebase Dynamic Links:

   1. In the Firebase console, open the Dynamic Links section.

   2. If you have not yet accepted the Dynamic Links terms and created a Dynamic Links domain, do so now.

      If you already created a Dynamic Links domain, take note of it. A Dynamic Links domain typically looks like the following example:

      example.page.link

      You will need this value when you configure your Apple or Android app to intercept the incoming link.

2. Configuring Android applications:

   1. If you plan on handling these links from your Android application, the Android package name needs to be specified in the Firebase Console project settings. In addition, the SHA-1 and SHA-256 of the application certificate need to be provided.
   2. You will also need to configure the intent filter for the deep link in you AndroidManifest.xml file.
   3. For more on this, refer to Receiving Android Dynamic Links instructions.

3. Configuring Apple applications:

   1. If you plan on handling these links from your application, the bundle ID needs to be specified in the Firebase Console project settings. In addition, the App Store ID and the Apple Developer Team ID also need to be specified.
   2. You will also need to configure the FDL universal link domain as an Associated Domain in your application capabilities.
   3. If you plan to distribute your application to iOS versions 8 and under, you will need to set your bundle ID as a custom scheme for incoming URLs.
   4. For more on this, refer to Receiving Apple platforms Dynamic Links instructions.

Handling email actions in a web application

You can specify whether you want to handle the action code link from a web application first and then redirect to another web page or mobile application after successful completion, provided the mobile application is available. This is done by setting handleCodeInApp to false in the FIRActionCodeSettings (Obj-C) or ActionCodeSettings (Swift) object. While a bundle ID or Android package name are not required, providing them will allow the user to redirect back to the specified app on email action code completion.

The web URL used here, is the one configured in the email action templates section. A default one is provisioned for all projects. Refer to customizing email handlers to learn more on how to customize the email action handler.

In this case, the link within the continueURL query parameter will be an FDL link whose payload is the URL specified in the ActionCodeSettings object. While you can intercept and handle the incoming link from your app without any additional dependency, we recommend using the FDL client library to parse the deep link for you.

When handling email actions such as email verification, the action code from the oobCode query parameter needs to be parsed from the deep link and then applied via applyActionCode for the change to take effect, i.e. email to be verified.

Handling email actions in a mobile application

You can specify whether you want to handle the action code link within your mobile application first, provided it is installed. With Android applications, you also have the ability to specify via the androidInstallIfNotAvailable that the app is to be installed if the device supports it and it is not already installed. If the link is clicked from a device that does not support the mobile application, it is opened from a web page instead. This is done by setting handleCodeInApp to true in the FIRActionCodeSettings (Obj-C) or ActionCodeSettings (Swift) object. The mobile application's Android package name or bundle ID will also need to be specified.The fallback web URL used here, when no mobile app is available, is the one configured in the email action templates section. A default one is provisioned for all projects. Refer to customizing email handlers to learn more on how to customize the email action handler.

In this case, the mobile app link sent to the user will be an FDL link whose payload is the action code URL, configured in the Console, with the query parameters oobCode, mode, apiKey and continueUrl. The latter will be the original URL specified in the FIRActionCodeSettings (Obj-C) or ActionCodeSettings (Swift) object. While you can intercept and handle the incoming link from your app without any additional dependency, we recommend using the FDL client library to parse the deep link for you. The action code can be applied directly from a mobile application similar to how it is handled from the web flow described in the customizing email handlers section.

When handling email actions such as email verification, the action code from the oobCode query parameter needs to be parsed from the deep link and then applied via applyActionCode for the change to take effect, i.e. email to be verified.