Phonegap Cordova Admob

Cordova, Phonegap Ionic and Intel XDK AdMob ads plugin

Maintained by appfeel

Made in Barcelona with Love and Code

Phonegap, Cordova, Ionic(Angular), Intel XDK AdMob plugin

Monetize your Cordova/Phonegap/Ionic(Angular)/XDK apps with AdMob ads, using latest Google AdMob SDK. With this Cordova/Phonegap/XDK plugin you can show AdMob ads as easy as:

admob.createBannerView({publisherId: "ca-app-pub-XXXXXXXXXXXXXXXX/BBBBBBBBBB"});

Or


admob.requestInterstitialAd({
  publisherId: "ca-app-pub-XXXXXXXXXXXXXXXX/BBBBBBBBBB",
  interstitialAdId: "ca-app-pub-XXXXXXXXXXXXXXXX/IIIIIIIIII"
});

Integrate cordova admob plugin

New Features

Sept-2016:

June-2015:

Dec-2014:

Nov-2014:

Oct-2014:

Testimonials

It was really easy to integrate, thanks.



Place your testimonial here

Platform SDK supported

Demo projects:

Quick start

To install this plugin, follow the Command-line Interface Guide. You can use one of the following command lines:

To use in Phonegap Build, place the following tag in your config.xml file:

<gap:plugin name="cordova-admob" source="npm" />

To start showing ads, place the following code in your onDeviceReady callback. Replace corresponding id's with yours:

Note: ensure you have a proper AdMob and tappx accounts and get your publisher id's.

    function onDeviceReady() {
      document.removeEventListener('deviceready', onDeviceReady, false);

      // Set AdMobAds options:
      admob.setOptions({
        publisherId:          "ca-app-pub-XXXXXXXXXXXXXXXX/BBBBBBBBBB",  // Required
        interstitialAdId:     "ca-app-pub-XXXXXXXXXXXXXXXX/IIIIIIIIII",  // Optional
        tappxIdiOS:           "/XXXXXXXXX/Pub-XXXX-iOS-IIII",            // Optional
        tappxIdAndroid:       "/XXXXXXXXX/Pub-XXXX-Android-AAAA",        // Optional
        tappxShare:           0.5                                        // Optional
      });

      // Start showing banners (atomatic when autoShowBanner is set to true)
      admob.createBannerView();

      // Request interstitial (will present automatically when autoShowInterstitial is set to true)
      admob.requestInterstitialAd();
    }

    document.addEventListener("deviceready", onDeviceReady, false)

If you don't specify tappxId, no tappx requests will be placed (even if you specify a tappxShare).

Angular.js based apps (Ionic) support

Include the following script in your index.html (just it, no need to copy any file: the plugin is in charge to copy the script when the app is prepared):

    <script src="lib/angular-admob/angular-admob.js"></script>

Here is a quick example on how to use Admob plugin with Angular.js based apps, for example Ionic:

    var app = angular.module('myApp', ['admobModule']);

    app.config(['admobSvcProvider', function (admobSvcProvider) {
      // Optionally you can configure the options here:
      admobSvcProvider.setOptions({
        publisherId:          "ca-app-pub-XXXXXXXXXXXXXXXX/BBBBBBBBBB",  // Required
        interstitialAdId:     "ca-app-pub-XXXXXXXXXXXXXXXX/IIIIIIIIII",  // Optional
        tappxIdiOS:           "/XXXXXXXXX/Pub-XXXX-iOS-IIII",            // Optional
        tappxIdAndroid:       "/XXXXXXXXX/Pub-XXXX-Android-AAAA",        // Optional
        tappxShare:           0.5                                        // Optional
      });

      // Optionally configure the events prefix (by default set to 'admob:')
      admobSvcProvider.setPrefix('myTag~');
    }]);


    app.run(['admobSvc', function (admobSvc) {
      // Also you could configure the options here (or in any controller):
      // admobSvcProvider.setOptions({ ... });

      admobSvc.createBannerView();
      // You could also call admobSvc.createBannerView(options);


      // Handle events:
      $rootScope.$on('myTag~' + admobSvc.events.onAdOpened, function onAdOpened(evt, e) {
        console.log('adOpened: type of ad:' + e.adType);
      });

      // The default prefix for events is 'admob:'
      // $rootScope.$on('admob:' + admobSvc.events...
    }]);

Javascript API

Note: All success callbacks are in the form 'function () {}', and all failure callbacks are in the form 'function (err) {}' where err is a String explaining the error reason.

setOptions(options, success, fail);

Set the options to start displaying ads:

Options

A JSON object whith the following fields:

Example (those are also the default options, except for tappxId's which are empty by default): 

{
  publisherId:          "ca-app-pub-XXXXXXXXXXXXXXXX/BBBBBBBBBB",
  interstitialAdId:     "ca-app-pub-XXXXXXXXXXXXXXXX/IIIIIIIIII",
  tappxIdiOS:           "/XXXXXXXXX/Pub-XXXX-iOS-IIII",
  tappxIdAndroid:       "/XXXXXXXXX/Pub-XXXX-Android-AAAA",
  tappxShare:           0.5,
  adSize:               admob.AD_SIZE.SMART_BANNER,
  bannerAtTop:          false,
  overlap:              false,
  offsetStatusBar:      false,
  isTesting:            false,
  adExtras :            {},
  autoShowBanner:       true,
  autoShowInterstitial: true
}

Banners

createBannerView(options, success, fail);

Create a new banner view.

showBannerAd(show, success, fail);

Show banner ads.

destroyBannerView();

Hide and destroy banner view.

Interstitials

requestInterstitialAd(options, success, fail);

Request an interstitial ad.
If options.autoShowInterstitial is set to true, the ad will automatically be displayed. Otherwise you should call showInterstitialAd() when admob.events.onAdLoaded event is called.
If you already called requestInterstitialAd() but the interstitial was never shown, the following calls to requestInterstitialAd() will result in the ad being inmediately available (the same ad as the one in the first call).

showInterstitialAd(success, fail);

Show an interstitial ad.
This method must be called after admob.events.onAdLoaded event is called. If there is no ad available it calls fail callback.

In App Purchase

recordResolution(purchaseId, resolution, success, fail);

Records the purchase status and conversion events.

recordPlayBillingResolution(purchaseId, billingResponseCode, success, fail);

Records the purchase status and conversion events for a play billing purchase.

Events

AdMobAds Cordova library will use the same events for Android as for iOS (the iOS ones are mapped to the Android ones). See Google Docs for more info.
To listen to any of those events you can use:

document.addEventListener(admob.events.onAdLoaded, function (e) { });

admob.events.onAdLoaded

Called when an ad is received.

admob.events.onAdFailedToLoad

Called when an ad request failed.

admob.events.onAdOpened

Called when an ad opens an overlay that covers the screen. Please note that onPause event is raised when an interstitial is shown.

admob.events.onAdClosed

Called when the user is about to return to the application after clicking on an ad. Please note that onResume event is raised when an interstitial is closed.

admob.events.onAdLeftApplication

Called when an ad leaves the application (e.g., to go to the browser).

admob.events.onInAppPurchaseRequested

Called when the user clicks the buy button of an in-app purchase ad. You shoud complete the transaction by calling admob.recordResolution(...) or admob.recordPlayBillingResolution(...).

Quick example with cordova CLI

    cordova create <project_folder> com.<company_name>.<app_name> <AppName>
    cd <project_folder>
    cordova platform add android
    cordova platform add ios

    // cordova will handle dependency automatically
    cordova plugin add cordova-admob

    // now remove the default www content, copy the demo html file to www
    rm -rf www/*;
    cp plugins/cordova-admob/test/* www/

    cordova prepare; cordova run android; cordova run ios;
    // or import into Xcode / eclipse

Complete example code

Note that the admob ads are configured inside onDeviceReady(). This is because only after device ready the AdMob Cordova plugin will be working.

    function initAds() {
      if (admob) {
        var adPublisherIds = {
          ios : {
            banner : "ca-app-pub-XXXXXXXXXXXXXXXX/BBBBBBBBBB",
            interstitial : "ca-app-pub-XXXXXXXXXXXXXXXX/IIIIIIIIII"
          },
          android : {
            banner : "ca-app-pub-XXXXXXXXXXXXXXXX/BBBBBBBBBB",
            interstitial : "ca-app-pub-XXXXXXXXXXXXXXXX/IIIIIIIIII"
          }
        };

        var admobid = (/(android)/i.test(navigator.userAgent)) ? adPublisherIds.android : adPublisherIds.ios;

        admob.setOptions({
          publisherId:      admobid.banner,
          interstitialAdId: admobid.interstitial,
          tappxIdiOS:       "/XXXXXXXXX/Pub-XXXX-iOS-IIII",
          tappxIdAndroid:   "/XXXXXXXXX/Pub-XXXX-Android-AAAA",
          tappxShare:       0.5
        });

        registerAdEvents();

      } else {
        alert('AdMobAds plugin not ready');
      }
    }

    function onAdLoaded(e) {
      if (e.adType === admob.AD_TYPE.INTERSTITIAL) {
        admob.showInterstitialAd();
        showNextInterstitial = setTimeout(function() {
          admob.requestInterstitialAd();
        }, 2 * 60 * 1000); // 2 minutes
      }
    }

    // optional, in case respond to events
    function registerAdEvents() {
      document.addEventListener(admob.events.onAdLoaded, onAdLoaded);
      document.addEventListener(admob.events.onAdFailedToLoad, function (e) {});
      document.addEventListener(admob.events.onAdOpened, function (e) {});
      document.addEventListener(admob.events.onAdClosed, function (e) {});
      document.addEventListener(admob.events.onAdLeftApplication, function (e) {});
      document.addEventListener(admob.events.onInAppPurchaseRequested, function (e) {});
    }

    function onDeviceReady() {
      document.removeEventListener('deviceready', onDeviceReady, false);
      initAds();

      // display a banner at startup
      admob.createBannerView();

      // request an interstitial
      admob.requestInterstitialAd();
    }

    document.addEventListener("deviceready", onDeviceReady, false);

Contributing

You can use this cordova plugin for free. You can contribute to this project in many ways:

You can also support this project by sharing 2% Ad traffic (it's not mandatory: if you are unwilling to share, please fork and remove the donation code) and by donations via paypal

Screenshots

iPhone:

Phonegp Cordova admob plugin in iPhone

iPad Banner Portrait:

Phonegp Cordova admob plugin in iPad

iPad Banner Landscape:

Phonegp Cordova admob plugin

License

The MIT License

Copyright (c) 2014 AppFeel

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Credits