In-app messages

import 'package:nexus_flutter/nexus.dart';

NexusInAppCopy Anchor Link

In-app messages (OneSignal-style). Fetches the messages meant for this user — the server applies the audience, assigns the A/B variant and fills in {{variables}} — then 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.

activeCopy Anchor Link

List<NexusInAppMessage> get active

All active in-app messages for the tenant.

currentCopy Anchor Link

final ValueNotifier<NexusInAppMessage?> current

The message currently requested to display (null when none). The overlay listens to this.

onActionCopy Anchor Link

void Function(NexusInAppAction action)? onAction

Called when a user taps a button (handle url / event actions yourself, e.g. navigate or launchUrl). Event-action buttons are also auto-tracked.

onTrackEventCopy Anchor Link

void Function(String event)? onTrackEvent

Wired by the SDK to the analytics track() for event-action buttons.

setProperties()Copy Anchor Link

Future<void> setProperties(Map<String, Object?> properties, {bool refetch = true})

Properties for audience targeting and personalisation, on top of the identify traits: setProperties({'plan': 'pro', 'coupon': 'SARA20'}) matches the console's plan conditions and fills {{coupon}}. Kept for this launch; pass refetch: false to wait for the next fetch.

Parameters

clearProperties()Copy Anchor Link

void clearProperties([Iterable<String>? keys])

Remove properties set with setProperties.

Parameters

attachRealtime()Copy Anchor Link

void attachRealtime(NexusRealtime realtime)

Wired by the SDK so a registered test device gets console tests instantly.

Parameters

fetch()Copy Anchor Link

Future<List<NexusInAppMessage>> fetch()

Fetch the active messages; on success, auto-show a session-start message.

Returns Future<List<NexusInAppMessage>>

onEvent()Copy Anchor Link

void onEvent(String name)

Called when an analytics event fires — shows a message triggered by it.

Parameters

show()Copy Anchor Link

void show(NexusInAppMessage m)

Show a specific message now (bypasses trigger, still respects frequency).

Parameters

tapButton()Copy Anchor Link

void tapButton(NexusInAppMessage m, NexusInAppButton b)

Handle a button tap: report the click, surface the action, auto-track event actions, copy copy values, then dismiss. Tappable images in a designed message come through here too, with the image block's id.

Parameters

dismiss()Copy Anchor Link

void dismiss(NexusInAppMessage m)

Dismiss the current message (X / backdrop tap).

Parameters

close()Copy Anchor Link

void close()

Clear the message from the screen.

dispose()Copy Anchor Link

void dispose()

NexusInAppActionCopy Anchor Link

Emitted when a user taps a button on an in-app message.

NexusInAppActionCopy Anchor Link

const NexusInAppAction({required this.messageId, required this.buttonId, required this.action, this.url, this.event, this.value, this.variantId})

Parameters

messageIdCopy Anchor Link

final String messageId

variantIdCopy Anchor Link

final String? variantId

The A/B variant the tap happened in, if any.

buttonIdCopy Anchor Link

final String buttonId

actionCopy Anchor Link

final String action

dismiss | url | event | copy.

urlCopy Anchor Link

final String? url

eventCopy Anchor Link

final String? event

valueCopy Anchor Link

final String? value

For copy: the text that was put on the clipboard.

NexusInAppButtonCopy Anchor Link

A button on an in-app message.

NexusInAppButtonCopy Anchor Link

const NexusInAppButton({required this.id, required this.text, required this.action, this.url, this.event, this.style, this.value})

Parameters

NexusInAppButton.fromJsonCopy Anchor Link

NexusInAppButton.fromJson(Map<String, dynamic> j)

Parameters

idCopy Anchor Link

final String id

textCopy Anchor Link

final String text

actionCopy Anchor Link

final String action

dismiss | url | event | copy (designed messages only).

urlCopy Anchor Link

final String? url

eventCopy Anchor Link

final String? event

valueCopy Anchor Link

final String? value

For copy: the text to put on the clipboard.

styleCopy Anchor Link

final String? style

primary | secondary | text.

NexusInAppMessageCopy Anchor Link

An in-app message the SDK can display (modal / banner / center / fullscreen).

NexusInAppMessageCopy Anchor Link

const NexusInAppMessage({required this.id, required this.layout, this.title, this.body, this.imageUrl, this.backgroundColor, this.textColor, this.buttons = const [], this.triggerType, this.triggerEvent, this.maxDisplays, this.perSession = false, this.design, this.variantId, this.isTest = false})

Parameters

NexusInAppMessage.fromJsonCopy Anchor Link

NexusInAppMessage.fromJson(Map<String, dynamic> j)

Parameters

idCopy Anchor Link

final String id

layoutCopy Anchor Link

final String layout

modal | bottom_sheet | banner_top | banner_bottom | center | fullscreen.

titleCopy Anchor Link

final String? title

bodyCopy Anchor Link

final String? body

imageUrlCopy Anchor Link

final String? imageUrl

backgroundColorCopy Anchor Link

final String? backgroundColor

textColorCopy Anchor Link

final String? textColor

buttonsCopy Anchor Link

final List<NexusInAppButton> buttons

triggerTypeCopy Anchor Link

final String? triggerType

session_start | event (null = show on fetch).

triggerEventCopy Anchor Link

final String? triggerEvent

maxDisplaysCopy Anchor Link

final int? maxDisplays

perSessionCopy Anchor Link

final bool perSession

designCopy Anchor Link

final NexusInAppDesign? design

The look designed in the console. Null for messages made before the designer — those render from title / body / imageUrl / buttons.

variantIdCopy Anchor Link

final String? variantId

The A/B variant this user was assigned (null when the message has no test).

isTestCopy Anchor Link

final bool isTest

A "send test" from the console: shown at once, outside triggers and caps, never reported.

NexusInAppDesignCopy Anchor Link

The designed look of an in-app message — built in the Nexus console's designer and delivered as content.design.

A vertical stack of blocks inside a styled frame. The backend validates and clamps every value before it is stored, so parsing here is lenient: anything missing falls back to the console's defaults, and an unknown block type is skipped rather than failing the whole message.

NexusInAppDesignCopy Anchor Link

const NexusInAppDesign({required this.blocks, required this.frame, required this.overlayColor, required this.dismissOnBackdropTap, required this.close, required this.animation, required this.autoDismissSeconds, required this.direction})

Parameters

tryParse()Copy Anchor Link

static NexusInAppDesign? tryParse(Object? raw)

Parameters

Returns NexusInAppDesign?

blocksCopy Anchor Link

final List<NexusInAppBlock> blocks

frameCopy Anchor Link

final NexusInAppFrame frame

overlayColorCopy Anchor Link

final Color overlayColor

Backdrop colour, opacity included (modal / sheet / center only).

dismissOnBackdropTapCopy Anchor Link

final bool dismissOnBackdropTap

closeCopy Anchor Link

final NexusInAppClose close

animationCopy Anchor Link

final String animation

fade | slide | zoom | none.

autoDismissSecondsCopy Anchor Link

final int autoDismissSeconds

0 = stays until dismissed.

directionCopy Anchor Link

final String direction

auto | ltr | rtl.

resolveDirection()Copy Anchor Link

TextDirection resolveDirection(TextDirection ambient)

auto follows the copy: right-to-left when the first strong character is Arabic / Hebrew script — the same rule the console preview uses.

Parameters

Returns TextDirection

NexusInAppFrameCopy Anchor Link

NexusInAppFrameCopy Anchor Link

const NexusInAppFrame({required this.background, required this.background2, required this.backgroundKind, required this.gradientAngle, this.backgroundImageUrl, required this.radius, required this.padding, required this.gap, required this.maxWidth, required this.shadow, required this.borderColor, required this.borderWidth})

Parameters

backgroundCopy Anchor Link

final Color background

background2Copy Anchor Link

final Color background2

backgroundKindCopy Anchor Link

final String backgroundKind

solid | gradient | image.

gradientAngleCopy Anchor Link

final double gradientAngle

CSS degrees: 180 = top to bottom.

backgroundImageUrlCopy Anchor Link

final String? backgroundImageUrl

radiusCopy Anchor Link

final double radius

paddingCopy Anchor Link

final double padding

gapCopy Anchor Link

final double gap

maxWidthCopy Anchor Link

final double maxWidth

shadowCopy Anchor Link

final String shadow

none | sm | md | lg.

borderColorCopy Anchor Link

final Color borderColor

borderWidthCopy Anchor Link

final double borderWidth

NexusInAppCloseCopy Anchor Link

NexusInAppCloseCopy Anchor Link

const NexusInAppClose({required this.show, required this.circle, required this.color, required this.atStart})

Parameters

showCopy Anchor Link

final bool show

circleCopy Anchor Link

final bool circle

colorCopy Anchor Link

final Color color

atStartCopy Anchor Link

final bool atStart

NexusInAppTapCopy Anchor Link

What tapping an image does.

NexusInAppTapCopy Anchor Link

const NexusInAppTap({required this.action, this.url, this.event})

Parameters

actionCopy Anchor Link

final String action

dismiss | url | event.

urlCopy Anchor Link

final String? url

eventCopy Anchor Link

final String? event

NexusInAppBlockCopy Anchor Link

sealed class NexusInAppBlock

One block of a designed message.

NexusInAppBlockCopy Anchor Link

const NexusInAppBlock(this.id)

Parameters

tryParse()Copy Anchor Link

static NexusInAppBlock? tryParse(Map<String, dynamic> j)

Parameters

Returns NexusInAppBlock?

idCopy Anchor Link

final String id

NexusInAppImageBlockCopy Anchor Link

class NexusInAppImageBlock extends NexusInAppBlock

NexusInAppImageBlockCopy Anchor Link

const NexusInAppImageBlock(super.id, {required this.url, this.aspectRatio, required this.contain, required this.radius, required this.bleed, this.tap})

Parameters

urlCopy Anchor Link

final String url

aspectRatioCopy Anchor Link

final double? aspectRatio

Null = the image's own ratio.

containCopy Anchor Link

final bool contain

radiusCopy Anchor Link

final double radius

bleedCopy Anchor Link

final bool bleed

Edge to edge — ignores the frame's padding.

tapCopy Anchor Link

final NexusInAppTap? tap

NexusInAppBadgeBlockCopy Anchor Link

class NexusInAppBadgeBlock extends NexusInAppBlock

NexusInAppBadgeBlockCopy Anchor Link

const NexusInAppBadgeBlock(super.id, {required this.text, required this.background, required this.foreground, required this.align})

Parameters

textCopy Anchor Link

final String text

backgroundCopy Anchor Link

final Color background

foregroundCopy Anchor Link

final Color foreground

alignCopy Anchor Link

final String align

NexusInAppHeadingBlockCopy Anchor Link

class NexusInAppHeadingBlock extends NexusInAppBlock

NexusInAppHeadingBlockCopy Anchor Link

const NexusInAppHeadingBlock(super.id, {required this.text, required this.size, required this.weight, required this.color, required this.align})

Parameters

textCopy Anchor Link

final String text

sizeCopy Anchor Link

final double size

weightCopy Anchor Link

final int weight

colorCopy Anchor Link

final Color color

alignCopy Anchor Link

final String align

NexusInAppTextBlockCopy Anchor Link

class NexusInAppTextBlock extends NexusInAppBlock

NexusInAppTextBlockCopy Anchor Link

const NexusInAppTextBlock(super.id, {required this.text, required this.size, required this.color, required this.align, required this.lineHeight})

Parameters

textCopy Anchor Link

final String text

sizeCopy Anchor Link

final double size

colorCopy Anchor Link

final Color color

alignCopy Anchor Link

final String align

lineHeightCopy Anchor Link

final double lineHeight

NexusInAppButtonsBlockCopy Anchor Link

class NexusInAppButtonsBlock extends NexusInAppBlock

NexusInAppButtonsBlockCopy Anchor Link

const NexusInAppButtonsBlock(super.id, {required this.row, required this.items})

Parameters

rowCopy Anchor Link

final bool row

Side by side (true) or stacked full-width (false).

itemsCopy Anchor Link

final List<NexusInAppDesignButton> items

NexusInAppCarouselBlockCopy Anchor Link

class NexusInAppCarouselBlock extends NexusInAppBlock

A swipeable row of up to 10 cards. Cards share the image shape and type sizes; all are as tall as the tallest, with buttons pinned to the bottom.

NexusInAppCarouselBlockCopy Anchor Link

const NexusInAppCarouselBlock(super.id, {required this.cards, required this.aspectRatio, required this.contain, required this.peek, required this.bleed, required this.radius, required this.gap, required this.padding, required this.titleSize, required this.bodySize, required this.showIndicator, required this.indicatorColor, required this.autoplaySeconds})

Parameters

cardsCopy Anchor Link

final List<NexusInAppCarouselCard> cards

aspectRatioCopy Anchor Link

final double aspectRatio

containCopy Anchor Link

final bool contain

peekCopy Anchor Link

final bool peek

Show the edge of the next card (cards are 84% wide).

bleedCopy Anchor Link

final bool bleed

Edge to edge — ignores the frame's side padding.

radiusCopy Anchor Link

final double radius

gapCopy Anchor Link

final double gap

paddingCopy Anchor Link

final double padding

titleSizeCopy Anchor Link

final double titleSize

bodySizeCopy Anchor Link

final double bodySize

showIndicatorCopy Anchor Link

final bool showIndicator

indicatorColorCopy Anchor Link

final Color indicatorColor

autoplaySecondsCopy Anchor Link

final int autoplaySeconds

0 = only by swiping.

NexusInAppCarouselCardCopy Anchor Link

NexusInAppCarouselCardCopy Anchor Link

const NexusInAppCarouselCard({required this.id, this.imageUrl, required this.title, required this.body, this.button, this.tap, required this.background, required this.titleColor, required this.bodyColor, required this.align})

Parameters

idCopy Anchor Link

final String id

Reported as the click's buttonId when the card itself is tapped.

imageUrlCopy Anchor Link

final String? imageUrl

titleCopy Anchor Link

final String title

bodyCopy Anchor Link

final String body

buttonCopy Anchor Link

final NexusInAppDesignButton? button

tapCopy Anchor Link

final NexusInAppTap? tap

backgroundCopy Anchor Link

final Color background

titleColorCopy Anchor Link

final Color titleColor

bodyColorCopy Anchor Link

final Color bodyColor

alignCopy Anchor Link

final String align

NexusInAppSpacerBlockCopy Anchor Link

class NexusInAppSpacerBlock extends NexusInAppBlock

NexusInAppSpacerBlockCopy Anchor Link

const NexusInAppSpacerBlock(super.id, {required this.height})

Parameters

heightCopy Anchor Link

final double height

NexusInAppDividerBlockCopy Anchor Link

class NexusInAppDividerBlock extends NexusInAppBlock

NexusInAppDividerBlockCopy Anchor Link

const NexusInAppDividerBlock(super.id, {required this.color, required this.thickness})

Parameters

colorCopy Anchor Link

final Color color

thicknessCopy Anchor Link

final double thickness

NexusInAppDesignButtonCopy Anchor Link

NexusInAppDesignButtonCopy Anchor Link

const NexusInAppDesignButton({required this.id, required this.text, required this.action, this.url, this.event, this.value, required this.variant, required this.background, required this.foreground, required this.radius})

Parameters

idCopy Anchor Link

final String id

textCopy Anchor Link

final String text

actionCopy Anchor Link

final String action

dismiss | url | event | copy.

urlCopy Anchor Link

final String? url

eventCopy Anchor Link

final String? event

valueCopy Anchor Link

final String? value

For copy: the text put on the clipboard.

variantCopy Anchor Link

final String variant

filled | outline | text.

backgroundCopy Anchor Link

final Color background

Fill (filled) or border (outline) colour.

foregroundCopy Anchor Link

final Color foreground

Label colour.

radiusCopy Anchor Link

final double radius

NexusInAppViewCopy Anchor Link

class NexusInAppView extends StatelessWidget

Default rendering for an in-app message. Bring your own UI via NexusInAppOverlay(messageBuilder: ...) if you'd rather.

NexusInAppViewCopy Anchor Link

const NexusInAppView({super.key, required this.message, required this.onButton, required this.onDismiss})

Parameters

messageCopy Anchor Link

final NexusInAppMessage message

onButtonCopy Anchor Link

final void Function(NexusInAppButton button) onButton

onDismissCopy Anchor Link

final VoidCallback onDismiss

NexusInAppDesignedViewCopy Anchor Link

class NexusInAppDesignedView extends StatefulWidget

Renders a message designed in the Nexus console: backdrop, placement for the layout, entrance animation, auto-dismiss, and the block stack.

Layout rules match the console preview exactly (padding, gap, edge-to-edge images, the close-button inset, shadows) — that is what makes the preview trustworthy. Fills the space it is given; NexusInAppOverlay gives it the whole screen.

NexusInAppDesignedViewCopy Anchor Link

const NexusInAppDesignedView({super.key, required this.message, required this.design, required this.onButton, required this.onDismiss})

Parameters

messageCopy Anchor Link

final NexusInAppMessage message

designCopy Anchor Link

final NexusInAppDesign design

onButtonCopy Anchor Link

final void Function(NexusInAppButton button) onButton

onDismissCopy Anchor Link

final VoidCallback onDismiss

NexusInAppBuilderCopy Anchor Link

typedef NexusInAppBuilder = Widget Function(BuildContext context, NexusInAppMessage message, void Function(NexusInAppButton button) onButton, VoidCallback onDismiss)

Bring your own in-app message UI. Return a widget; drive it with the provided callbacks (button tap / dismiss).

NexusInAppOverlayCopy Anchor Link

class NexusInAppOverlay extends StatefulWidget

Hosts the currently-active in-app message above your app. Add it via MaterialApp.builder so it has a Material/Overlay/MediaQuery ancestor:

MaterialApp(
  builder: (context, child) => NexusInAppOverlay(child: child!),
  // ...
)

NexusInAppOverlayCopy Anchor Link

const NexusInAppOverlay({super.key, required this.child, this.messageBuilder})

Parameters

childCopy Anchor Link

final Widget child

messageBuilderCopy Anchor Link

final NexusInAppBuilder? messageBuilder