iOS

Set the deployment target to iOS 16.0

FlitzLoader requires iOS 16.0. The Flutter template targets an older version, and pod install or package resolution fails until you raise it in two places:

• In ios/Podfile, set the platform line (the template ships it commented out): platform :ios, '16.0'.
• In Xcode, set the Runner target's Minimum Deployments to 16.0 (IPHONEOS_DEPLOYMENT_TARGET = 16.0).

Add the dependency

platform :ios, '16.0'

source 'https://cdn.cocoapods.org/'
source 'https://dl.cloudsmith.io/basic/leancode/flitz/cocoapods/index.git'

target 'Runner' do
  use_frameworks! :linkage => :static
  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
  pod 'FlitzLoader', '<plugin-version>'
end

pod repo add flitz https://dl.cloudsmith.io/basic/leancode/flitz/cocoapods/index.git
pod install

Subclass the app delegate

In ios/Runner/AppDelegate.swift, extend BundleLoaderAppDelegate instead of FlutterAppDelegate, and register your plugins through its two hooks. Merge these lines into your existing delegate; do not replace the file.

import UIKit
import Flutter
import FlitzLoader

@main
@objc class AppDelegate: BundleLoaderAppDelegate {
    override func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        // … your existing launch setup …
        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
    }

    // Your app's own plugins, on the engine that renders your UI.
    override func registerHostPlugins(with engineBridge: FlutterImplicitEngineBridge) {
        GeneratedPluginRegistrant.register(with: engineBridge.pluginRegistry)
    }

    // The same plugins on every bundle engine.
    override func registerPlugins(with engine: FlutterEngine) {
        GeneratedPluginRegistrant.register(with: engine)
    }
}

BundleLoaderAppDelegate already implements FlutterImplicitEngineDelegate, and its didInitializeImplicitFlutterEngine(_:) cannot be overridden. Remove the template's FlutterImplicitEngineDelegate conformance and that method, and move your plugin registration into registerHostPlugins(with:). On an older template that calls GeneratedPluginRegistrant.register(with: self) in didFinishLaunchingWithOptions, move that registration there too.

registerPlugins(with:) runs once per bundle engine, right after that engine starts and before it is shown. The loader cannot call GeneratedPluginRegistrant itself — that class is generated in your project — so without the override, bundles run with no plugins and method-channel calls fail with MissingPluginException.

Change the scene delegate's base class

A current flutter create project has ios/Runner/SceneDelegate.swift (class SceneDelegate: FlutterSceneDelegate {}) and an Info.plist whose UISceneDelegateClassName already names $(PRODUCT_MODULE_NAME).SceneDelegate. Change the one base class:

import Flutter
import UIKit
import FlitzLoader

class SceneDelegate: BundleLoaderSceneDelegate {}

This step is required in a UIScene app: incoming URLs and the launch lifecycle are delivered to the scene delegate, not the app delegate. BundleLoaderSceneDelegate routes flitz:// URLs, forwards the bundle's own deeplinks to the running bundle engine, and replays the scene connection into that engine — which is created late, after the bundle downloads. Without the replay, a bundle cold-launched from a flitz://download link never delivers its launch event to scene-aware plugins, and plugins such as FirebaseMessaging hang on init. The scene delegate also opens the panel for flitz-panel links, and with Launch set to panel it puts the panel on screen at a cold start — see Opening the panel.

Register the URL scheme

iOS does not auto-merge plist contributions. Register the URL scheme in ios/Runner/Info.plist:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>FlitzLoader</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>flitz</string>
    </array>
  </dict>
</array>

Keep the entry's name FlitzLoader. Without sign-in the loader ignores the name; with sign-in on, the name is how the loader finds its scheme, and with any other name every load fails with "Loader build is broken".

To use your own scheme, change the single <string>flitz</string> value — the loader recognizes its URLs by authority, not scheme. A scheme starts with a letter and uses lowercase letters, digits, +, -, or ., at most 32 characters — the only form flitz publish accepts. With sign-in on, keep the scheme your client id is registered for. See Custom schemes.

Build and run

Build in release mode — a debug host cannot run bundles — and install on a physical device; the loader framework has no Simulator slice, so a Simulator build does not link:

flutter build ios --release
xcrun devicectl device install app --device <device-id> build/ios/iphoneos/Runner.app

xcrun devicectl list devices prints the device identifier. Avoid flutter build ipa here: its default export is for App Store upload, and the result does not install on a development device.

Then open a bundle: open the landing page flitz publish prints on the device and tap its button, or open its flitz://download?url=https://… link directly. The loader downloads the bundle over HTTPS and runs it. With sign-in on, the loader signs you in before it downloads.

A cold launch from the link (app not already running) exercises the scene-connection replay from the scene-delegate step — the path scene-aware plugins depend on. To test it, launch the app from the link:

xcrun devicectl device process launch --device <device-id> --terminate-existing \
  --payload-url 'flitz://download?url=<percent-encoded-bundle-url>' <bundle-identifier>