SDKInstance class
Internal singleton that backs the public Digia static facade.
This is an implementation detail of the SDK. App developers never see or reference this class — all calls flow through Digia.
- Implemented types
- Mixed-in types
Properties
-
allCampaigns
→ List<
CampaignModel> -
All campaigns currently cached in the store. Exposed for host/dev tooling
(e.g. the medihub "campaign lab" screen) to enumerate fetched campaigns.
no setter
- anchorRegistry → AnchorRegistry
-
no setter
-
campaignFetchForTesting
→ Future<
void> -
Completes when the campaign fetch started by initialize has settled
the SDK state (ready or failed). Tests await it instead of guessing.
no setter
-
captureBubbleHiddenNotifier
→ ValueNotifier<
bool> -
final
-
captureFlashNotifier
→ ValueNotifier<
int> -
final
-
captureMediaNotifier
→ ValueNotifier<
bool> -
final
-
captureModeNotifier
→ ValueNotifier<
bool> -
Capture controls are debug-only and independent from Sync.
final
-
captureStructureNotifier
→ ValueNotifier<
bool> -
final
-
captureTextNotifier
→ ValueNotifier<
bool> -
final
- clockForTesting ↔ int Function()?
-
Replaces the session clock (epoch milliseconds) in tests, so a test can
simulate a day. Null, the default, keeps the system clock.
getter/setter pair
- controller → DigiaOverlayController
-
Controller for inline campaigns, notifies when they change.
Exposed so DigiaHost can subscribe at mount time.
no setter
- currentScreen → String?
-
no setter
- events → EngageEventEmitter
-
Experience-event emitter used by render surfaces (DigiaSlot,
DigiaHost, nudge widgets) to route lifecycle events to CEP and/or Digia.
no setter
- floaterStoryOrchestrator → FloaterStoryOrchestrator
-
no setter
- guideManager → GuideShowcaseManager
-
no setter
- guideOrchestrator → GuideOrchestrator
-
no setter
- hashCode → int
-
The hash code for this object.
no setterinherited
- isReady → bool
-
Whether core is READY, so deliver routes instead of dropping.
no setteroverride
-
no setter
- networkClientFactoryForTesting ↔ NetworkClientFactory?
-
Replaces the SDK's network client in tests. The production client is a
DioNetworkClient that owns its whole engine configuration.
getter/setter pair
- pipOrchestrator → PipOrchestrator
-
no setter
- presentations → PresentationCoordinator
-
Internal accessor for tests and host tooling. Never app-facing.
no setter
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
- sdkState → SDKState
-
no setter
-
servicesListenable
→ ValueListenable<
SDKServices?> -
Changes whenever the services are assigned or replaced, so a widget built
before initialize finished picks them up when they appear.
no setter
- servicesOrNull → SDKServices?
-
Core SDK services, or null until initialize has built them.
no setter
-
successfulCapturePagesNotifier
→ ValueNotifier<
List< String> > -
final
- surveyOrchestrator → SurveyOrchestrator
-
no setter
- themeMode → DigiaThemeMode
-
no setter
Methods
-
bindNudgeRoute(
CEPTriggerPayload payload, ModalRoute route) → void -
bindSurveyProgress(
int token, ({int? abandonedAtItem, int? answeredCount}) read()?) → void -
campaignForPayload(
CEPTriggerPayload payload) → CampaignModel? -
Looks up the campaign for
payload(live test entry if present, else the real cache). Used by inline surfaces to attach campaign context. -
captureCurrentPage(
TextDirection textDirection) → Future< String> -
clearAllInlineContent(
) → void - Clears all inline content (carousels/stories) across every placement.
-
clearInlineContent(
List< String> placementKeys) → void -
Clears inline content (carousels/stories) for each key in
placementKeys. Once loaded, inline content is retained indefinitely — hosts should call this on logout so a stale user's content doesn't linger across the account switch. No-op ifplacementKeysis empty. -
clearPendingNudgeDismiss(
String campaignId) → void -
Clears a pending reason that never led to a pop — e.g.
maybePopreturned false because the nudge closed in the same frame. -
clearUserId(
) → Future< void> -
deliver(
CEPTriggerPayload trigger) → CampaignPresentation -
Delivers a CEP trigger into the Digia engine.
override
-
didChangeAccessibilityFeatures(
) → void -
Called when the system changes the set of currently active accessibility
features.
inherited
-
didChangeAppLifecycleState(
AppLifecycleState state) → void -
Called when the system puts the app in the background or returns
the app to the foreground.
override
-
didChangeLocales(
List< Locale> ? locales) → void -
Called when the system tells the app that the user's locale has
changed. For example, if the user changes the system language
settings.
inherited
-
didChangeMetrics(
) → void -
Called when the application's dimensions change. For example,
when a phone is rotated.
inherited
-
didChangePlatformBrightness(
) → void -
Called when the platform brightness changes.
inherited
-
didChangeTextScaleFactor(
) → void -
Called when the platform's text scale factor changes.
inherited
-
didChangeViewFocus(
ViewFocusEvent event) → void -
Called whenever the PlatformDispatcher receives a notification that the
focus state on a view has changed.
inherited
-
didHaveMemoryPressure(
) → void -
Called when the system is running low on memory.
inherited
-
didPopRoute(
) → Future< bool> -
Called when the system tells the app to pop the current route, such as
after a system back button press or back gesture.
inherited
-
didPushRoute(
String route) → Future< bool> -
Called when the host tells the application to push a new route onto the
navigator.
inherited
-
didPushRouteInformation(
RouteInformation routeInformation) → Future< bool> -
Called when the host tells the application to push a new
RouteInformation and a restoration state onto the router.
inherited
-
didRequestAppExit(
) → Future< AppExitResponse> -
Called when a request is received from the system to exit the application.
inherited
-
dwellElapsedMs(
String cepCampaignId) → int? -
Milliseconds since
cepCampaignId's surface was marked visible, for callers that must stamptime_to_action_msat the moment of the tap rather than when they get around to reporting it. -
failNudgePresentation(
CEPTriggerPayload payload, DropReason reason, String detail) → void - A nudge DigiaHost could not present (no navigator, or the present threw): nothing reached the screen, so it leaves the surface and settles as a drop now rather than blocking every later campaign (SR61).
-
floaterStoryActionScope(
BuildContext context) → EngageActionScope - Action bindings for content inside a story floater.
-
flushAnalytics(
) → Future< void> -
getAnonymousId(
) → String -
getInlineCampaign(
String placementKey) → CEPTriggerPayload? - Gets the active inline campaign for a given placement key, if any.
-
handleCancelBackGesture(
) → void -
Called when a predictive back gesture is canceled, indicating that no
navigation should occur.
inherited
-
handleCommitBackGesture(
) → void -
Called when a predictive back gesture is finished successfully, indicating
that the current route should be popped.
inherited
-
handleLiveTestCampaign(
LiveTestInvocation invocation) → void -
Handles one
campaign_testSSE event: ACKsreceived, then routes the inline campaign through the same_routeStoredCampaignpath an organic CEP trigger uses. -
handleStartBackGesture(
PredictiveBackEvent backEvent) → bool -
Called at the start of a predictive back gesture.
inherited
-
handleStatusBarTap(
) → void -
Called when the user taps the status bar on iOS, to scroll a scroll
view to the top.
inherited
-
handleUpdateBackGestureProgress(
PredictiveBackEvent backEvent) → void -
Called when a predictive back gesture moves.
inherited
-
initialize(
DigiaConfig config) → Future< void> -
Returns when the campaign fetch has settled the SDK state (ready or
failed) or
_initializeCapafter the call, whichever comes first. Never throws: a failure leaves the SDK in SDKState.failed. -
markNudgeAutoDismiss(
String campaignId) → void - Marks the nudge's close as an authored auto-dismiss. Only the nudge auto-dismiss timer calls it, for full-screen nudges.
-
markNudgeCtaDismiss(
String campaignId) → void -
Marks the nudge's close as caused by its own CTA. Only
EngageActionRunner's
dismissbinding in the nudge presenter calls it. -
markNudgeDismissed(
CEPTriggerPayload payload) → void - Fired when the nudge is dismissed — by the user or programmatically.
-
markNudgeScreenExit(
String campaignId) → void - Marks the nudge's close as a screen exit. Only setCurrentScreen calls it, when the active campaign no longer targets the new screen.
-
markSurveyCompleted(
Map< String, dynamic> response, [Map<String, SurveyAnswer> answers = const {}]) → void - Reports completion and clears the active survey.
-
markSurveyDismissed(
{int? abandonedAtItem, int? answeredCount}) → void -
Clears the active survey after the user closes the result page.
Fired when the user closes the survey without completing it.
abandonedAtItemis the 1-based question they were on;answeredCountis how many they had answered. -
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
onHostMounted(
) → void - Called by DigiaHost when it mounts into the widget tree.
-
onHostUnmounted(
) → void - Called by DigiaHost when it is removed from the widget tree.
-
openDebugSettingsFromOverlay(
) → Future< void> -
Pushes the debug settings screen from DigiaRecordingBadge, which lives
above the app's own Navigator (inside DigiaHost's
Stack, same as_presentNudge) — so it can't resolveNavigator.of(context)from its own BuildContext and must go through_navigatordirectly instead of the BuildContext-basedDigia.openDebugSettings. -
pipActionScope(
BuildContext context) → EngageActionScope - Action bindings for buttons inside the expanded PiP content.
-
pushDebugSettingsRoute(
) → Future< void> - Pushes the debug settings screen, at most one at a time.
-
recordAnchorSeen(
String anchorKey) → void - Called by DigiaAnchor the first time an anchor key mounts. Recorded against the currently-set screen name (see setCurrentScreen) — anchors require one server-side, so this is skipped if no screen is set yet.
-
recordSlotSeen(
String placementKey) → void - Called by DigiaSlot the first time a placement key mounts.
-
register(
DigiaCEPPlugin plugin) → void -
reportAnchorlessGuideFailure(
int guideToken, DiagnosticReason code, String message) → void -
reportBannerClicked(
CEPTriggerPayload payload, {String? actionType, String? actionUrl}) → void -
reportCarouselStepClicked(
CEPTriggerPayload payload, {required int itemIndex, String? actionType, String? actionUrl}) → void - A carousel item (or its CTA) was tapped. The first item tap also counts as an experience-level engagement click (once, deduped).
-
reportCarouselStepViewed(
CEPTriggerPayload payload, {required int itemIndex, required int itemTotal, required bool auto}) → void -
A carousel item scrolled into view.
auto= autoplay advance vs manual swipe.itemIndexis 1-based. -
reportFloaterStoryClicked(
{required String elementId, required String actionType, required String ctaRole, String? ctaLabel, String? actionUrl}) → void - SDK chrome taps on the window itself — opening the story, and the ×.
-
reportFloaterStoryStepClicked(
CEPTriggerPayload payload, {required String ctaLabel, required String actionType, required String ctaRole, String? actionUrl, int? timeToActionMs}) → void - An authored CTA on the window or inside a story — the real conversion.
-
reportInlineCanvasClicked(
CEPTriggerPayload payload, {String? elementId, String? ctaLabel, String? actionType, String? ctaRole}) → void - An element on an inline canvas was tapped.
-
reportInlineCanvasDismissed(
CEPTriggerPayload payload) → void - The author's Hide action removed an inline canvas from its slot.
-
reportInlineCanvasPrimaryClicked(
CEPTriggerPayload payload, {String? elementId}) → void -
reportInlineTimerClicked(
CEPTriggerPayload payload, ResolvedInlineTimerConfig config, InlineTimerState renderedState, Duration remaining, {required bool isPrimary, String? elementId, String? label, String? actionType, String? actionUrl}) → void -
reportInlineTimerDismissed(
CEPTriggerPayload payload, ResolvedInlineTimerConfig config, InlineTimerState renderedState) → void -
reportInlineTimerRendered(
CEPTriggerPayload payload, ResolvedInlineTimerConfig config, InlineTimerState state, Duration remaining) → void -
reportNudgeClicked(
CEPTriggerPayload payload, {String? elementId, String? ctaLabel, String? actionType, String? ctaRole}) → void -
reportNudgeImpression(
CEPTriggerPayload payload, NudgeConfig config) → void - Fired once when the nudge first becomes visible (its impression).
-
reportPipClicked(
{required String elementId, required String actionType, required PipState state, required String ctaRole}) → void - SDK chrome taps on the PiP itself — expand, collapse, close, mute, play.
-
reportPipStepClicked(
CEPTriggerPayload payload, {required String ctaLabel, required String actionType, required String ctaRole, String? actionUrl, int? timeToActionMs}) → void - An authored CTA inside the expanded content — the PiP's real conversion.
-
reportSlotFirstRender(
CEPTriggerPayload payload) → void - Fired when an inline slot first paints. Records the deduped Digia impression as a CarouselViewed or StoriesViewed depending on the campaign type. Mirrors Android's reportSlotFirstRender.
-
reportStoryCompleted(
CEPTriggerPayload payload, {required int itemTotal, int? timeToCompleteMs}) → void -
Last story frame viewed.
itemTotal= frames viewed;timeToCompleteMsfrom open. -
reportStoryOpened(
CEPTriggerPayload payload, {required int itemIndex}) → void -
A story was opened (ring/thumbnail tapped) — drives Digia's open rate.
itemIndexis the 1-based item opened. -
reportStoryStepClicked(
CEPTriggerPayload payload, {required int itemIndex, String? ctaLabel, String? actionType, String? actionUrl}) → void - A CTA inside a story frame was tapped.
-
reportStoryStepDismissed(
CEPTriggerPayload payload, {required int itemIndex}) → void -
Story closed before the last frame.
itemIndexis the 1-based frame on close. -
reportStoryStepViewed(
CEPTriggerPayload payload, {required int itemIndex, required int itemTotal}) → void -
A story frame became visible.
itemIndexis 1-based;itemTotal= frames in this story. -
reportSurveyAnswered(
String stepId, Map< String, dynamic> answer) → void -
Fired after a question (any block other than welcome) is answered.
stepIdidentifies the node. First-party Digia analytics only. -
reportSurveyCompleted(
Map< String, dynamic> response, [Map<String, SurveyAnswer> answers = const {}]) → void -
Fired once when the survey finishes (idempotent per showing). Beyond the
Completedanalytics event,answers(when supplied) are POSTed to the backend'srecordSubmissionendpoint via SubmissionReporter. -
reportSurveyQuestionSkipped(
String nodeId, int itemIndex) → void - Fired when the user advances past an unanswered, optional question. First-party Digia analytics only.
-
reportSurveyQuestionViewed(
String nodeId, int itemIndex) → void -
Fired when a (non-content) question becomes visible.
itemIndexis the 1-based respondent traversal depth. Stamps the view time fortime_to_answer_ms. First-party Digia analytics only. -
reportSurveyStartClicked(
) → void -
reportSurveyStarted(
) → void - Fired once when the survey first becomes visible (its impression).
-
reportWelcomeCtaClicked(
) → void -
Fired for the survey's single
Clickedengagement signal — on the welcome screen's start CTA, or on the first question's CTA when the welcome screen is hidden. Only a physical welcome Start also emits the coarse CEP click. -
resetForTesting(
{SDKServices? services}) → void -
resolveActiveCampaign(
) → CampaignModel? - Resolves the CampaignModel for the active payload so DigiaHost can switch on its config type and present the correct experience. Returns null (and auto-dismisses) when no matching campaign is found.
-
setCaptureModeEnabled(
bool enabled) → Future< void> -
setCaptureProfile(
{bool? includeText, bool? includeImagesAndMedia, bool? includeOtherStructuralNodes}) → Future< void> -
setCurrentScreen(
String name) → void - Sets the current screen. This is the single source of truth for screen scoping — a PiP belongs to the screen named here when it opened, and ends when this reports a different one. That is the expected end of most PiP impressions, not an error path.
-
setCustomKVHandler(
FutureOr< void> handler(Map<String, String> payload)?) → void -
setDeepLinkHandler(
FutureOr< void> handler(String deepLink)?) → void -
setNudgeRouteVisible(
bool visible) → void -
setOpenURLHandler(
FutureOr< void> handler(String deepLink)?) → void -
setServicesForTesting(
SDKServices services) → void -
setThemeMode(
DigiaThemeMode themeMode) → void - Selects the theme used when Campaign Canvas colors are rendered.
-
setUserId(
String userId) → Future< void> -
Buffered until the services exist — not merely until initialize has
been called: a host's unawaited
initialize()followed bysetUserId()lands while they are still being built (review B6). -
toString(
) → String -
A string representation of this object.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited
Static Properties
- idGenerator ↔ String Function()
-
Mints presentation ids.
getter/setter pair
- instance → SDKInstance
-
Internal accessor used only by Digia and DigiaHost.
no setter