Core Building Block: STRWidgetController

STRWidgetController is a controller for Widgets in Storyly Placement SDK to access widget specific methods/apis. You need use a generic PlacementWidget to access a typed widget controller.

Application needs to hold a reference to the controller obtained from the onWidgetReady callback of StorylyPlacement to open content.

const placementRef = useRef<StorylyPlacementMethods>(null);
const storyBarWidgetRef = useRef<PlacementWidget | null>(null);

<StorylyPlacement
    ref={placementRef}
    provider={provider}
    onWidgetReady={(event) => {
        if (event.widget.type === 'story-bar') {
            storyBarWidgetRef.current = event.widget;
        }
    }}
/>

const placementRef = useRef<StorylyPlacementMethods>(null);
const videoFeedWidgetRef = useRef<PlacementWidget | null>(null);

<StorylyPlacement
    ref={placementRef}
    provider={provider}
    onWidgetReady={(event) => {
        if (event.widget.type === 'video-feed') {
            videoFeedWidgetRef.current = event.widget;
        }
    }}
/>

Deep Links to Content

This guide shows you how to handle deep links in your application and open a fullscreen content programmatically.

Storyly Dashboard generates a deep link with the application's predefined custom scheme.

🚧

Warning

You need to set the URL Scheme in the Storyly Dashboard -> Settings -> Apps & Websites -> URL Scheme in order to get the deep links properly from the dashboard.

🚧

Warning

Make sure that the application schema is defined in your application's AndroidManifest.xml file.

🚧

Warning

Make sure that the application schema is defined in your application's Info.plist file.

🚧

Warning

Application needs to handle intent routing, determine from the URL's host whether it is related to Storyly and pass the related URI to the Storyly Placement SDK to open content. The host will be storyly for Storyly Dashboard generated deep link URLs.

Open Fullscreen Content with Deep Link URI

You need to pass the deep link to the open method of the controller.

const storyBarController = placementRef.current?.getWidget<STRStoryBarController>(storyBarWidgetRef.current);
storyBarController?.open({ uri: url });

const videoFeedController = placementRef.current?.getWidget<STRVideoFeedController>(videoFeedWidgetRef.current);
videoFeedController?.open({ uri: "your-deeplink-uri" });

Open Fullscreen Content with Content IDs

You need to pass the content ids to the open method of the controller.

const storyBarController = placementRef.current?.getWidget<STRStoryBarController>(storyBarWidgetRef.current);
storyBarController?.openWithId({
    storyGroupId: "story_group_id",
    storyId: "story_id",   // optional
    playMode: "default"
});

const videoFeedController = placementRef.current?.getWidget<STRVideoFeedController>(videoFeedWidgetRef.current);
videoFeedController?.openWithId({
    groupId: "group_id",
    itemId: "item_id",     // optional
    playMode: "default"
});

Play Modes in Content Links

Play Modes are used to define the behavior of the content when it is opened. StoryBar and VideoFeed follow the same play modes.

• Playing to the End

This mode plays the content to the end starting from the specified content and then closes the fullscreen content. This is the default play mode.

• Playing a Single Content Group

This mode plays only the specified group starting from the specified content. You need to define the play mode as "story-group" for StoryBar / "feed-group" for VideoFeed.

• Playing a Single Content Item

This mode plays only the specified item. You need to define the play mode as "story" for StoryBar / "feed" for VideoFeed.

Setup Listeners

You need to set up listeners to handle events from the open methods. StoryShowFailed is triggered the content could not be opened due to invalid parameters or inactive content for that user.

<StorylyPlacement
    ref={placementRef}
    provider={provider}
    onFail={(event) => {
        if (event.widget.type === 'story-bar') {
            if (event.payload.event === 'StoryShowFailed') {
                // handle story show failure
                console.log('StoryBar StoryShowFailed:', event.payload.message);
            }
        }
    }}
/>

<StorylyPlacement
    ref={placementRef}
    provider={provider}
    onFail={(event) => {
        if (event.widget.type === 'video-feed') {
            if (event.payload.event === 'FeedShowFailed') {
                // handle video feed show failure
                console.log('VideoFeed FeedShowFailed:', event.payload.message);
            }
        }
    }}
/>