Core Building Block: STRWidgetController

STRWidgetController is a controller for Widgets in Storyly Placement SDK to access widget specific methods.

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

private var storyBarController: STRStoryBarController? = null

placementView.listener = object : STRListener {
    override fun onWidgetReady(
        widget: STRWidgetController, 
        ratio: Float
    ) {
        widget.storyBar { storyBarController = it }
    }
}

private var videoFeedController: STRVideoFeedController? = null

placementView.listener = object : STRListener {
    override fun onWidgetReady(
        widget: STRWidgetController, 
        ratio: Float
    ) {
        widget.videoFeed { videoFeedController = it }
    }
}

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

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.

storyBarController?.open(payload = uri)

videoFeedController?.open(payload = uri)

Open Fullscreen Content with Content IDs

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

storyBarController?.open(
    storyGroupId = "story_group_id",
    storyId = "story_id",   // optional
    play = STRStoryBarPlayMode.Default
)

videoFeedController?.open(
    groupId = "group_id",
    itemId = "item_id",     // optional
    play = STRVideoFeedPlayMode.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 StoryGroup for StoryBar / FeedGroup 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.

placementView.listener = object : STRListener {
    override fun onFail(
        widget: STRWidgetController, 
        payload: STRErrorPayload
    ) {
        payload.storyBar { barErrorPayload ->
            if (barErrorPayload.error == StoryBarError.StoryShowFailed) {
                // handle story show failure
            }
        }
    }
}

placementView.listener = object : STRListener {
    override fun onFail(
        widget: STRWidgetController, 
        payload: STRErrorPayload
    ) {
        payload.videoFeed { feedErrorPayload ->
            if (feedErrorPayload.error == VideoFeedError.FeedShowFailed) {
                // handle video feed show failure
            }
        }
    }
}