How-to: book HTML interstitial ads in the Cxense Mobile SDK

2016-11-08 15:37:27 UTC

Updated 09.04.2015 

With an integration of Cxense (formerly Emediate) Mobile SDK in your iOS and Android app, booking of rich media / HTML5 interstitial ads in your e-paper publication is possible. These HTML ads will be presented as full-screen ads presented between the publication pages.

In this article, you will find documentation of which possibilities Visiolink offers for booking interstitials to your e-paper through Cxense Mobile SDK and a guide to booking the HTML interstitials in the Cxense Display interface.  

Understanding the Cxense Display ad booking interface might require some basic introduction. If you are new to the interface and have questions regarding basic functionalities, please contact Cxense support.

Creating HTML ads requires a high level of technical skills. At Visiolink we have teamed up with the digital ad agency OnAds providing two ways of helping you create HTML interstitial ads:

Rich Media Template Ads: Access to a self-service ad builder tool for creation of 6 predefined easy to build creative formats. Please read this article for details and video examples:  
Rich Media Premium Ads: Full creative corporation with our digital ad agency for creating custom ads.

Contact Visiolink to hear more about these solutions.

1.0 Visiolink HTML ad solution

At Visiolink, we have built a clear concept for inserting Content Units on both Fixed Placements and Frequency-Controlled Placements in the e-paper for iOS and Android. This concept will be presented here.

1.1 What you need

In order to display HTML interstitials booked through the Cxense Display interface in your e-paper app, you need:

  • The Interstitial feature in your app
  • Integration of the Cxense Mobile SDK in your app
  • Access to Cxense Display

1.2 Fixed Placements

You can create up to five fixed placements in your e-paper publication. A placement is defined as a reserved ad space placed after an odd page in the e-paper publication, see illustration 1.

 These are the requirements:

  • You must create one Content Unit (CU) per placement
  • Placements can only be placed after odd page numbers
  • There must be at least three pages between each placement. If there is a placement after page 1, the next possible placement is after page 5, See illustration 1
  • Once the app is submitted, placements and CU’s cannot be changed

Illustration 1


1.3 Frequency-Controlled Interstitials

Besides Fixed Placements it is possible to create one CU containing Frequency-Controlled interstitials. These are shown in the app according to a set number of swipes. If the frequency is set to 7 swipes, the interstitial will be shown for each 7 swipes between pages (3 swipes is subtracted from the frequency number when first opening a publication. This optimizes the likeliness that more readers will be exposed for the ad).

The frequency number cannot be lower than 5. You can book more interstitials (campaigns) to this CU at the same time.

1.4 App logic and general requirements and restrictions

To fully understand the behavior of interstitial display in the app, please take notion of these rules controlling the display logic:

  • The app will preload the interstitial closest to the page that is being read. The interstitials are preloaded in order to minimize load time when the reader reaches an interstitial placement. This means that swiping fast between pages can course an interstitial to not be displayed.
  • Due to performance considerations, the app can only preload the interstitial of one placement at the time.  
  • When testing fixed placement interstitials, you should simulate a normal reader behavior. Rushing between interstitials might not leave the device enough time register that an interstitial is active and thus skip the placement.   
  • If more than one interstitial is booked in one CU (only possible with frequency-controlled interstitials), the app will display the interstitial that has been displayed the least amount of times on the reader’s device.
  • Display of any interstitial will reset the frequency counter of frequency controlled interstitials
  • An area of three swipes before and after a fixed placement will be held free of frequency-controlled interstitials in order to avoid spamming the reader with several ads within a short page span.
  • If no campaigns are booked to a CU within the app, the placement will be skipped and the user is led to the next coming page of the publication.
  • A campaign cannot be limited to a specific edition of your publication. Once it is booked on a CU, it will appear in all editions available in the app throughout the booked period
  • Interstitials will only be displayed when the device is online
  • Visiolink allows an interstitial to take over the whole screen including control of gestures. To prevent that the reader gets stuck on an interstitial that has taken over the swipe gesture, which is usually used to turn to next/previous page, we have built in three different page turn options:
    • Edge swipe: Swipe from the edge of the device on to the screen in order to turn to next/previous page, see illustration 2
    • Arrows: Press the arrows on the left or right in order to turn to next/previous page. The arrows will appear every time the reader swipes within the app, see illustration 2
    • Multiple Swipes (iOS only): Swiping three times within two seconds in the same direction will turn to the next/previous page as this behavior indicates that the reader is no longer absorbing the message of the ad, but rather that he or she is interested in turning the page.


Illustration 2


2.0 HTML5 ad display through the Cxense Mobile SDK

The Cxense mobile SDK expects HTML interstitials that work both on phone and tablet full-screen and both landscape and portrait. It is up to the producer of the interstitial to make sure that it is responsive and looks as desired on all screen sizes and both orientations.

When an interstitial is to be presented, the app will ask the Cxense SDK to serve the ad booked on the CU corresponding to the upcoming placement in the app. If any active campaigns are available, an in-app Cxense web view will open and the control is handed over to the logic within the HTML ad.

The ad is displayed full-screen, so you have all normal possibilities to make use of the full-screen as with a normal web page. No restrictions are made in the web-view so best practice for general web development apply. When links in the ad are activated, a popover browser view takes the user to the landing page, which can be closed to return to the ad.

The iOS SDK is MRAID compatible. The Android SDK is not yet MRAID compatible.

Please note that we for Android 4.3 and lower advise to use static ads as alternative/fallback to interactive ads, as these Android versions are not suited for all HTML5 elements. 

2.1 SDK Pre-load and html5 polite load

The SDK and the Visiolink app pre-load your next ad to the user’s device to speed up the flow and presentation of the ad. But even when preloaded, a heavy HTML5 ad can take time to load into the web view. To further optimize, you can add “polite load” to your ad before the entire ad is to be presented. Polite load can be managed by ordering the ad to present a static picture at first, and only afterwards present the heavy animations and video. 

Hooks for starting and stopping animations (iOS only)

If you want to make use of animations that start up when the user is presented for the ad, Visiolink provides a JavaScript function you can use in your ad:


If you want to make sure that animations stop when the user has moved away from the ad, please use this hook:


This hook is especially useful when performing ads with audio, so that you can make sure that the audio stops when the user moves away from the ad.

2.2 How to get clicks and tracking

To get clicks and tracking correct, it is important that the Cxense click macro is correctly integrated in the interstitial.

Cxense click macro is: EASLink=

Example for using Cxense click macro in HTML5 banner:
<a href=”EASLink=”>Go to homepage</a>

or by JavaScript (’EASLink=’);

If you use any other way to redirect to your homepage / destination url, simply apply EASLink= before the url.

2.3 How to setup Cxense Display for interstitial booking

In order to make ready for displaying HTML interstitials in your e-paper app(s), you need to do the following:

  • Create up to 5 individual Content Units for Fixed Placements
    • Name these CU’s logically according to the placements in the app, e.g. “NewspaperTitle_p1”, “NewspaperTitle_p5” etc.
  • Create 1 CU for frequency-controlled interstitials
  • NB: When creating the CU’s you will be asked to state a height and a width of the CU. If you plan to execute HTML ads only, the size is irrelevant as scaling is controlled by the ad. Set the size to e.g. 1x1 px (it is important that you use the same size when creating Campaigns, as CU size and Campaign size must match)
  • You must provide Visiolink with the ID number (four or five digits) of each CU and the corresponding page numbers (odd numbers only) after which you will like to place the CUs

At Visiolink we use JavaScript tags for executing ads. Following you will find a step-by-step guide of how to book a JavaScript tag for interstitial display.    

  • Create a new campaign
    • Give the campaign a name
    • Provide a first date and a last date indicating the period the campaign should be active
    • Priority Level must be Available impressions
    • Type should be Banner
    • Size must correspond with the size of the Content Unit that you have planned to use for this campaign
    • Press “Add”


Illustration 3

  • Now you are ready to add a creative to the campaign
    • Press “Add creatives”
    • In the next screen, press “[HTML]”
    • In the next screen, press “Paste in your own HTML content”
    • In the window you must wrap the JS tag in this simple HTML and place the JS tag in the <div> tag

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "">
<style type="text/css">
html, body

    padding: 0px;

    left: 0px;






Illustration 4

  • Press “Update”
  • Press “Commit”

Now you can find your campaign in the overview under Advertising -> View Campaign, and from here, you must add the campaign to the desired CU. Furthermore you must change the status of the campaign from “Waiting for Approval” to “Approved”

Now the campaign will be ready for execution in the app on the first date of the campaign.


2.4 Examples of JS tags

Below you will find two examples of JavaScript tags that will execute two different HTML ads. The tags contain image files fitted for both tablets and phones as well as both portrait and landscape. Furthermore, they contain logic that will detect device type (based on screen size) and orientation of device.

Example of a responsive image ad:

<script type="text/javascript" src=""></script>


Example of a 3D cube with up to four sides:

<script type="text/javascript" src=""></script>

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request