Flutter
Open the native Graffity AR Cloud experience from Flutter with a platform channel . Dart calls openAR and closeAR. On each platform, the channel presents the same native host used in the iOS SDK and Android SDK quick starts. The host owns the SDK, permissions, AR view, and shutdown.
These docs use iOS SDK 5.6.0 and Android SDK 5.5.0.
Requirements
- An access token from Graffity Console. Load it at runtime from your backend instead of hard-coding it.
- A Flutter app with iOS and/or Android targets.
- Everything listed in the native requirements: iOS (iOS 18.0+, physical ARKit device) and Android (API 28+, ARCore-supported device, JDK 17).
Dart client
Every platform uses the same channel name, graffity.tech/arcloud.
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
class GraffityAR {
static const _channel = MethodChannel('graffity.tech/arcloud');
/// Presents the native AR host. Completes once it is shown, not when VPS localizes.
static Future<void> open(String accessToken) =>
_channel.invokeMethod<void>('openAR', {'accessToken': accessToken});
/// Ends the session and closes the native AR host, if one is open.
static Future<void> close() => _channel.invokeMethod<void>('closeAR');
}
class OpenARButton extends StatelessWidget {
const OpenARButton({super.key, required this.accessToken});
final String accessToken;
@override
Widget build(BuildContext context) {
return ElevatedButton(
onPressed: () async {
try {
await GraffityAR.open(accessToken);
} on PlatformException catch (error) {
if (!context.mounted) return;
ScaffoldMessenger.of(context).showSnackBar(
SnackBar(content: Text(error.message ?? 'Unable to open AR.')),
);
}
},
child: const Text('Open AR'),
);
}
}iOS
Install the SDK
Set the deployment target to 18.0 in ios/Podfile (platform :ios, '18.0') and in the Runner target. Open ios/Runner.xcworkspace, then follow Install the SDK to add the GraffityARCloud package product to Runner. Add the camera and location descriptions to Info.plist.
Add the AR host
Copy the complete UIKit ARExperienceViewController into the Runner target. It retains the SDK, embeds its view, and provides a native Close button that shuts down the session.
Add the channel handler
This in-app plugin owns the channel. It presents from the foreground window, so it does not depend on window?.rootViewController and works with both app lifecycles.
import UIKit
import Flutter
final class GraffityARPlugin: NSObject, FlutterPlugin {
private weak var arHost: ARExperienceViewController?
static func register(with registrar: FlutterPluginRegistrar) {
let channel = FlutterMethodChannel(
name: "graffity.tech/arcloud",
binaryMessenger: registrar.messenger()
)
registrar.addMethodCallDelegate(GraffityARPlugin(), channel: channel)
}
func handle(_ call: FlutterMethodCall, result: @escaping FlutterResult) {
Task { @MainActor in
switch call.method {
case "openAR":
self.open(arguments: call.arguments, result: result)
case "closeAR":
await self.close(result: result)
default:
result(FlutterMethodNotImplemented)
}
}
}
@MainActor
private func open(arguments: Any?, result: @escaping FlutterResult) {
guard let args = arguments as? [String: Any],
let token = args["accessToken"] as? String,
!token.isEmpty else {
result(FlutterError(code: "INVALID_TOKEN", message: "accessToken must be a nonempty string.", details: nil))
return
}
guard arHost == nil else {
result(FlutterError(code: "AR_ALREADY_OPEN", message: "Close the current AR session first.", details: nil))
return
}
guard let presenter = Self.topViewController() else {
result(FlutterError(code: "NO_PRESENTER", message: "No view controller is available.", details: nil))
return
}
do {
let host = try ARExperienceViewController(accessToken: token)
host.modalPresentationStyle = .fullScreen
arHost = host
presenter.present(host, animated: true) { result(nil) }
} catch {
result(FlutterError(code: "AR_INIT_FAILED", message: error.localizedDescription, details: nil))
}
}
@MainActor
private func close(result: @escaping FlutterResult) async {
guard let host = arHost else {
result(nil)
return
}
arHost = nil
await host.endSession()
host.dismiss(animated: true) { result(nil) }
}
@MainActor
private static func topViewController() -> UIViewController? {
let scene = UIApplication.shared.connectedScenes
.compactMap { $0 as? UIWindowScene }
.first { $0.activationState == .foregroundActive }
var top = scene?.keyWindow?.rootViewController
while let presented = top?.presentedViewController {
top = presented
}
return top
}
}The weak arHost reference clears automatically when the user taps the host’s own Close button.
Register the plugin
Register it next to GeneratedPluginRegistrant in AppDelegate.swift. Use the tab that matches your Runner.
UIScene lifecycle
For apps migrated to Flutter’s UIScene lifecycle , where AppDelegate adopts FlutterImplicitEngineDelegate:
import UIKit
import Flutter
@main
@objc class AppDelegate: FlutterAppDelegate, FlutterImplicitEngineDelegate {
override func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
super.application(application, didFinishLaunchingWithOptions: launchOptions)
}
func didInitializeImplicitFlutterEngine(_ engineBridge: FlutterImplicitEngineBridge) {
GeneratedPluginRegistrant.register(with: engineBridge.pluginRegistry)
if let registrar = engineBridge.pluginRegistry.registrar(forPlugin: "GraffityARPlugin") {
GraffityARPlugin.register(with: registrar)
}
}
}Android
Install the SDK
In android/, follow Install the SDK to add tech.graffity.android:arcloud:5.5.0, set minSdk = 28 in android/app/build.gradle.kts, and use JDK 17. Add the manifest permissions, ARCore metadata, and Activity declaration.
Add the AR host
Copy the complete GraffityARActivity host and layout into your app package and replace the example package with yours. It creates the SDK, requests permissions, checks ARCore installation, and shuts down on Close, Back, or GraffityARActivity.closeActive().
Add the channel handler
package com.example.app
import android.content.Intent
import io.flutter.embedding.android.FlutterActivity
import io.flutter.embedding.engine.FlutterEngine
import io.flutter.plugin.common.MethodChannel
class MainActivity : FlutterActivity() {
override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
super.configureFlutterEngine(flutterEngine)
MethodChannel(
flutterEngine.dartExecutor.binaryMessenger,
"graffity.tech/arcloud"
).setMethodCallHandler { call, result ->
when (call.method) {
"openAR" -> openAR(call.argument<String>("accessToken"), result)
"closeAR" -> {
GraffityARActivity.closeActive()
result.success(null)
}
else -> result.notImplemented()
}
}
}
private fun openAR(token: String?, result: MethodChannel.Result) {
if (token.isNullOrBlank()) {
result.error("INVALID_TOKEN", "accessToken must be a nonblank string.", null)
return
}
if (GraffityARActivity.isOpen) {
result.error("AR_ALREADY_OPEN", "Close the current AR session first.", null)
return
}
try {
startActivity(
Intent(this, GraffityARActivity::class.java)
.putExtra(GraffityARActivity.EXTRA_ACCESS_TOKEN, token)
)
result.success(null)
} catch (error: Exception) {
result.error("AR_INIT_FAILED", error.message, null)
}
}
}Flutter delivers method calls on the main thread, so the handler can start and finish Activities directly.
Errors and events
openAR completes when the native host is presented (iOS) or launched (Android). It does not wait for permission approval, SDK initialization, or VPS localization.
| Error code | Meaning |
|---|---|
INVALID_TOKEN | accessToken is missing or blank. |
AR_ALREADY_OPEN | A host is already open. Call closeAR first. |
NO_PRESENTER | iOS only: no foreground screen is available to present from. |
AR_INIT_FAILED | SDK initialization or launch failed; see the message. |
If Dart needs runtime events such as localization or arrival, add an EventChannel and forward callbacks from GraffityARCloudDelegate and GraffityARCloudListener.
Run on a device
Run with flutter run on a physical device. AR does not run in the iOS Simulator or Android Emulator. Grant camera and location access, then follow the on-screen guidance in a mapped venue.
Report issues through the issue center.