Integrating Platform-Specific Code in Flutter

Core Concepts & Terminology
Binding to Native C/C++ Code (FFI)
Implementing Platform Channels & Pigeon
Hosting Native Platform Views
Integrating Web Content & Wasm
Workflows

Core Concepts & Terminology

FFI (Foreign Function Interface): The
```
dart:ffi
```
library used to bind Dart directly to native C/C++ APIs.
Platform Channel: The asynchronous message-passing system (
```
MethodChannel
```
,
```
BasicMessageChannel
```
) connecting the Dart client (UI) to the host platform (Kotlin/Java, Swift/Objective-C, C++).
Pigeon: A code-generation tool that creates type-safe Platform Channels.
Platform View: A mechanism to embed native UI components (e.g., Android
```
View
```
, iOS
```
UIView
```
) directly into the Flutter widget tree.
JS Interop: The modern, Wasm-compatible approach to interacting with JavaScript and DOM APIs using
```
package:web
```
and
```
dart:js_interop
```
.

Binding to Native C/C++ Code (FFI)

Use FFI to execute high-performance native code or utilize existing C/C++ libraries without the overhead of asynchronous Platform Channels.

Project Setup

If creating a standard C/C++ integration (Recommended since Flutter 3.38): Use the
```
package_ffi
```
template. This utilizes
```
build.dart
```
hooks to compile native code, eliminating the need for OS-specific build files (CMake, build.gradle, podspec).
bash
```
flutter create --template=package_ffi <package_name>
```
If requiring access to the Flutter Plugin API or Play Services: Use the legacy
```
plugin_ffi
```
template.
bash
```
flutter create --template=plugin_ffi <plugin_name>
```

Implementation Rules

Symbol Visibility: Always mark C++ symbols with
```
extern "C"
```
and prevent linker discarding during link-time optimization (LTO).
cpp
```
extern "C" __attribute__((visibility("default"))) __attribute__((used))
```
Dynamic Library Naming (Apple Platforms): Ensure your
```
build.dart
```
hook produces the exact same filename across all target architectures (e.g.,
```
arm64
```
vs
```
x86_64
```
) and SDKs (
```
iphoneos
```
vs
```
iphonesimulator
```
). Do not append architecture suffixes to the
```
.dylib
```
or
```
.framework
```
names.
Binding Generation: Always use
```
package:ffigen
```
to generate Dart bindings from your C headers (
```
.h
```
). Configure this in
```
ffigen.yaml
```
.

Implementing Platform Channels & Pigeon

Use Platform Channels when you need to interact with platform-specific APIs (e.g., Battery, Bluetooth, OS-level services) using the platform's native language.

Pigeon (Type-Safe Channels)

Always prefer

package:pigeon

over raw

MethodChannel

implementations for complex or frequently used APIs.

Define the messaging protocol in a standalone Dart file using Pigeon annotations (
```
@HostApi()
```
).
Generate the host (Kotlin/Swift/C++) and client (Dart) code.
Implement the generated interfaces on the native side.

Threading Rules

Main Thread Requirement: Always invoke channel methods destined for Flutter on the platform's main thread (UI thread).
Background Execution: If executing channel handlers on a background thread (Android/iOS), you must use the Task Queue API (
```
makeBackgroundTaskQueue()
```
).
Isolates: To use plugins/channels from a Dart background
```
Isolate
```
, ensure it is registered using
```
BackgroundIsolateBinaryMessenger.ensureInitialized(rootIsolateToken)
```
.

Hosting Native Platform Views

Use Platform Views to embed native UI components (e.g., Google Maps, native video players) into the Flutter widget tree.

Android Platform Views

Evaluate the trade-offs between the two rendering modes and select the appropriate one:

If requiring perfect fidelity, accessibility, or SurfaceView support: Use Hybrid Composition (
```
PlatformViewLink
```
+
```
AndroidViewSurface
```
). This appends the native view to the hierarchy but may reduce Flutter's rendering performance.
If prioritizing Flutter rendering performance and transformations: Use Texture Layer (
```
AndroidView
```
). This renders the native view into a texture. Note: Quick scrolling may drop frames, and
```
SurfaceView
```
is problematic.

iOS Platform Views

iOS exclusively uses Hybrid Composition.

Implement

FlutterPlatformViewFactory

and

FlutterPlatformView

in Swift or Objective-C.

Use the
```
UiKitView
```
widget on the Dart side.
Limitation:
```
ShaderMask
```
and
```
ColorFiltered
```
widgets cannot be applied to iOS Platform Views.

Integrating Web Content & Wasm

Flutter Web supports compiling to WebAssembly (Wasm) for improved performance and multi-threading.

Wasm Compilation

Compile to Wasm using:
```
flutter build web --wasm
```
.
Server Configuration: To enable multi-threading, configure your HTTP server to emit the following headers:
- ```
Cross-Origin-Embedder-Policy: credentialless
```
  (or
```
require-corp
```
  )
- ```
Cross-Origin-Opener-Policy: same-origin
```
Limitation: WasmGC is not currently supported on iOS browsers (WebKit limitation). Flutter will automatically fall back to JavaScript if WasmGC is unavailable.

Web Interop

If writing new web-specific code: Strictly use
```
package:web
```
and
```
dart:js_interop
```
.
Do NOT use:
```
dart:html
```
,
```
dart:js
```
, or
```
package:js
```
. These are incompatible with Wasm compilation.
Embedding HTML: Use
```
HtmlElementView.fromTagName
```
to inject arbitrary HTML elements (like
```
<video>
```
) into the Flutter Web DOM.

Workflows

Workflow: Creating a Native FFI Integration

Use this workflow when binding to a C/C++ library.

Task Progress:
- 1. Run
```
flutter create --template=package_ffi <name>
```
  .
- 2. Place C/C++ source code in the
```
src/
```
  directory.
- 3. Ensure all exported C++ functions are wrapped in
```
extern "C"
```
  and visibility attributes.
- 4. Configure
```
ffigen.yaml
```
  to point to your header files.
- 5. Run
```
dart run ffigen
```
  to generate Dart bindings.
- 6. Modify
```
hook/build.dart
```
  if linking against pre-compiled or system libraries.
- 7. Run validator ->
```
flutter test
```
  -> review errors -> fix.

Workflow: Implementing a Type-Safe Platform Channel (Pigeon)

Use this workflow when you need to call Kotlin/Swift APIs from Dart.

Task Progress:
- 1. Add
```
pigeon
```
  to
```
dev_dependencies
```
  .
- 2. Create
```
pigeons/messages.dart
```
  and define data classes and
```
@HostApi()
```
  abstract classes.
- 3. Run the Pigeon generator script to output Dart, Kotlin, and Swift files.
- 4. Android: Implement the generated interface in
```
MainActivity.kt
```
  or your Plugin class.
- 5. iOS: Implement the generated protocol in
```
AppDelegate.swift
```
  or your Plugin class.
- 6. Dart: Import the generated Dart file and call the API methods.
- 7. Run validator -> verify cross-platform compilation -> review errors -> fix.

Workflow: Embedding a Native Platform View

Use this workflow when embedding a native UI component (e.g., a native map or camera view).

Task Progress:
- 1. Dart: Create a widget that conditionally returns
```
AndroidView
```
  (or
```
PlatformViewLink
```
  ) for Android, and
```
UiKitView
```
  for iOS based on
```
defaultTargetPlatform
```
  .
- 2. Android: Create a class implementing
```
PlatformView
```
  that returns the native Android
```
View
```
  .
- 3. Android: Create a
```
PlatformViewFactory
```
  and register it in
```
configureFlutterEngine
```
  .
- 4. iOS: Create a class implementing
```
FlutterPlatformView
```
  that returns the native
```
UIView
```
  .
- 5. iOS: Create a
```
FlutterPlatformViewFactory
```
  and register it in
```
application:didFinishLaunchingWithOptions:
```
  .
- 6. Run validator -> test on physical Android and iOS devices -> review UI clipping/scrolling issues -> fix.

flutter-interoperating-with-native-apis

NPX Install

Tags

SKILL.md Content