Ads

Introduction

The Storyteller SDK supports displaying ads that can be created in the Storyteller CMS (First Party Ads), as well as Ads from Google Ad Manager via an SDK extension developed by Storyteller.

Which source of ads is used can be configured on your behalf by a member of the Storyteller Delivery Team.

Storyteller First Party Ads

If your tenant is configured to use Storyteller First Party Ads, which can be managed in the Storyteller CMS, then no changes to the Storyteller integration code are necessary. The Ads code is managed entirely within the Storyteller SDK.

Storyteller GAM SDK

To use Ads from Google Ad Manager in Storyteller, first reach out to your Storyteller contact and they will assist you with setting up Google Ad Manager to traffic ads to Storyteller.

You will then need to use the Storyteller Google Ad Manager SDK plugin to fetch the ads from Google Ad Manager storyteller_gam_sdk. The plugin configures the native Storyteller GAM modules on both iOS and Android and forwards ad requests through a Dart callback.

Basic Setup

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

dependencies:
  storyteller_sdk: 11.0.0-alpha
  storyteller_gam_sdk: 11.0.0-alpha

Then install the dependencies:

flutter pub get

Configure the GAM module

Call StorytellerGAMModule.setup after Storyteller.initialize succeeds. Provide a StorytellerGAMModuleConfiguration that returns an ad unit ID for every request. You can also supply custom native template IDs and optional key-value pairs.

import 'package:storyteller_gam_sdk/storyteller_gam_sdk.dart';

Future<void> configureGam() async {
  await StorytellerGAMModule.setup(
    StorytellerGAMModuleConfiguration(
      adUnit: (StorytellerAdRequestInfo request) {
        if (request is StoriesAdRequestInfo) {
          return '/YOUR_STORIES_AD_UNIT_ID';
        }
        if (request is ClipsAdRequestInfo) {
          return '/YOUR_CLIPS_AD_UNIT_ID';
        }
        return 'YOUR_DEFAULT_AD_UNIT_ID';
      },
      customNativeTemplateIds: const StorytellerCustomNativeTemplateIds(
        stories: 'YOUR_STORIES_TEMPLATE_ID',
        clips: 'YOUR_CLIPS_TEMPLATE_ID',
      ),
      customKvps: () => {
        'appmode': 'prod'
      },
      enableDebugLogging: true,
    ),
  );
}

Call configureGam immediately after initialising Storyteller so requests are ready before the user opens a story or clip.

customKvps is evaluated on the native side before each ad request. The value produced during setup seeds the initial cache only; subsequent requests invoke the Dart callback again so you can pass dynamic state (for example, the current screen/entry point).

Understanding ad request payloads

Storyteller surfaces detailed context for every ad opportunity:

• StoriesAdRequestInfo
• placement – native placement code configured in Storyteller Studio.
• categories – list of category IDs associated with the story.
• story – ItemInfo describing the story and its categories.
• adIndex – zero-based index of the requested ad slot.
• ClipsAdRequestInfo
• collection – collection ID currently being viewed.
• clip – ItemInfo for the active clip.
• nextClip – optional ItemInfo for the clip that will follow.
• adIndex – zero-based index of the requested ad slot.

Use this metadata to return different ad units per placement, populate targeting parameters, or skip ads for particular scenarios.

Logging and troubleshooting

Set enableDebugLogging to true (the default) while integrating; the native SDKs mirror log lines to the Flutter console. For production builds you can switch it off.