Prerequisites

Do Flutter Get Started all the way until finishing step 4.

Step Summary

Add the Initialization code.
Add the Application class to the Manifest (in case you are using it)
Add the Tagged Wrappers, Tagged Buttons
Note the Transitions Events
Add the testing Single Data
Test everything is working
Change everything to production code
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(); //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:

Transitions events are detected by the single tag automatically after initialization. They happen when a navigation event occurs between two routes.
Button Presses when the R89Tag widget detects an onTap event for its child for a specified tag: attribute.

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

This step is for testing purposes and you are only going to see test ads when using this approach, but this is very helpful to us if you provide this peace of code to tell us where you want to place the ads.

Later when in production, this code will be removed and you have hopefully added flexible tagged wrappers and tagged all the button as possible so we can change your ad slots from the server without the need of updating the app.

Go into production

For going into production you will need to use your ids:

Remove the methods R89SDK.setDebug() and addTestingSingleTagData() .
Change the App ID in the manifest for the production one.
Change the GADApplicationIdentifier in the info.plist for the production one.
Change the appId and publisherId in the initialization method for the production ones.
it’s also recommended to remove R89SDK.setLogLevel(LogLevels.DEBUG) but not needed.

How does it work?

We monitor your app to determine the active route/screen at any given moment. For each route/screen, we maintain a record of events and tags that you have supplied, enabling us to place ads in those tagged views or during specific transitions and events from the record.

We have the capability to display Display ads on a tagged wrappers or trigger an Interstitial ads during the transition from one screen to another or in button press. And many other things All of this can be achieved without the need of coding specific triggers or manually adding the ad to the view. It is as simple as initializing the SDK.

Flutter Single Tag Implementation