Skip to main content
Version: 3.0.0-beta.1

Events

Attach event listeners to run custom logic when things happen in the widget — analytics, navigation overrides, custom actions, and more.

Version 3.0.0 changes

Story-prefixed callbacks were renamed; their old names remain available as deprecated callbacks during 3.x. onLoad and onAdDisplayed keep their names, but their parameters changed from StorifyMeStory to StorifyMeExperience, so update those method signatures.

Basic usage​

main.dart
class MyWidget extends StatefulWidget with NativeEventListener {

// Only override what you need — all methods have default no-ops


void onLoad(int widgetId, List<StorifyMeExperience> experiences) {
debugPrint('Loaded ${experiences.length} experiences for widget $widgetId');
}


void onFailed(StorifyMeError error) {
debugPrint('Widget ${error.widgetId} failed: ${error.message}');
}


void onOpened(StorifyMeExperience? experience, int index) {
debugPrint('Opened: ${experience?.name} (${experience?.type}) at index $index');
}


void onFinished(StorifyMeExperience? experience, int index) {
analytics.track('experience_completed', experience?.id);
}


void onClosed(StorifyMeExperience? experience) {
debugPrint('Closed: ${experience?.name}');
}


void onShared(StorifyMeExperience? experience) {
debugPrint('Shared: ${experience?.name}');
}

}

Handle experience navigation (onExperienceWillOpen)​

Fires when an experience has a navigation URL and the user requests that navigation. Read the URL from navigationUrl. Return StorifyMeOpenAction.open to let the SDK proceed or StorifyMeOpenAction.intercept if your app handled navigation.


Future<StorifyMeOpenAction> onExperienceWillOpen(StorifyMeExperience? experience) {
debugPrint('onExperienceWillOpen: $experience');
if (experience?.navigationUrl != null && myApp.canHandle(experience!.navigationUrl!)) {
myApp.navigate(experience.navigationUrl!);
return Future.value(StorifyMeOpenAction.intercept); // SDK won't open viewer
}
return Future.value(StorifyMeOpenAction.open); // SDK opens viewer normally
}

Fires when a user taps a CTA, product tag, or any link inside the viewer.


Future<StorifyMeLinkTriggerCompletion> onLinkTriggered(String url) {
debugPrint('onLinkTriggered: $url');
return Future.value(StorifyMeLinkTriggerCompletion.openLinkByDefault);
}

Content type discrimination​


void onOpened(StorifyMeExperience? experience, int index) {
switch (experience?.type) {
case StorifyMeExperienceType.story:
showStoryAnalytics(experience!);
break;
case StorifyMeExperienceType.shorts:
showShortsAnalytics(experience!);
break;
case StorifyMeExperienceType.snap:
showSnapAnalytics(experience!);
break;
case StorifyMeExperienceType.ad:
trackAdImpression(experience!);
break;
default:
break;
}
}

Commerce events​

Mix in StorifyMeCommerceListener and register it before initializing the SDK. It provides typed cart and checkout callbacks.

The listener includes onCartItemAdded, onCartItemRemoved, onCartUpdated, onCartCleared, and onCheckout.

class _MyAppState extends State<MyApp> with StorifyMeCommerceListener {

void onCartItemAdded(String productId, int quantity) {
cart.add(productId, quantity);
}


void onCheckout(StorifyMeCart cartSnapshot) {
debugPrint('Checkout ${cartSnapshot.total} ${cartSnapshot.currency}');
}
}

// During initState, before initPlugin:
_storifyMePlugin.setCommerceListener(this);

onShopping(type, dataJson) remains as a deprecated generic callback for existing integrations.

Typed interaction events​

StorifyMeInteractionListener provides structured action and analytics payloads while the legacy onAction and onEvent string callbacks remain available.

class _MyAppState extends State<MyApp> with StorifyMeInteractionListener {

void onInteractionAction(StorifyMeInteractionAction action) {
debugPrint('${action.type}: ${action.value}');
}


void onInteractionEvent(StorifyMeInteractionEvent event) {
analytics.track(event.action, event.context);
}


Future<StorifyMeLinkTriggerCompletion> onLinkTriggered(String url) async {
return StorifyMeLinkTriggerCompletion.openLinkByDefault;
}
}

// During initState, before initPlugin:
_storifyMePlugin.setInteractionListener(this);

The mixin also provides onLinkTriggered(url). Return StorifyMeLinkTriggerCompletion.openLinkByDefault or ignorePresentingLink to choose how links are handled.

Widget lifecycle and integrity events​

NativeEventListener also provides onSizeChanged(widgetId, height), onScrolled(widgetId, offsetX), and onIntegrityFailed(widgetId, experienceId, reason). Configure integrity keys using Params.INTEGRITY_PUBLIC_KEYS during SDK initialization; without keys, integrity checks are disabled.

onLinkOpenTriggered — deprecated compatibility callback​

NativeEventListener.onLinkOpenTriggered remains available for 2.x integrations. New code should use StorifyMeInteractionListener.onLinkTriggered and onInteractionAction.

Click to view full code
String? elementType;
String? buttonValue;


void onAction(String type, String dataJson) {
try {
// Extract "data" object
final Map<String, dynamic> dataMap = jsonDecode(dataJson);

// Extract the element type (e.g., BUTTON, PRODUCT_TAG, etc.)
elementType = dataMap['type'] as String?;

// Extract button value
final dataSection = dataMap['data'] as Map<String, dynamic>?;
buttonValue = dataSection?['value'] as String?;
} catch (e) {
elementType = null;
buttonValue = null;
}
}


Future<StorifyMeLinkTriggerCompletion> onLinkOpenTriggered(String url) {
// Declare a late Future variable to hold the completion result
late Future<StorifyMeLinkTriggerCompletion> completionFuture;

// Example condition — replace with your own logic
final checkSomeCondition = (elementType == 'BUTTON' && buttonValue == url);

if (checkSomeCondition) {
// Prevent opening the link and handle manual link opening
completionFuture = Future.value(StorifyMeLinkTriggerCompletion.ignorePresentingLink);
} else {
// Proceed with the default link handling
completionFuture = Future.value(StorifyMeLinkTriggerCompletion.openLinkByDefault);
}

// Reset values after handling the link open trigger
elementType = null;
buttonValue = null;

return completionFuture;
}

Callback reference (3.0.0)​

MethodWhen it fires
onLoad(widgetId, experiences)Widget data loaded successfully
onFailed(error)Loading failed with a structured StorifyMeError
onOpened(experience, index)User opened an experience in the viewer
onFinished(experience, index)All pages of an experience were viewed
onClosed(experience)Viewer was closed
onShared(experience)User shared an experience
onExperienceWillOpen(experience)User tapped a widget item — before viewer opens
onLinkTriggered(url)User tapped a link inside the viewer
onInteractionAction(action)Custom action button or interactive content triggered
onInteractionEvent(event)Analytics event occurred
StorifyMeCommerceListener callbacksCart or checkout interaction occurred
onSizeChanged(widgetId, height)Widget height changed
onScrolled(widgetId, offsetX)Widget scroll offset changed
onIntegrityFailed(widgetId, experienceId, reason)An experience failed signature verification

onFail(exceptionMessage) is retained as a deprecated callback for 2.x integrations.

Migration from 2.x​

2.x (deprecated, removed in 4.0.0)3.x
onLoad(int widgetId, List<StorifyMeStory> stories)onLoad(int widgetId, List<StorifyMeExperience> experiences)
onStoryOpened(StorifyMeStory story, int index)onOpened(StorifyMeExperience? experience, int index)
onStoryClosed(StorifyMeStory story)onClosed(StorifyMeExperience? experience)
onStoryShared(StorifyMeStory story)onShared(StorifyMeExperience? experience)
onStoryDeeplinkTriggered(StorifyMeStory? story) → StorifyMeStoryDeeplinkTriggerCompletiononExperienceWillOpen(StorifyMeExperience? experience) → StorifyMeOpenAction
StorifyMeStoryDeeplinkTriggerCompletion.openStoryByDefaultStorifyMeOpenAction.open
StorifyMeStoryDeeplinkTriggerCompletion.ignorePresentingStoryStorifyMeOpenAction.intercept