Skip to main content

End-to-End Getting Started Guide

This walkthrough guides you step-by-step through deploying your very first TkushPatch OTA hotfix: from initial Flutter project bootstrapping to executing dynamic code modifications on a physical device, bypassing application store review delays entirely.

5-Step Getting Started Journey
  1. Initialization: Configures shorebird.yaml and adds the Flutter SDK package.
  2. Release Build: Compiles base binaries using tk-ota-push release.
  3. Device Installation: Installs the application package on a mobile device or emulator.
  4. Patch Publication: Modifies Dart code and publishes an update with tk-ota-push patch.
  5. Live Update: Restarts the app to observe immediate over-the-air activation.

Step 1: Prerequisites and CLI Installation​

Verify that your Flutter development environment is healthy (flutter doctor) and install the TkushPatch CLI:

# Activate tk-ota-push globally via Dart
dart pub global activate --source path /path/to/tkushpatch_releases/tk-ota-push

# Verify installation
tk-ota-push --version

Authenticate against your self-hosted sovereign control plane:

tk-ota-push login --server https://console.tkushpatch.domain.com

Your default browser opens the /cli/login consent view. Upon confirmation, credentials are secure in ~/.shorebird/credentials.json.

Step 2: Bootstrapping the Flutter Project​

At the root directory of your Flutter application, initialize TkushPatch configuration:

tk-ota-push init

This command generates the project manifest shorebird.yaml:

app_id: 8f2c3d10-4e5a-4b91-a8d2-11e4f901c238
base_url: https://api.tkushpatch.domain.com

Add the client SDK package to your pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  tk_ota_push: ^1.2.0

In lib/main.dart, initialize the update engine during application bootstrap:

import 'package:flutter/material.dart';
import 'package:tk_ota_push/tk_ota_push.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Initialize sovereign OTA client
  await TkOtaPush.initialize();

  runApp(const BankingApplication());
}

Step 3: Compiling and Registering the Baseline Release​

The baseline Store release represents the original native binary submitted to app marketplaces (Google Play or Apple App Store).

Compile and register release 1.0.0+1:

tk-ota-push release android --artifact=apk

The CLI invokes Flutter's AOT toolchain, extracts native shared libraries (application binary) for target architectures (arm64-v8a and armeabi-v7a), indexes debug symbols in a .symbols archive, and registers binary metadata with your sovereign server.

Install the compiled APK onto your physical testing device:

adb install -r build/app/outputs/flutter-apk/app-release.apk

Launch the app on your handset to verify proper baseline operation.

Step 4: Applying Dart Code Changes​

Open your application source code (e.g. lib/home_page.dart) and introduce a visible UI or business logic modification:

// Before
Text("Current Balance: $12,500", style: TextStyle(color: Colors.black))

// After hotfix edit
Text("Available Balance: $12,500 ✨ (Hotpatched Live)", style: TextStyle(color: Colors.green, fontWeight: FontWeight.bold))

Step 5: Generating and Publishing the OTA Patch​

Publish the hotfix targeting baseline version 1.0.0+1:

tk-ota-push patch android --release-version=1.0.0+1 --track=staging

The compressed binary diff engine computes the micro-differential between old and new application binary artifacts. The resulting payload (typically under 50 KB) is transmitted to the server under STAGED quarantine status.

Step 6: Four-Eyes Governance Sign-Off​

  1. Navigate to the TkushPatch web console (https://console.tkushpatch.domain.com/approvals).
  2. Observe Patch #1 pending in the quarantine approval queue.
  3. Verify the 3 automated compliance guardrails:
    • ✅ Native bridge intact (zero C++/Java/Objective-C modifications).
    • ✅ SHA-256 target checksum validated.
    • ✅ Dart .symbols archive indexed.
  4. Click Approve and Sign with cryptographic signing engine.
  5. The patch status transitions to APPROVED_AND_SIGNED.

Step 7: Live Execution on the Smartphone​

  1. Launch your mobile application on the test device.
  2. In the background, tk_ota_push queries the server, downloads the differential archive, validates the RSA signature in the native Rust updater, and applies the binary patch.
  3. Minimize or close the app, then relaunch it.
  4. Immediate Validation: Your hotfixed Dart code executes live on screen: "Available Balance: $12,500 ✨ (Hotpatched Live)".

Congratulations! You have completed a full sovereign code push deployment cycle without awaiting external app store reviews.