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.

Initialize successfully before mounting this widget and use a Cards collection containing published content for the same API key. Give the widget a finite, positive width in your Flutter layout.

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 uses a provisional height and then updates to the measured native card height. Android starts at initialHeight or a cached measurement. iOS caps the provisional height to the available width and reuses a cached measurement only at the same width. 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.

Reloads and configuration changes#

reloadData() requests a native reload; its Future does not wait for onDataLoadComplete. A reload requested before the controller attaches is queued. The widget detaches its controller when disposed. Changing collectionId or context recreates the native Card view automatically; changing a deprecated argument has no effect. Use Themes for global Cards styling.

If Cards remain blank, inspect result.success and result.error, check the collection and its published content, and follow Troubleshooting. iOS does not provide a Cards count through this callback, so do not interpret a null dataCount as an empty collection.