Core Building Block: STRWidgetController

STRWidgetController is the base controller for all widgets in the Storyly Placement SDK. It provides access to common methods like opening content via a deep link URI, pausing, and resuming.

To use these methods, your application should hold a reference to the StorylyPlacementController obtained from the onStorylyPlacementCreated callback, and then resolve the widget controller from the onWidgetReady callback. If you need widget-specific functionality (like opening by ID), you can resolve a typed controller (e.g., STRStoryBarController) via getWidget.

StorylyPlacementController? _controller;
STRWidgetController? _widgetController;
STRStoryBarController? _storyBarController;

// ... inside your build method
StorylyPlacementView(
  provider: _provider,
  onStorylyPlacementCreated: (controller) {
    _controller = controller;
  },
  onWidgetReady: (event) {
    // Hold base controller for general methods (e.g., open with URI)
    _widgetController = _controller?.getWidget<STRWidgetController>(event.widget);

    // Hold typed controller for widget-specific methods (e.g., open with IDs)
    _storyBarController =
        _controller?.getWidget<STRStoryBarController>(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 (Android) and Info.plist (iOS) files.

🚧

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.

_widgetController?.open(uri: uri);

Open Fullscreen Content with Content IDs

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

_storyBarController?.openWithId(
  storyGroupId: "story_group_id",
  storyId: "story_id",   // optional
  playMode: "default",
);

_videoFeedController?.openWithId(
  feedGroupId: "feed_group_id",
  feedId: "feed_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. You set them via the playMode parameter of openWithId.

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 (playMode: "default").

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. The onFail callback is triggered when the content could not be opened due to invalid parameters or inactive content for that user. The STRErrorPayload exposes the event name and a human-readable message.

StorylyPlacementView(
  provider: _provider,
  onStorylyPlacementCreated: (controller) {
    _controller = controller;
  },
  onFail: (event) {
    final payload = event.payload;
    debugPrint(
      'Placement fail on ${event.widget.type}: '
      'event=${payload.event}, message=${payload.message}',
    );
    // handle content show failure
  },
)