Storyteller Home Component

StorytellerHomeView is a widget that allows multiple Stories and Clips Rows or Grids to be embedded in a single screen in your application in a list.

How to Use

The code samples below show how to use the StorytellerHomeView widget in Flutter. The component includes built-in pull-to-refresh support on both iOS and Android platforms, and you can also use the controller's reloadData() method to refresh data programmatically.

Mount Home after successful SDK initialization, using a valid Home configuration for the same API key. The sample below fills the bounded Scaffold body; use Expanded or another finite size when placing Home in a Column.

Basic Usage

Create a StorytellerHomeView widget by passing the required homeId parameter. The widget accepts the following parameters:

• homeId - (required) an identifier of the home configuration you want to load.
• theme - an optional theme parameter to be used for styling. If no theme is supplied, the global theme set via Storyteller.setTheme(...) is used.
• uiStyle - an optional parameter for overriding the appearance of the component. Possible values are 'light', 'dark', and 'auto'. The default styling is 'auto' and it uses the system setting value.
• context - optional context data that will be included in analytics callbacks for attribution. This allows you to track which sources drive engagement with your home content. See Analytics for more details.
• controller - an optional StorytellerHomeViewController for programmatic control of the view.

import 'package:flutter/material.dart';
import 'package:storyteller_sdk/storyteller_sdk.dart';

class MyHomePage extends StatefulWidget {
  const MyHomePage({Key? key}) : super(key: key);

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  final StorytellerHomeViewController _controller = StorytellerHomeViewController();

  @override
  void dispose() {
    _controller.detach();
    super.dispose();
  }

  void _refreshContent() {
    // Programmatically refresh the home content
    _controller.reloadData();
  }

  @override
  Widget build(BuildContext context) {
    // Create a custom theme
    final theme = StorytellerTheme(
      // Customize the theme
      light: ThemeType(
        // Add your theme settings
        lists: ThemeLists(
          backgroundColor: '#FFFFFF',
        ),
      ),
    );

    return Scaffold(
      appBar: AppBar(
        title: const Text('Storyteller Home'),
        actions: [
          IconButton(
            icon: const Icon(Icons.refresh),
            onPressed: _refreshContent,
          ),
        ],
      ),
      body: StorytellerHomeView(
        homeId: 'YOUR_HOME_ID',
        controller: _controller,
        theme: theme,
        uiStyle: 'auto',
        context: {
          'source': 'main-tab',
          'user_segment': 'premium',
          'variant': 'personalized',
        },
      ),
    );
  }
}

For a live reference, the Showcase account tab renders this widget in StorytellerHomeScreen with an on-screen homeId picker and manual reload actions.

Reload and lifecycle

Home loads its configured content natively and provides built-in pull-to-refresh. reloadData() requests a refresh; its Future is not a content-load completion event. A call made before the controller attaches is queued for attachment. The widget detaches its controller on disposal.

homeId, theme, uiStyle, and context configure the native view at creation. Recreate the widget with a new key to apply changed configuration; reloading the same native view keeps its existing configuration. Flutter Home does not expose data-load or tile callbacks. Use list widgets when you need those callbacks, and Troubleshooting when a configured Home renders no content.