Interstitial ads

Article
08/24/2017

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

This walkthrough shows how to include interstitial video ads in Windows 8.1 and Windows Phone 8.1 apps that are written using JavaScript and HTML

Note Interstitial banner ads are not supported in Windows 8.1 and Windows Phone 8.1 apps.

What are interstitial video ads?

Unlike standard banner ads, which are confined to a portion of a UI in an app or game, interstitial video ads are shown on the entire screen. Two basic forms are frequently used in games.

With paywall ads, the user must watch an ad at some regular interval. For example, between game levels.
With rewards-based ads, the user is explicitly seeking some benefit, such as a hint or extra time to complete the level, and initializes the ad through the app’s user interface.

Note The API for interstitial ads does not handle any user interface except at the time of video playback. Refer to theinterstitial best practices for guidelines on what to do, and avoid, as you consider how to integrate interstitial ads in your app.

Prerequisites

Install the Microsoft Advertising SDK for Windows and Windows Phone 8.x with Visual Studio 2015 or Visual Studio 2013.

Code development

In Visual Studio, open your project or create a new project.
If your project targets Any CPU, update your project to use an architecture-specific build output (for example, x86). If your project targets Any CPU, you will not be able to successfully add a reference to the Microsoft advertising library in the following steps.
From the Solution Explorer window, right click References, and select Add Reference....
In Reference Manager, select one of the following references depending on your project type:
- For a Windows 8.1 project: Expand Windows 8.1, click Extensions, and then select the check box next to Microsoft Advertising SDK for Windows 8.1 Native (JS).
- For a Windows Phone 8.1 project: Expand Windows Phone 8.1, click Extensions, and then select the check box next to Microsoft Advertising SDK for Windows Phone 8.1 Native (JS).
In Reference Manager, click OK.
Open the default.html file (or other html file as appropriate for your project).
In the <head> section, after the project’s JavaScript references of default.css and default.js, add the reference to ad.js.
```
<script src="/MSAdvertisingJS/ads/ad.js"></script>
```
In a .js file in your project, declare an InterstitialAd object and several fields that contain the application ID and ad unit ID for your interstitial ad. The following code example assigns the applicationId and adUnitId fields to the test values for interstitial video ads provided in Set up ad units in your app.Note Every InterstitialAd has a corresponding ad unit that is used by our services to serve ads to the control, and every ad unit consists of an ad unit ID and application ID. In these steps, you assign test ad unit ID and application ID values to your control. These test values can only be used in a test version of your app. Before you publish your app to the Store, you must replace these test values with live values from Windows Dev Center.
```
var interstitialAd = null;
var applicationId = "d25517cb-12d4-4699-8bdc-52040c712cab";
var adUnitId = "test";
```

In code that runs on startup (for example, in the constructor for the page), instantiate the InterstitialAd object and wire up event handlers for events of the object.

interstitialAd = new MicrosoftNSJS.Advertising.InterstitialAd();
interstitialAd.onErrorOccurred = errorOccurredHandler;
interstitialAd.onAdReady = adReadyHandler;
interstitialAd.onCancelled = cancelledHandler;
interstitialAd.onCompleted = completedHandler;

Approximately 30-60 seconds before you need the ad, use the RequestAd method to pre-fetch the ad. This allows enough time to request and prepare the ad before it should be shown. Be sure to specify InterstitialAdType.video for the ad type.
```
if (interstitialAd) {
    interstitialAd.requestAd(MicrosoftNSJS.Advertising.InterstitialAdType.video, applicationId, adUnitId);
}
```
At the point in your code where you want to show the interstitial video ad, confirm that the InterstitialAd is ready to be shown and then show it by using the Show method.
```
if (interstitialAd && interstitialAd.state === MicrosoftNSJS.Advertising.InterstitialAdState.ready) {
       interstitialAd.show();
}
```

Define the event handlers for the InterstitialAd object.

function adReadyHandler(sender) {
  // Your code goes here.
}

function errorOccurredHandler(sender, args) {
  // Your code goes here.
}

function completedHandler(sender) {
  // Your code goes here.
}

function cancelledHandler(sender) {
  // Your code goes here.
}

Build and test your app to confirm it is showing test ads.

Release your app with live ads using Windows Dev Center

In the Dev Center dashboard, go to the Monetize with ads page for your app and create an ad unit. For the ad unit type, specify Video interstitial. Make note of both the ad unit ID and the application ID.
In your code, replace the test ad unit values with the live values you generated in Dev Center.
Submit your app to the Store using the Dev Center dashboard.
Review your advertising performance reports in the Dev Center dashboard.

Guidelines for interstitial ads

Set up ad units in your app

Interstitial ads

What are interstitial video ads?

Prerequisites

Code development

Release your app with live ads using Windows Dev Center

Related topics

Additional resources