A Flutter plugin to display ads from Appodeal. It currently supports Banner, MREC, Interstitial, Reward and Non-Skippable ads.
⚠ Package Archived ⚠ - Please use the official Appodeal package from now on
This project was created by me when there was no official support for Appodeal on Flutter. But now that the Appodeal team created their own official package I don't see a reason to keep maintaining this one.
I thank everybody that downloaded, contributed with PRs an supported this package.
- Add the dependency to the
pubspec.yaml
file in your project:
dependencies:
appodeal_flutter: # use the latest version
- Install the plugin by running the command below in the terminal, in your project's root directory:
$ flutter pub get
- Follow the Appodeal installation instructions available for iOS and Android. However, ignore the steps to include the Appodeal SDK dependencies in Gradle (Android) and Cocoapods (iOS) since these steps will be done by this package.
-
The Appodeal framework includes mutiple libraries from different ad providers, so it's very likely that the inclusion of this plugin in your project will make it exceed to 64K limit method count of Android. To solve this problem you need to enable multidex in your project; follow the instructions here to learn how to do that.
-
Your Android project must use Gradle 4.0.1 or greater. If you are using an older version, please upgrade it by editing the file
android/build.gradle
.
- Follow the instructions available here to learn how to implement the permission request to track users, but ignore the part to include some code in the
AppDelegate
file. This code is already included in this plugin and it will be executed when you call the functionAppodeal.requestIOSTrackingAuthorization()
, before the initialization of Appodeal (see below).
This plugin comes with all possible ad networks supported by Appodeal enabled by default. I made this decision to give more flexibility to the developers using this project, but this comes with a drawback: if you don't intend to use Google AdMob in your app, then you are still forced to add a fake application ID in your project otherwise AdMob will make the app crash if it doesn't find an ID 😬
To add this fake AdMob ID (again, only if you don't intend to use AdMob, otherwise you should use your real AdMob identifier) you must:
Edit the file android/app/src/main/AndroidManifest.xml
and add this into the <application>
tag:
<application ...>
...
<meta-data
android:name="com.google.android.gms.ads.APPLICATION_ID"
android:value="ca-app-pub-0000000000000000~0000000000" />
...
</application>
Edit the file ios/Runner/Info.plist
and add this into the <dict>
tag:
<dict>
...
<key>GADApplicationIdentifier</key>
<string>ca-app-pub-0000000000000000~0000000000</string>
...
</dict>
Import the plugin as early as possible somewhere in your project (ideally in the file main.dart
), then initialize the plugin by calling the functions Appodeal.setAppKeys()
and Appodeal.initialize()
:
First you need to set the app keys:
// Set the Appodeal app keys
Appodeal.setAppKeys(
androidAppKey: '<your-appodeal-android-key>',
iosAppKey: '<your-appodeal-ios-key>',
);
Where androidAppKey
and iosAppKey
are the keys associated with your app in your Appodeal account. At least one of these keys must be set before the initialization (either Android or iOS), otherwise you will get an error.
Afterwards you can initialize Appodeal with the function:
// Initialize Appodeal
await Appodeal.initialize(
hasConsent: true,
adTypes: [AdType.banner, AdType.mrec, AdType.interstitial, AdType.reward, AdType.nonSkippable],
testMode: true,
verbose: true,
);
// At this point you are ready to display ads
-
hasConsent
(mandatory) you must set eithertrue
orfalse
, depending if the user granted access to be tracked in order to received better ads. See section about collecting user consent for more information. -
adTypes
(optional) you must set a list (of typeAdType
) with all the ad types that you would like to display in your app. If this parameter is undefined or an empty list then no ads will be loaded. -
testMode
(optional) you must set eithertrue
orfalse
(default) depending if you are running the ads during development/test or production. -
verbose
(optional) you must set eithertrue
orfalse
(default) if you want Appodeal's verbose logs to be visible amongst the Flutter logs.
Before you initialize the plugin and start displaying ads, you might need to collect the user's consent to be tracked online, depending on his location or the operating system that he is using.
Since iOS 14+ you are required to request a specific permission before you can have access to Apple's IDFA (a sort of proprietary cookie used by Apple to track users among multiple advertisers... ah Apple, always Apple 🙄). To request this permission call the function Appodeal.requestIOSTrackingAuthorization()
:
// iOS 14+: request permission to track users
// on iOS <= 13 and Android this function does nothing; it just returns true
await Appodeal.requestIOSTrackingAuthorization();
For iOS versions before 14 and for Android devices this function won't do anything, so it's safe to call it on any device OS or version.
Depending on the location of your users, they might be protected by the privacy laws GDPR or CCPA. These laws require, among other things, that app developers must collect user consent before the advertisers can track them online. You can check if the user is protected by any privacy laws, by calling the function Appodeal.shouldShowConsent()
:
bool shouldShow = await Appodeal.shouldShowConsent();
if (shouldShow) { /* Request user consent */ }
Keep in mind that the function above will also return false
if the user previously accepted or declined the request to be tracked online. So it's important to always call this function in advance to avoid annoying the user with permission requests that he already answered.
After you determine if you need to request user consent, you have two options to collect this consent:
- You can design the UI with all the legal information and multiple options to let the user decline, accept or partially accept the options to be tracked. After you collect this information yourself, you then need to pass the value
true
orfalse
to the parameterhasConsent
during the Appodeal initialization.
or:
-
You can use the UI provided by the Consent Manager framework. With this option you can't customize the UI used to collect the user consent, however it does the heavy lifting for you of creating and displaying a window with all the legal wording, permission options and everything that is necessary to get the user's permission to be tracked. If you decide to go with option # 2 then you must call two functions:
2.1. Call the function
Appodeal.requestConsentAuthorization()
to display a window requesting the user consent to be tracked:await Appodeal.requestConsentAuthorization();
2.2. After the user grants or decline consent, you can call the function
Appodeal.fetchConsentInfo()
to fetch the consent info:var consent = await Appodeal.fetchConsentInfo(); var hasConsent = consent.status == ConsentStatus.personalized || consent.status == ConsentStatus.partlyPersonalized; await Appodeal.initialize(hasConsent: hasConsent, ...)
After you collect all the permissions and the plugin properly initialized, you are ready to display the ads:
To display a banner or MREC ad in your app, just include the widgets AppodealBanner()
or AppodealMrec()
somewhere in your widget tree. For example:
...
// Add a banner ad
Center(
child: AppodealBanner()
),
// or a MREC ad
Center(
child: AppodealMrec()
),
...
To show an interstitial, reward or non-skippable ad, call the function Appodeal.show()
passing the type of ad that you would like to show as a paremeter (mandatory) and the placement name (optional):
Appodeal.show(AdType.interstitial, placementName: "placement-name"); // Show an interstitial ad
Appodeal.show(AdType.reward, placementName: "placement-name"); // Show a reward ad
Appodeal.show(AdType.nonSkippable); // Show a non-skippable ad without placement name
You can define callbacks to your ads and track when an event occurs; it can be done by calling the callback functions below:
Appodeal.setBannerCallback((event) {})
Appodeal.setMrecCallback((event) {})
Appodeal.setInterstitialCallback((event) {})
Appodeal.setRewardCallback((event) {})
Appodeal.setNonSkippableCallback((event) {})
Every callback carries the parameter event
of type String
and you can use it to determine what event has been triggered. For example, if I wanted to know when the user watched a reward ad until the end, I could use the following callback code:
Appodeal.setRewardCallback((event) {
if (event == 'onRewardedVideoFinished') {
print('The user watched the reward ad until the end');
}
})
and if later I don't want to track reward events anymore, I just need to pass the value null
to the same callback function:
Appodeal.setRewardCallback(null);
The full list of events that you can track is below:
onBannerLoaded
, onBannerFailedToLoad
, onBannerShown
, onBannerClicked
, onBannerExpired
.
onMrecLoaded
, onMrecFailedToLoad
, onMrecShown
, onMrecClicked
, onMrecExpired
.
onInterstitialLoaded
, onInterstitialFailedToLoad
, onInterstitialShown
, onInterstitialShowFailed
, onInterstitialClicked
, onInterstitialClosed
, onInterstitialExpired
.
onRewardedVideoLoaded
, onRewardedVideoFailedToLoad
, onRewardedVideoShown
, onRewardedVideoShowFailed
, onRewardedVideoFinished
, onRewardedVideoClosed
, onRewardedVideoExpired
, onRewardedVideoClicked
.
onNonSkippableVideoLoaded
, onNonSkippableVideoFailedToLoad
, onNonSkippableVideoShown
, onNonSkippableVideoShowFailed
, onNonSkippableVideoFinished
, onNonSkippableVideoClosed
, onNonSkippableVideoExpired
.
If you like this project then please consider becoming a sponsor. Your contribution will help me dedicate more time working on bugs and new features for this and other projects.
appodeal_flutter is released under the MIT License. See LICENSE for details.
Vinicius Egidio (vinicius.io)