Configuration

Introduction#

The magic_deeplink plugin is configured via a single Dart file at lib/config/deeplink.dart in your consumer project. This file is generated automatically when you run the install command, and contains all values required for both runtime deep link handling and server-side asset file generation.

dart run <app>:artisan deeplink:install

The install command scaffolds lib/config/deeplink.dart with placeholder values. Replace the placeholders with your real credentials before running your app or generating server-side files.

The Deeplink Config File#

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

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

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

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

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

Register it with Magic.init() alongside your other config factories:

await Magic.init(
  configFactories: [
    appConfig,
    deeplinkConfig,
  ],
);

Driver Selection#

The 'driver' key determines which platform abstraction is used to receive incoming links. Currently, only one driver is available:

'driver': 'app_links',

DeeplinkServiceProvider.boot() reads this value and instantiates the matching driver. If the value does not match a known driver, no driver is registered and deep links will not be handled. The provider goes on to check driver.isSupported before wiring anything further: on web, AppLinksDriver.isSupported is false (the browser has no Universal Link / App Link mechanism for it to wrap), so no driver is set on the manager and no link subscription is created there, even though 'driver': 'app_links' is still the correct config value on every platform.

iOS Configuration#

iOS Universal Links require an apple-app-site-association (AASA) file hosted at your domain. The ios block provides the values needed to generate that file.

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

The AASA the generator writes uses Apple's modern appIDs + components shape (TN3155), with each app identifier constructed as TEAM_ID.BUNDLE_ID. There is no apps key and no legacy appID + paths entry: Apple's own guidance warns that mixing the two schemas may produce unexpected behaviour for universal links.

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

Android Configuration#

Android App Links require an assetlinks.json file hosted at your domain. The android block provides the values needed to generate that file.

'android': {
  'package_name': 'com.example.app',
  'sha256_fingerprints': [
    'AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99',
  ],
},

To retrieve the SHA-256 fingerprint for your keystore:

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

Each fingerprint produces a separate entry in assetlinks.json. Supply multiple fingerprints when you need to support several signing configurations (e.g. debug, release, CI):

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

Paths#

The paths array controls which URL paths your app claims to handle. This value is used in both the iOS apple-app-site-association and to filter which URIs the runtime driver passes to your handlers.

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

The default '/*' matches all paths under your domain. You can restrict this to specific prefixes:

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

Accessing Configuration Values#

At runtime, all values are accessible via the Config facade using dot notation with the deeplink namespace:

// Check whether deep linking is enabled
final enabled = Config.get<bool>('deeplink.enabled', true);

// Get the active driver name
final driver = Config.get<String>('deeplink.driver');

// Get the domain
final domain = Config.get<String>('deeplink.domain');

// Get the iOS team ID
final teamId = Config.get<String>('deeplink.ios.team_id');

// Get the Android package name
final packageName = Config.get<String>('deeplink.android.package_name');

The DeeplinkServiceProvider passes the entire deeplink map to the driver's initialize() method during boot():

await driver.initialize(config.get('deeplink') ?? {});

CLI Generate Command#

The generate command reads lib/config/deeplink.dart automatically and uses your config values to produce the server-side asset files. CLI flags override config file values when both are present.

dart run <app>:artisan deeplink:generate --output ./public

This creates two files in the specified output directory:

You can override individual values without editing the config file using CLI flags:

dart run <app>:artisan deeplink:generate \
  --output ./public \
  --team-id ABCDE12345 \
  --bundle-id com.example.app \
  --package-name com.example.app \
  --sha256-fingerprints AA:BB:CC:... \
  --paths /app/* \
  --paths /invite/*