--- title: "Customize Flutter Nutrient SDK with native APIs" canonical_url: "https://www.nutrient.io/guides/flutter/customize/" md_url: "https://www.nutrient.io/guides/flutter/customize.md" last_updated: "2026-05-15T09:08:03.624Z" description: "Customize Flutter Nutrient SDK with native API documentation, including methods, properties, and code examples." --- # Bridge Nutrient native Android, iOS, and Web APIs in Flutter **Try platform adapters (beta):** [Platform adapters](https://www.nutrient.io/guides/flutter/platform-adapters.md) offer a simple alternative for accessing native SDK APIs through built-in language bindings — no plugin fork or Pigeon code generation required. Nutrient Flutter SDK is built on top of the Nutrient iOS, Android, and Web SDKs, which offer a comprehensive set of APIs to interact with document viewers and editors. Nutrient Flutter SDK exposes a subset of the most frequently used APIs, but in some cases, you may need to access additional native APIs that aren’t directly available. This guide will show you how to bridge Nutrient’s native APIs for iOS and Android using [Pigeon](https://pub.dev/packages/pigeon) and for the Web using the `dart:js` package. ## Prerequisites Before proceeding, ensure your development environment includes the following: - [Flutter SDK](https://flutter.dev/docs/get-started/install) - [Xcode](https://developer.apple.com/xcode/) - [Android Studio](https://developer.android.com/studio) - Basic knowledge of Flutter and Dart - Basic understanding of iOS (Swift) and Android (Kotlin) development ## Forking and cloning the Nutrient Flutter plugin repository The Nutrient Flutter plugin source code is publicly available on GitHub. Follow the steps below. 1. **Fork the repository**— Fork the [Nutrient Flutter repository](https://github.com/PSPDFKit/pspdfkit-flutter) to your GitHub account. 2. **Clone the forked repository** — Clone the repository to your local machine: ```bash git clone https://github.com//pspdfkit-flutter.git ``` - If you’re new to forking repositories, check out [this guide on GitHub](https://docs.github.com/en/get-started/quickstart/fork-a-repo) for detailed instructions on forking and keeping your fork in sync with the upstream repository. Once you have your fork ready, proceed to set up the project structure. ## Setting up the project structure For ease of development, organize your project in a structure where the Flutter app and the plugin sit as sibling directories: ```text app-root/ ├── myapp/ ├── pspdfkit-flutter/ ``` 1. **Create a new Flutter app** — In the `app-root` directory, run the following commands to create a new Flutter app and clone the forked repository: ```bash flutter create myapp ``` 2. Add the Nutrient Flutter plugin as a dependency in your `pubspec.yaml` file: ```yaml dependencies: nutrient_flutter: path:../pspdfkit-flutter ``` ## Defining a new API in Dart with Pigeon [Pigeon](https://pub.dev/packages/pigeon) is a code generator that simplifies the process of bridging APIs between Flutter and native platforms. It generates platform-specific code for iOS and Android based on the API definitions you provide in Dart. To bridge a new API, you need to define the API in a Dart file and then generate the platform-specific code using the Pigeon tool. - **Edit the Pigeon file** — Open the `pspdfkit-flutter/pigeons/nutrient.dart` file and define the new API. As an example, this guide will show how to bridge the `PdfDocument.getPageCount()` API : ```dart abstract class PdfDocumentApi { // Other existing APIs. @async int getPageCount(); } ``` - For more information on how to define APIs, refer to the [Pigeon documentation](https://pub.dev/packages/pigeon). ## Generating platform-specific code using Pigeon With the API defined, generate the platform-specific code using the Pigeon tool. 1. **Install Pigeon** — Ensure an up-to-date version of the [Pigeon](https://pub.dev/packages/pigeon) package is added to the `pspdfkit-flutter` `pubspec.yaml` file under the `dev_dependencies` section: ```yaml dev_dependencies: pigeon: ^22.4.0 ``` 2. **Run the Pigeon command** — Switch to the `pspdfkit-flutter` directory and run the following command: ```bash dart run pigeon --input pigeons/nutrient.dart ``` This will generate or update the following files to include the new API: - `./lib/api/nutrient.g.dart` — The Dart API file interface - `./ios/Classes/api/NutrientApis.g.swift` — The iOS API interface file - `./android/src/main/java/com/pspdfkit/flutter/pspdfkit/api/NutrientApi.g.kt` — The Android API interface file These generated files will contain all the necessary code to bridge the new API between Flutter and the native platforms. ## Implementing the API on Android To implement the API on Android, go to the Kotlin file where the native Android code will interact with Flutter: `pspdfkit-flutter/android/src/main/java/com/pspdfkit/flutter/pspdfkit/FlutterPdfDocument.kt`. - **Edit the `FlutterPdfDocument` class** — This class implements the generated `PdfDocumentApi` interface. Implement the `getPageCount()` method as follows: ```kotlin class FlutterPdfDocument ( private val pdfDocument: PdfDocument ) : PdfDocumentApi { // Other existing API implementations. override fun getPageCount(callback: (Result) -> Unit) { // The `PdfDocument` instance is already available, so you can get the page count directly. callback(Result.success(pdfDocument.pageCount.toLong())) } } ``` Here, `pdfDocument` is an instance of the [`PdfDocument`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.document/-pdf-document/index.html) class, which is already available in the Android codebase. You just had to call the [`getPageCount`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.document/-pdf-document/get-page-count.html) property to get the total number of pages in the document. ## Implementing the API on iOS To implement the API on iOS, you need to update the Swift file at `pspdfkit-flutter/ios/Classes/FlutterPdfDocument.swift`. - **Edit the `FlutterPdfDocument` class** — This class implements the generated `PdfDocumentApi` protocol. Implement the `getPageCount()` method as follows: ```swift class FlutterPdfDocument: NSObject, PdfDocumentApi { // Other existing API implementations. func getPageCount(completion: @escaping (Result) -> Void) { if let pageCount = document?.pageCount { completion(.success(Int64(pageCount))) } else { let error = NutrientApiError(code: "", message: "Failed to get page count.", details: nil ) completion(.failure(error)) } } } ``` Here, `document` is an instance of the [`Document`](https://www.nutrient.io/api/ios/documentation/pspdfkit/document) class, which is already available in the iOS codebase. You just had to call the [`pageCount`](https://www.nutrient.io/api/ios/documentation/pspdfkit/document/pagecount) property to get the total number of pages in the document. ## Implementing the API in Flutter Now, you’ll update the Dart files to expose the newly added `getPageCount` method in the Flutter Nutrient plugin. 1. **Update the `PdfDocument` interface** — Edit `lib/src/document/pdf_document.dart` and define the new API method as follows: ```dart abstract class PdfDocument { // Other existing APIs Future getPageCount(); } ``` 2. **Update the `PdfDocumentNative` class** — Implement the new method in `lib/src/document/pdf_document_native.dart`: ```dart class PdfDocumentNative extends PdfDocument { // Other existing APIs. @override Future getPageCount() { return _api.getPageCount(); } } ``` ## Implementing the API for Web Unlike iOS and Android, the Web platform doesn’t require platform channels or Pigeon to communicate with the JavaScript APIs. Instead, use the built-in [`dart:js`](https://api.dart.dev/stable/3.5.4/dart-js/dart-js-library.html) package to interact with the Web platform. To implement the `getPageCount` API for the Web platform, update the following files. 1. **Edit the `NutrientWebInstance` class** — This is where you’ll add the web-specific logic to get the document title. Update `lib/src/web/nutrient_web_instance.dart` as follows: ```dart class NutrientWebInstance { // Other existing APIs. Future getPageCount() async { try { // Access the Nutrient JavaScript instance to get the page count. var count = _nutrientInstance['totalPageCount']; return Future.value(count); } catch (e) { throw Exception('Failed to get document title: $e'); } } } ``` Here `_nutrientInstance` is the `JsObject` reference to the JavaScript instance of the [`PSPDFKit.Instance`](https://www.nutrient.io/api/web/PSPDFKit.Instance.html), which is already available in the Web codebase. You just had to access the `totalPageCount` property to get the total number of pages in the document. To learn more about `dart:js`, refer to the [official documentation](https://api.dart.dev/stable/3.5.4/dart-js/dart-js-library.html). 2. **Edit `PdfDocumentWeb`** — Next, update `lib/src/document/pdf_document_web.dart` to add access to the new API on the Web platform: ```dart class PdfDocumentWeb extends PdfDocument { // Other existing APIs. @override Future getPageCount() { return _instance.getPageCount(); } } ``` ## Using the new API in your Flutter app Now that you’ve implemented the `getPageCount` method across all platforms, you can use it in your Flutter app. For example: ```dart NutrientView( document: document, onDocumentLoaded: (pdfDocument) async { var pageCount = await pdfDocument.getPageCount(); print('Document page count: $pageCount'); }, ) ``` ## Backward compatibility If you’re currently using method channels for bridging APIs and aren’t ready to fully transition to Pigeon, you can continue using the existing method channels alongside the new Pigeon APIs. To do this, set `useLegacy` to `true` when initializing Nutrient: ```dart // This is now deprecated, but it still works for backward compatibility. `Nutrient.initialize()` no longer supports legacy mode. await Pspdfkit.initialize( useLegacy: true, ); ``` This will ensure the existing method channels are used for communication with the native platform. --- ## Related pages - [Flutter PDF bookmark SDK](/guides/flutter/bookmarks.md) - [Explore advanced PDF capabilities with demos](/guides/flutter/demo.md) - [Dart PDF library](/guides/flutter/dart.md) - [Download Flutter library](/guides/flutter/downloads.md) - [Changelog for Flutter](/guides/flutter/changelog.md) - [Flutter PDF library](/guides/flutter.md) - [Flutter guides: Integrate our PDF library](/guides/flutter/intro.md) - [Knowledge base](/guides/flutter/kb.md) - [Open PDF files in Flutter](/guides/flutter/open-a-document.md) - [Troubleshooting](/guides/flutter/troubleshoot.md) - [Upgrade and migration guides](/guides/flutter/upgrade.md)