D.7 State in Email Actions

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.

⭐ To use ActionCodeSettings, your app must have Firebase Dynamic Links enabled and ready: https://github.com/myflashlab/Firebase-ANE/wiki/I.1-Add-Dynamic-links

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 iOS 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.

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 OAuth redirect domains if it is not already there.

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

Parameter	type	Description
url	String	Sets the link (state/continue URL) which has different meanings in different contexts: 1. When the link is handled in the web action widgets, this is the deep link in the continueUrl query parameter. 2. When the link is handled in the app directly, this is the continueUrl query parameter in the deep link of the Dynamic Link.
iOSBundleID	String	Sets the iOS bundle ID. This will try to open the link in an iOS app if it is installed. The iOS app needs to be registered in the Console.
androidPackageName	String	Sets the Android package name. This will try to open the link in an android app if it is installed.
androidInstallIfNotAvailable	Boolean	specifies whether to install the Android app if the device supports it and the app is not already installed. If this field is provided without a packageName, an error is thrown explaining that the packageName must be provided in conjunction with this field.
androidMinVersion	String	The minimum version of the app that is supported in this flow. If minimumVersion is specified, and an older version of the app is installed, the user is taken to the Play Store to upgrade the app. The Android app needs to be registered in the Console.
handleCodeInApp	Boolean	Whether the email action link will be opened in a mobile app or a web link first. The default is false. When set to true, the action code link will be be sent as a Universal Link or Android App Link and will be opened by the app if installed. In the false case, the code will be sent to the web widget first and then on continue will redirect to the app if installed.

The following example illustrates how to send an email verification link that will open in a mobile app first as a Firebase Dynamic 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.

// get the user's email
var userEmail:String = FirebaseUser.email;

// build the continueUrl
var url:String = "https://www.example.com/?email=" + userEmail;

// pass the continueUrl to ActionCodeSettings
var settings:ActionCodeSettings = new ActionCodeSettings(url);
settings.dynamicLinkDomain = "yourURLPrefix.page.link";
settings.handleCodeInApp = true;
settings.androidPackageName = "air.com.example.app"; // if not manually set, it will be set automatically
settings.androidInstallIfNotAvailable = true;
settings.androidMinVersion = "12";
settings.iOSBundleID = "com.example.app"; // if not manually set, it will be set automatically

FirebaseUser.listener.addEventListener(FirebaseUserEvents.SEND_EMAIL_VERIFICATION_RESULT, onSendEmailVerification);
FirebaseUser.sendEmailVerification(settings);

function onSendEmailVerification(e:FirebaseUserEvents):void
{
	if(e.result == Auth.RESULT_SUCCESS)
	{
		trace("onSendEmailVerification successful");
	}
	else
	{
		trace("onSendEmailVerification: " + e.msg);
	}
}