Events
Attach event listeners to run custom logic when things happen in the widget — analytics, navigation overrides, custom actions, and more.
All onStory* props are renamed (drop noun prefix). The old names still fire with deprecation warnings until 4.0.0.
The type passed to callbacks changed from the old story shape to StorifyMeExperience; see the TypeScript reference.
Basic usage
import {
StorifyMeEnv,
StorifyMeError,
StorifyMeExperience,
StorifyMeOpenAction,
StorifyMeLinkTriggerCompletion,
StorifyMeWidget,
} from 'react-native-storifyme';
export default function App(): React.JSX.Element {
return (
<StorifyMeWidget
accountId={ACCOUNT_ID}
apiKey={API_KEY}
env={ENV}
widgetId={WIDGET_ID}
style={styles.box}
onLoad={(e) => {
const { widgetId, experiences } = e.nativeEvent;
console.log(
`Widget ${widgetId} loaded with ${experiences.length} experiences`
);
}}
onFail={(error: StorifyMeError) => {
console.log(`Error loading widget ${error}`);
}}
onOpened={(e) => {
const { experience, index } = e.nativeEvent;
console.log(`Opened: ${experience?.name} at index ${index}`);
}}
onFinished={(e) => {
const { experience, index } = e.nativeEvent;
console.log(`Finished: ${experience?.id} at index ${index}`);
}}
onClosed={(e) => {
const { experience } = e.nativeEvent;
console.log(`Closed: ${experience?.name}`);
}}
onShared={(e) => {
const { experience } = e.nativeEvent;
console.log(`Shared: ${experience?.name}`);
}}
onAction={(e) => {
const { type, data } = e.nativeEvent;
console.log(`On action: ${type}, data: ${JSON.stringify(data)}`);
}}
onEvent={(e) => {
const { type, data } = e.nativeEvent;
console.log(`On event: ${type}, event: ${JSON.stringify(data)}`);
}}
onShopping={(e) => {
const { type, data } = e.nativeEvent;
console.log(`onShopping: ${type}, data: ${JSON.stringify(data)}`);
}}
onExperienceWillOpen={async (e) => {
return StorifyMeOpenAction.OPEN;
}}
onLinkOpenTriggered={async (e) => {
return StorifyMeLinkTriggerCompletion.OPEN_LINK_BY_DEFAULT;
}}
/>
);
}
onLoad
Fires when the widget loads successfully. The event carries the widgetId and a list of all loaded experiences.
<StorifyMeWidget
onLoad={(e) => {
const { widgetId, experiences } = e.nativeEvent;
console.log(`Widget ${widgetId} loaded with ${experiences.length} experiences`);
}}
/>
onFail
Fires when the widget loading fails. Use this to hide the widget or retry loading.
<StorifyMeWidget
onFail={(error) => {
console.log(`Error loading widget ${error}`);
}}
/>
onOpened
Fires when the user opens an experience in the full-screen viewer.
<StorifyMeWidget
onOpened={(e) => {
const { experience, index } = e.nativeEvent;
console.log(`Opened: ${experience?.name} at index ${index}`);
}}
/>
onFinished
Fires when an experience completes naturally (plays through to the end). Useful for tracking completion rates and differentiating fully-watched experiences from dismissed ones.
Note: This fires only when the experience finishes playing. If the user closes before completion, only onClosed fires.
<StorifyMeWidget
onFinished={(e) => {
const { experience, index } = e.nativeEvent;
console.log(`Finished: ${experience?.id} at index ${index}`);
// Track completion analytics
// Award points or badges
// Trigger follow-up actions
}}
/>
Common use cases:
- Track experience completion rates for analytics
- Award engagement points when users complete an experience
- Trigger notifications or rewards after completion
- Differentiate completed vs dismissed experiences in metrics
onClosed
Fires when the user closes the full-screen viewer.
<StorifyMeWidget
onClosed={(e) => {
const { experience } = e.nativeEvent;
console.log(`Closed: ${experience?.name}`);
}}
/>
onShared
Fires when the user shares an experience.
<StorifyMeWidget
onShared={(e) => {
const { experience } = e.nativeEvent;
console.log(`Shared: ${experience?.name}`);
}}
/>
onAction
Fires when the user engages with an interactive component. Use this to override default behaviour — for example, open a product page inside the app instead of the website, or react to a quiz answer.
<StorifyMeWidget
onAction={(e) => {
const { type, data } = e.nativeEvent;
console.log(`On action: ${type}, data: ${JSON.stringify(data)}`);
}}
/>
onEvent
Fires on every analytics event (slide view, engaging element answer, etc.).
While this prop can collect analytics on your side, we suggest adding analytics processors in the StorifyMe admin app under integrations.
<StorifyMeWidget
onEvent={(e) => {
const { type, data } = e.nativeEvent;
console.log(`On event: ${type}, event: ${JSON.stringify(data)}`);
}}
/>
onShopping
Fires on every cart interaction. Supported types:
- CART_UPDATED — Happens every time the cart is changed
- CART_ITEM_ADDED — Happens when a product is added to the cart
- CART_ITEM_REMOVED — Happens when a product is removed from the cart
- CHECKOUT — Happens when the user clicks the Checkout button
<StorifyMeWidget
onShopping={(e) => {
const { type, data } = e.nativeEvent;
console.log(`onShopping: ${type}, data: ${JSON.stringify(data)}`);
}}
/>
Intercept widget item tap (onExperienceWillOpen)
Fires when the user taps an experience card before the viewer opens. Return StorifyMeOpenAction.OPEN to proceed normally or StorifyMeOpenAction.INTERCEPT to handle navigation yourself.
<StorifyMeWidget
onExperienceWillOpen={async (e) => {
const { experience } = e.nativeEvent;
if (experience?.deeplink && myApp.canHandle(experience.deeplink)) {
myApp.navigate(experience.deeplink);
return StorifyMeOpenAction.INTERCEPT; // SDK won't open viewer
}
return StorifyMeOpenAction.OPEN; // SDK opens viewer normally
}}
/>
Intercept link clicks (onLinkOpenTriggered)
Fires when the user taps a CTA, product tag, or any link inside the viewer.
<StorifyMeWidget
onLinkOpenTriggered={async (e) => {
if (e.nativeEvent.url.includes('custom-link')) {
console.log('Handling link manually:', e.nativeEvent.url);
return StorifyMeLinkTriggerCompletion.IGNORE_PRESENTING_LINK;
}
return StorifyMeLinkTriggerCompletion.OPEN_LINK_BY_DEFAULT;
}}
/>
If you need additional context about the link, retrieve it from onAction. The onAction event fires first, followed by onLinkOpenTriggered.
Click to view full code
import React, { useRef } from 'react';
import { View, NativeSyntheticEvent } from 'react-native';
import {
StorifyMeEnv,
StorifyMeWidget,
StorifyMeLinkTriggerCompletion,
} from 'react-native-storifyme';
export default function App(): React.JSX.Element {
// Refs to store data between events
const elementTypeRef = useRef<string | null>(null);
const buttonValueRef = useRef<string | null>(null);
// onAction handler
function onAction({
nativeEvent: { data, type },
}: NativeSyntheticEvent<{ type: string; data: any }>): void {
console.log('onAction:', data, type);
// Parse the "data" if it comes as a JSON string
const parsedData = typeof data === 'string' ? JSON.parse(data) : data;
// Extract "data" object
const buttonData = parsedData?.data;
// Extract button value
buttonValueRef.current = buttonData?.value ?? '';
// Extract the element type (e.g., BUTTON, PRODUCT_TAG, etc.)
elementTypeRef.current = type ?? '';
}
// onLinkOpenTriggered handler
async function onLinkOpenTriggered(
event: NativeSyntheticEvent<{ url: string }>
): Promise<StorifyMeLinkTriggerCompletion> {
// Example condition — replace with your own logic
const checkSomeCondition =
elementTypeRef.current === 'BUTTON' &&
buttonValueRef.current === event.nativeEvent.url;
// Reset after use
elementTypeRef.current = null;
buttonValueRef.current = null;
if (checkSomeCondition) {
// Prevent opening the link and handle manual link opening
return StorifyMeLinkTriggerCompletion.IGNORE_PRESENTING_LINK;
} else {
// Proceed with the default link handling
return StorifyMeLinkTriggerCompletion.OPEN_LINK_BY_DEFAULT;
}
}
return (
<StorifyMeWidget
accountId={ACCOUNT_ID}
apiKey={API_KEY}
env={ENV}
widgetId={WIDGET_ID}
style={styles.box}
onAction={onAction}
onLinkOpenTriggered={onLinkOpenTriggered}
/>
);
}
Prop reference (3.0.0)
| Prop | When it fires |
|---|---|
onLoad | Widget data loaded successfully |
onFail | Loading failed |
onOpened | User opened an experience in the viewer |
onFinished | All pages of an experience were viewed |
onClosed | Viewer was closed |
onShared | User shared an experience |
onExperienceWillOpen | User tapped a widget item — before viewer opens |
onLinkOpenTriggered | User tapped a link inside the viewer |
onAction | Custom action button triggered |
onEvent | Analytics event occurred |
onShopping | E-commerce interaction (cart, checkout) |
Migration from 2.x
| 2.x (deprecated, removed in 4.0.0) | 3.x |
|---|---|
onLoad={(stories) => {}} | onLoad={(e) => { const { widgetId, experiences } = e.nativeEvent; }} |
onStoryOpened={(story, index) => {}} | onOpened={(e) => { const { experience, index } = e.nativeEvent; }} |
onStoryClosed={(story) => {}} | onClosed={(e) => { const { experience } = e.nativeEvent; }} |
onStoryFinished={(story, index) => {}} | onFinished={(e) => { const { experience, index } = e.nativeEvent; }} |
onStoryShared={(story) => {}} | onShared={(e) => { const { experience } = e.nativeEvent; }} |
onStoryDeeplinkTriggered={async (e) => StorifyMeStoryDeeplinkTriggerCompletion.OPEN_STORY_BY_DEFAULT} | onExperienceWillOpen={async (e) => StorifyMeOpenAction.OPEN} |
StorifyMeStoryDeeplinkTriggerCompletion.OPEN_STORY_BY_DEFAULT | StorifyMeOpenAction.OPEN |
StorifyMeStoryDeeplinkTriggerCompletion.IGNORE_PRESENTING_STORY | StorifyMeOpenAction.INTERCEPT |