initialize static method

Future<void> initialize({ String? androidLicenseKey, String? iosLicenseKey, String? webLicenseKey, @Deprecated('Register a controller type with Nutrient.addAdapterClass<T>() and select ' 'it via NutrientDocumentView<T> instead. Will be removed in a future ' 'release.') NutrientPlatformAdapter? androidAdapter, @Deprecated('Register a controller type with Nutrient.addAdapterClass<T>() and select ' 'it via NutrientDocumentView<T> instead. Will be removed in a future ' 'release.') NutrientPlatformAdapter? iosAdapter, @Deprecated('Register a controller type with Nutrient.addAdapterClass<T>() and select ' 'it via NutrientDocumentView<T> instead. Will be removed in a future ' 'release.') NutrientPlatformAdapter? webAdapter, })

Initialize the Nutrient SDK.

Must be called before using NutrientView or accessing adapters.

License Keys: License keys are optional. If not provided or set to null, the SDK will run in trial mode with watermarks.

Platform Adapters: Adapters are also optional. When you don't pass one for the current platform, the SDK registers its built-in default adapter, which gives you the full default viewer. Pass a custom adapter only when you need to customize the viewer or reach platform-specific APIs. The simplest possible setup is therefore just:

await Nutrient.initialize();
// ... then use NutrientDocumentView(documentPath: ...)

Trial Mode (no license key):

await Nutrient.initialize(
  androidLicenseKey: null,
  iosLicenseKey: null,
  webLicenseKey: null,
);

Single Platform Example:

// For Android only
await Nutrient.initialize(
  androidLicenseKey: 'YOUR_ANDROID_KEY',
);

Multi-Platform Example:

await Nutrient.initialize(
  androidLicenseKey: 'YOUR_ANDROID_KEY',
  iosLicenseKey: 'YOUR_IOS_KEY',
  webLicenseKey: 'YOUR_WEB_KEY',
);

Custom controllers (preferred): register a controller type once, then select it per view — each NutrientDocumentView<T> builds a fresh instance:

await Nutrient.initialize(androidLicenseKey: 'YOUR_ANDROID_KEY');
Nutrient.addAdapterClass<MyController>(() => createMyAdapter());
// …later: NutrientDocumentView<MyController>(documentPath: '…')

The androidAdapter / iosAdapter / webAdapter parameters are deprecated: they register one process-shared adapter per platform. Prefer addAdapterClass + NutrientDocumentView<T> (or pass a per-view adapter:) so views don't share controller state. The parameters still work during the deprecation window and will be removed in a future release.

Throws StateError if already initialized.

Implementation

static Future<void> initialize({
  String? androidLicenseKey,
  String? iosLicenseKey,
  String? webLicenseKey,
  @Deprecated(
    'Register a controller type with Nutrient.addAdapterClass<T>() and select '
    'it via NutrientDocumentView<T> instead. Will be removed in a future '
    'release.',
  )
  NutrientPlatformAdapter? androidAdapter,
  @Deprecated(
    'Register a controller type with Nutrient.addAdapterClass<T>() and select '
    'it via NutrientDocumentView<T> instead. Will be removed in a future '
    'release.',
  )
  NutrientPlatformAdapter? iosAdapter,
  @Deprecated(
    'Register a controller type with Nutrient.addAdapterClass<T>() and select '
    'it via NutrientDocumentView<T> instead. Will be removed in a future '
    'release.',
  )
  NutrientPlatformAdapter? webAdapter,
}) async {
  if (_initialized) {
    throw StateError(
      'Nutrient has already been initialized. '
      'Call Nutrient.initialize() only once.',
    );
  }

  // License keys are optional - if null/empty, SDK runs in trial mode
  _androidLicenseKey = androidLicenseKey;
  _iosLicenseKey = iosLicenseKey;
  _webLicenseKey = webLicenseKey;

  _androidAdapter = androidAdapter;
  _iosAdapter = iosAdapter;
  _webAdapter = webAdapter;
  _initialized = true;

  // Adapters are only required when you want to customize the viewer. When
  // the caller didn't pass one for the current platform, fall back to the
  // SDK's built-in default adapter so `NutrientDocumentView` works out of the
  // box.
  _ensureDefaultAdapterForCurrentPlatform();

  // Activate the native license. This is an SDK-global, stateless step owned
  // by the platform implementation — independent of any per-view adapter.
  // Android licenses the SDK and iOS sets the license key (both must run
  // before any document opens); web no-ops and injects the key per-load.
  final platform = NutrientFlutterPlatform.instance;
  if (platform != null) {
    await platform.activateLicense(currentLicenseKey);
  } else if (currentLicenseKey != null && currentLicenseKey!.isNotEmpty) {
    // A key was provided but no platform implementation is registered — the
    // SDK would silently run in trial mode. Surface it rather than fail
    // quietly.
    debugPrint(
      '[Nutrient.initialize] A license key was provided for '
      '$defaultTargetPlatform but no platform implementation is registered, '
      'so the license cannot be activated — the SDK will run in trial mode.',
    );
  }
}