Contents
The Cocoon MoPub plugin is a Cordova plugin aimed at providing easy integration with the MoPub ads network.
Installation
To add the MoPub plugin to your project first go to your project configuration and once there go to the Setting section and click on the “Plugins” tab. You should see something like this:
If you click on the “Cocoon” category you will see al the Cocoon available plugins. Over the plugins list you will see a dropdown menu set to “All” by default. Click on the menu to see the available Cocoon plugins categories, you should see a list of plugins with at least the following groups:
Select the “MoPub SDK” plugin. Then the MoPub related plugins should be filtered in the plugins list.
Now click on install and your project will include the MoPub plugin in the next compilation.
Now you are ready to compile the Developer App to start testing your MoPub ads.
MoPub Adapters
MoPub is an Ad network mediator so you can integrate other third party networks using Mopub. You just need to install the MoPub Ad network adapter for the network you want and configure it in the MoPub administration panel.
To install the MoPub adapter, go to the Cocoon plugins list and choose “MoPub Adapters” from the list:
In the plugins list you will see all the supported MoPub adapters. Just select the one (or ones, you can install several adapters at the same time) you want to install and click on the “Install” button on the right side.
No further configurations are needed in the Cocoon side, all the adapter configuration is done in the MoPub administration panel. You can read more information about it here.
There are several adapters available:
AdColony
This adapter does not require further configuration.
AdMob
This adapter does not require further configuration.
AppLovin
This adapter requires the SDK_KEY, which you can find in your AppLovin dashboard. Add this SDK key to your config.xml
.
1 2 3 4 5 |
<plugin name="cocoon-plugin-ads-[android|ios]-mopub-applovin" spec="*"> <variable name="SDK_KEY" value="[Your SDK key]" /> </plugin> |
Parameters
For this plugin you need to add the parameters from the source code. See the integration guide bellow and the example to see how to setup the MoPub parameters.
Also, due to changes in iOS 10, this plugin has the optional parameter: CALENDAR_USAGE_DESCRIPTION.
1 2 3 4 5 6 7 |
<plugin name="cocoon-ads-ios-mopub" spec="*"> <variable name="CALENDAR_USAGE_DESCRIPTION" value="[Your description]" /> </plugin> |
MoPub needs the permission to access the device calendar and this parameter is used in iOS only to display a description of the usage of the calendar the first time the application tries to use it. If not set, a default permission request text will be used.
Integration
Cordova needs to be specifically loaded in your index.html so it can start the Cordova framework and load the plugins that you have installed in your project. So first thing is to add the cordova.js
script tag to your index.html.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta charset="utf-8" /> <meta name="format-detection" content="telephone=no" /> <meta name="msapplication-tap-highlight" content="no" /> <!-- WARNING: for iOS 7, remove the width=device-width and height=device-height attributes. See https://issues.apache.org/jira/browse/CB-4323 --> <meta name="viewport" content="user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width, height=device-height, target-densitydpi=device-dpi" /> <title>Ads demo</title> </head> <body style="margin:0; padding:0;"> <script type="text/javascript" src="cordova.js"></script> <script type="text/javascript" src="js/pixi.min.js"></script> <script type="text/javascript" src="js/demo.js"></script> </body> </html> |
That’s the only code script you need to include in your index.html for the plugin to be ready to be used. Cordova will do the rest.
Important: Remember to wait for the deviceready
event before using the plugin as that is the moment when the plugin will be fully initialized.
1 2 3 4 5 6 7 8 |
function main() { // You application code }; document.addEventListener('deviceready', main, false); |
Usage
Let’s see some code snippets showing how to use the Cocoon MoPub plugin in your application.
Initialization
First you need to configure the IDs for the different MoPub ads types.
Getting the IDs
You can find the IDs in the MoPub application settings:
- Configured Ads
- Code integration
- Ad ID
Copy paste the ID in your Javascript code and you are ready to go. You can read the complete MoPub guide here.
Setting up the IDs
At plugin configuration time
There are two ways of setting up the ads IDs in your code. First, you can call the Cocoon.Ad.MoPub.configure
method with a configuration (you can omit any of those platforms if you are not targeting to them)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
Cocoon.Ad.MoPub.configure({ android: { appId: "b195f8dd8ded45fe847ad89ed1d016da", banner: "252412d5e9364a05ab77d9396346d73d", interstitial: "24534e1901884e398f1253216226017e", rewardedVideo: "15173ac6d3e54c9389b9a5ddca69b34b", personalizedAdsConsent: false, }, ios: { appId: "0ac59b0996d947309c33f59d6676399f", banner: "2aae44d2ab91424d9850870af33e5af7", interstitial: "4f117153f5c24fa6a3a92b818a5eb630", rewardedVideo: "98c29e015e7346bd9c380b1467b33850", personalizedAdsConsent: false, } }); |
The appId
is the Id the plugin will use to initialize the MoPubSDK. Any AdUnit will should work.
This will setup IDs for an ad that you can later create calling the creation method without parameters:
1 2 3 4 5 |
var banner = Cocoon.Ad.MoPub.createBanner(); var interstitial = Cocoon.Ad.MoPub.createInterstitial(); var rewardedVideo = Cocoon.Ad.MoPub.createRewardedVideo(); |
At ad creation time
Another option is to pass the ID at creation time:
1 2 3 4 5 |
var banner = Cocoon.Ad.MoPub.createBanner("252412d5e9364a05ab77d9396346d73d"); var interstitial = Cocoon.Ad.MoPub.createInterstitial("24534e1901884e398f1253216226017e"); var rewardedVideo = Cocoon.Ad.MoPub.createRewardedVideo("15173ac6d3e54c9389b9a5ddca69b34b"); |
This can be useful in case you want to create several ad instances with different IDs.
Note that the appId
parameter must be passed through the Cocoon.Ad.MoPub.configure
method regardless of the way the ads IDs are provided.
GDPR
The optional parameter personalizedAdsConsent
in the Cocoon.Ad.MoPub.configure
method determines if the user has consented to be targeted by personalized ads. This parameter spreads to every Cocoon MoPub adapter installed.
Banners
1 2 3 |
var banner = Cocoon.Ad.MoPub.createBanner(); |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
banner.on("load", function(){ console.log("Banner loaded " + banner.width, banner.height); }); banner.on("fail", function(){ console.log("Banner failed to load"); }); banner.on("show", function(){ console.log("Banner shown a modal content"); }); banner.on("dismiss", function(){ console.log("Banner dismissed the modal content"); }); banner.on("click", function(){ console.log("Banner clicked"); }); |
First thing you have to do after creating a banner is to listen to its life cycle events:
- load: A banner has been loaded and is ready to be shown.
- fail: The banner load has failed so there is no ad available to be shown at the moment.
- show: The banner has been showed probably as consequence of calling the “show” method.
- dismiss: The banner has been collapsed.
- click: The user has clicked on the banner.
1 2 3 4 |
banner.show(); banner.hide(); |
Interstitials
Creating an interstitial
1 2 3 |
var interstitial = Cocoon.Ad.MoPub.createInterstitial(); |
Listening to interstitial events
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
interstitial.on("load", function(){ console.log("Interstitial loaded"); }); interstitial.on("fail", function(error){ console.log("Interstitial failed: " + JSON.stringify(error)); }); interstitial.on("show", function(){ console.log("Interstitial shown"); }); interstitial.on("dismiss", function(){ console.log("Interstitial dismissed"); }); interstitial.on("click", function(){ console.log("Interstitial clicked"); }); |
First thing you have to do after creating an interstitial is to listen to its life cycle events:
- load: An interstitial has been loaded and is ready to be shown.
- fail: The interstitial load has failed so there is no ad available to be shown at the moment.
- show: The interstitial has been showed probably as consequence of calling the “show” method.
- dismiss: The interstitial has been closed by the user.
- click: The user has clicked on the interstitial.
Showing an interstitial
1 2 3 |
interstitial.show() |
The interstitials cannot be hidden from code.
Rewarded Videos
Creating a rewarded video
1 2 3 |
var interstitial = Cocoon.Ad.MoPub.createRewardedVideo(); |
Listening to rewarded videos events
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 |
rewardedVideo.on("load", function(){ console.log("Rewarded video loaded"); }); rewardedVideo.on("fail", function(error){ console.log("Rewarded video failed: " + JSON.stringify(error)); }); rewardedVideo.on("show", function(){ console.log("Rewarded video shown"); }); rewardedVideo.on("dismiss", function(){ console.log("Rewarded video dismissed"); }); rewardedVideo.on("reward", function(reward, error){ if (!error) { console.log("Rewarded video completed"); } else { console.log("Rewarded video failed: " + JSON.stringify(error)); } }); rewardedVideo.on("click", function(){ console.log("Rewarded video clicked"); }); |
First thing you have to do after creating a rewarded video is to listen to its life cycle events:
- load: A rewarded video has been loaded and is ready to be shown.
- fail: The rewarded video load has failed so there is no ad available to be shown at the moment.
- show: The rewarded video has been showed probably as consequence of calling the “show” method.
- dismiss: The rewarded video has been closed by the user.
- reward: The user has watched enough to receive the reward. But an error not captured by fail could have occurred.
- click: The user has clicked on the rewarded video.
Showing an interstitial
1 2 3 |
rewardedVideo.show() |
The rewarded videos cannot be hidden from code.
Example
API
Testing
To test your MoPub plugin integration:
- Install the MoPub plugin (and adapters if needed) in your project
- Compile a Developer App
- Launch you app from the Developer App using a zip or a URL options