nexus library
Nexus — one Flutter SDK for all Inverge Nexus services.
Initialise once, then use any service (all correlated to one session):
await Nexus.init(const NexusConfig(apiKey: 'nxs_...'));
runApp(NexusScope(child: MyApp()));
// …
context.nexus.events.track('signed_up');
context.nexus.realtime.join('orders:42');
Classes
- CallKitAction
- CallQualitySample
- One transport-quality sample the engine emits; reported to the control plane and surfaced to the app for a live quality indicator.
- Nexus
- The Nexus umbrella SDK — one entry point for every service. Initialise once at startup; then use any service, all correlated to the same journey session:
- NexusCall
- Immutable snapshot of the current call, exposed via a ValueListenable.
- NexusCallKit
-
Native calling seam — CallKit (iOS) / ConnectionService (Android) + VoIP push.
The SDK reports call lifecycle to the OS so incoming calls ring on the lock
screen and in-call actions come from the system UI. Provide a real
implementation (e.g. over
flutter_callkit_incoming) viaNexus.instance.voice.useCallKit(...). The default is a no-op so the SDK runs without the native dependency. - NexusConfig
- Configuration for Nexus.init.
- NexusErrors
- Error & crash monitoring. Once installed, it reports every uncaught error automatically — Flutter framework errors, uncaught async (Dart) errors, and native crashes (Java/Kotlin, Swift/ObjC, background code). Native crashes are persisted by the native SDK and forwarded on the next launch. Manual capture is still available for handled errors.
- NexusEvents
- Product analytics. Events are buffered, batched, and handed to the durable outbox — correlated to the current session and retried until delivered.
- NexusFlags
- Feature flags & remote config. Call load to evaluate all flags for the current user, then read them synchronously.
- NexusInApp
-
In-app messages (OneSignal-style). Fetches the active messages for the tenant,
evaluates triggers (session start / custom event) and frequency caps locally,
requests display, and reports impressions/clicks. Rendering is done by
NexusInAppOverlay(default UI) or your own widget driven by current. - NexusInAppAction
- Emitted when a user taps a button on an in-app message.
- NexusInAppButton
- A button on an in-app message.
- NexusInAppMessage
- An in-app message the SDK can display (modal / banner / center / fullscreen).
- NexusInAppOverlay
-
Hosts the currently-active in-app message above your app. Add it via
MaterialApp.builderso it has a Material/Overlay/MediaQuery ancestor: - NexusInAppView
-
Default rendering for an in-app message. Bring your own UI via
NexusInAppOverlay(messageBuilder: ...)if you'd rather. - NexusIvrOverlay
-
The SDK's built-in IVR menu screen. Auto-shown whenever an IVR session is
active (alongside NexusVoiceOverlay); opt out with
autoShowOverlay: falseand build your own fromNexus.instance.voice.ivr. - NexusIvrSession
- NexusJoinToken
- Everything a client needs to join the media plane for one leg. Minted by the control plane; the client never fabricates any of it.
- NexusLinks
- Deep linking & attribution (OneLink-style). On first open, report the install/open so the backend attributes it and returns the deferred deep-link data.
- NexusLiveActivity
- Live Activities — a live, updating view of an in-progress event on the iOS Lock Screen / Dynamic Island and as an Android live ongoing notification.
- NexusLog
-
Central, leveled logger for the SDK. Configured once from NexusConfig at
Nexus.init; every component logs through the static methods so output is consistent ([Nexus] HH:mm:ss.SSS LEVEL message) and centrally gated. - NexusLogs
- Structured logging. Lines are buffered, batched, and handed to the durable outbox — correlated to the current session and retried until delivered.
- NexusMask
- Redact a widget from session replay. The wrapped subtree renders normally to the user, but its on-screen area is painted over with a solid block in every captured replay frame — so sensitive pixels (card numbers, tokens, PII) never leave the device.
- Reports route changes to Nexus so session replay's Pages tab shows the screens a user moved through. Add it to your app's navigator:
- NexusPlatform
- The native surface of the SDK: device/app context and (native-backed) session replay capture. Platform implementations (Kotlin/Swift/web) provide these; the pure-Dart services (events, errors, logs, realtime, …) work without native code.
- NexusPush
-
Nexus Push. With
pushEnabled: truethis is fully turn-key — start runs at init and handles permission, token acquisition, registration, refresh and open-tracking for you. The manual methods (registerToken/reportOpen) stay available for BYO-token setups (e.g. raw APNs or your own messaging plugin). - NexusRealtime
- Realtime messaging over Socket.IO. Authenticates with the API key + the current journey identity, so realtime connections join the same session.
- NexusRemoteConfig
- Firebase-style Remote Config. Fetches the active template for this app instance, resolves conditional values server-side, and exposes typed getters with in-app defaults as the fallback.
- NexusReplay
-
Session replay. Captures the app as rrweb-compatible screenshot frames +
pointer events via
NexusReplayController(Flutter-side, all platforms) and ships them to/partner/replay, correlated to the session. Also accepts batches from a native recorder if one is present (future native SDKs). - NexusScope
-
Makes the initialised Nexus available through the widget tree, and — when
session replay is enabled — installs the RepaintBoundary + pointer listener
the recorder captures from. Optional for access (
context.nexusfalls back to the global Nexus.instance), but required for replay. - NexusSessions
-
The sessions spine.
identifynames the end-user;trackstarts/refreshes the journey session other services correlate into. - NexusSurvey
- NexusSurveyChoice
- NexusSurveyController
- Drives one survey: holds answers, step position, validity, and submit/dismiss.
- NexusSurveyOverlay
-
Hosts the currently-active survey above your app. Add it via
MaterialApp.builderso it has a Material/Overlay/MediaQuery ancestor: - NexusSurveyQuestion
- NexusSurveys
-
In-product surveys. Fetches the surveys a user is eligible for, decides which
to show (auto-show for popover/banner types + event triggers), and submits
answers. The rendering is done by
NexusSurveyOverlay(default UI) or your own widget driven byNexusSurveyController. - NexusSurveyTrigger
- NexusSurveyView
-
The built-in survey card. Renders one question at a time with progress, a
thank-you screen, and default widgets per question type. Pass a
questionBuilder to override individual questions, or replace the whole card
via
NexusSurveyOverlay(surveyBuilder: ...). - NexusVoice
-
Nexus Voice — the client calling API. Talks to the Voice control plane
(
/partner/voice/*), drives a pluggable NexusVoiceEngine for media and an optional NexusCallKit for the native call UI, and exposes the live call as a ValueListenable. Follows the SDK rule: it NEVER throws into the app — failures are logged and surface as a failed/ended call state. - NexusVoiceEngine
-
The media-transport seam. Nexus Voice's control plane is engine-agnostic; the
actual WebRTC connection to the media plane (LiveKit) is provided by a
NexusVoiceEngine. Ship a real engine by registering one via
Nexus.instance.voice.useEngine(...)— e.g. a thin adapter overlivekit_client(see the SDK README). Keeping media out of the core keeps the base package dependency-light and lets any transport slot in. - NexusVoiceOverlay
-
The SDK's built-in, auto-shown call screen. Renders full-screen whenever
there is an active call (
Nexus.instance.voice.current) — outbound and incoming — with mute / speaker / hold / hangup (and accept / decline while ringing inbound). Auto-mounted whenvoiceEnabled; opt out withNexusConfig(autoShowOverlay: false)and place your own UI, or wrap NexusVoiceOverlay yourself. - NoopCallKit
- No-op default. The SDK still works for in-app (foreground) calling; the OS call UI simply isn't shown until a real CallKit implementation is registered.
- NoopVoiceEngine
-
Default engine when none is registered: it does NO media. It logs and reports
a
connectedstate so control-plane flows can be exercised end-to-end without audio (useful in tests / before wiring a real transport). It never throws.
Enums
- CallKitActionType
- NexusIvrStatus
-
State of an in-app IVR (visual phone-tree) session. The caller sees the
current
prompt; whenawaitingInputis true a keypad is shown and each press calls NexusVoice.pressIvrKey. On reaching a "talk to an agent" step the SDK connects a real call automatically (status→ connecting), and the NexusIvrSession clears once that call takes over. - NexusLogLevel
- Verbosity of the SDK's diagnostic logging.
- PushPlatform
- The device platform a push token belongs to.
- PushProvider
- The delivery provider a push token targets.
- VoiceCallDirection
- VoiceCallState
- Call state — the subset a client observes (mirrors the server machine).
- VoiceEndpointType
- VoiceEngineState
Extensions
- NexusBuildContext on BuildContext
-
context.nexus— access the SDK from any widget. - VoiceCallStateX on VoiceCallState
Functions
-
showNexusIncomingCall(
Map data) → Future< void> - Show the native incoming-call UI directly from a voice push payload.
Typedefs
- NexusEventHandler = void Function(dynamic data)
- NexusInAppBuilder = Widget Function(BuildContext context, NexusInAppMessage message, void onButton(NexusInAppButton button), VoidCallback onDismiss)
- Bring your own in-app message UI. Return a widget; drive it with the provided callbacks (button tap / dismiss).
- NexusLogSink = void Function(NexusLogLevel level, String message, [Object? error, StackTrace? stackTrace])
-
A custom log sink — receive every record the SDK emits (e.g. to forward it
into your own logging, or into Nexus Logs). Set via
NexusConfig.onLog. - NexusQuestionBuilder = Widget Function(BuildContext context, NexusSurveyController controller, NexusSurveyQuestion question)
-
Override the rendering of a single question. Return your own widget; read the
current value with
controller.answerFor(question.id)and write it withcontroller.setAnswer(...)/controller.toggleChoice(...). - NexusSurveyBuilder = Widget Function(BuildContext context, NexusSurveyController controller)
- Fully replace the survey UI. You receive the NexusSurveyController; render whatever you want and drive it (answers, next/back, complete, dismiss, close).
-
SurveySubmit
= Future<
void> Function(NexusSurvey survey, Map<String, Object?> answers, {bool completed, bool dismissed}) - Persists a response (partial or terminal). Wired to the surveys service.