Events
Attach event listeners to run custom logic when things happen in the widget — analytics, navigation overrides, custom actions, and more.
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
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
}
Intercept link clicks (onLinkTriggered)
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)
| Method | When 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 callbacks | Cart 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) → StorifyMeStoryDeeplinkTriggerCompletion | onExperienceWillOpen(StorifyMeExperience? experience) → StorifyMeOpenAction |
StorifyMeStoryDeeplinkTriggerCompletion.openStoryByDefault | StorifyMeOpenAction.open |
StorifyMeStoryDeeplinkTriggerCompletion.ignorePresentingStory | StorifyMeOpenAction.intercept |