Skip to content

Cards#

StorytellerCardView embeds a native Storyteller Cards collection in your Flutter layout. The native iOS and Android SDKs render the card content, while Flutter passes configuration, analytics context, reload requests, and size updates across the platform-view bridge.

Basic usage#

class CardsSection extends StatefulWidget {
  const CardsSection({super.key});

  @override
  State<CardsSection> createState() => _CardsSectionState();
}

class _CardsSectionState extends State<CardsSection> {
  final _controller = StorytellerCardViewController();

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

  @override
  Widget build(BuildContext context) {
    return StorytellerCardView(
      collectionId: 'featured-cards',
      controller: _controller,
      context: const {
        'screen': 'home_feed',
        'placement': 'feed_item',
      },
      onDataLoadComplete: (result) {
        if (!result.success) {
          debugPrint('Cards failed to load: ${result.error}');
        }
      },
    );
  }

  Future<void> refreshCards() async {
    await _controller.reloadData();
  }
}

Key parameters:

  • collectionId - the Storyteller Cards collection to render. Supply a non-blank value to render native Cards content.
  • context - optional analytics attribution metadata.
  • controller - optional StorytellerCardViewController for programmatic reloads.
  • initialHeight - finite, positive placeholder height until native content reports its measured size. The default is 760.
  • onDataLoadComplete(StorytellerCardLoadResult result) - called when native data loading finishes. Android also reports dataCount; iOS reports success or failure. Error payloads include type and message, with causeMessage when the native platform exposes an underlying cause.

Upgrade compatibility#

The constructor keeps the older optional storyId, clipId, theme, and onTileTapped arguments as deprecated source-compatibility shims. They do not enable legacy card content. A StorytellerCardView without a non-blank collectionId renders no content.

Sizing behaviour#

Cards can change height after native content loads. StorytellerCardView starts at initialHeight and then updates to the measured native card height. The default is intentionally tall enough to avoid composing too many off-screen native Card views before Android reports the measured size, while still letting the native SDK own the final height.

For a full feed integration, review the Showcase StorytellerCardWidget.