What is Placement

Storyly Placement is a powerful, server-driven framework designed to dynamically render various widget experiences—such as Story Bars, Banners, and Swipe Cards—within a single host view. By decoupling the UI configuration from your app's codebase, Placement enables you to switch between different widget types in real-time without requiring a new app release.

📘

Placement Architecture

Server Driven Surface

Placement is a server-driven surface that can render different Storyly experiences (e.g., Story Bar, Banner) in a single host view, based on configuration and rules fetched at runtime.

Single Integration Point

It centralizes data loading, rendering, analytics, and commerce hooks via a single provider and a single view, enabling sophisticated, dynamic experiences without hardcoding which widget to show.

Core Building Blocks

These core building blocks are mandatory to integrate and start enabling features with Storyly Flows

📘

Placement Blocks

Placement Data Provider

It fetches and manages the content/config for a placement and exposes listener callbacks.

Placement View

It hosts the actual widget determined at runtime (e.g., Story Bar, Banner), exposes UI and analytics callbacks, and adapts its size to the selected widget.

Setup SDK

Import Module

Before you use Storyly Placement in your app, you must first add the Storyly Placement package.

yarn add storyly-placement-react-native

npm install storyly-placement-react-native

📘

Tip

You can find the latest version’s release notes here.

Android Installation

React Native standard auto-linking would be sufficient for Android side.

🚧

Warning

Storyly SDK targets Android API level 24 (Android 7.0, Nougat) or higher.

iOS Installation

You need to update Pods in project's iOS Side.

// this should be executed inside 'ios' folder
pod update

🚧

Warning

Storyly SDK targets iOS 12 or higher.

Fabric Support

This section explains how to enable or disable Fabric according to your project setup.

Storyly Placement supports both New (Fabric) and Legacy (Old) Architectures.

Android Installation

You need to set newArchEnabled property in the project's android/gradle.properties.

newArchEnabled=true

iOS Installation

You need to set RCT_NEW_ARCH_ENABLED flag in the project's ios/Podfile

export RCT_NEW_ARCH_ENABLED=1 && pod update

Initialize Components

This section explains how to set up and connect the core Placement components: data provider, placement view, and listener callbacks.

useStorylyPlacementProvider

You need to use the useStorylyPlacementProvider hook to initialize your data source. This should be done within your component.

import { useStorylyPlacementProvider, type StorylyPlacementConfig } from "storyly-placement-react-native";

const placementConfig: StorylyPlacementConfig = {
    token: "<your_placement_token_here>",
};

const placementListener = {
    onLoad: (event) => console.log("Data loaded", event),
    onLoadFail: (event) => console.error("Data load failed", event),
};

const placementProvider = useStorylyPlacementProvider(placementConfig, placementListener);

🚧

Warning

Please login to Storyly dashboard and get your placement token.

StorylyPlacement

This is the host view that actually changes widgets in and out based on the placement content. You attach it to your component tree and connect it to the provider.

import { StorylyPlacement } from "storyly-placement-react-native";

// ... inside your component
<StorylyPlacement
    style={{ width: "100%", height: placementHeight }}
    provider={placementProvider}
/>

Storyly Callbacks

Storyly Placement provides several listener callbacks that allow your application to react to changes in widget state, user interactions, and analytics events.

📘

Info

onWidgetReady

This callback is triggered when the active widget ready to render. It gives a width-to-height ratio for the best rendering of view.

onActionClicked

This callback is triggered when the user interacts with the widget’s action area (e.g., swipe-up or action button).

Placement Size Handling

This section explains how to resize the StorylyPlacement whenever the widget changes its size ratio.

import { useState } from "react";
import { Dimensions } from "react-native";
import { StorylyPlacement } from "storyly-placement-react-native";

// ... inside your component
<StorylyPlacement
    style={{ width: "100%", height: placementHeight }}
    provider={provider}
		onWidgetReady={handleWidgetReady}
/>  

const screenWidth = Dimensions.get('window').width;
const [placementHeight, setPlacementHeight] = useState(0);

const handleWidgetReady = (event) => {
    // Calculate target height using the reported ratio
    const targetHeight = screenWidth / event.ratio;
    setPlacementHeight(targetHeight);
};

🚧

Warning

You must test with different widget types in the Dashboard's Placement page to verify that dynamic sizing behaves as expected. You can use this as a verification step in your initialization.

Placement Action Handling

This section shows how to handle Swipe Up and Action Button clicks from user.

The redirection needs to be handled by the application itself when the end‑user clicks any action in the content. In order to handle this action, you must register onActionClicked callback.

import { useState } from "react";
import { Dimensions } from "react-native";
import { StorylyPlacement } from "storyly-placement-react-native";

// ... inside your component
<StorylyPlacement
    style={{ width: "100%", height: placementHeight }}
    provider={provider}
		onActionClicked={handleActionClicked}
/>    

const handleActionClicked = (event) => {
    const { url, payload, widget } = event;
    console.log(`onActionClicked: url=${url}, payload=${payload}`);
    // Handle navigation or custom product actions here.
};

🚧

Warning

Please confirm onActionClicked callback is triggered upon any action in the content. Make sure your app navigates correctly and check the logs to validate.

📘

Best Practices

• You must honor onWidgetReady for responsive UI.
• You must handle onActionClicked for navigation for actions of end‑user.