Deep linking

The Mapp Engage Flutter plugin supports deep links delivered through push notifications and in-app interactions. Deep links let your app open a specific screen, route the user to relevant content, or trigger a defined navigation flow.

This guide explains how deep link delivery works and how to handle deep link callbacks in your Flutter app.

How deep linking works

When a push notification or in-app action contains a deep link, the SDK delivers that link through a callback handler. Your app is responsible for reading the delivered value and routing the user to the correct destination.

This means the SDK delivers the deep link, but your application controls the navigation behavior.

Assign the deep link callback

Use didReceiveDeepLinkWithIdentifier to listen for incoming deep links.

MappSdk.didReceiveDeepLinkWithIdentifier = (dynamic arguments) {
  final String url = arguments.toString();

  // Parse the URL and route the user
};

Assign this callback before calling MappSdk.engage(...) to avoid missing early events.

Initialize the callback before SDK startup

If your app handles deep links at launch time, define the callback before initializing the SDK.

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  MappSdk.didReceiveDeepLinkWithIdentifier = (dynamic arguments) {
    final String url = arguments.toString();
    print('Deep link received: $url');
  };

  await MappSdk.engage(
    'YOUR_SDK_KEY',
    'YOUR_GOOGLE_PROJECT_ID',
    SERVER.L3,
    'YOUR_APP_ID',
    'YOUR_TENANT_ID',
  );

  runApp(MyApp());
}

This helps ensure your app is ready to receive navigation-related events as early as possible.

Handle the delivered deep link

The callback payload is passed as dynamic. In most cases, you can convert it to a string and then parse it using your app's preferred routing approach.

MappSdk.didReceiveDeepLinkWithIdentifier = (dynamic arguments) {
  final String url = arguments.toString();

  // Example: route using your navigation layer
  // router.go(url);
};

You can integrate this with routing solutions such as Navigator, GoRouter, or any app-specific navigation service.

Handle custom link actions

In addition to standard deep links, the SDK can deliver custom link actions.

MappSdk.didReceiveCustomLinkWithIdentifier = (dynamic arguments) {
  print('Custom link received: $arguments');
};

Use this callback when your app needs to react to custom action payloads that are not handled as regular deep link URLs.

Use a central navigation layer

For maintainability, route deep links through a central navigation layer instead of handling navigation directly inside each callback.

This approach helps you:

• Keep SDK callbacks lightweight

• Apply consistent routing logic across the app

• Validate incoming links before navigation

• Reuse navigation handling for other deep link sources

Recommended deep link flow

1. Assign the deep link callback before SDK initialization

2. Initialize the SDK with MappSdk.engage(...)

3. Receive the deep link in the callback handler

4. Convert and validate the payload

5. Pass the result to your app's routing layer

This keeps link delivery and app navigation clearly separated.

Common mistakes

• Assigning the deep link callback after SDK initialization

• Handling navigation logic directly in multiple callback locations

• Assuming the SDK performs app navigation automatically

• Not validating the delivered link before routing

Best practices

• Assign deep link callbacks before calling engage()

• Convert and validate callback payloads before navigation

• Use a central navigation layer for routing decisions

• Keep callback handlers focused on delivery, not UI orchestration

• Log incoming links during development to verify payload structure