Prerequisites

Step Summary

  1. Add the Initialization code.

  2. Add the Application class to the Manifest (in case you are using it)

  3. Add the Tagged Wrappers, Tagged Buttons

  4. Note the Transitions Events

  5. Add the testing Single Data

  6. Test everything is working

  7. Change everything to production code

  8. Your app is now prepared for monetization with us.

Initialize the SDK

Use the R89SDK.initialize(,singleTag: true) method to initialize the SDK with enabled single tag functionality.

R89SDK.setLogLevel(LogLevel.debug); //This is for testing purposes, remove it on prod
R89SDK.setDebug(getLocalFakeData: true); //This is for testing purposes, remove it on prod

addTestingSingleTagData() /* This is a later step */

R89SDK.initialize(
      publisherId: "TestRefinery89ID", /* This is for testing purposes, change it on prod */
      appId: "TestDemoApp", /* This is for testing purposes, change it on prod */
      singleTag: true);

Your publisherId and appId will be provided to you during onboarding process by email, you can also retrieve them from the web interface after login.

This appID is not the same as the Manifest App Id or the Info.plist GADApplicationIdentifier you used in previous steps.

Add navigation observer.

Just before starting to put R89Tag widgets into your widget tree, make sure to add R89SDK.routeObserver to your navigatorObservers list

@override
Widget build(BuildContext context) {
  return MaterialApp(
    navigatorObservers: [
      R89SDK.routeObserver,
    ],
    // ...
  );
}

Tagged wrappers

Tagged Wrappers are the containers inside which the ads will show, they are normal widgets, called R89Tag with the tag: attribute set. You need to add as many as you can, remember that placing a tagged wrapper does not mean we need to use it.

In the sample below two R89Tag widgets are placed in a widget tree with pre-configured tag parameters.

@override
Widget build(BuildContext context) =>
    const Column(
      crossAxisAlignment: CrossAxisAlignment.center,
      children: <Widget>[
        // ...
        // The banner_tag will be replaced with the banner ad.
        R89Tag(tag: 'banner_tag'),
        // The outstream_tag will be replaced with the video outstream ad.
        R89Tag(tag: 'outstream_tag'),
        // ...
      ],
    );

The R89Tag widget can be used inside the scrollable widget as well (such as ListView.builder).

  @override
  Widget build(BuildContext context) =>
      ListView.builder(
        itemCount: 100,
        itemBuilder: (context, index) =>
            R89Tag(
              tag: 'scroll_tag',
              itemIndex: index,
              child: ListTile(
                leading: const Icon(
                  Icons.star_rounded,
                  color: Colors.amber,
                ),
                title: Text(features[index % features.length]),
              ),
            ),
      );

As you may notice, besides the tag parameter, the itemIndex is provided to R89Tag, which is used by the SDK to decide whether to display an ad for a given item position or not.

n a more complex scenario, If R89Tag is used in multiple scrollable widgets on the same screen, a key parameter needs to be specified for it. The key parameter uniquely identifies the scrollable widget. Use the ValueKey to identify the name of the scrollable widget.
In the sample below there are two scrollable widgets vertical and horizontal. The vertical one is a SliverList and the other is a horizontal ListView positioned at the index 3.

  @override
  Widget build(BuildContext context) =>
    Scaffold(
      body: CustomScrollView(
        slivers: [
          SliverList(
              delegate: SliverChildBuilderDelegate(
                  childCount: 40,
                      (context, index) =>
                  index != 3
                      ? R89Tag(
                      key: const ValueKey('v_scroll'),
                      tag: 'infinite_scroll',
                      itemIndex: index,
                      child: Text("Item $index"))
                      : KeepAliveWrapper(
                    child: SizedBox(
                      height: 400,
                      child: ListView.builder(
                        scrollDirection: Axis.horizontal,
                        itemCount: 40,
                        itemBuilder: (context, index) =>
                            R89Tag(
                              key: const ValueKey('h_scroll'),
                              tag: 'infinite_scroll',
                              itemIndex: index,
                              child: Text("Item $index"),
                            ),
                      ),
                    ),
                  ))),
        ],
      ),
    );

The R89Tag from the vertical list has a value key ValueKey('v_scroll') and the other from the horizontal list has ValueKey('h_scroll'). Those keys are used by the R89SDK to separate the scrollable widgets and apply the ad placement logic separately for each of them.

With this added to your views we can detect that tag and place an ad inside of it if the single tag data says so.

Events

Events can trigger other formats, right now the single tag supports:

Example of transition:

class MainPage extends StatelessWidget {
  ...
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: ListView(
        children: [
          ...
          ListTile(
            ...
            onTap: () {
              Navigator.of(context).push(MaterialPageRoute(
                  builder: (context) => const NewsPostDetailsPage(),
                  // Specify the route name.
                  settings: const RouteSettings(name: 'NewsPostDetailsPage')));
            },
          ),
        ],
      ),
    );
  }
}

class NewsPostDetailsPage extends StatelessWidget {
  ...
}

In this example an interstitial would be triggered when we see the NewsPostDetailsPage comes to live after loading.

Example of button press:

with this button code

class MainPage extends StatefullWidget {
  ...
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: ListView(
        children: [
          ...
          R89Tag(
            tag: 'play_video_trailer_tag',
            child: ListTile(
              ...
              title: const Text('Play Video'),
              onTap: () => playVideoTrailer(),
            ),
          ),
          ...
        ],
      ),
    );
  }
}

In this example an interstitial would be triggered when the button is pressed and when the interstitial is closed the playVideoTrailer() method will be executed.

Adding testing single tag data

Go back to the point where the SDK was initialized at the start of the guide, we are going to test all the transitions, tagged wrappers, and tagged buttons you have placed in the app.

Before the initialization method, we called addTestingSingleTagData() which uses the R89SDK.singleTagConfiguration to add the testing data needed for debugging the SDK.

More info in → Flutter How To Test Single Tag Implementation

When using the SingleTagConfigBuilder you are not going to be able to select the ad units that are for production, they are by default the testing config id in Flutter - Ad Formats.

void addTestingSingleTagData() {
  R89SDK.singleTagConfiguration
  // Define the initial route name as the main screen
    ..initialRouteName = '/'

  // Configure the main screen with ad placements
    ..addAdScreenConfig(
        adScreenConfig: AdScreenConfig(screenName: '/')
        // Add a banner inside the wrapper with the tag 'main_page_bottom_ad_container'
          ..addBanner(
            tag: 'main_page_bottom_ad_container',
            getAllWithTag: false, // Only use the first tagged wrapper in "/"
            wrapperRelativePositionAfter: true, // Place the ad after the child of R89Tag(child:...)
          )
        // Trigger an interstitial when transitioning from "MainPage" ("/") to "NewsPostDetailPage"
          ..addInterstitial(eventToTrack: 'NewsPostDetailPage')
        // Trigger an interstitial when a child of R89Tag(tag:'play_video_trailer_tag',child:...) is pressed
          ..addInterstitial(eventToTrackButton: 'play_video_trailer_tag')
    );
}