Aller au contenu principal

Installation du SDK Flutter tk_ota_push

Le package tk_ota_push fournit à la fois le runtime mobile embarqué dans votre application Flutter (package:tk_ota_push/tk_ota_push.dart) et l'outil en ligne de commande de déploiement (tk-ota-push / tkushpatch). Seule la bibliothèque runtime est compilée dans votre binaire mobile ; le code de la CLI (bin/tk_ota_push.dart) n'est jamais exporté ni embarqué dans l'application finale.

Prérequis techniques​

ComposantExigenceDétails
SDK Dart>=3.5.4 <4.0.0Défini dans pubspec.yaml du package tk_ota_push (v1.0.0).
FlutterToolchain ShorebirdLe moteur d'exécution C++/Rust (libflutter.so / Flutter.framework) doit provenir de la toolchain Flutter patchée (~/.shorebird/bin/cache/flutter).
Plateformes mobilesAndroid & iOSAndroid (aarch64 / arm64-v8a, arm / armeabi-v7a, x86_64) et iOS (aarch64 / arm64).
Dépendance interneshorebird_code_push: ^2.0.7Embarquée transitivement par tk_ota_push et ré-exportée (UpdateStatus, UpdateTrack, Patch).

1. Ajout de la dépendance dans pubspec.yaml​

Vous pouvez intégrer tk_ota_push selon trois modes de distribution (registre privé/public, dépôt Git souverain ou chemin local monorepo).

Depuis pub.dev ou un registre Dart interne​

dependencies:
  flutter:
    sdk: flutter
  tk_ota_push: ^1.0.0

Depuis un dépôt Git interne (Recommandé en entreprise)​

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

Depuis un chemin local (Développement / Monorepo)​

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

Exécutez ensuite la résolution des dépendances :

flutter pub get

2. Déclaration de l'asset shorebird.yaml​

Le moteur natif C++/Rust embarqué dans l'application lit sa configuration d'amorçage (app_id, base_url, channel, auto_update, patch_public_key, patch_verification) directement depuis les assets Flutter compilés (flutter_assets/shorebird.yaml).

Vous devez obligatoirement déclarer shorebird.yaml dans la section flutter.assets de votre pubspec.yaml :

flutter:
  uses-material-design: true
  assets:
    - shorebird.yaml
Garde-fou d'intégrité des assets

Toute modification de la liste flutter.assets ou des fichiers référencés modifie l'empreinte SHA-256 calculée par FlutterProject.computeAssetsManifestHash(). Assurez-vous que shorebird.yaml est présent dès la compilation de la Release Store initiale.

3. Configuration Android (AndroidManifest.xml)​

Sur Android, le moteur natif Rust et le SDK Dart ont besoin de la permission réseau INTERNET pour interroger /api/v1/patches/check, télécharger les différentiels /api/v1/patches/artifacts/... et transmettre la télémétrie /api/v1/patches/events.

Ouvrez android/app/src/main/AndroidManifest.xml et vérifiez la présence de la permission :

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- Obligatoire pour la vérification et le téléchargement des patchs OTA -->
    <uses-permission android:name="android.permission.INTERNET"/>

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

Cas particulier : Serveur local en HTTP non chiffré (Développement / LAN)​

À partir d'Android 9 (API 28), les requêtes HTTP en clair (http://...) sont bloquées par défaut. Si vous testez sur un serveur de développement local (ex: http://192.168.0.199:8080 ou http://10.0.2.2:8080), autorisez le trafic cleartext dans votre manifeste de développement ou via une configuration réseau dédiée :

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

En production, utilisez toujours une URL https:// et désactivez usesCleartextTraffic.

4. Configuration iOS (Info.plist)​

Sur iOS, l'accès réseau sortant en HTTPS est autorisé par défaut sans permission supplémentaire dans ios/Runner/Info.plist.

Stockage local du moteur OTA sur iOS​

Le moteur Rust persiste son état local (state.json contenant le client_id UUID v4 et les métadonnées de patchs) dans le bac à sable applicatif privé :

  • Chemin principal : Library/Application Support/shorebird_updater/state.json
  • Repli inspecté par TkOtaPush.readClientId() : Documents/shorebird_updater/state.json

Aucune clé additionnelle n'est requise dans Info.plist, sauf si vous testez contre un serveur HTTP local non TLS sur un iPhone physique ; dans ce cas uniquement (en environnement de test), configurez NSAppTransportSecurity :

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

5. Activation de la CLI de déploiement (Poste développeur / CI)​

Pour compiler vos Releases et vos Patchs, activez globalement l'exécutable fourni par le package tk_ota_push :

# Activation depuis un clone local
dart pub global activate --source path ./tk_ota_push

# Ou activation depuis pub.dev
dart pub global activate tk_ota_push

Deux commandes équivalentes sont alors disponibles dans votre terminal : tk-ota-push et l'alias tkushpatch.