Installing the tk_ota_push Flutter SDK

The tk_ota_push package provides both the mobile runtime embedded within your Flutter application (package:tk_ota_push/tk_ota_push.dart) and the deployment command-line interface (tk-ota-push / tkushpatch). Only the runtime library is compiled into your mobile binary; the CLI code (bin/tk_ota_push.dart) is never exported or bundled into your final production application.

Technical Prerequisites

Component	Requirement	Details
Dart SDK	>=3.5.4 <4.0.0	Specified in pubspec.yaml of the tk_ota_push package (v1.0.0).
Flutter	Shorebird Toolchain	The C++/Rust runtime engine (libflutter.so / Flutter.framework) must originate from the patched Flutter toolchain (~/.shorebird/bin/cache/flutter).
Mobile Platforms	Android & iOS	Android (aarch64 / arm64-v8a, arm / armeabi-v7a, x86_64) and iOS (aarch64 / arm64).
Internal Dependency	shorebird_code_push: ^2.0.7	Transitively embedded by tk_ota_push and re-exported (UpdateStatus, UpdateTrack, Patch).

1. Adding the Dependency to pubspec.yaml

You can integrate tk_ota_push through three distribution models (private/public registry, sovereign Git repository, or local monorepo path).

From pub.dev or an Internal Dart Registry

dependencies:
  flutter:
    sdk: flutter
  tk_ota_push: ^1.0.0

From an Internal Git Repository (Recommended for Enterprises)

dependencies:
  flutter:
    sdk: flutter
  tk_ota_push:
    git:
      url: https://git.enterprise.internal/mobile/tkushpatch_releases.git
      path: tk_ota_push
      ref: main

From a Local Path (Development / Monorepo)

dependencies:
  flutter:
    sdk: flutter
  tk_ota_push:
    path: ../tk_ota_push

Next, resolve your project dependencies:

flutter pub get

2. Declaring the shorebird.yaml Asset

The C++/Rust native engine embedded in the application reads its bootstrap configuration (app_id, base_url, channel, auto_update, patch_public_key, patch_verification) directly from compiled Flutter assets (flutter_assets/shorebird.yaml).

You must declare shorebird.yaml in the flutter.assets section of your pubspec.yaml:

flutter:
  uses-material-design: true
  assets:
    - shorebird.yaml

Asset Integrity Safeguard

Any modification to the flutter.assets list or to referenced asset files modifies the SHA-256 fingerprint calculated by FlutterProject.computeAssetsManifestHash(). Make sure shorebird.yaml is present from the initial Store Release build.

3. Android Configuration (AndroidManifest.xml)

On Android, the native Rust engine and Dart SDK require the INTERNET network permission to query /api/v1/patches/check, download patch differentials /api/v1/patches/artifacts/..., and submit telemetry events /api/v1/patches/events.

Open android/app/src/main/AndroidManifest.xml and verify the permission is declared:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- Required for checking and downloading OTA patches -->
    <uses-permission android:name="android.permission.INTERNET"/>

    <application
        android:label="My Application"
        android:name="${applicationName}"
        android:icon="@mipmap/ic_launcher">
        <!-- ... -->
    </application>
</manifest>

Special Case: Unencrypted Local HTTP Server (Development / LAN)

Starting with Android 9 (API 28), cleartext HTTP requests (http://...) are blocked by default. When testing against a local development server (e.g., http://192.168.0.199:8080 or http://10.0.2.2:8080), permit cleartext traffic in your development manifest or via network security configuration:

<application
    android:label="My Application"
    android:name="${applicationName}"
    android:usesCleartextTraffic="true"
    android:icon="@mipmap/ic_launcher">

In production environments, always enforce https:// URLs and disable usesCleartextTraffic.

4. iOS Configuration (Info.plist)

On iOS, outbound HTTPS access is permitted by default without requiring additional permission keys in ios/Runner/Info.plist.

Local Storage for the OTA Engine on iOS

The Rust engine persists its local state (state.json containing the UUID v4 client_id and patch metadata) within the private app sandbox:

• Primary directory: Library/Application Support/shorebird_updater/state.json
• Fallback inspected by TkOtaPush.readClientId(): Documents/shorebird_updater/state.json

No additional keys are required in Info.plist, unless testing against a non-TLS local HTTP server on a physical iPhone; in that scenario only (test environments), configure NSAppTransportSecurity:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsLocalNetworking</key>
    <true/>
</dict>

5. Activating the Deployment CLI (Developer Workstation / CI)

To build your Releases and Patches, activate the command-line binary provided by the tk_ota_push package globally:

# Activation from a local checkout
dart pub global activate --source path ./tk_ota_push

# Or activation from pub.dev
dart pub global activate tk_ota_push

Two equivalent commands become available in your terminal: tk-ota-push and the alias tkushpatch.