Cordova SDK

Requirements

  • Heyzap Cordova requires cordova-ios engine 3.8.0 and above and cordova-android engine 4.0.0 and above.

Step 1. Configure Dynamic Documentation

Get the latest Heyzap Cordova plugin here.

Select the version of the Heyzap SDK you wish to view documentation for, and then select the networks you are integrating. The documentation on this page will update with specific instructions that may apply to your selections.

Network Selection:

Step 2. Add the SDK to your Cordova project

In your Cordova project, run:

cordova plugin add heyzap-cordova

The SDK includes Heyzap, as well as wrappers for all 3rd-party networks.

Step 3. Choose your 3rd-party SDKs

3rd-party SDKs must be added to the individual platform generated projects.

Adding Frameworks to iOS

The Xcode platform project can be found under {PROJECT_ROOT}/platforms/ios/{PROJECT_NAME}.xcodeproj. Once the platform project is opened with Xcode, additional frameworks can be added by dragging the .framework files onto the Project Navigator under the "Frameworks" group and checking Copy Items if needed.

Adding Libraries to Android

The Android platform project can be found under {PROJECT_ROOT}/platforms/android. Additional Ad Network SDKs can be added by copying any necessary .jar files into the libs folder of the Android platform project.


AdColony

AdMob

Apple iAd

AppLovin

Chartboost

Domob

Facebook Audience Network

Fyber Exchange

HyprMX

InMobi

Leadbolt

MdotM

MoPub

UnityAds

Vungle

If you haven't already, use our Integration Wizard to setup the 3rd-party networks you want to use with mediation.

The Heyzap SDK will automatically detect and initialize the SDKs from 3rd-party networks, therefore no code changes are required.

Step 4. Platform specific configurations

iOS Only

Make sure that C and Objective-C modules are enabled in the iOS Platform project. In Xcode, select the project in the Project Navigator. Under the Build Settings tab, set Enable Modules (C and Objective-C) to yes.

Android Only

Ensure that Google Play Services is installed on your development machine. If it is not installed, use the Android SDK Manager (run {ANDROID_SDK_HOME}/tools/android) to select and install "Google Play Services" under the Android Extras section.

Step 5. Initialize the SDK

In your application's deviceready event handler, start the Heyzap SDK:

document.addEventListener('deviceready', function() {
  HeyzapAds.start("<PUBLISHER ID>").then(function() {
    // Start fetching ads

  }, function(error) {
    // Handle Error

  });
}, false);

All calls made from the Heyzap Cordova SDK will return an ES-6 style promise. The success callback will indicate that a native call went through successfully, while a failure callback will indicate that something went wrong with the native SDK call.

Step 6: Test your 3rd-Party Integrations (Optional)

The Heyzap SDK comes with a Mediation Debug View that you can test each network you've integrated with:

The first screen lets you pick a network. Once you choose a network, you'll see if:

  1. The network is installed correctly.
  2. The network has valid credentials on your dashboard.
  3. The network is enabled on your dashboard.

From here, you can select a type of ad (Interstitial, Video, Incentivized, or Banner), fetch that ad, and then display it.

To use the Mediation Debug View, simply call HeyzapAds.showMediationTestSuite() after you start the SDK.

document.addEventListener('deviceready', function() {
  HeyzapAds.start("<PUBLISHER ID>").then(function() {

    return HeyzapAds.showMediationTestSuite(); // returns a Promise

  }, function(error) {
    // Handle Error

  });
}, false);

At this point, you should launch the Mediation Debug View and verify that each network you want to use has the correct credentials and shows ads correctly.

Step 7. Show Ads

Methods you call on the Heyzap SDK will automatically dispatch to your enabled 3rd-party SDKs; a call to show will iterate over ad networks in order of expected CPM until it finds one that has an ad, optimizing CPM and fill rate. Use the code below to display your preferred ad format.

Note that the returned Promise object's callbacks do not indicate if the Ad was shown. They simply indicate if the call to the platform's native SDK was successful or unsuccessful (i.e. if the native call threw an error).

To find out if an ad was successfully fetched/shown by the native SDK, see the callbacks section in our Advanced Features doc.

Interstitial Ads

You do not have to call fetch() on Interstitial Ads, they are automatically fetched from our server.

HeyzapAds.InterstitialAd.show().then(function() {
  // Native call successful.

}, function(error) {
  // Handle Error

});

Video Ads

As early as possible, and after showing a video ad, call fetch:

HeyzapAds.VideoAd.fetch().then(function() {
  // Native call successful.

}, function(error) {
  // Handle Error

});

Later, such as after a level is completed:

HeyzapAds.VideoAd.show().then(function() {
  // Native call successful.
  return HeyzapAds.VideoAd.fetch();

}, function(error) {
  // Handle Error

});

Rewarded Video Ads

As early as possible, and after showing a rewarded video ad, call fetch:

HeyzapAds.IncentivizedAd.fetch().then(function() {
  // Native call successful.

}, function(error) {
  // Handle Error

});

Later, such as after a level is completed:

HeyzapAds.IncentivizedAd.show().then(function() {
  // Native call successful.
  return HeyzapAds.IncentivizedAd.fetch();

}, function(error) {
  // Handle Error

});

Banner Ads

To use banner ads, you must be using AdMob, Facebook Audience Network, or InMobi.

Note: Most banner networks have a setting on their dashboard to automatically refresh at a given time interval. If you want to use this feature, it is strongly recommended that you use the same time interval on all of the banner networks you are using. Different refresh rates for different networks can result in confusing impression statistics.

To show a banner you must specify a position (HeyzapAds.BannerAd.POSITION_TOP or HeyzapAds.BannerAd.POSITION_BOTTOM):

HeyzapAds.BannerAd.show(HeyzapAds.BannerAd.POSITION_TOP).then(function() {
  // Native call successful.

}, function(error) {
  // Handle Error

});

To hide a currently showing banner:

HeyzapAds.BannerAd.hide().then(function() {
  // Native call successful.

}, function(error) {
  // Handle Error

});

To completely remove a currently loaded banner:

HeyzapAds.BannerAd.destroy().then(function() {
  // Native call successful.

}, function(error) {
  // Handle Error

});

For details on configuring the sizes of banners, more customizable placement of banners, callbacks, and more, please see the Banner sections of our Advanced Guide.

All good? Head over to your mediation dashboard to view revenue, impressions, eCPM, network credentials, and more.


More Information:

To view Advanced Features, click here.
To view the source code for the Cordova plugin, click here.