Flutter Hybrid Integration Solution for Native Mobile Apps

This article introduces a comprehensive Flutter hybrid integration solution for native mobile applications, designed to address the challenge of integrating Flutter into existing native projects without requiring all developers to set up a full Flutter development environment.

Background

When preparing to adopt Flutter, most native developers are unfamiliar with it. Therefore, a "comfortable" integration approach needed to be designed that minimizes the learning curve and configuration overhead for native team members.

Hybrid Integration Approach

2.1 Considerations

Using the standard Flutter project structure would require native developers to also configure Flutter environment and understand Flutter technologies, which incurs significant cost.

Tight coupling between projects would make the development process uncomfortable.

2.2 Android Integration

The official integration method uses strong project coupling through Gradle configuration:

# setting.gradle
setBinding(new Binding([gradle: this]))
evaluate(new File(
'../managementcenter/.android/include_flutter.groovy'
))

# build.gradle
dependencies {
  implementation project(':flutter')
  ...........
}

This approach, while convenient for development and debugging, requires all native developers to configure Flutter environment.

2.3 iOS Integration

Official iOS Hybrid Approach

Injects podhelper.rb script via eval binding in native project Podfile, executed during pod install/update

Pod locally depends on Flutter engine (Flutter.framework) and FlutterPluginRegistrant

Flutter plugins are resolved from .flutter-plugins file generated by flutter packages get

In post_install hook, imports Generated.xcconfig configuration for xcode_backend.sh script preparation

In BuildPhases, injects xcode_backend.sh script for Flutter artifact building

Advantages

Seamless development - after configuration, development can proceed entirely within Flutter project

No need to separately split components, avoiding version management and release costs

Disadvantages

Strong coupling - requires modifying existing native project configuration

Requires modifying existing pod xcconfig settings

All team members must configure Flutter environment to compile successfully

2.4 Summary

Based on these considerations, the solution treats each Flutter business module as an independent artifact that can be integrated into different apps.

Flutter Artifact Structure

3.1 Android

Android produces AAR files for the Flutter module and all plugin dependencies.

3.2 iOS

iOS produces Flutter.framework, App.framework, and flutter_assets directory.

Flutter Artifact Collection

4.1 Android

On Android, integrating Flutter is relatively simple - just obtain the AAR files. A Python script is used to collect plugin AAR files based on the .flutter-plugins file:

from shutil import copyfile
import os
import requests

# File type to collect
BuildRelease = True
aarType = "-release.aar" if BuildRelease else "-debug.aar"

pluginFilePath = '../.flutter-plugins'

# Current project's flutter.aar
currentFlutterPath = '../.android/Flutter/build/outputs/aar/'

# Output path
outputFilePath = os.path.abspath('flutter_aar.py').replace("flutter_aar.py", "aars/")

endPath = 'android/build/outputs/aar/'

def collect_aar(plugins):
    all_collection_success = True
    if os.path.exists(outputFilePath):
        print('copy aar to: ' + outputFilePath)
    else:
        print('target path: ' + outputFilePath + ' not exist')
        os.makedirs(outputFilePath)
        print('create target path: ' + outputFilePath)

    for key, value in plugins.items():
        aar_path = value + key + aarType
        try:
            copyfile(aar_path, outputFilePath + key + aarType)
            print('copy flutter aar success at path: ' + aar_path)
        except IOError:
            all_collection_success = False
            print('copy flutter aar error at path: ' + aar_path)
            pass

file_object = open(pluginFilePath, 'r')
try:
    plugin_map = {}
    for line in file_object:
        array = line.split('=')
        plugin_map[array[0]] = array[1].replace('\n', '') + endPath

    plugin_map['flutter'] = currentFlutterPath
    collect_aar(plugin_map)
finally:
    file_object.close()

Execute the collection script:

#!/usr/bin/env bash

cd ..
cd .android
echo "start clean"
./gradlew clean
echo "start assembleRelease"
./gradlew assembleRelease
cd ..
cd android-build

echo "clean old aar file"
rm -rf aars

echo "start copy aar file"
# Only collect release
python flutter_aar.py

echo "copy aar file finish"

4.2 iOS

By analyzing the xcode_backend.sh script, it was found that as long as Flutter compilation artifacts are available, the host project can integrate Flutter functionality.

Script Analysis

engine/Flutter.framework → Flutter.framework (Flutter core library)

Debug mode: Dart code compiled (JIT) → App.framework

Non-debug mode: Dart code compiled (AOT) → App.framework

Resources packaged → flutter_assets

Solution Design

Compile all plugins into .a libraries with corresponding header files

Add App.framework and engine/Flutter.framework

Put all artifacts into a private pod library for native projects to depend on

Script Implementation

The script performs: flutter clean → flutter packages get → flutter build ios --debug → compile all plugins for both device and simulator architectures → merge with lipo → generate registration entry binary library.

Flutter Artifact Upload

5.1 Android

After artifact collection, upload to Maven repository for easy integration and version control:

apply plugin: 'youzan.maven.upload'

zanMavenUpload {
    version = '0.0.2'
    childGroup = "flutter-apub"
}

uploadItems {
    "fluttertoast" {
        targetFile = file('../../android-build/aars/fluttertoast-release.aar')
    }

    "image_picker" {
        targetFile = file('../../android-build/aars/image_picker-release.aar')
    }
    ............
}

Summary

This article comprehensively describes YouZan's Flutter hybrid integration solution. Currently, YouZan's internal apps have already used Flutter to develop some pages as a pilot. Future plans include piloting on production apps, with ongoing development of Flutter infrastructure libraries.