Configuration

Quick Reference#

The install command scaffolds the file with placeholder values (example.com, YOUR_TEAM_ID, com.example.app, YOUR_SHA256_FINGERPRINT); the doctor reports any that are left.

The Deeplink Config File#

lib/config/deeplink.dart exports one top-level getter that returns a nested Map<String, dynamic>:

Map<String, dynamic> get deeplinkConfig => {
  'deeplink': {
    'enabled': true,
    'driver': 'app_links',
    'domain': 'example.com',

    'ios': {
      'team_id': 'YOUR_TEAM_ID',
      'bundle_id': 'com.example.app',
    },

    'android': {
      'package_name': 'com.example.app',
      'sha256_fingerprints': [
        'YOUR_SHA256_FINGERPRINT',
      ],
    },

    'paths': [
      '/*',
    ],
  },
};

A 'scheme': 'https' entry in an older published config is read by nothing, so you can delete it.

lib/main.dart hands the getter to Magic.init as a factory:

import 'package:magic/magic.dart';

import 'config/app.dart';
import 'config/deeplink.dart'; // added by the install

Future<void> main() async {
  await Magic.init(
    configFactories: [
      () => appConfig,
      () => deeplinkConfig,
    ],
  );
}

Driver Selection#

The 'driver' key names the platform abstraction that receives incoming links:

DeeplinkServiceProvider.boot() creates AppLinksDriver for 'app_links' and nothing for any other value, so a different name wires no driver and no link subscription. The provider then checks driver.isSupported before wiring further: on web, Windows and Linux no driver is set on the manager and no subscription is created, and 'driver': 'app_links' stays the correct value on every platform. See Drivers.

iOS Configuration#

iOS Universal Links need an apple-app-site-association (AASA) file hosted at your domain. The ios block holds the values the generator needs:

The generator writes Apple's appIDs plus components shape, with the app identifier built as TEAM_ID.BUNDLE_ID and one components entry per path. It never writes the legacy appID plus paths entry or an apps key: mixing the two schemas may produce unexpected behaviour for universal links, and the doctor warns when a file does.

{
  "applinks": {
    "details": [
      {
        "appIDs": ["ABCDE12345.com.example.app"],
        "components": [
          { "/": "/*", "comment": "Matches any URL whose path matches /*" }
        ]
      }
    ]
  }
}

Android Configuration#

Android App Links need an assetlinks.json file hosted at your domain. The android block holds the values the generator needs:

keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android

Each fingerprint produces its own entry in assetlinks.json:

'sha256_fingerprints': [
  'AA:BB:CC:...', // debug keystore
  'DD:EE:FF:...', // release keystore
],

Paths#

paths is the list of URL path patterns written into the components of the iOS AASA file. It does not filter links at runtime: which paths your app routes is decided by the paths of the RouteDeeplinkHandler you register. See Handlers.

'paths': [
  '/app/*',
  '/invite/*',
  '/reset-password',
],

Accessing Configuration Values#

At runtime magic's Config facade reads every value with dot notation:

import 'package:magic/magic.dart';

final bool enabled = Config.get<bool>('deeplink.enabled', true) ?? true;
final String? domain = Config.get<String>('deeplink.domain');
final String? teamId = Config.get<String>('deeplink.ios.team_id');

DeeplinkServiceProvider passes the whole deeplink map to driver.initialize() during boot(). AppLinksDriver does not read it; a custom driver can.

Related Documentation#

• CLI: deeplink:generate reads these keys and deeplink:doctor validates them.
• Installation: the install command and the native setup.
• Drivers: what the driver key selects.
• Service Provider: how boot() reads enabled and driver.
• Configuration in Magic: config factories and dot notation.