Quick Start Guide

Getting your application token

• Log in to the Storyfyd dashboard (storyfyd.io).
• Navigate to: Settings → SDK.
• Copy your application token and pass it to your init() or configure() method.

Security best practices

Never hardcode your application token directly in client-side bundles. Fetch it securely from your own backend at runtime.

// ❌ Źle — token widoczny w źródle strony
storyfydWeb.init({ token: 'eyJ0eXAiOiJKV1...' });

// ✅ Dobrze — token pobrany z własnego backendu w runtime
const res = await fetch('/api/storyfyd-token');
const { token } = await res.json();
storyfydWeb.init({ token });

Passing user data from the SDK

The id field is sent via the X-User-Id header. The remaining attributes (name, email, labels, custom) are JSON-serialized into a single X-User header. The exact same format applies across Web, React, and iOS SDKs.

user: {
  id: 'user123',               // → nagłówek X-User-Id
  name: 'John Doe',
  email: '[email protected]',
  labels: ['vip', 'lang_pl'],   // steruje targetowaniem Audiences
  custom: { plan: 'pro' }       // dostępne tylko w tokenach personalizacji {{plan}}
}
// name, email, labels, custom trafiają razem do wspólnego nagłówka X-User (JSON)

Targeting with labels in the dashboard

• In the Storyfyd dashboard, go to Audiences and create a new Audience of type "Labels".
• Name it exactly as the label value sent in the SDK's labels array (e.g. label "vip" requires an Audience named "vip") — the match is exact.
• In Story Group settings, add an include or exclude rule referencing that Audience to show or hide content for viewers matching that label.

Example use case: language-targeted content (PL / EN)

Labels provide an effortless way to display different Story Groups based on user language or customer segment — without touching SDK code, configured entirely in the dashboard.

• On SDK init, pass labels based on the user's selected language, e.g. labels: ['lang_pl'] or labels: ['lang_en'].
• In Audiences, create two Labels-type Audiences: "lang_pl" and "lang_en".
• Create dedicated Story Groups for each language and assign the matching Audience as an include rule — Polish customers see Polish Stories, and English-speaking users see English Stories.

Custom properties & content personalization

Fields passed under custom (e.g. { plan: 'pro' }) do not affect Audience targeting — they are stored on the viewer's profile and used exclusively for resolving personalization tokens ({{plan}}) inside the story creator.

Where user data comes from

Storyfyd does not manage your end-user sessions — your own application knows who is currently logged in. Fetch their id, email, labels, and custom attributes from your auth/database layer and pass them to the SDK on initialization.

Full list of init() parameters

Component props for <StoryfydWidget />

useStoryfyd() hook — programmatic control

import { useStoryfyd } from '@storyfyd/sdk-react';

function MyComponent() {
  const storyfyd = useStoryfyd('YOUR_TOKEN', {
    onReady: () => console.log('Ready!')
  });

  return (
    <div>
      <storyfyd-web ref={storyfyd.ref} />
      <button onClick={storyfyd.play}>Play</button>
      <button onClick={storyfyd.pause}>Pause</button>
      <button onClick={storyfyd.close}>Close</button>
      <button onClick={() => storyfyd.navigate(0, 0)}>Navigate</button>
    </div>
  );
}

configure() parameters

StoryfydConfiguration — visual styling

StoryfydDelegate methods

In-app navigation (Deep Links)

Buttons, SwipeUp gestures, and clickable images can navigate directly inside your app (e.g. to a specific product screen). Set the appUrl field in the Storyfyd creator. When tapped, the SDK invokes storyfydShouldHandleURL(_:) on your delegate before falling back to opening an external browser.

• Register your app's custom URL scheme in the dashboard: Settings → SDK → App URL Scheme.
• Use this scheme in the appUrl field in the story creator (e.g. yourscheme://product?id=42).
• Return true from storyfydShouldHandleURL to handle navigation yourself — the viewer closes automatically, and you perform navigation inside storyfydDidCloseViewer().

final class AppDeepLinkHandler: StoryfydDelegate {
    var pendingRoute: AppRoute?
    private var routeAfterClose: AppRoute?

    func storyfydShouldHandleURL(_ url: URL) -> Bool {
        guard let route = AppRoute(url: url) else { return false }
        routeAfterClose = route
        return true // viewer zamknie się automatycznie
    }

    // Wywoływane po zakończeniu animacji zamknięcia viewera
    func storyfydDidCloseViewer() {
        guard let route = routeAfterClose else { return }
        pendingRoute = route
        routeAfterClose = nil
    }
}

Integration with UIKit applications

StoryfydDelegate is a standard Swift protocol — it works identically in UIKit projects. Embed the stories view by wrapping it in a UIHostingController, and handle deep links exactly as you would in SwiftUI.

class MyDeepLinkHandler: StoryfydDelegate {
    weak var navigationController: UINavigationController?

    func storyfydShouldHandleURL(_ url: URL) -> Bool {
        guard url.scheme == "yourscheme" else { return false }
        return true  // handle recognised scheme, let SDK close the viewer
    }

    func storyfydDidCloseViewer() {
        guard ... else { return }
        // navigate after the viewer is fully dismissed
        let vc = ProductViewController()
        navigationController?.pushViewController(vc, animated: true)
    }
}

// In your UIViewController:
let handler = MyDeepLinkHandler()
handler.navigationController = navigationController

let storiesView = StoryfydStoriesView(delegate: handler)
let hostingVC = UIHostingController(rootView: storiesView)
hostingVC.view.frame = CGRect(x: 0, y: 0, width: view.bounds.width, height: 120)
addChild(hostingVC)
view.addSubview(hostingVC.view)
hostingVC.didMove(toParent: self)

Deep link execution flow

• User taps a CTA element configured with appUrl: "yourscheme://product?id=42".
• The SDK calls storyfydShouldHandleURL(_:) → your delegate returns true.
• The story viewer smoothly closes.
• storyfydDidCloseViewer() is called.
• Your app transitions to the destination screen (e.g. product details or checkout).

Stories are not loading

Common causes: missing or invalid API token, wrong API host, or CORS restrictions. Inspect the browser console and Network tab for HTTP 401/403 errors or blocked cross-origin requests.

Widget does not render in React

Make sure the web script is loaded before the React component mounts, your token is valid, and no CORS errors appear in the console.

Background video does not autoplay

Modern browsers permit video autoplay only when muted — the SDK sets this automatically. Also verify that your video uses MP4 (H.264) or WebM format and that CORS headers on your asset server permit streaming.

Props do not update dynamically in React

The widget initializes once on mount. To force re-initialization when the token or user changes, pass a dynamic key prop: <StoryfydWidget key={token} />.