Playwire Flutter SDK #

Playwire Flutter SDK is a plugin developed by Playwire for in-app monetization.
It bridges the Playwire native SDKs (Android/iOS) into Flutter and exposes a simple Dart API for initialization and loading/showing ads.

Requirements

• Flutter >= 3.22.0
• Dart >= 3.4.0
• Android MinAPI >= 23
• iOS deployment target >= 13.0

1. Import Playwire SDK #

Android #

Playwire Flutter SDK for Android is consumed from a remote GitHub Packages repository. Although public, GitHub still requires authentication. For more information on authentication, see the official GitHub Package's guide.

• Add authentication using your Github credentials in android/build.gradle.kts

allprojects {
    repositories {
        maven {
            name = "GithubPackages"
            url = uri("https://maven.pkg.github.com/intergi/playwire-android-binaries")
            credentials {
                username = "USERNAME"
                password = "PASSWORD"
            }
        }

        maven {
            url = uri("https://android-sdk.is.com/")
        }
        maven {
            url = uri("https://artifact.bytedance.com/repository/pangle/")
        }
        maven {
            url = uri("https://cboost.jfrog.io/artifactory/chartboost-ads/")
        }
        maven {
            url = uri("https://dl-maven-android.mintegral.com/repository/mbridge_android_sdk_oversea")
        }
        maven {
            url = uri("https://repo.pubmatic.com/artifactory/public-repos/")
        }
        maven {
            url = uri("https://maven.ogury.co")
        }
        maven {
            url = uri("https://s3.amazonaws.com/smaato-sdk-releases/")
        }
        maven {
            url = uri("https://verve.jfrog.io/artifactory/verve-gradle-release")
        }
    }
}

• Add the repositories to your app/build.gradle.kts

repositories {  
    maven("https://android-sdk.is.com/")  
    maven("https://artifact.bytedance.com/repository/pangle/")  
    maven("https://cboost.jfrog.io/artifactory/chartboost-ads/")  
    maven("https://dl-maven-android.mintegral.com/repository/mbridge_android_sdk_oversea")  
    maven("https://repo.pubmatic.com/artifactory/public-repos/")  
    maven("https://maven.ogury.co")  
    maven("https://s3.amazonaws.com/smaato-sdk-releases/")  
    maven("https://verve.jfrog.io/artifactory/verve-gradle-release")  
}

• Add dependencies in app/build.gradle.kts

a) Standard/NonCOPPA

implementation(platform("com.google.firebase:firebase-bom:34.4.0"))
implementation "com.intergi.playwire:playwiresdk_total:11.6.0"

b) COPPA

implementation(platform("com.google.firebase:firebase-bom:34.4.0"))
implementation "com.intergi.playwire:playwiresdk_coppa:11.6.0"

iOS #

a) Standard/NonCOPPA

Add Playwire pod to your Podfile

pod 'Playwire'

b) COPPA

pod 'Playwire/Coppa'

Flutter #

Add playwire_flutter to your pubspec.yaml

flutter pub add playwire_flutter

2. Setup Consent Management #

a) Standard/NonCOPPA #

Option A: Let Playwire Manage Consent

If you plan to use Playwire for consent management, no additional work is needed.

Playwire SDK provides Google User Messaging Platform (UMP) support out of the box. This flow will automatically be triggered when Playwire SDK is initialized.

Option B: Your own CMP solution

To use your own CMP platform, ensure that the CMP flow is triggered before initializing the Playwire SDK.

Let Playwire SDK know that another CMP flow was used.

Playwire.setCMP(CMPType.alreadyLaunched)

b) COPPA #

COPPA apps should disable sharing of personal information.

Playwire.setCMP(CMPType.none)

3. Add Google Ad Manager to Info.plist #

This is specific to your app and will be provided to you by your account manager.

Android #

Add the GAM App ID to your app's AndroidManifest.xml.

<meta-data  
  android:name="com.google.android.gms.ads.AD_MANAGER_APP"  
  android:value="true"/>  
<meta-data  
  android:name="com.google.android.gms.ads.APPLICATION_ID"  
  android:value="PROVIDED_BY_ACCOUNT_MANAGER"/>

iOS #

Add GADApplicationIdentifier in your app's Info.plist file.

<key>GADIsAdManagerApp</key>
<true/>
<key>GADApplicationIdentifier</key>
<string>PROVIDED_BY_ACCOUNT_MANAGER</string>

4. Declaring IDFA (iOS) #

a) Standard/NonCOPPA #

This step is needed to ensure IDFA (Advertiser ID) is sent to advertisers.

Add NSUserTrackingUsageDescription to your app's Info.plist file

<key>NSUserTrackingUsageDescription</key>
<string>This identifier will be used to deliver personalized ads to you.</string>

The description will appear as part of the IDFA alert with the consent form.

b) COPPA #

Skip this step for a COPPA app.

5. SKAdNetwork (iOS) #

In your app's Info.plist file, add SKAdNetworks listed in this file: https://app.intergient.com/skadnetworkitems/skadnetworkitems.xml

Consult the following links for more info:

• https://developer.apple.com/documentation/storekit/skadnetwork
• https://developer.apple.com/documentation/storekit/configuring-a-source-app

6. Initialize #

Initialize the Playwire SDK with your publisherId and appId provided by your account manager. This is ideally done right after app start. This step needs to be taken before ads are requested.

await Playwire.initialize(publisherId: publisherId, appId: appId);

7. Request ads #

Once the SDK is initialized, you can request ads.

The following is an example of loading a banner ad.

import 'package:flutter/material.dart';
import 'package:logging/logging.dart';
import 'package:playwire_flutter/playwire.dart';

class BannerWidget extends StatelessWidget {
  final String adUnitId;

  const BannerWidget({super.key, required this.adUnitId});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
        body: Align(
          alignment: Alignment.center,
          child: PlaywireBannerView(
            adUnitId: adUnitId,
            autoload: true,
            onAdLoaded: () {
              Logger.root.fine("Banner loaded");
            },
            onAdFailedToLoad: ({code, message}) {
              Logger.root.fine("Banner failed to load");
            },
            onAdImpression: () {
              Logger.root.fine("Banner impression");
            },
            onAdClicked: () {
              Logger.root.fine("Banner ad clicked");
            },
            width: 320,
            height: 50
          ),
        )
    );
  }
}

Requesting ads #

App Open #

An app open ad is an ad unit for publishers who want to monetize their app’s loading or splash screen. It appears to users when they open or switch back to the app. This ad unit is recommended for apps with a high frequency of opens per daily user.

To implement an app open ad, call Playwire.loadAppOpen with the ad unit alias given by your account manager. When the ad is done loading, call Playwire.showAppOpen.

import 'dart:async';

import 'package:flutter/material.dart';
import 'package:playwire_flutter/event_types.dart';
import 'package:playwire_flutter/playwire.dart';

class AppOpenWidget extends StatefulWidget {
  final String adUnitId;

  const AppOpenWidget({super.key, required this.adUnitId});

  @override
  State<AppOpenWidget> createState() => _AppOpenWidgetState();
}

class _AppOpenWidgetState extends State<AppOpenWidget> {
  StreamSubscription? sub;

  @override
  void initState() {
    super.initState();

    sub = Playwire.events.listen((e) {
      if (e.category != PlaywireEventCategory.appOpen) {
        return;
      }

      switch (e.appOpen) {
        case AppOpenEventType.loaded:
          _showAppOpen();
          break;
        case AppOpenEventType.loadFailed:
          break;
        case AppOpenEventType.failedToOpen:
          break;
        case AppOpenEventType.closed:
          break;
        default:
          break;
      }
    });
  }

  @override
  void dispose() {
    sub?.cancel();
    super.dispose();
  }

  Future<void> _loadAppOpen() async {
    Playwire.loadAppOpen(adUnitId: widget.adUnitId);
  }

  Future<void> _showAppOpen() async {
    Playwire.showAppOpen(widget.adUnitId);
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: FutureBuilder(
          future: _loadAppOpen(),
          builder: (context, asyncSnapshot) {
            return Container(
              color: Theme.of(context).colorScheme.surface,
              child: const Row(),
            );
          }
      ),
    );
  }
}

Banner #

Banner ads are rectangular ads that appear within the app, either at the top or bottom of the screen. They may stay on screen while users interact with the app, and can be refreshed automatically or manually under specific conditions.

To implement a banner ad, use the PlaywireBannerView widget to show a banner ad with the given width and height.

import 'package:flutter/material.dart';
import 'package:playwire_flutter/playwire.dart';

class BannerWidget extends StatelessWidget {
  final String adUnitId;

  const BannerWidget({super.key, required this.adUnitId});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
        body: Align(
          alignment: Alignment.center,
          child: PlaywireBannerView(
            adUnitId: adUnitId,
            autoload: true,
            onAdLoaded: () {},
            onAdFailedToLoad: ({code, message}) {},
            onAdImpression: () {},
            onAdClicked: () {},
            width: 320,
            height: 50
          ),
        )
    );
  }
}

Refreshing banner ads

Let your account manager know if you want the banner ad to refresh automatically or not. Currently, there is no support for manually refreshing a banner ad.

Interstitial #

Interstitial ads are full-screen ads that cover the entire screen.

To implement an interstitial ad, call Playwire.loadInterstitial with the ad unit alias given by your account manager. When the ad is done loading, call Playwire.showInterstitial.

import 'dart:async';

import 'package:flutter/material.dart';
import 'package:playwire_flutter/event_types.dart';
import 'package:playwire_flutter/playwire.dart';

class InterstitialWidget extends StatefulWidget {
  final String adUnitId;

  const InterstitialWidget({super.key, required this.adUnitId});

  @override
  State<InterstitialWidget> createState() => _InterstitialWidgetState();
}

class _InterstitialWidgetState extends State<InterstitialWidget> {
  StreamSubscription? sub;

  @override
  void initState() {
    super.initState();

    sub = Playwire.events.listen((e) {
      if (e.category != PlaywireEventCategory.interstitial) {
        return;
      }

      switch (e.interstitial) {
        case InterstitialEventType.loaded:
          _showInterstitial();
          break;
        case InterstitialEventType.loadFailed:
          break;
        case InterstitialEventType.failedToOpen:
          break;
        case InterstitialEventType.closed:
          break;
        default:
          break;
      }
    });
  }

  @override
  void dispose() {
    sub?.cancel();
    super.dispose();
  }

  Future<void> _loadInterstitial() async {
    await Playwire.loadInterstitial(adUnitId: widget.adUnitId);
  }

  Future<void> _showInterstitial() async {
    await Playwire.showInterstitial(widget.adUnitId);
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
        body: FutureBuilder(
          future: _loadInterstitial(),
          builder: (context, asyncSnapshot) {
            return Container(
              color: Theme.of(context).colorScheme.surface,
              child: const Row(),
            );
          }
        )
    );
  }
}

Rewarded #

A rewarded ad is a full-screen ad that covers the app's interface until a user closes it. This ad offers users a chance to get in-app rewards in exchange for watching a video ad or engaging in a playable ad. These rewards are configured during the ad unit creation.

To implement a rewarded ad, call Playwire.loadRewarded with the ad unit alias given by your account manager. When the ad is done loading, call Playwire.showRewarded.

import 'dart:async';

import 'package:flutter/material.dart';
import 'package:playwire_flutter/event_types.dart';
import 'package:playwire_flutter/playwire.dart';

class Rewarded extends StatefulWidget {
  final String adUnitId;

  const Rewarded({super.key, required this.adUnitId});

  @override
  State<Rewarded> createState() => _RewardedState();
}

class _RewardedState extends State<Rewarded> {
  StreamSubscription? sub;

  @override
  void initState() {
    super.initState();

    sub = Playwire.events.listen((e) {
      if (e.category != PlaywireEventCategory.rewarded) {
        return;
      }

      switch (e.rewarded) {
        case RewardedEventType.loaded:
          _showRewarded();
          break;
        case RewardedEventType.loadFailed:
          break;
        case RewardedEventType.failedToOpen:
          break;
        case RewardedEventType.closed:
          break;
        default:
          break;
      }
    });
  }

  @override
  void dispose() {
    sub?.cancel();
    super.dispose();
  }

  Future<void> _loadRewarded() async {
    await Playwire.loadRewarded(adUnitId: widget.adUnitId);
  }

  Future<void> _showRewarded() async {
    await Playwire.showRewarded(widget.adUnitId);
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
        body:  FutureBuilder(
            future: _loadRewarded(),
            builder: (context, asyncSnapshot) {
              return Container(
                color: Theme.of(context).colorScheme.surface,
                child: const Row(),
              );
            }
        )
    );
  }
}

Debugging and Targeting #

Test Mode #

You can enable test mode for the SDK if you want to see test ads. Without test ads enabled, you may not see any ads in local development. Do not have test ads enabled in production.

Playwire.setTest(true);

Logging #

You can turn on logs for the SDK by turning on the console logger.

Playwire.startConsoleLogger();