Flutter

Flutter apps (which contain android/ and ios/ sub-projects).

integrate

For a Flutter project, alphyn-cli integrate:

1. Downloads the SDK plugin (the federated alphyn_sdk_flutter tree) and verifies its integrity before any write.
2. Vendors the plugin into the project and adds it to pubspec.yaml as a path dependency. Run flutter pub get afterward to link it. The plugin carries the Dart facade and the native wiring; the native binaries themselves (Alphyn.xcframework for iOS, the com.byterialab:alphyn-sdk AAR for Android) resolve from the Alphyn package registry when the app is built.
3. Wires the iOS layer when an ios/ directory is present: it merges the required Info.plist keys (including the attestation-host ATS exception), adds the launch hook to the iOS AppDelegate (register() + initialize(interval:)), and installs the archive post-action into the app’s shared Xcode scheme, creating that scheme when the project has none, so archive builds always auto-register. The iOS framework ships through the plugin’s CocoaPods podspec, which fetches it from the registry during pod install.
4. Wires the Android layer when an android/ directory is present:
   • installs a Gradle build hook into android/app so every Android build auto-registers its APK hash (the exact same hook a native Android project gets, so the platforms never drift);
   • registers the authenticated Alphyn package registry as a Maven repository in the android root build script’s allprojects.repositories so :app can resolve the SDK AAR (required: Gradle’s default repository mode otherwise ignores the plugin’s own repo and the build fails to find the AAR);
   • adds the native SDK initialization to your launcher Activity’s onCreate (before super.onCreate()), resolved from the manifest.

lib/main.dart is not modified. integrate starts the SDK in native code on both platforms, which happens before any Dart runs. The plugin does expose AlphynSdk.initialize(), and it is the entry point when you wire the integration by hand (see Native Initialization); calling it in a CLI-integrated project is harmless, because the native core returns early once it is already initialized, but it is not required. 5. Records the result in alphyn.json.

Because the native binaries resolve from the registry, your build must supply your app API key as ALPHYN_REGISTRY_KEY: Gradle reads it to resolve the AAR, and pod install reads it to fetch the iOS framework. See SDK Registry Access:

export ALPHYN_REGISTRY_KEY=<YOUR_APP_API_KEY>

alphyn-cli new flutter scaffolds a starter by delegating to flutter create, so the Flutter toolchain must be on your PATH.

register

Nothing to run manually. The iOS build registers at archive time via the post-action, and the Android build registers at build time via the Gradle hook, both installed by integrate; run alphyn-cli doctor to confirm they are wired. Pass --apk only to register a specific Android APK by hand (a split or App Bundle output the hook skips, or a CI step).

A Flutter project enrolls under one portal app per platform, each with its own API key (see How to Register Your App). Give integrate both: --android-api-key (or --android-api-key-file) is the Android app’s key and --ios-api-key (or --ios-api-key-file) is the iOS app’s key; the generic --api-key is not accepted on a Flutter project, so a build can never register under the other platform’s key. integrate writes each into a gitignored .alphyn/ key file that the Gradle hook and the Xcode archive post-action read automatically, so every build registers with no further setup. To override per build, point alphyn.api.key.file (Gradle) or ALPHYN_IOS_API_KEY_FILE (the Xcode archive environment) at a key file; for a manual register --apk, pass --android-api-key / --android-api-key-file. The backend accepts a registration only from the matching platform’s key.

Development builds (iOS debug hash)

During development an iOS app’s hash changes on every build and is never registered (iOS registration happens at archive time). Pin your app’s development debug hash from the dashboard (App Details) so flutter run builds on iOS initialize the SDK:

alphyn-cli integrate --android-api-key <key> --ios-api-key <key> --ios-debug-hash <64-hex>

The hash is rendered into the #if DEBUG branch of the Swift launch hook, so a release build never carries it, and it is recorded in alphyn.json across re-runs. integrate also enrolls a development build signature with the backend (this uses the iOS app’s key), which a dev build needs before its first archive; SDK init in the dev loop then succeeds when the pinned hash matches the app’s dashboard debug hash. --android-debug-hash exists for the deliberate Android cases (a build environment without the hook, or pinning one specific registered build); normally the Gradle hook already registers every Android build.

The enrollment needs no build and no archive: it is a pure CLI call, and the development build signature appears in the dashboard as soon as it runs. register performs the same enrollment, so once the hash is pinned you can re-ensure it at any time without a full re-integrate (the pinned hash is recorded, so later runs need no flag; the iOS key comes from --ios-api-key or the provisioned .alphyn/ios-api.key):

alphyn-cli register --android-api-key <key>

The enrollment is idempotent, and alphyn-cli doctor reports the development build signature as enrolled. A real archive-time signature does not require the Xcode UI either: xcodebuild runs the same scheme post-action, so a terminal or CI archive registers itself (the usual signing requirements apply; a simulator build is not an archive):

cd ios
xcodebuild -workspace Runner.xcworkspace -scheme Runner -configuration Release \
  -destination 'generic/platform=iOS' archive -archivePath build/Runner.xcarchive

doctor

Confirms the pubspec.yaml dependency points at the vendored plugin; the iOS layer; the Android build hook, the registry Maven repository, and the native init in your launcher Activity (each when present); the minSdk advisory; and that the vendored plugin still matches the recorded checksum. The Android init check fails loudly if the launcher Activity cannot be located, so an app that would register but not start the SDK is caught. When a development debug hash is pinned, it also reports whether the development build signature is enrolled on the backend (advisory; it never fails the run).

remove

Removes the pubspec.yaml dependency, the iOS edits, the Android layer (build hook, registry Maven repository, launcher-Activity init), and the vendored plugin, and removes alphyn.json.