React Native
React Native components for StorySDK using WebView to display stories.
SDK token
To get SDK token go to app settings page and copy SDK token:

Installation
NPM
npm install @storysdk/react-native react-native-webview
Yarn
yarn add @storysdk/react-native react-native-webview
Usage
StoryGroups
Component for displaying a list of story groups:
import { StoryGroups } from '@storysdk/react-native';
// In your component
<StoryGroups
token="YOUR_TOKEN"
onGroupClick={(groupId) => {
// Handle group click
setSelectedGroupId(groupId);
}}
groupImageWidth={80}
groupImageHeight={80}
groupTitleSize={14}
/>
StoryModal
Component for displaying stories in a modal window:
import { StoryModal } from '@storysdk/react-native';
// In your component
<StoryModal
token="YOUR_TOKEN"
groupId={selectedGroupId}
onClose={() => setSelectedGroupId(null)}
storyWidth={300}
storyHeight={600}
/>
Onboarding Implementation
For onboarding flows, use the StoryModal
component with an Onboarding ID instead of a regular groupId:
import { StoryModal } from '@storysdk/react-native';
// For onboarding implementation
<StoryModal
token="YOUR_TOKEN"
groupId="ONBOARDING_ID" // Use your Onboarding ID here
onClose={() => setOnboardingComplete(true)}
/>
Important: When an Onboarding ID is specified, the modal window will open automatically. Only use the StoryModal
component for onboarding implementations.
Props
StoryGroups
token
(required) - SDK token for accessing StorySDKonGroupClick
- Handler for group click eventsgroupImageWidth
- Width of group image in pixelsgroupImageHeight
- Height of group image in pixelsgroupTitleSize
- Font size of group title in pixelsgroupClassName
- CSS class for styling individual groupgroupsClassName
- CSS class for styling groups containeractiveGroupOutlineColor
- Outline color for active groupgroupsOutlineColor
- Outline color for all groupsarrowsColor
- Color of navigation arrowsbackgroundColor
- Background color of the componentonError
- Error handler callback that receives error detailsonEvent
- Event handler callback that receives event type and associated data
StoryModal
token
(required) - SDK token for accessing StorySDKgroupId
- Group ID to display (or Onboarding ID for onboarding flows)onClose
- Handler for modal close eventstoryWidth
- Width of story in pixelsstoryHeight
- Height of story in pixelsisShowMockup
- Whether to show device mockup around storiesisShowLabel
- Whether to show labelsisStatusBarActive
- Whether status bar is activeautoplay
- Automatically play through storiesarrowsColor
- Color of navigation arrowsbackgroundColor
- Background color of the componentforbidClose
- Prevent modal from being closed (useful for critical onboarding flows)onError
- Error handler callback that receives error detailsonEvent
- Event handler callback that receives event type and associated data
SDK Events
StoryGroups
and StoryModal
components can handle the following events through the onEvent
prop:
groupClose
- Group of stories closedgroupOpen
- Group of stories openedstoryClose
- Story closedstoryOpen
- Story openedstoryNext
- Navigation to next storystoryPrev
- Navigation to previous storywidgetAnswer
- User response to a widgetwidgetClick
- Widget clickstoryModalOpen
- Modal window openedstoryModalClose
- Modal window closedgroupClick
- Story group clicked
onEvent Usage Example
import React, { useState } from 'react';
import { View } from 'react-native';
import { StoryGroups, StoryModal } from '@storysdk/react-native';
const App = () => {
const [selectedGroupId, setSelectedGroupId] = useState(null);
const handleEvent = (eventType, eventData) => {
console.log(`Event: ${eventType}`, eventData);
// Example of handling a specific event
if (eventType === 'widgetClick') {
console.log('User clicked on a widget:', eventData);
}
};
return (
<View style={{ flex: 1 }}>
<StoryGroups
token="YOUR_TOKEN"
onGroupClick={setSelectedGroupId}
onEvent={handleEvent}
/>
<StoryModal
token="YOUR_TOKEN"
groupId={selectedGroupId}
onClose={() => setSelectedGroupId(null)}
onEvent={handleEvent}
/>
</View>
);
};
export default App;
Usage Example
Standard Story Implementation
import React, { useState } from 'react';
import { View } from 'react-native';
import { StoryGroups, StoryModal } from '@storysdk/react-native';
const App = () => {
const [selectedGroupId, setSelectedGroupId] = useState(null);
return (
<View style={{ flex: 1 }}>
<StoryGroups
token="YOUR_TOKEN"
onGroupClick={setSelectedGroupId}
/>
<StoryModal
token="YOUR_TOKEN"
groupId={selectedGroupId}
onClose={() => setSelectedGroupId(null)}
/>
</View>
);
};
export default App;
Onboarding Implementation
import React, { useState, useEffect } from 'react';
import { View } from 'react-native';
import { StoryModal } from '@storysdk/react-native';
import AsyncStorage from '@react-native-async-storage/async-storage';
const App = () => {
const [showOnboarding, setShowOnboarding] = useState(false);
// Check if user has completed onboarding
useEffect(() => {
const checkOnboardingStatus = async () => {
try {
const onboardingCompleted = await AsyncStorage.getItem('onboardingCompleted');
if (onboardingCompleted !== 'true') {
setShowOnboarding(true);
}
} catch (error) {
console.error('Error checking onboarding status:', error);
}
};
checkOnboardingStatus();
}, []);
const handleOnboardingComplete = async () => {
try {
await AsyncStorage.setItem('onboardingCompleted', 'true');
setShowOnboarding(false);
} catch (error) {
console.error('Error saving onboarding status:', error);
}
};
return (
<View style={{ flex: 1 }}>
{/* Your app content */}
{/* Onboarding modal */}
<StoryModal
token="YOUR_TOKEN"
groupId={showOnboarding ? "ONBOARDING_ID" : null}
onClose={handleOnboardingComplete}
forbidClose={false} // Set to true if onboarding must be completed
/>
</View>
);
};
export default App;
Media Background Playback Permissions
For proper background media playback (audio/video), you need to configure additional permissions in your project:
iOS
Add the following to your iOS project's Info.plist
file:
<key>UIBackgroundModes</key>
<array>
<string>audio</string>
</array>
If you encounter the error ProcessAssertion::acquireSync Failed to acquire RBS assertion 'WebKit Media Playback'
, you may need to add additional entitlements to your project:
Create or edit the
.entitlements
file in your iOS project rootAdd the following entitlements:
<key>com.apple.runningboard.assertions.webkit</key>
<true/>
<key>com.apple.multitasking.systemappassertions</key>
<true/>
In Xcode, go to project settings > Signing & Capabilities and add the "Background Modes" capability, then enable the "Audio, AirPlay, and Picture in Picture" option
Android
Add the following to your Android project's AndroidManifest.xml
:
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
These permissions are necessary to ensure continuous media playback even when the app is minimized or the screen is locked.
Last updated
Was this helpful?