pikd_flutter_ar 0.8.0-beta.5

Flutter bridge for the PIKD native AR SDK, providing ARKit and ARCore sessions, geospatial placement, navigation, interactions, and physics.

pikd_flutter_ar

Flutter bridge over PIKDARKit for ARKit and ARCore. The native SDK owns AR session management, rendering, geospatial placement, navigation, interactions, and physics; this package exposes those capabilities through typed Dart APIs and a Flutter platform view.

Release candidate: pikd_flutter_ar version 0.8.0-beta.5.

Installation

After the package and its native dependencies are published, add:

dependencies:
  pikd_flutter_ar: ^0.8.0-beta.5

Then run flutter pub get. The plugin resolves PIKDARKit automatically from Maven Central on Android and Swift Package Manager on iOS with Flutter 3.44 or newer. CocoaPods remains a fallback for older Flutter projects. Consumers do not need PIKD repository access, GitHub credentials, Git LFS, or a locally copied framework.

Host-app requirements (each otherwise surfaces as a cryptic build error): Android minSdk ≥ 24 and mavenCentral() available; Android MainActivity may extend FlutterActivity or FlutterFragmentActivity. Use FlutterFragmentActivity when your app uses AndroidX FragmentActivity integrations such as biometrics (local_auth); Flutter 3.44 or later for iOS SwiftPM; iOS deployment target ≥ 15.0; and a physical device for AR. The integration requirements are described below and in the repository's PIKD SDK integration guide.

Two examples — pick the right one

• example/ (here) — the smallest possible version: fetch nearby drops, place them in AR, tap to collect. Deliberately bare — no surrounding app UI, no prebuilt screens. Start here to understand AR on its own.
• The full PIKD demo app — all five prebuilt module screens, live and sample data, brand rebranding, and opening AR from the Explore map. Start there to see the whole product working.

Both need a physical device for AR and an issued PIKD SDK key for live data.

If you mount PikdArView, don't call PikdAr.startArSession() at all — the view owns the session. It auto-starts on attach on both platforms (iOS didMoveToWindow, Android onAttachedToWindow), and handles the not-yet-initialised case itself. Calling it yourself is a real double-start: both land in one pending-completion slot, so the view's (completion-less) start replaces yours and your await never resumes, and the duplicate start can leave native session state inconsistent across a close/reopen. Subscribe to PikdAr.events first and wait for ArSessionStarted, with a timeout that proceeds anyway (an already-running session emits no new event). Both examples show this shape.

Why this exists

It provides the Flutter host bridge for the PIKD SDK while keeping the rendering engine in the native Android and iOS SDKs.

Public API (Dart)

import 'package:pikd_flutter_ar/pikd_flutter_ar.dart';

await PikdAr.initialize(PikdArConfig(
  userId: 'opaque-user-id',
  apiBaseUrl: 'https://api.pikd.app/sdk/v1',  // <- your tenant's /sdk/v1 base URL
  authToken: scopedToken,
  mockGps: true,                               // dev/testing
));

PikdAr.events.listen((e) {
  switch (e) {
    case AssetPlaced(:final assetId): /* ... */
    case Interaction(:final assetId): /* collected */
    case SurfaceDetectionChanged(:final isDetected): /* coach UI */
    default: break;
  }
});

// Embed the AR camera surface; overlay your own Flutter UI on top. Mounting the
// view STARTS the session — don't also call startArSession() (see the note above);
// wait for the ArSessionStarted event before loading.
Stack(children: [const PikdArView(), MyHud()]);

// …then, once ArSessionStarted has arrived:
final asset = await PikdAr.loadAsset(modelUrl, 'drop-1');
await PikdAr.placeAssetOnSurface(asset.id);
// Placement must precede playback, and needs a short settle (~1200ms) before the
// native side has an instance to animate:
await PikdAr.playAssetAnimation(asset.id, asset.animations.first, loop: true);

PikdAr.startArSession() / stopArSession() remain available for hosts that render AR without PikdArView.

Providing location (and other host capabilities)

PIKD's core is plugin-free by design (ADR 0005): cross-cutting capabilities — location, push, analytics, maps, identity — are host-provided. You inject what you already have and PIKD uses it; this keeps consumers from pulling dependencies they don't need.

Location — wire your location plugin behind CallbackLocationProvider. The example uses geolocator (an example dependency, not a core one):

import 'package:geolocator/geolocator.dart';

final location = CallbackLocationProvider(() async {
  if (!await Geolocator.isLocationServiceEnabled()) return null;
  var perm = await Geolocator.checkPermission();
  if (perm == LocationPermission.denied) perm = await Geolocator.requestPermission();
  if (perm == LocationPermission.denied || perm == LocationPermission.deniedForever) {
    return null; // graceful: the feature degrades, never throws
  }
  final p = await Geolocator.getCurrentPosition();
  return (lat: p.latitude, lng: p.longitude);
});

final here = await location.currentLocation();          // use for nearby queries
// With PikdSdk, inject it so PIKD uses it everywhere:
// PikdSdk.initialize(clientId: ..., providers: PikdProviders(location: location));

See example/lib/main.dart for the full flow (device location → nearby drops).

Push is bring-your-own — PIKD does not configure push and ships no Firebase dependency (push is host infra: your Firebase/APNs project, certs, and permission UX). If you want PIKD to route notifications, hand it a token from your existing push setup via CallbackPushProvider(() async => /* your FCM/APNs token */).

RN → Flutter mapping

react-native-ar	pikd_flutter_ar
initialize(SDKConfig)	PikdAr.initialize(PikdArConfig)
startARSession() / stop...	PikdAr.startArSession() / stopArSession()
loadAsset(url, id)	PikdAr.loadAsset(url, id)
placeAssetOnSurface(id)	PikdAr.placeAssetOnSurface(id)
createAnchor(...)	PikdAr.createAnchor(...)
setMockLocation(...)	PikdAr.setMockLocation(...)
addXListener(cb) (emitter)	PikdAr.events (Stream<ArEvent>)
<PIKDARView>	PikdArView (PlatformView)

Method channels and platform-view identifiers are private implementation details; integrate through PikdAr, PikdArView, and ArEvent rather than invoking native channels directly.

How it's wired

The Dart layer maps directly to native method channels, event channels, and a single AR platform view.

Piece	Where
Method/Event channel handler	ios/pikd_flutter_ar/Sources/pikd_flutter_ar/FlutterPikdArPlugin.swift · android/.../FlutterPikdArPlugin.kt
PikdArView PlatformView	ios/pikd_flutter_ar/Sources/pikd_flutter_ar/FlutterPikdArViewFactory.swift (embeds the SDK's shared ARView, mirroring RN's PIKDARViewContainer)
iOS PIKDARKit artifact	SwiftPM binary target for the GCS-hosted PIKDARKit 0.8.0-beta.3 XCFramework (CocoaPods fallback retained)
Android PIKDARKit artifact	Maven Central dependency app.pikd:pikd-sdk:0.8.0-beta.3

License

This package is proprietary software. Use requires a written SDK agreement with ELEOS WORLD LTD. See LICENSE and the PIKD SDK license page.