Flutter SDK Initialization

The Magify Flutter SDK is initialized through a single call: MagifyClient.instance.init(MagifyConfig config).

Creating the client

Build a MagifyConfig and pass it to init, typically before runApp:

import 'package:flutter/widgets.dart';
import 'package:magify_flutter_sdk/magify_sdk.dart';

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

  await MagifyClient.instance.init(
    const MagifyConfig(
      applicationName: 'MyApplication',
      defaultConfig: 'assets/magify_default_config.json',
      isSandbox: false,
    ),
  );

  runApp(const MyApp());
}

init creates the client and waits until it is ready to use. Every other member of MagifyClient.instance — analytics, purchases, features, content, and so on — requires init to have completed first.

Calling init more than once

Calling init again is safe. Concurrent and later calls return the Future of the first call and do not create a second client instance — the config passed to those later calls is simply ignored. This means you can safely call init from more than one widget/provider/controller without coordinating who calls it first.

A failed call is not cached: if initialization fails, the next call to init retries from scratch with the config given at that call.

Checking initialization state

if (MagifyClient.instance.isInitialized) {
  // safe to call any other member
}

isInitialized is a synchronous getter. It becomes true only after init has completed successfully.

Handling errors

init throws MagifyException when initialization fails (for example, an unreadable or malformed configuration asset):

try {
  await MagifyClient.instance.init(config);
} on MagifyException catch (e) {
  // e.code, e.message, e.details
}

Because a failed call isn't cached, you can retry init — for example after checking connectivity or falling back to a different defaultConfig asset — without restarting the app.

The MagifyConfig shape

At minimum, MagifyConfig needs an isSandbox flag, plus an applicationName and a defaultConfig asset key resolvable for the platform the app runs on — either set here, or via the platform's ios/android section (see Per-platform overrides):

const MagifyConfig({
  String? applicationName,
  String? defaultConfig,
  required bool isSandbox,
  String? clientId,
  MagifyIosConfig ios = const MagifyIosConfig(),
  MagifyAndroidConfig android = const MagifyAndroidConfig(),
});

init throws ArgumentError synchronously if applicationName or defaultConfig cannot be resolved for the running platform.

A more complete example, overriding settings per platform:

await MagifyClient.instance.init(
  MagifyConfig(
    applicationName: 'Example iOS',
    defaultConfig: 'assets/Magify-Config.json',
    isSandbox: isSandbox,
    clientId: clientId,
    android: const MagifyAndroidConfig(
      applicationName: 'example-android',
      defaultConfig: 'assets/default-config.json',
    ),
    ios: const MagifyIosConfig(
      applicationName: 'Example iOS',
      defaultConfig: 'assets/Magify-Config.json',
    ),
  ),
);

See Configuration options for what each field does.

Next step

Continue to Configuration options for the full field reference.