remote_in_app_messaging library

Remote In-App Messaging (IAM).

A host-agnostic, JSON-driven in-app messaging engine. The host application supplies all I/O and side-effects via IamHostBindings (loading the JSON payload, getting the current user, tracking events, opening URLs, etc.), and this package handles schema, eligibility evaluation, display, and per-message persistence.

Public API surface is intentionally small: wire IamHostBindings, call IamService.init(bindings), and invoke onAppLaunch / onRoute / onEvent from the host.

Classes

BottomSheetIamRenderer
Renders an IamContent as a modal bottom sheet card.
EligibleMessage
Result of a successful engine evaluation: the selected message plus the resolved variant (already sticky-persisted).
FullscreenIamRenderer
Renders an IamContent as a fullscreen takeover route.
HiveIamStateStore
Hive-backed implementation of IamStateStore.
IamAlignment
Arbitrary (x, y) alignment in [-1, 1] — equivalent to Alignment(x, y). If named is provided, it wins over (x, y).
IamAnalyticsMapper
Builds the analytics parameter maps shared across iam_message_shown, iam_cta_clicked, iam_dismissed, and iam_cta_invalid_path events.
IamBody
Shared body layout for modal / bottom sheet / fullscreen renderers: optional image → title → body → up to two CTAs.
IamBodyStyle
All visual parameters of IamBody that can be expressed in JSON.
IamBorderRadius
JSON-friendly BorderRadius. When all is provided, it is applied to every corner.
IamBorderSide
JSON-friendly BorderSide.
IamContent
IamCta
IamCtaActionParams
Parameters threaded through every action handler.
IamCtaButton
Shared CTA button used by all IAM renderers.
IamCtaButtonStyle
All visual parameters of IamCtaButton that can be expressed in JSON.
IamCtaDispatcher
Translates a tapped IamCta into a side effect on the host (open deep link, open external URL, or no-op for close).
IamEdgeInsets
JSON-friendly EdgeInsets. When all is provided, the other fields are ignored.
IamFrequency
IamHostBindings
Host-supplied integration contract.
IamImage
Source/format-aware image widget used by image-bearing IAM layouts.
IamMessageRepository
Owns parsed-messages caching and reload semantics.
IamMessageState
Per-message persisted state. Keyed by InAppMessage.id in the state store.
IamRenderer
Contract every IAM renderer (modal / bottom sheet / fullscreen) satisfies.
IamRenderResult
IamService
Thin host-facing facade over the IAM coordinator. Use IamService.init in app bootstrap, then dispatch triggers from the host wiring via onAppLaunch, onRoute, and onEvent.
IamSize
JSON-friendly Size (width / height).
IamStateStore
Per-message persistence contract. Keyed by InAppMessage.id.
IamTargeting
IamTextStyle
JSON-friendly TextStyle. Only the most useful properties are exposed.
IamTrigger
IamTriggerContext
Runtime context describing what fired an IAM evaluation tick.
IamUserContext
Runtime user + device/app context used to evaluate targeting rules.
IamVariant
IamVariantPicker
Pure variant selection logic, lifted out of InAppMessagingEngine.
IamVariantPickResult
Result of IamVariantPicker.pick: the chosen index plus a flag that tells the engine whether the pick came from sticky persistence (no need to re-write the store) or from a fresh roll (must persist).
ImageOnlyModalIamRenderer
Renders an IamContent as an image-only modal: the image fills the dialog, with a translucent close chip overlaid in the top-right corner.
InAppMessage
InAppMessagesParser
Tolerant parser for the IAM JSON payload.
InAppMessagingCoordinator
Orchestrates evaluation → render → analytics → persistence for a single trigger tick. Serializes display with a re-entrancy lock so that only one message is ever on screen at a time.
InAppMessagingEngine
Pure evaluator that, given the current campaign list and a trigger/user context, returns at most one eligible EligibleMessage.
InMemoryIamStateStore
In-memory implementation of IamStateStore.
ModalIamRenderer
Renders an IamContent as a centered modal dialog.

Enums

IamActionType
Action executed when a CTA is tapped.
IamBoxFit
JSON enum mirroring Flutter's BoxFit. Only the common cases are exposed.
IamCrossAxisAlignment
JSON enum mirroring Flutter's CrossAxisAlignment for the body column.
IamCtaIconAlignment
Where to place an icon relative to its label inside IamCtaButton.
IamCtaIconAlignmentJson
JSON enum for the icon position inside an IamCtaButton.
IamCtaResult
Outcome of a CTA dispatch.
IamDismissBehavior
What happens after the user dismisses a message.
IamFontStyle
JSON enum mirroring Flutter's FontStyle.
IamFontWeight
JSON enum mirroring Flutter's FontWeight.
IamLayout
Visual layout of an in-app message.
IamNamedAlignment
JSON enum for a small named Alignment grid. Arbitrary (x, y) pairs can be expressed via IamAlignment.
IamRenderOutcome
Outcome of showing an IAM surface.
IamTextAlign
JSON enum mirroring Flutter's TextAlign for the title and body texts.
IamTriggerType
What triggers evaluation of an in-app message.

Extensions

IamAlignmentExt on IamAlignment
IamAlignmentPatterns on IamAlignment
Adds pattern-matching-related methods to IamAlignment.
IamBodyStylePatterns on IamBodyStyle
Adds pattern-matching-related methods to IamBodyStyle.
IamBorderRadiusExt on IamBorderRadius
IamBorderRadiusPatterns on IamBorderRadius
Adds pattern-matching-related methods to IamBorderRadius.
IamBorderSideExt on IamBorderSide
IamBorderSidePatterns on IamBorderSide
Adds pattern-matching-related methods to IamBorderSide.
IamBoxFitExt on IamBoxFit
IamContentPatterns on IamContent
Adds pattern-matching-related methods to IamContent.
IamCrossAxisAlignmentExt on IamCrossAxisAlignment
IamCtaButtonStylePatterns on IamCtaButtonStyle
Adds pattern-matching-related methods to IamCtaButtonStyle.
IamCtaFallbackStyleExt on IamCta
Convenience extensions on the freezed IamCta model.
IamCtaPatterns on IamCta
Adds pattern-matching-related methods to IamCta.
IamEdgeInsetsExt on IamEdgeInsets
IamEdgeInsetsPatterns on IamEdgeInsets
Adds pattern-matching-related methods to IamEdgeInsets.
IamFontStyleExt on IamFontStyle
IamFontWeightExt on IamFontWeight
IamFrequencyPatterns on IamFrequency
Adds pattern-matching-related methods to IamFrequency.
IamMessageStatePatterns on IamMessageState
Adds pattern-matching-related methods to IamMessageState.
IamSizeExt on IamSize
IamSizePatterns on IamSize
Adds pattern-matching-related methods to IamSize.
IamTargetingPatterns on IamTargeting
Adds pattern-matching-related methods to IamTargeting.
IamTextAlignExt on IamTextAlign
IamTextStyleExt on IamTextStyle
IamTextStylePatterns on IamTextStyle
Adds pattern-matching-related methods to IamTextStyle.
IamTriggerContextAnalytics on IamTriggerContext
Analytics-friendly views over IamTriggerContext.
IamTriggerContextPatterns on IamTriggerContext
Adds pattern-matching-related methods to IamTriggerContext.
IamTriggerPatterns on IamTrigger
Adds pattern-matching-related methods to IamTrigger.
IamUserContextPatterns on IamUserContext
Adds pattern-matching-related methods to IamUserContext.
IamVariantPatterns on IamVariant
Adds pattern-matching-related methods to IamVariant.
IamVariantWeightExt on IamVariant
Helper extension that clamps negative weights to 0. Centralized so the picker, future debug tooling, and tests share one definition.
InAppMessagePatterns on InAppMessage
Adds pattern-matching-related methods to InAppMessage.

Constants

defaultIamStateBoxName → const String
Default Hive box name used by HiveIamStateStore.

Functions

buildDispatchedIamBody(BuildContext context, IamContent content, {bool showCloseButton = true, CrossAxisAlignment? crossAxisAlignment, bool fullscreen = false}) → IamBody
Internal helper shared by ModalIamRenderer, BottomSheetIamRenderer, and FullscreenIamRenderer.
buildIamImage({required String path, BoxFit fit = BoxFit.contain, double? height, double? width}) → Widget
Top-level helper that returns the right widget for path.
compareSemver(String a, String b) → int
Lightweight semver-ish comparison used for minAppVersion / maxAppVersion targeting. Supports MAJOR.MINOR.PATCH[.BUILD] with any pre-release suffix after a - or + being ignored. Missing components default to 0.
isVersionInRange(String version, {String? min, String? max}) → bool
Returns true if version is within [min, max] (both inclusive). Either bound may be null / empty — treated as "no bound".
parseIamColor(String? hex) → Color?
Parses a #RRGGBB or #AARRGGBB hex string into a Color.
resolveResult(IamRenderResult? result) → IamRenderResult
Collapses a nullable IamRenderResult (returned by showDialog, showModalBottomSheet, or Navigator.push) into a non-null result by treating null as a dismiss outcome.
resolveStyle<T>(T? widget, T? json, T fallback) → T
Style precedence resolver shared by IamBody and IamCtaButton.
resolveStyleNullable<T>(T? widget, T? json, [T? fallback]) → T?
Same as resolveStyle but the fallback is itself nullable. Useful when a missing JSON value should propagate as null to keep the underlying widget's own default.

Typedefs

HiveIamStoreErrorLogger = void Function(Object error, [StackTrace? stackTrace, String? context])
Signature for an optional error logger, kept compatible with IamHostBindings.logError tear-offs.
IamBodyCloseButtonBuilder = Widget Function(BuildContext context, VoidCallback onClose)
Signature for fully customizing the close button in IamBody.
IamBodyImageBuilder = Widget Function(BuildContext context, String imageUrl)
Signature for fully customizing the image slot in IamBody.
IamErrorLogger = void Function(Object error, [StackTrace? stackTrace, String? context])
Signature for a host-supplied error logger. Kept available so existing callers that already store bindings.logError as a tear-off can keep passing it directly into the parser.