Skip to content

Quickstart Guide#

This guide walks through the basic Flutter integration steps:

  1. Add the storyteller_sdk dependency
  2. Initialize the SDK with your API key (and optional user identifier)
  3. Render a Storyteller widget in your UI

Prerequisites#

  • A Storyteller API key (provided by the Storyteller team)
  • Platform support:
  • iOS 13.0+
  • Android API 24+

1) Install the SDK#

Add the dependency to your app's pubspec.yaml:

dependencies:
  storyteller_sdk: ^11.6.5

Then fetch packages:

flutter pub get

For iOS, add both Storyteller CocoaPods sources above the CocoaPods CDN in the app's ios/Podfile:

source 'https://github.com/getstoryteller/storyteller-sdk-ios-podspec.git'
source 'https://github.com/getstoryteller/storyteller-lottie-ios-podspec.git'
source 'https://cdn.cocoapods.org/'

2) Initialize Storyteller#

Initialize Storyteller as early as possible (typically in main() before runApp). Provide your API key and optionally an externalId that maps to your user record.

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

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  final result = await Storyteller.initialize(
    'YOUR_API_KEY',
    externalId: 'YOUR_USER_ID', // optional
  );

  if (!result.success) {
    // Initialization failed. The message is a human-readable description.
    // You can also report this to your logging/analytics system.
    throw Exception(result.message ?? 'Storyteller initialization failed');
  }

  runApp(const MyApp());
}

Next:

  • If you use externalId, read Working with Users for user-related APIs.
  • If you need privacy controls, configure StorytellerEventTrackingOptions during initialization (see Privacy and Tracking).

Compare this to the Showcase bootstrap in lib/main.dart, which initializes storage, the deep-link service, and then restores the SDK session before runApp.

3) Render a Storyteller widget#

Storyteller provides multiple widgets for displaying Stories and Clips. A common starting point is a stories row:

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

class StoriesSection extends StatelessWidget {
  const StoriesSection({super.key});

  @override
  Widget build(BuildContext context) {
    return const SizedBox(
      height: 320,
      child: StorytellerStoriesRowView(
        // Optional: pass categories configured in Storyteller
        // categories: ['news', 'sports'],
      ),
    );
  }
}

See List Components for grids, clips lists, callbacks, and StorytellerListViewController.

Next steps#