Mobile Web

From mkMob Developer Wiki
Jump to: navigation, search

Mobile Web Integration Guide

Important: mkMob JavaScript tags are optimized for mobile websites, and not for mobile applications, or for third party development platforms. This means that even though it is possible to use mkMob JavaScript tags with mobile applications or third part development platforms, results may vary and mkMob will not be able to provide support.



Setting Up

  1. Create your account. Visit www.mkmob.com to register a new account.
  2. Register your property.
  3. Next, paste the code snippet provided below into the source code of your mobile website. Note: It has to be pasted on all the pages where you want to display mkMob ads.
<script type="text/javascript">
  var mkmob_conf = {
    propertyId: "YOUR-PROPERTY-ID",
    slotId: "YOUR-ADSLOT-ID",
    test: true
  };
</script>
<script type="text/javascript" src="//cdn.mkmob.com/ad/mkmob.js"></script>


Integrating the Ad Code

Further steps can be taken to intergrate your JavaScript Ad Code

During development and testing, the test parameter should be set to true, to ensure that only test ads are sent. When you set test to false, you will receive live ads.

  • The propertyId parameter is the unique ID of your site. You can manage your sites by first clicking the Publisher tab, next click My Properties and then click Manage beneath your property name. Before you can manage properties, you must sign in at https://www.mkmob.com/user/?login
  • The slotId parameter corresponds to the dimensions of the slot or box where ads appear on your site.

The recommended slot type for most publishers is MMA, which is a 320x50 slot that is compatible with rich media ads.

Notes:

The SDK will fetch ads asynchronously, so it will not block the loading of your page. The SDK script tags must be part of the HTML of the page; they cannot be generated dynamically by JavaScript.


Fetching Ads On Demand

By default, the JavaScript ad code inserts ads when the page is first loaded. To fetch ads on demand, add the parameter manual:true to the config object:

<div id="mkmob-ad-slot"></div>
<script type="text/javascript">
  var mkmob_conf = {
    propertyId: "YOUR-PROPERTY-ID",
    slotId: "YOUR-ADSLOT-ID",
    test: true,
    manual: true
  };
</script>
<script type="text/javascript" src="//cdn.mkmob.com/ad/mkmob.js"></script>

When the manual:true parameter is present, the ad is not loaded automatically at page load. The ad can then be fetched at some other time in the life cycle of the page, using the getNewAd function:

<script type="text/javascript">
  _mkmob.getNewAd(document.getElementById('mkmob-ad-slot'));
</script>

Note: After the ad has been loaded, a new ad can be fetched into the same slot using the same getNewAd call. This can be used to periodically reload the ad slot.

_mkmob.getNewAd can have a config object as an optional second parameter. If provided, the new config object will be used for making ad requests.

<script type="text/javascript">
  var new_config = {
    propertyId: "YOUR-PROPERTY-ID",
    slotId: "YOUR-ADSLOT-ID",
    test: true
  }
  _mkmob.getNewAd(document.getElementById('mkmob-ad-slot'), new_config);
</script>


Interstitial Ads

To show interstitial ads, ensure that slotId represents an ad slot of type Interstitial. Next, add the parameters adtype:"int" and manual:true to the config object:

<div id="mkmob-ad-slot"></div>
<script type="text/javascript">
  var mkmob_conf = {
    propertyId: "YOUR-PROPERTY-ID",
    slotId: "YOUR-ADSLOT-ID",   
    test: true,
    manual: true,
    adtype: "int"
  };
</script>
<script type="text/javascript" src="//cdn.mkmob.com/ad/mkmob.js"></script>
<script type="text/javascript">
  _mkmob.addEventListener("close", function(event){/* handle close button */});
</script>

Later, when you want to show the interstitial ad, fetch the ad with the following code:

<script type="text/javascript">
  _mkmob.getNewAd(document.getElementById('mkmob-ad-slot'));
</script>

When _mkmob.getNewAd is invoked, the ad is fetched and displayed. _mkmob.getNewAd can have a config object as an optional second parameter. If provided, the new config object will be used for making ad requests.

<script type="text/javascript">
    var new_config = {
        propertyId: "YOUR-PROPERTY-ID",
        slotId: "YOUR-ADSLOT-ID",   
        test: true
     }
   _mkmob.getNewAd(document.getElementById('mkmob-ad-slot'), new_config);
</script>

Interstitial ads contain a button to close them. When users click this button, any listener functions registered on the close event will be called.

To receive a callback when the ad is closed, register a JavaScript handler via _mkmob.addEventListener(). Refer to the example shown above.

The interstitial ad should be presented in a modal dialog, so that the user can interact with or dismiss the interstitial ad to proceed. Typically, this consists of a translucent overlay covering the entire browser viewport area, preventing the user from interacting with the web page, with the ad placed in the center.

Here is an example of a modal window using CSS and HTML. This example assumes a 320px wide ad slot, and is optimized for iOS and Android browsers:

<body>
  ...
  <!-- end of your page content -->
  <!-- begin ad interstitial overlay -->
  <div id="overlay">
    <div id="hbox">
      <div id="mkmob-ad-slot"></div>
      <script type="text/javascript">
        var mkmob_conf = {
          propertyId: "YOUR-PROPERTY-ID",
          slotId: "YOUR-ADSLOT-ID",
          test: true,
          manual: true,
          adtype: "int"
        };
      </script>
      <script type="text/javascript" src="//cdn.mkmob.com/ad/mkmob.js"></script>  
    </div>
  </div>
  <style type="text/css" media="screen">
  #overlay {
    visibility: hidden;
    position: absolute;
    width: 100%;
    height: 100%;
    left: 0px;
    top: 0px;
    z-index: 1000;
    background-color: rgba(0, 0, 0, 0.75);
    display: table;
  }
  #hbox {
    display: table-cell;
    vertical-align: middle;
    margin: 0px auto;
    text-align: center;
  }
  #mkmob-ad-slot {
    margin: 0;
  }
  </style>
  <script type="text/javascript" charset="utf-8">
    function fetchInterstitial() {
      _mkmob.getNewAd(document.getElementById('mkmob-ad-slot'));  
    }
    function showOverlay() {
      document.getElementById('overlay').style.visibility = 'visible';
    }
    function hideOverlay() {
      document.getElementById('overlay').style.visibility = 'hidden';
    }
    _mkmob.addEventListener("load", showOverlay);
    _mkmob.addEventListener("close", hideOverlay);
 
    fetchInterstitial();
  </script>
</body>

IMPORTANT

The SDK will fire the onload event when an interstitial ad has been successfully fetched from the server and has loaded into your page. The event will NOT be fired for No-Fill Responses or errors. You need to register a listener for this event via _mkmob.addEventListener() to prevent showing an empty modal window in case of an error or a NFR. To learn more about errors and NFRs, please read Handling Errors and No Fills Using Callback.

Note: To receive interstitial ads from the server, the ad slot must be of type Interstitial.


Auto Refreshing Ads

You can now enable auto refresh of text and banner ads, and specify a refresh interval (in seconds).

<div id="mkmob-ad-slot"></div>
<script type="text/javascript">
  var mkmob_conf = {
    propertyId: "YOUR-PROPERTY-ID",
    slotId: "YOUR-ADSLOT-ID",
    test: true,
    autoRefresh: 30 // note: in seconds, the minimum accepted value is 30
  };
</script>
<script type="text/javascript" src="//cdn.mkmob.com/ad/mkmob.js"></script>


Handling Errors and No Fills Using Callback

A publisher can be notified when an error is encountered while serving ads. This helps the publisher take appropriate steps to make better use of the information provided via the callback system. You can register callbacks for Errors and No-Fill Responses.

For example, if a publisher faces an NFR (No-Fill Response) scenario, a callback is sent notifying that there is a NFR. The publisher can now take steps to address and blank real estate issue that was caused by non-availability of ads.

<div id="mkmob-ad-slot"></div>
<script type="text/javascript">
  var mkmob_conf = {
    propertyId: "YOUR-PROPERTY-ID",
    slotId: "YOUR-ADSLOT-ID",
    test: true,
    // Register a No-Fill Response callback
    nofill: function() {
        /* do something else. call to other ad network or logic to display in-house ads, etc. */
    }
  };
</script>
<script type="text/javascript" src="//cdn.mkmob.com/ad/mkmob.js"></script>

The API will send a notification in case any errors occurred. To catch errors, you need to register a callback with the error parameter in your config object:

<div id="mkmob-ad-slot"></div>
<script type="text/javascript">
  var mkmob_conf = {
    propertyId: "YOUR-PROPERTY-ID",
    slotId: "YOUR-ADSLOT-ID",
    test: true,
    // Register an error handler
    error : function(message) {
        /* do something with the message. */
    }
  };
</script>
<script type="text/javascript" src="//cdn.mkmob.com/ad/mkmob.js"></script>


Serving Sticky Banner Ads

Sticky banner ads are those that remain stuck to a position on the screen even if the page is scrolled up or down. mkMob supports sticky banner ads when integrated using the JavaScript Ad Code. This feature is configurable where you can choose to set the sticky ad to the left or right, or on top or bottom of the screen.

<div id="mkmob-ad-slot" class="mkmob-ad"></div>
<script type="text/javascript">
  var mkmob_conf = {
    propertyId: "YOUR-PROPERTY-ID",
    slotId: "YOUR-ADSLOT-ID",
    test: true,
    sticky: "bottom" // "top", "right", "bottom" and "left".
  };
</script>
<script type="text/javascript" src="//cdn.mkmob.com/ad/mkmob.js"></script>

IMPORTANT

The sticky banner ad feature currently works only on devices running iOS version 5 or later or Android version 3 or later. On other devices, the parameter is ignored, and the sticky banner ad behaves like a normal banner ad, and is shown in the page in the position where the code is inserted.


Passing Demographic Information

Demographic data about the user may be passed to mkMob's Ad Server to assist with ad targeting. Demographic parameters are specified along with the Property ID, Slot ID, and so on, in the mkmob_conf object.

Supported Parameters

Parameter

Value

latlong_accu This should contain the latitude, longitude, and accuracy, separated by commas. This parameter is required if the request is needed to be considered for geo-targeting. The accuracy value should be "0" if the correct accuracy value is unavailable. Here, the accuracy is the radial accuracy of the lat-long data provided. More information on how to determine accuracy value can be found at http://en.wikipedia.org/wiki/Decimal_degrees.

Example: latlong_accu: "<Values as Latitude, Longitude, Accuracy>"

age User's age in years as an unsigned integer between 14 and 100. Values below 14 will be not be used for targeting due to privacy controls.
gender User's gender, if known. Accepted values are f or m in lowercase.
keywords A comma-separated list of words that will be used to return a contextually targeted ad.
reftag The value is a string used when Reporting/Performance Metrics groupings are needed by the publisher. The reftag may contain a maximum of 32 characters, it will be truncated if longer.


For example, reftag: "contact" can be used to group Reporting/Performance metrics based on advertisements served on a contact page.

Example code:

<script type="text/javascript">
  var mkmob_conf = {
    propertyId: "YOUR-PROPERTY-ID",
    slotId: "YOUR-ADSLOT-ID",
    test: true,
    gender: "m",
    age: 25,
    keywords: "cricket,hockey,golf"
  };
</script>
<script type="text/javascript" src="//cdn.mkmob.com/ad/mkmob.js"></script>


Opening Click URLs in a New Window

Publishers can now decide whether to open a click URL/Landing Page in the same window or in a new window.

The targetWindow parameter allows you this control. To open click URLs in a new window, the parameter value must be set to "_blank".

Sample JavaScript Code:

<script type="text/javascript">
  var mkmob_conf = {
    propertyId: "YOUR-PROPERTY-ID",
    slotId: "YOUR-ADSLOT-ID",
    test: true,
    targetWindow : "_blank"  // possible values "_blank" or "_top", default "_top".
  };
</script>
<script type="text/javascript" src="//cdn.mkmob.com/ad/mkmob.js"></script>

Note: If the targetWindow parameter is not present, or is not set to either "_blank" or "_top", it defaults to "_top", which opens the click URL in the same window.


Sample Ad Request URL from JavaScript

http://ads.mkmob.com/showad.asm?mk-propertyid=<Property ID>&mk-ad-slot=<Slot ID>&mk-ads=1&mk-version=pr-SDK-JSC-20140430&mk-format=HTML&__t=1336045859328&mk-frame=mkmob-frame-1gtaRZ&mk-mode=live