Skip to main content
Version: 3.x.x

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

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​

App.tsx
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.

App.tsx
<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.

App.tsx
<StorifyMeWidget
onFail={(error) => {
console.log(`Error loading widget ${error}`);
}}
/>

onOpened​

Fires when the user opens an experience in the full-screen viewer.

App.tsx
<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.

App.tsx
<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.

App.tsx
<StorifyMeWidget
onClosed={(e) => {
const { experience } = e.nativeEvent;
console.log(`Closed: ${experience?.name}`);
}}
/>

onShared​

Fires when the user shares an experience.

App.tsx
<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.

App.tsx
<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.).

Adding different analytics

While this prop can collect analytics on your side, we suggest adding analytics processors in the StorifyMe admin app under integrations.

App.tsx
<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
App.tsx
<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.

App.tsx
<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
}}
/>

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

App.tsx
<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
App.tsx
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)​

PropWhen it fires
onLoadWidget data loaded successfully
onFailLoading failed
onOpenedUser opened an experience in the viewer
onFinishedAll pages of an experience were viewed
onClosedViewer was closed
onSharedUser shared an experience
onExperienceWillOpenUser tapped a widget item — before viewer opens
onLinkOpenTriggeredUser tapped a link inside the viewer
onActionCustom action button triggered
onEventAnalytics event occurred
onShoppingE-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_DEFAULTStorifyMeOpenAction.OPEN
StorifyMeStoryDeeplinkTriggerCompletion.IGNORE_PRESENTING_STORYStorifyMeOpenAction.INTERCEPT