Skip to main content

Dynamic Links

To start using the Dynamic Links package within your project, import it at the top of your project files:

import 'package:firebase_dynamic_links/firebase_dynamic_links.dart';

Before using Dynamic Links, you must first have ensured you have initialized FlutterFire.

To create a new Dynamic Links instance, call the instance getter on FirebaseDynamicLinks:

FirebaseDynamicLinks dynamicLinks = FirebaseDynamicLinks.instance;

By default, this allows you to interact with Dynamic Links using the default Firebase App used whilst installing FlutterFire on your platform.

On Android, if you'd like to use Dynamic Links with a secondary Firebase App, use the instanceFor method:

// Android only
FirebaseApp secondaryApp = Firebase.app('SecondaryApp');
FirebaseDynamicLinks dynamicLinks = FirebaseDynamicLinks.instanceFor(app: secondaryApp);

Setting up a prefix#

Before using Dynamic Links, ensure you have first created a new link prefix on the Firebase Console.

For example, the my-awesome-app.page.link has been added on this project:

Setting up a prefix
Setting up a prefix

Create a Dynamic Link#

A dynamic link can be created directly from the Firebase Console, or programmatically via the firebase_dynamic_links plugin. Once a link has been created, you can use send them to users (via emails, push notifications, in-app content etc.). Upon opening, your application can handle the link however you like, for example opening a specific screen.

Build Dynamic Link#

To build a Dynamic Link, use the FirebaseDynamicLinks.buildLink API in your application code like so:

final DynamicLinkParameters parameters = DynamicLinkParameters(
// The Dynamic Link URI domain. You can view created URIs on your Firebase console
uriPrefix: 'https://my-awesome-app.page.link',
// The deep Link passed to your application which you can use to affect change
link: Uri.parse('https://www.example.com/view-to-open'),
// Android application details needed for opening correct app on device/Play Store
androidParameters: const AndroidParameters(
packageName: androidPackageName,
minimumVersion: 1,
),
// iOS application details needed for opening correct app on device/App Store
iosParameters: const IOSParameters(
bundleId: iosBundleId,
minimumVersion: '2',
),
);
final Uri uri = await dynamicLinks.buildLink(parameters);

The method accepts a DynamicLinkParameters instance, which at a minimum requires a uriPrefix (defined in the Firebase Console), along with a link, which is passed to your application when a user opens the app via a created link.

Build Short Dynamic Link#

You can also build a short Dynamic Link which simply makes the Dynamic Link URL shorter. This does entail an additional native SDK request to the Firebase server whilst the above buildLink() does not. To build a short Dynamic Link, use the FirebaseDynamicLinks.buildShortLink API in your application code like so:

final DynamicLinkParameters parameters = DynamicLinkParameters(
// The Dynamic Link URI domain. You can view created URIs on your Firebase console
uriPrefix: 'https://example.page.link',
// The deep Link passed to your application which you can use to affect change
link: Uri.parse('https://www.example.com/view-to-open'),
// Android application details needed for opening correct app on device/Play Store
androidParameters: const AndroidParameters(
packageName: androidPackageName,
minimumVersion: 1,
),
// iOS application details needed for opening correct app on device/App Store
iosParameters: const IOSParameters(
bundleId: iosBundleId,
minimumVersion: '2',
),
);
final ShortDynamicLink shortDynamicLink = await FirebaseDynamicLinks.instance.buildShortLink(parameters);
final Uri uri = shortDynamicLink.shortUrl;

Handling Dynamic Links#

To handle a Dynamic Link in your application, two scenarios require implementing.

Terminated State#

If the application is terminated, the FirebaseDynamicLinks.getInitialLink method allows you to retrieve the Dynamic Link that opened the application.

This is an asynchronous request, so it makes sense to handle a link before rendering application logic, such as a navigator. For example, you could handle this in the main function:

Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
await Firebase.initializeApp(options: DefaultFirebaseConfig.platformOptions);
// Get any initial links
final PendingDynamicLinkData? initialLink = await FirebaseDynamicLinks.instance.getInitialLink();
runApp(MyApp(initialLink));
}

Within your application logic, you can then check whether a link was handled and perform an action, for example:

if (initialLink != null) {
final Uri deepLink = initialLink.link;
// Example of using the dynamic link to push the user to a different screen
Navigator.pushNamed(context, deepLink.path);
}

Alternatively, if you wish to identify if an exact Dynamic Link was used to open the application, pass it to the getDynamicLink method instead:

String link = 'https://dynamic-link-domain/ke2Qa';
final PendingDynamicLinkData? initialLink = await FirebaseDynamicLinks.instance.getDynamicLink(Uri.parse(link));

Background / Foreground State#

Whilst the application is open, or in the background, you may listen to Dynamic Links events using a stream handler. The FirebaseDynamicLinks.onLink getter returns a Stream containing a PendingDynamicLinkData:

FirebaseDynamicLinks.instance.onLink.listen((dynamicLinkData) {
Navigator.pushNamed(context, dynamicLinkData.link.path);
}).onError((error) {
// Handle errors
});