Flutter Dynamic SDK Integration Guide

Send this prompt to your AI to complete Shiply SDK integration

Copy the prompt below and paste it into your AI assistant to automatically complete Shiply SDK integration.

Based on https://skillhub.cn/install/skillhub.md, install shiply-commercial-sdk-integration.
After the skill is installed, use the skill Integrate Flutter Dynamic SDK.

1. Privacy and Security

Flutter Dynamic SDK

Version: 1.7.1

Last updated: March 18, 2026

SDK overview: Provides dynamic update capabilities for the Flutter framework, enabling developers to update or fix issues online

Service provider: Shenzhen Tencent Computer Systems Company Limited

Integration guide: Flutter Dynamic SDK Integration Guide

Privacy policy: Conch Dynamic SDK Privacy Policy

2. Obtain the SDK and License

Flutter dynamic updates are a restricted-access feature. If you are interested, please contact us to obtain the SDK and related permissions.

3. SDK Integration

The Conch-Flutter SDK builds a complete runtime service system by customizing the Dart compiler and pairing it with a proprietary Dart interpreter, enabling dynamic repair and hot updates for Flutter applications.

Overall workflow overview

The complete Conch-Flutter SDK workflow consists of four stages, forming a closed loop from project modification to patch release, as shown below:

Phase 1: Integrate the SDK and modify the project

• Complete Conch-Flutter SDK environment setup and ensure the development environment is fully configured (see 3.1 Configure Conch-Flutter SDK)
• Integrate runAppWrapper() at the application entry point and call the patch loading method (see 3.2 Project Modification)

Phase 2: Build the baseline package (see 4. Build Baseline Package)

• Android: Run flutter build apk --release to build the baseline package
• iOS: Run flutter build ios --release to build the baseline package
• Two important artifacts are generated:
  • Install package: APK (Android) or IPA (iOS), used for app distribution and release
  • Symbol file (conch_base_<versionCode>.json): Records all methods and symbol information for the current version; must be archived, as it is the key basis for creating patches later

Phase 3: Build the patch (see 5. Patch Creation)

• After the baseline package is released, when you need to fix bugs or adjust functionality:
  • Prepare the baseline symbol file (from archives)
  • Run flutter build patch to create the patch package

Phase 4: Upload to the platform (see 6. Publish Patch)

• Upload the generated patch package to the Shiply platform for release and management
• Enable hot updates for Flutter applications

3.1 Configure Conch-Flutter SDK

3.1.1 Clone the Conch-Flutter repository

Clone command:

git clone https://cnb.cool/tencent-tds/Conch-Flutter

Authentication:

On the first pull, you will be prompted for authentication credentials, as shown:

Enter username and token:

• Username: cnb
• Password: Enter the Token we provide as the password

Switch to the specified version:

git checkout flutter3.22.3_extRelease1.7.1

Tag naming convention:

Tag format: flutter{FlutterVersion}_extRelease{ConchSDKVersion}

• Example: flutter3.22.3_extRelease1.7.1
• Flutter version: 3.22.3 (corresponds to the Flutter framework version)
• Conch SDK version: 1.7.1 (corresponds to the Conch dynamic SDK version)

Notes:

• Make sure you use a Tag version that matches your project's Flutter version
• If the project path contains Chinese characters, spaces, or special characters, move the project to a path with ASCII-only characters; otherwise compilation may fail
• If you encounter authentication issues, verify that the Token is valid or contact technical support

3.1.2 Configure environment variables

Add the Conch-customized Flutter SDK path to your environment variables (macOS example):

export PATH=/{YourPath}/conch-flutter/bin:$PATH

• Replace {YourPath} with the actual path.

3.1.3 Handle macOS security dialogs

When running certain unnotarized apps or tools on macOS, the system may show security warning dialogs (such as "cannot open the app" or "from an unidentified developer").

The Conch SDK and its toolchain have passed compliance checks. However, due to the nature of certain binaries and the toolchain, system security protections may still be triggered at runtime, causing dialog prompts. This is normal and does not affect Conch functionality or development use.

macOS assigns the com.apple.quarantine attribute (Quarantine) to apps or files downloaded from the network, which can cause runtime dialogs. You can remove this attribute to avoid dialogs. Newer SDK releases include a removal script; you will need to enter your sudo password during execution:

cd /{YourPath}/conch-flutter
sh ./xattr_quarantine_inFlutter.sh

Expected output:

Detecting and removing quarantine attributes from Flutter tools...
Flutter directory: {YourPath}/conch-flutter
Quarantine attributes removed from Flutter tools to prevent popup dialogs!

3.1.4 Verify configuration

Run the following command to check whether the Flutter SDK is configured correctly:

flutter --version

Output similar to the following indicates success when the Flutter version includes Conch extReleasex.x.x:

enheng@LUCKIERGONG-MC2 ~ % flutter --version
ConchFlutter execute: --version
Flutter 3.22.3 • Conch extRelease1.7.1 • channel [user-branch] • https://cnb.cool/tencent-tds/Conch-Flutter
Framework • revision aa73bc9e53 (11 days ago) • 2025-11-20 17:23:32 +0800
Engine • revision 27fce7e964
Tools • Dart 3.4.4 • DevTools 2.34.1

flutter doctor -v

Output similar to the following indicates success when the Flutter SDK path points to the configured Conch Flutter path:

ConchFlutter execute: doctor -v
[!] Flutter (Channel [user-branch], 3.22.3, on macOS 15.6 24G84 darwin-arm64 (Rosetta), locale zh-Hans-CN)
    ! Flutter version 3.22.3 on channel [user-branch] at /Users/enheng/development/conch-flutter-cnb
      Currently on an unknown channel. Run `flutter channel` to switch to an official channel.
      If that doesn't fix the issue, reinstall Flutter by following instructions at
      https://flutter.dev/docs/get-started/install.
    ! Upstream repository https://cnb.cool/tencent-tds/Conch-Flutter is not a standard remote.
      Set environment variable "FLUTTER_GIT_URL" to https://cnb.cool/tencent-tds/Conch-Flutter to dismiss this
      error.
    • Framework revision aa73bc9e53 (11 days ago), 2025-11-20 17:23:32 +0800
    • Engine revision 27fce7e964
    • Dart version 3.4.4
    • DevTools version 2.34.1
    • If those were intentional, you can disregard the above warnings; however it is recommended to use "git"
      directly to perform update checks and upgrades.

[✓] Android toolchain - develop for Android devices (Android SDK version 36.1.0)
    • Android SDK at /Users/enheng/Library/Android/sdk
    • Platform android-36, build-tools 36.1.0
    • Java binary at: /Users/enheng/Library/Java/JavaVirtualMachines/ms-17.0.16/Contents/Home/bin/java
    • Java version OpenJDK Runtime Environment Microsoft-11926164 (build 17.0.16+8-LTS)
    • All Android licenses accepted.

3.2 Project Modification

3.2.1 Configure Conch dependencies

Step 1: Add Conch API dependency

Add the Conch API dependency under dependencies in pubspec.yaml:

dependencies:
  conch_api:
    sdk: flutter

Step 2: Configure Conch plugin parameters

Add Conch configuration at the top level of pubspec.yaml (outside dependencies):

# Conch dynamic configuration (top level of the file)
conch:
  enable: true                  # Whether to enable Conch hot update
  versionCode: 1.0.0            # Version number for this build
  targetBaseVersions: 1.0.0     # Used when creating patches; target baseline version
  licensePath: ./conch_license  # Path to the license certificate file

3.2.2 Source code modification

Only modify the application entry file (usually lib/main.dart): replace runApp() with ConchLoaderAPI.runAppWrapper(), and call ConchLoaderAPI.requestPatch() at an appropriate time after app startup to pre-download the latest patch.

Step 1: Import Conch API

import 'package:conch_api/conch_api.dart';

Step 2: Configure runtime parameters

Create a ConchParams object with the required parameters (see parameter details below):

final params = ConchParams(
  appId: "your_app_id",        // Required: AppId assigned by the Shiply platform
  appKey: "your_app_key",      // Required: AppKey assigned by the Shiply platform
  moduleName: "your_module",   // Required: Module name (must match the Shiply platform)
  appVersion: "1.0.0",         // Required: App version
  deviceId: "device_123",      // Optional: Device ID (for staged rollout)
  env: "online"                // Optional: Shiply release environment; defaults to "online" (production); use the environment ID for other environments
);

Step 3: Replace the startup method

Replace the original runApp(const MyApp()) with ConchLoaderAPI.runAppWrapper(), and call runApp() inside appBuilder:

Important: startup order requirement

ConchLoaderAPI.runAppWrapper() must run first before anything else. All other app initialization (plugin init, SDK init, global config, etc.) should go inside the appBuilder callback. This ensures patches are loaded before the app starts.

Code executed before patch loading will not be covered by the patch, which can cause old and new logic to coexist in the same run and lead to exceptions or unexpected behavior.

Integration example:

import 'package:flutter/material.dart';
import 'package:conch_api/conch_api.dart'; // ① Import

void main() {
  // Original
  //runApp(const MyApp()); 

  final params = ConchParams(          // ② Configure parameters
    appId: "your_app_id",              // Obtain from Shiply
    appKey: "your_app_key",            // Obtain from Shiply
    moduleName: "your_module",         // Module name
    appVersion: "1.0.0",               // App version
  );

                                      // ③ Replace startup method
    ConchLoaderAPI.runAppWrapper(
      params,
      appBuilder: () => runApp(const MyApp()),
    ),
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My App',
      home: Scaffold(
        body: Center(
          child: Text('Hello World'),
        ),
      ),
    );
  }
}

Step 4: Fetch the latest patch

Important: You must manually call requestPatch() in your app; otherwise remote patches cannot be downloaded locally.

// Call at an appropriate time after app startup
ConchLoaderAPI.requestPatch();

Notes:

• Downloads patches from the server and installs them locally
• Downloads and installs only; does not load into the runtime
• Downloaded patches are loaded automatically on the next cold start

3.2.3 Patch status query

Call queryPatchLoadResult() to synchronously query the current patch load status without triggering network requests or patch loading.

final result = ConchLoaderAPI.queryPatchLoadResult();

Return value PatchLoadResult?:

• Non-null: Contains patch load status (resultCode, moduleName, version, taskId)
• null: Load flow not completed

For detailed API documentation, see API Reference

4. Build Baseline Package

After SDK integration, follow this workflow to build the baseline package:

Steps:

1. Configure versionCode in pubspec.yaml (recommended to match appVersion, e.g. 1.0.0)

conch:
  enable: true                  # Whether to enable Conch hot update
  versionCode: 1.0.0            # Version number for this build
  licensePath: ./conch_license  # Path to the license certificate file

Conch determines the business scope at baseline build time; the default scope is the main project. If your business includes submodules, add moduleIncludes:

conch:
  enable: true                  # Whether to enable Conch hot update
  moduleIncludes:
    - package:xxx

Important: Configuring too many entries in moduleIncludes significantly increases baseline package size. Configure only the actual business scope; third-party libraries are not recommended.

2. Run the build command: flutter build apk --release / flutter build ios --release
3. Collect artifacts:
   • Baseline APK (for release)
   • Symbol file .dart_tool/conch_build/conch_base_1.0.0.json (must be archived)

Important:

• Symbol files are required to create patches; archive symbol files for every baseline version.
• Conch only takes effect in release mode.

5. Patch Creation

After the baseline package is released, you can create patches based on it when fixing bugs or adjusting functionality:

Steps:

1. Prepare the symbol file

Place the archived baseline symbol file (e.g. conch_base_1.0.0.json) in the conch_base/ directory at the project root (create the directory if it does not exist).

2. Configure patch parameters

In pubspec.yaml:

conch:
  enable: true 
  targetBaseVersions: 1.0.0      # Target baseline version (must match the symbol file version)
  licensePath: ./conch_license  # Path to the license certificate file

Parameter description:

• targetBaseVersions: Creates a patch for the version specified by targetBaseVersions. Must exactly match the symbol file version (e.g. if the symbol file is conch_base_1.0.0.json, use 1.0.0); otherwise patch generation fails because the baseline symbol file cannot be found.

3. Build the patch

flutter build patch

After compilation, the following artifacts are generated:

• Patch package: .dart_tool/conch_build/patch_zip/conch_result_diff.zip (upload to the Shiply platform)

6. Publish Patch

Upload the generated patch package conch_result_diff.zip to the Shiply release platform.

For platform usage, see: Platform User Guide

7. FAQ and Troubleshooting

Documentation: See the FAQ for common questions and answers

Important:

Before releasing hot-update code to production, test with hot updates as early as possible, preferably using the production baseline package. Do not publish to production without testing.