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 StorySDK
* `onGroupClick` - Handler for group click events
* `groupImageWidth` - Width of group image in pixels
* `groupImageHeight` - Height of group image in pixels
* `groupTitleSize` - Font size of group title in pixels
* `groupClassName` - CSS class for styling individual group
* `groupsClassName` - CSS class for styling groups container
* `activeGroupOutlineColor` - Outline color for active group
* `groupsOutlineColor` - Outline color for all groups
* `arrowsColor` - Color of navigation arrows
* `backgroundColor` - Background color of the component
* `onError` - Error handler callback that receives error details
* `onEvent` - Event handler callback that receives event type and associated data
#### StoryModal
* `token` (required) - SDK token for accessing StorySDK
* `groupId` - Group ID to display (or Onboarding ID for onboarding flows)
* `onClose` - Handler for modal close event
* `storyWidth` - Width of story in pixels
* `storyHeight` - Height of story in pixels
* `isShowMockup` - Whether to show device mockup around stories
* `isShowLabel` - Whether to show labels
* `isStatusBarActive` - Whether status bar is active
* `autoplay` - Automatically play through stories
* `arrowsColor` - Color of navigation arrows
* `backgroundColor` - Background color of the component
* `forbidClose` - Prevent modal from being closed (useful for critical onboarding flows)
* `onError` - Error handler callback that receives error details
* `onEvent` - 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 closed
* `groupOpen` - Group of stories opened
* `storyClose` - Story closed
* `storyOpen` - Story opened
* `storyNext` - Navigation to next story
* `storyPrev` - Navigation to previous story
* `widgetAnswer` - User response to a widget
* `widgetClick` - Widget click
* `storyModalOpen` - Modal window opened
* `storyModalClose` - Modal window closed
* `groupClick` - Story group clicked
#### onEvent Usage Example
```tsx
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 (
setSelectedGroupId(null)}
onEvent={handleEvent}
/>
);
};
export default App;
```
### Usage Example
#### Standard Story Implementation
```tsx
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 (
setSelectedGroupId(null)}
/>
);
};
export default App;
```
#### Onboarding Implementation
```tsx
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 (
{/* Your app content */}
{/* Onboarding modal */}
);
};
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:
```xml
UIBackgroundModes
audio
```
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:
1. Create or edit the `.entitlements` file in your iOS project root
2. Add the following entitlements:
```xml
com.apple.runningboard.assertions.webkit
com.apple.multitasking.systemappassertions
⚡️ Please note that in order for stories to be displayed in the SDK, they need to be published.
### Onboarding
NVExtentedActivityIndicatorView
```swift
import UIKit
import StorySDK
import NVActivityIndicatorView
class NVExtentedActivityIndicatorView: UIView, SRLoader {
var indicator: NVActivityIndicatorView = NVActivityIndicatorView.ballSpin()
init() {
super.init(frame: CGRect(x: 0, y: 0, width: 72, height: 72))
addSubview(indicator)
}
required init?(coder: NSCoder) {
fatalError("init(coder:) has not been implemented")
}
func startAnimating() {
indicator.startAnimating()
}
func stopAnimating() {
indicator.stopAnimating()
}
}
```
Lottie
```swift
import UIKit
import StorySDK
import Lottie
class LottieLoadingIndicatorView: UIView, SRLoader {
var indicator: LottieAnimationView!
init() {
super.init(frame: CGRect(x: 0, y: 0, width: 24, height: 24))
indicator = LottieAnimationView(name: "equalizer-icon")
addSubview(indicator)
}
required init?(coder: NSCoder) {
fatalError("init(coder:) has not been implemented")
}
func startAnimating() {
indicator.play()
}
func stopAnimating() {
indicator.stop()
}
}
```
or even
Rive
```swift
import UIKit
import StorySDK
import RiveRuntime
class RiveLoadingIndicatorView: UIView, SRLoader {
var model = RiveViewModel(fileName: "Screencut_Logo_Loader")
var indicator: RiveView!
init() {
super.init(frame: CGRect(x: 0, y: 0, width: 80, height: 80))
indicator = model.createRiveView()
addSubview(indicator)
indicator.frame = bounds
}
required init?(coder: NSCoder) {
fatalError("init(coder:) has not been implemented")
}
func startAnimating() {
model.play()
}
func stopAnimating() {
model.stop()
}
}
```
***
In additional you also can handle custom method defined in dashboard (using `onWidgetMethodCall` from `SRStoryWidgetDelegate` protocol) for instance define action on onboarding close event or request rate your during onboarding. Like this:
```swift
func onWidgetMethodCall(_ selectorName: String?) {
guard let selectorName else { return }
switch selectorName {
case "onboarding-finished":
setupFinished()
case "scrollNext":
if !onRateDisplayed {
onRateDisplayed = true
rate()
}
default:
break
}
}
```
### License
StorySDK is available under the MIT license. See the LICENSE file for more info.
### Example project
You can see an example of usage [here](https://github.com/StorySDK/story-ios-sdk-example).
# Cordova
This guide describes how to add and use StorySDK to Cordova app
## SDK token
To get SDK token go to app settings page and copy SDK token:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Your Page Title</title>
<script src="https://cdn.jsdelivr.net/npm/@storysdk/core@latest/dist/bundle.umd.js"></script>
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@storysdk/core@latest/dist/bundle.css">
</head>
<body>
<!-- Place your HTML element with SDK token here -->
<div id="storysdk" data-storysdk-token="YOUR_SDK_TOKEN"></div>
<!-- Other content on your page -->
</body>
</html>
and Google servers for analytics tracking. For example, add the following code to the **``** section:
```html
audio
```
⚡️ Please note that in order for stories to be displayed in the SDK, they need to be published.
## Customisation
By specifying the following data attributes in the HTML tag, you can control the appearance, behavior, and functionality of the SDK directly from HTML without additional JavaScript configuration.
* **`data-storysdk-group-image-width`**\
Specifies the width of the group image in pixels, controlling how large the group’s main image will appear.
* **`data-storysdk-group-image-height`**\
Sets the height of the group image, allowing you to control the image’s vertical display size.
* **`data-storysdk-group-title-size`**\
Adjusts the font size of the group title, so you can set the desired emphasis for the group title text.
* **`data-storysdk-group-class-name`**\
Allows a custom CSS class to be applied to the individual group elements. Use this to apply unique styling to each group.
* **`data-storysdk-groups-class-name`**\
Adds a custom CSS class to the container for multiple groups. This is useful for controlling overall styling for the collection of groups.
* **`data-storysdk-autoplay`**\
Enables autoplay for stories if set to `"true"`. The stories will play automatically without requiring user interaction.
* **`data-storysdk-group-id`**\
Identifies a specific group ID to load within the SDK, allowing targeted display of group content when autoplay is enabled.
* **`data-storysdk-start-story-id`**\
Sets the initial story to display when the SDK opens, letting you direct users to a specific story.
* **`data-storysdk-forbid-close`**\
Prevents users from closing the SDK interface if set to `"true"`. Useful for mandatory viewing scenarios.
* **`data-storysdk-is-show-mockup`**\
Displays the story content within a device mockup if set to `"true"`, providing a preview within a simulated device frame.
* **`data-storysdk-is-status-bar-active`**\
Activates a status bar at the top of the story if set to `"true"`, helping indicate story progress.
* **`data-storysdk-open-in-external-modal`**\
Opens stories within an external modal if set to `"true"`. This is useful if you want to display content in a standalone modal overlay.
* **`data-storysdk-groups-outline-color`**\
Specifies a custom outline color for groups. This is useful for visually highlighting or differentiating specific groups within the interface.
* **`data-storysdk-active-group-outline-color`**\
Specifies a custom outline color for the active group or for the group when hovered over. This helps emphasize the currently selected or focused group in the interface.
Example of usage:
```html
```
# Create account
Description of all the steps to create a StorySDK account
**1) Registration**
To access all the features of StorySDK, you need to create an account. There are two registration options available:
* Register via email
* Register via Google