GuideXR Optimize Flutter SDK #

The official Flutter SDK for GuideXR Optimize — a patient engagement and revenue intelligence platform for healthcare providers, built by Spatial Guide.

The SDK is a single, versioned client for everything an app needs to talk to GuideXR Optimize — event tracking, user/device registration, attribution capture, notification lifecycle tracking, a notification inbox, and in-app messages — so your app doesn't hand-roll and separately maintain this plumbing.

Contents #

• Prerequisites
• Install
• Quick start
• Configuration reference
• Event tracking
• User & device registration
• Attribution capture
• Consent
• Destinations: Firebase, Meta, and other forwarders
• Notification lifecycle tracking
• Notification inbox
• In-app messages
• Offline delivery
• Adopting the SDK in an app with existing users
• Example app

Prerequisites #

You need a GuideXR Optimize account with an API key and a channel ID. See spatial.guide/guidexr-optimize for account setup.

Install #

dependencies:
  guidexr_optimize_flutter_sdk: ^0.1.0

Quick start #

Call init once, as early as possible in main():

import 'package:flutter/material.dart';
import 'package:guidexr_optimize_flutter_sdk/guidexr_optimize_flutter_sdk.dart';

final navigatorKey = GlobalKey<NavigatorState>();

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await GuidexrOptimize.init(OptimizeConfig(
    baseUrl: 'https://your-optimize-endpoint',
    apiKey: 'YOUR_API_KEY',
    channelId: 'YOUR_CHANNEL_ID',
    source: 'my_app',
    navigatorKey: navigatorKey,           // required for in-app overlays
    onDeepLink: (link) => router.go(link),
  ));

  runApp(MyApp());
}

Every other API on this page assumes init has already been called and is accessed via the singleton:

final sdk = GuidexrOptimize.instance;

Configuration reference #

Everything the SDK needs is one OptimizeConfig, passed once to init.

Event tracking #

sdk.trackPageView('home_page');
sdk.trackClick('add_to_cart_click', attributes: {'sku': 'X1'});
sdk.trackBackendOnly('server_only_event');   // skips destination forwarders
sdk.trackCustom('custom_event', attributes: {...});

sdk.trackAppOpen(
  openSource: OptimizeOpenSource.push,       // .push / .deepLink / .direct
  notificationId: id,
  campaignId: campaignId,
);

trackPageView de-duplicates consecutive identical calls automatically — you don't need your own "don't fire the same screen view twice" logic. app_install (fired exactly once per real device) and app_version_changed are handled automatically by init — you never call these yourself.

Attributes that should ride along on every event (not just one call site) — e.g. a field your backend expects on every event, not just in identifiers — can be set once instead of passed everywhere:

sdk.setDefaultEventAttributes({'user_phone': profile.phone ?? ''});
// cleared automatically on reset()

If your backend requires that anonymous (pre-login) traffic carry no persistent device identifier, set gateDeviceIdUntilIdentified: true in your config — device_id is then sent as "" until the first registerUser call sets a real external_id, and blanked again after reset(). Registration calls (registerUser/registerDevice) always send the real device id regardless of this flag — registering is the identify-time call.

User & device registration #

await sdk.registerUser(
  externalId: userId,
  profile: OptimizeProfile(
    email: email,
    firstName: firstName,
    lastName: lastName,
    phone: phone,
  ),
  channelPreferences: {'push_opt_in': pushPermissionGranted},
);

await sdk.registerDevice(fcmToken: token, pushEnabled: pushPermissionGranted);

// On logout:
await sdk.reset();

Channel preferences default to opted-in for every channel except push_opt_in, which reflects the OS notification permission and defaults to false if you don't pass it explicitly. An explicit false you do pass is always respected.

If a screen or listener ends up calling registerUser/registerDevice more often than the identity/token actually changes (e.g. on every rebuild, or a notification icon tapped repeatedly), set minRegistrationInterval to skip the redundant network call:

OptimizeConfig(
  minRegistrationInterval: const Duration(minutes: 15),
  ...
)

A call for a genuinely different externalId (registerUser) or a rotated token/toggled push state (registerDevice) is never throttled, regardless of timing — only an exact repeat within the window is skipped. externalId is still recorded locally either way.

Attribution capture #

// A deep link (e.g. from your router/deep-link package):
await sdk.captureAttributionFromUri(uri);

// Play Install Referrer:
await sdk.captureAttributionFromInstallReferrer(referrerString);

// A resolved Meta deferred deep link (you fetch it — the SDK has no
// Meta SDK dependency):
await sdk.captureAttributionFromUri(
  resolvedUri,
  attributionSource: 'meta_deferred',
  priority: AttributionSourcePriority.metaDeferred,
);

Capture is priority-based (installReferrer < metaDeferred < manualDeepLink) and expires after 30 days. A single attribution_capture event fires only when the capture actually changes something — not on every call.

Attribution is almost always captured before login (a deep link or install referrer arrives at first launch), so by default attribution_capture fires immediately with an empty external_id. If a downstream workflow correlates that event by identity (e.g. a CRM sync), set deferAttributionEventUntilIdentified: true — the event is held (only the latest capture survives if more than one arrives before login) and fires automatically, with the real external_id, right after your next successful registerUser call.

Consent #

await sdk.setConsent(OptimizeConsent(
  analytics: true,
  marketing: true,
  location: false,
  version: 'v1',
  source: 'onboarding',
));

Attached automatically to every event and user-registration payload from then on.

Destinations: Firebase, Meta, and other forwarders #

The SDK never depends on firebase_analytics or facebook_app_events — apps that don't use them shouldn't have to pull them in. Instead, implement OptimizeForwarder using whatever destinations you've already set up:

class MyFirebaseForwarder implements OptimizeForwarder {
  @override
  bool get isReady => Firebase.apps.isNotEmpty;

  @override
  Future<void> onEvent(OptimizeEvent event) =>
      FirebaseAnalytics.instance.logEvent(
        name: FirebaseNaming.normalizeName(event.name),
        parameters: FirebaseNaming.normalizeParams(event.attributes),
      );

  @override
  Future<void> onIdentify(OptimizeIdentity identity) =>
      FirebaseAnalytics.instance.setUserId(id: identity.externalId);

  @override
  Future<void> onReset() => FirebaseAnalytics.instance.setUserId(id: null);
}

sdk.addForwarder('firebase', MyFirebaseForwarder());

FirebaseNaming.normalizeName/normalizeParams (also exported by the SDK) handle Firebase's own naming rules — lowercase, [a-z0-9_], a 40-character cap, and a 25-parameter cap — so you don't reimplement them.

A few things worth knowing:

• Every registered, enabled, ready forwarder receives onEvent in parallel with the backend call — one broken forwarder never blocks the backend or another forwarder.
• trackBackendOnly events skip forwarders entirely.
• sdk.setForwarderEnabled('firebase', false) is a runtime kill switch.
• Optionally declare intent up front so misconfiguration is caught early:

  OptimizeConfig(
    destinations: {Destination.firebase: true, Destination.meta: true},
    ...
  )
  

  If a destination is flagged true but never registered (or its isReady is false), the SDK logs a clear warning via onLog on your first tracked event — instead of silently dropping data.
• Session-replay/screen-tracking tools (e.g. Microsoft Clarity) don't need the full forwarder interface — call their screen-name API directly at your own trackPageView call site instead.

A Meta forwarder, with standard events and identity sync #

MetaNaming (also exported by the SDK) maps page views to Meta's own fb_mobile_content_view standard event, so Meta's ad platform recognizes it the way it recognizes that event from its own SDK — a raw custom event name doesn't get that treatment. Meta identity sync (setUserID/setUserData/AdvertiserTrackingEnabled) has no core-SDK hook of its own; it belongs in your forwarder's onIdentify/onReset, same as any other vendor-specific call:

class MyMetaForwarder implements OptimizeForwarder {
  @override
  bool get isReady => true; // Meta App Events has no async init to wait on

  @override
  Future<void> onEvent(OptimizeEvent event) async {
    final standard = MetaNaming.standardEventFor(event.type);
    final params = FirebaseNaming.normalizeParams(event.attributes); // reused for type coercion only
    if (standard == MetaNaming.contentView) {
      await FacebookAppEvents().logEvent(
        name: standard!,
        parameters: {...params, ...MetaNaming.contentViewParams(event.name)},
      );
    } else {
      await FacebookAppEvents().logEvent(name: event.name, parameters: params);
    }
  }

  @override
  Future<void> onIdentify(OptimizeIdentity identity) async {
    await FacebookAppEvents().setUserID(identity.externalId);
    // Sync ATT status yourself (app_tracking_transparency package) —
    // the SDK has no ATT dependency:
    await FacebookAppEvents().setAdvertiserTracking(
      enabled: await isAttAuthorized(),
    );
  }

  @override
  Future<void> onReset() => FacebookAppEvents().clearUserID();
}

Notification lifecycle tracking #

sdk.notifications.trackReceived(notificationId);
sdk.notifications.trackImpression(notificationId);
sdk.notifications.trackClicked(notificationId);
sdk.notifications.trackButtonAction(notificationId, buttonId);
sdk.notifications.trackDismissed(notificationId);

Wire these into your own FCM listeners:

FirebaseMessaging.onMessage.listen((message) async {
  if (await sdk.inApp.handleForegroundFcm(message.data)) return; // handled as in-app

  final id = OptimizeNotificationPayload.extractNotificationId(message.data);
  sdk.notifications.trackReceived(id);
  // ... render your own tray notification ...
});

FCM's background isolate doesn't have the GuidexrOptimize singleton — construct a standalone tracker there instead:

@pragma('vm:entry-point')
Future<void> firebaseMessagingBackgroundHandler(RemoteMessage message) async {
  final id = OptimizeNotificationPayload.extractNotificationId(message.data);
  OptimizeNotificationTracker(yourConfig).trackReceived(id);
}

A repeat call for the same (notificationId, event) within a few seconds is deduped automatically — e.g. FCM's getInitialMessage() and onMessageOpenedApp both firing for one cold-start tap won't double-count a clicked event. You don't need your own guard for that.

Parsing helpers for the data payload:

OptimizeNotificationPayload.extractNotificationId(message.data);
OptimizeNotificationPayload.extractDeeplink(message.data);
OptimizeNotificationButton.parseAll(message.data); // action buttons

Notification inbox #

Data layer only — build your own list UI on top:

final page = await sdk.inbox.list(page: 1, pageSize: 20);
await sdk.inbox.setRead(notificationId, isRead: true);
await sdk.inbox.setReadBulk(notificationIds, isRead: true); // auto-chunked at 20
await sdk.inbox.clear(notificationId);
await sdk.inbox.clearAll();

In-app messages #

// On launch and on resume:
await sdk.inApp.evaluatePending();

// In your foreground FCM listener (see above) — returns true if the
// payload was an in-app message, whether or not it was displayed:
await sdk.inApp.handleForegroundFcm(message.data);

Given navigatorKey/onDeepLink in your config, matching messages are presented automatically as one of four overlay types (full-screen, modal, top banner, bottom banner), with impression/clicked/ button_action/dismissed tracking built in. You don't build any of this UI yourself. Overlay images are fetched through cached_network_image, so a repeated campaign image isn't re-downloaded on every impression. If the notification arrives before your navigator is mounted (a cold start), the SDK retries showing it a few times over a few seconds before giving up and waiting for the next launch/resume — you don't need your own "not ready yet" handling for that race.

onDeepLink receives whatever string the campaign was configured with — deciding whether that's an in-app route or an external URL is yours to make, the same way you'd handle any other deep link:

onDeepLink: (link) {
  final uri = Uri.tryParse(link);
  if (uri != null && uri.host != 'your-app-domain.com') {
    launchUrl(uri, mode: LaunchMode.externalApplication);
  } else {
    router.go(link); // internal route
  }
},

Offline delivery #

Failed events (transport error or a 5xx response) are queued and retried automatically — you don't need to do anything for this to work. 4xx responses are never retried, since the payload itself was rejected.

await sdk.flushQueue(); // optional manual trigger, e.g. from your own
                        // connectivity listener or app-lifecycle hook

There's no hard guarantee of delivery before the OS suspends your app — that would need native background-task APIs, which this package deliberately doesn't add. flushQueue() narrows the window; it doesn't close it.

Adopting the SDK in an app with existing users #

If your app already tracks an anonymous id under its own storage, wire legacyAnonymousIdProvider before shipping to your existing user base — skipping this fires a spurious app_install for every existing user on their first launch of the updated app, corrupting install-count and retention data.

OptimizeConfig(
  ...
  legacyAnonymousIdProvider: () => yourExistingAnonymousIdStorage.peek(),
)

This provider must be strictly read-only. Return null when nothing exists yet; never create a value as a side effect. A "get-or-create" style method (mints a value the first time it's called) will return non-empty even for a genuinely new install, which the SDK cannot distinguish from a real pre-existing value — silently suppressing app_install forever, not just for your existing users. If your existing service only exposes a get-or-create method, add a true read-only variant and wire that instead.

Consulted exactly once — the very first init() call where the SDK's own storage is still empty. Every launch after that reads the SDK's own storage directly and never calls this again.

Example app #

See example/ for a runnable app covering initialization, event tracking, and registration.