Quickstart Guide

This is a developers' guide for setting up Storyteller for native Flutter apps. This guide will cover the basic technical steps for initializing the Storyteller SDK, authenticating a user, and adding a StorytellerStoriesRowView to your app.

Resources

You can use the Storyteller Flutter Showcase App to help you set up Storyteller in your Flutter app.

How to Add the SDK to Your Project

Before you can add the Flutter SDK to your app, you will need to obtain an API Key. This is a secret key used to authenticate the SDK in your app. Throughout this document it will be marked as [APIKEY].

SDK Installation

Add Storyteller package to your app's pubspec.yaml:

dependencies:
  storyteller_sdk: 11.0.0-alpha

Then install the dependencies:

flutter pub get

SDK Initialization

Make sure the Flutter bindings are initialised and call Storyteller.initialize before running your app. Provide the API key from the Storyteller dashboard and an optional externalId so that user activity can be associated with a known profile.

Before using the Flutter SDK in your app, initialize a Storyteller by using the initialize(String, externalId: String?) method.

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',
  );

  if (!result.success) {
    // handle error
  }

  runApp(const MyApp());
}

Initialization errors:

• invalidAPIKeyError: when an invalid API key is used
• networkError: when the call to load the settings for the SDK fails (i.e. a non-success HTTP status code is returned)
• networkTimeoutError: when the call to load the settings for the SDK times out
• jsonParseError: when a malformed settings response is received from the server

Storyteller.initialize is asynchronous, so Storyteller.isInitialized will change its value to true only when the asynchronous call finishes. For any subsequent Storyteller.initialize call, Storyteller.isInitialized will already be true.

Implementing StorytellerDelegate Callbacks

Storyteller has callbacks for events which can be implemented, see StorytellerDelegate for more details.

External User IDs

You can optionally use externalId to authenticate a user on the API.

For more information about Users and External IDs please see Working with Users

Adding a StorytellerStoriesRowView

Use any of the provided widgets to surface Storyteller content. For a scrollable grid of stories, drop the widget directly into your widget tree and supply the category identifiers you have configured in Storyteller.

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(),
    );
  }
}

Other layout options include StorytellerStoriesGridView, StorytellerClipsRowView, StorytellerClipsGridView, and StorytellerEmbeddedClipsView. All widgets rely on the native Android (API 24+) and iOS (13.0+) Storyteller SDKs that are bundled with the plugin.