Installation

Introduction#

magic_deeplink adds Universal Links (iOS) and App Links (Android) to your Magic application. It follows the same ServiceProvider + driver + handler pattern used throughout the framework, so it wires up in exactly the same way as every other Magic plugin.

Under the hood the package delegates all platform stream handling to app_links. There is no native Android or iOS code in this plugin — platform support lives entirely inside app_links.

Requirements#

• Dart SDK: 3.6.0 or higher
• Flutter: 3.27.0 or higher
• Magic Framework installed and bootstrapped (lib/config/app.dart present)

Installing the Package#

Add magic_deeplink to your Flutter project:

flutter pub add magic_deeplink

Or add it manually to pubspec.yaml:

dependencies:
  magic_deeplink: ^0.0.3

Then fetch dependencies:

flutter pub get

Running the Install Command#

Magic Deeplink ships its own CLI command. Run it from your project root to scaffold the configuration file and inject the provider automatically:

dart run magic_deeplink:install

The command performs the following steps:

1. Validates that lib/config/app.dart exists (Magic must be installed first).
2. Creates lib/config/deeplink.dart with sensible defaults.
3. Injects DeeplinkServiceProvider into the providers list in lib/config/app.dart.
4. Injects () => deeplinkConfig into the configFactories list in lib/main.dart.

dart run magic_deeplink:install --force

Registering the Service Provider#

If you ran dart run magic_deeplink:install, the provider was already injected. The relevant section of lib/config/app.dart will look like this:

import 'package:magic/magic.dart';
import 'package:magic_deeplink/magic_deeplink.dart'; // injected by install

final appConfig = {
  'app': {
    'name': Env.get('APP_NAME', 'My App'),
    'providers': [
      (app) => RouteServiceProvider(app),
      (app) => AppServiceProvider(app),
      (app) => DeeplinkServiceProvider(app), // injected by install
    ],
  },
};

Injecting the Config Factory#

The install command also adds the deeplink config factory to Magic.init() in lib/main.dart:

import 'package:flutter/material.dart';
import 'package:magic/magic.dart';
import 'config/app.dart';
import 'config/deeplink.dart'; // injected by install

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Magic.init(
    configFactories: [
      () => appConfig,
      () => deeplinkConfig, // injected by install
    ],
  );

  runApp(MagicApplication(title: 'My App'));
}

Configuration Reference#

The generated lib/config/deeplink.dart looks like this out of the box:

Map<String, dynamic> get deeplinkConfig => {
  'deeplink': {
    'enabled': true,
    'driver': 'app_links',   // only supported driver
    'domain': 'example.com', // your Universal Link / App Link domain
    'scheme': 'https',

    'ios': {
      'team_id': 'YOUR_TEAM_ID',     // Apple Developer Team ID
      'bundle_id': 'com.example.app', // app bundle identifier
    },

    'android': {
      'package_name': 'com.example.app',
      'sha256_fingerprints': [
        'YOUR_SHA256_FINGERPRINT', // keystore SHA-256, colon-separated
      ],
    },

    'paths': [
      '/*', // path patterns handled as deep links
    ],
  },
};

Replace example.com, the team/bundle identifiers, and the SHA-256 fingerprint with your real values before deploying.

Next Steps#

Now that the plugin is installed and wired up:

• Configuration — Learn how to customise paths, schemes, and platform settings.
• Handlers — Add your own URI handlers with RouteDeeplinkHandler.
• CLI Tools — Use dart run magic_deeplink:generate to produce the Apple App Site Association and Android Asset Links files.