ASP

Contents 1 Introduction 2 Installation 3 Ad Placement and Number of Ads 4 Examples 4.1 Example 1 - Setting User/Page Parameters 4.2 Example 2 - Minimalist Request 5 API Reference 5.1 FetchAd 5.1.1 Description 5.1.2 Returns 5.2 FetchAdByLocation(String placement) 5.2.1 Description 5.2.2 Parameters 5.2.3 Returns 5.2.3.1 IMPORTANT 5.3 GetMkhojHeaders 5.3.1 Description 5.3.2 Returns 5.4 GetMkhojUrl 5.4.1 Description 5.4.2 Returns 5.5 GetPostBody 5.5.1 Description 5.5.2 Returns 5.6 MkhojAd() 5.6.1 Description 5.7 ParseResponse 5.7.1 Description 5.7.2 Parameters 5.7.3 Returns 5.8 RequestAds 5.8.1 Description 5.8.1.1 TIP 5.9 SetAdPlacements 5.9.1 Description 5.9.2 Parameter 5.9.3 Returns 5.10 SetBannerSize 5.10.1 Description 5.10.2 Parameter 5.10.3 Returns 5.11 SetNumOfAds 5.11.1 Description 5.11.2 Parameter 5.11.3 Returns 5.12 SetPageDescription 5.12.1 Description 5.12.2 Parameter 5.12.3 Returns 5.13 SetPageKeywords 5.13.1 Description 5.13.2 Parameter 5.13.3 Returns 5.14 SetPageType 5.14.1 Description 5.14.2 Parameter 5.14.3 Returns 5.15 SetSiteId 5.15.1 Description 5.15.2 Parameter 5.15.3 Returns 5.16 SetTestMode 5.16.1 Description 5.16.2 Parameter 5.16.3 Returns 5.16.3.1 TIP 5.17 SetUserAge 5.17.1 Description 5.17.2 Parameters 5.17.3 Returns 5.18 SetUserGender 5.18.1 Description 5.18.2 Parameter 5.18.3 Returns 5.19 SetUserId 5.19.1 Description 5.19.2 Parameter 5.19.3 Returns 5.20 SetUserInterests 5.20.1 Description 5.20.2 Parameter 5.20.3 Returns 5.21 SetUserLocation 5.21.1 Description 5.21.2 Parameter 5.21.3 Returns 6 Dos and Don'ts 7 Avoiding Caching of Ads

Introduction

This guide is intended to give publishers an understanding of integrating their mobile web property with InMobi's ad serving system using ASP.

The guide explains the syntax and semantics of parameters sent to InMobi's Ad Server while making an ad request, and lays out the guidelines to be followed while using the API/Library.

At a broad level, the publisher requests for ads from InMobi's ad serving system by setting certain required and optional parameters (explained later in this guide). The API is used to send this request over HTTP to InMobi's Ad Server to retrieve multiple ads.

The InMobi Ad Server allows publishers to request for multiple ads in a single call, therefore limiting protocol overhead and ensuring better targeting.

The flow diagram below illustrates the ad request and retrieval process.

Installation

The provided MkhojAd.asp file has to be placed in the path of the webserver directory. This file can be imported (using the include ASP directive) in an ASP page, and used for making ad requests.

Ad Placement and Number of Ads

If an ad is required for the top 20% of the web page, then the value associated should be string top.

Similarly, if an ad is required for the middle 60% of the web page, then the value associated should be string middle, and if an ad is required for the bottom 20% of the web page, then the value associated should be string bottom. However, if the placement value does not matter, then the string value page should be used to include the ad anywhere in the web page.

If the placement values are specified and set, then the number of ads requested are calculated using the number of placement values provided. This overrides the specification of number of ads using the function SetNumOfAds(NUMBER_OF_ADS). If the placement values are not specified at all, then the SetNumOfAds(NUMBER_OF_ADS) function call is mandatory to provide the number of ads requested.

If a placement value is provided n number of times, where n<=3, the ads retrieved for this placement value will be n. While using the function FetchAdByPlacement(PLACEMENT) to retrieve the ad for this placement, this function will return an ad for a maximum of n calls.

However, if placement values are not specified, and the number of ads requested are specified using the function call SetNumOfAds(NUMBER_OF_ADS), then the ads retrieved are associated with placement value page. While using the function FetchAdByPlacement(PLACEMENT), the publisher can provide any non-null string value to retrieve an ad.

Alternatively, the publisher can get ads by making a call to FetchAd() without any arguments.

Examples

Example 1 - Setting User/Page Parameters

This example shows how to set a few user and page parameters to fetch an ad.

<%@ Language=VBScript%>
<!-- #include file="MkhojAd.asp" -->

<%

'Creating InMobi's ad class object.
dim mkhojAd
Set mkhojAd = New MkhojAd

mkhojAd.SetSiteId(“abc123”)

'Setting end user's age
mkhojAd.SetUserAge(25)

'Setting end user's unique ID on publisher's website
mkhojAd.SetUserId("test id");

'Setting end user's gender
mkhojAd.SetUserGender(“m”);

'Setting end user's location
Dim locArray(3)
locArray(0) = "Bangalore"
locArray(1) = "Karnataka"
locArray(2) = "India"
mkhojAd.SetUserLocation(locArray);

'Setting end user's interests
mkhojAd.SetUserInterests(“Internet Browsing");

'Set publisher's webpage type
mkhojAd.SetPageType("News");

'Set publisher's page keywords
mkhojAd.SetPageKeywords("News and current affairs");

'Set publisher's webpage description
mkhojAd.SetPageDescription("News – National and Local");

'set the placement values for which Ads are required
Dim plcmcnt(3)
plcmnt(0) = "top"
plcmnt(1) = "bottom"
plcmnt(2) = "middle“

mkhojAd.SetAdPlacements( plcmcnt);

'Request ads from InMobi's Ad Server
mkhojAd.RequestAds();

'Fetch ad for top 20% of the page
Response.Write(mkhojAd.FetchAdByLocation("top"));

'fetch ad for middle 60% of the page
Response.Write(mkhojAd.FetchAdByLocation("middle"));

'fetch ad for bottom 20% of the page
Response.Write(mkhojAd.FetchAdByLocation("bottom"));

%>

Example 2 - Minimalist Request

This example shows how to request multiple ads using a minimum set of function calls.

<%@ Language=VBScript%>
<!-- #include file="MkhojAd.asp" -->

<%

'Creating InMObi's ad class object.
dim mkhojAd
Set mkhojAd = New MkhojAd

mkhojAd.SetSiteId(“abc123”)

'Set number of ads
mkhojAd.SetNumAds(2);

'Request ads from InMobi's Ad Server
mkhojAd.RequestAds();

Response.Write(mkhojAd.FetchAd());
Response.Write(mkhojAd.FetchAd());

%>

API Reference

FetchAd

---

public function FetchAd( )

Description

Returns the ad text if an ad is available. Otherwise, a blank string is returned. This function should only be used when a publisher has not provided any placement values at the time of ad request. If placement values were not provided, this function call will return an ad for a maximum number of times of the value of the numberOfAds argument provided by the publisher at the time of ad request.

Returns

The ad text to be directly printed/written in an HTML page to show the ad. A blank string if an ad is not available.

FetchAdByLocation(String placement)

---

public function FetchAd(“placement”)

Description

Returns the ad text for a specified ad placement value. The placement value can be one of the strings top, middle, bottom, or page. The placements are specified while making an ad request. If not specified, then ads returned are associated with placement value page. If the ad placements were not specified while making an ad request, the user has the option of specifying other placements like top-left, left, right, and so on.

Parameters

adPlacement – The string value specifying the placement of the requested ad in the page (top, middle, bottom, page).

Returns

The ad text for the specified adPlacement value (provided by user at time of an ad request), to be directly printed/written in an HTML page to show the ad. A blank string if an ad is not found for the specified adPlacement value.

IMPORTANT

Calling FetchAdByPlacement(String) function n number of times for a particular placement value, where n is greater than the number of times this particular placement value was specified while making an ad request will not return a valid ad. The number of times this function will return a valid ad will be less than or equal to the number of times this particular placement value is specified while making an ad request.

The reason for returning less number of ads than the number actually requested can be because of no fill, that is, when InMobi's Ad Server served no fill ad, which is the string value:

<!--InMobi. No ad for this position.-->

As this is a comment for an HTML page, it will not be visible to the end user.

GetMkhojHeaders

---

public function GetMkhojHeaders()

Description

This function returns the necessary headers that are set before sending an ad request to InMobi. This function has to be invoked if publishers want to have their own curl-library to make ad requests.

Returns

An array of strings containing the necessary headers.

GetMkhojUrl

---

public function GetMkhojUrl()

Description

This function returns the URL to which the request has to be sent to make an ad request. This function has to be invoked if publishers want to have their own curl-library to make ad requests.

Returns

A string containing the InMobi URL.

GetPostBody

---

public function GetPostBody()

Description

Constructs and returns the post body content to be sent along with an ad request to InMobi's Ad Server. The content to be sent is URL encoded in UTF-8 encoding format.

Returns

The post body content to be sent as part of HTTP request while making an ad request.

MkhojAd()

---

public Sub Class_Initialize()

Description

Constructs a new MkhojAdclass object for the publisher's siteId. This object is used for setting required parameters (for example, ad placement values, number of ads, and so on) and optional parameters (for example, user's age, location, and so on), and making ad request. The fetchAd(String) method can be used to fetch the ad content for a specified placement value if the publisher has specified the placement values before making an ad request.

If siteId provided is not valid or has a wrong value, then no ads can be received.

ParseResponse

---

public function ParseResponse(mkResponse)

Description

This function parses the content received for an ad request to InMobi's Ad Server. After parsing the contents, each individual ad is stored in the associated array of ads for a particular placement value. For example, for ad placement value top, there will be an array of ads (the string values) saved in a hashtable.

Parameters

The response received from InMobi after an ad request is made.

Returns

Boolean value true if the response was parsed successfully. Else, false.

RequestAds

---

public function RequestAds()

Description

This function makes an HTTP request to InMobi's Ad Server assuming that all required and optional parameters are set. After receiving contents from InMobi's Ad Server, this function internally makes calls to other class functions to parse and associate the ads with their placement values, and finally saves them in their respective arrays.

Only after this function call, the fetchAd(String adPlacement) function call can be made.

TIP

If you want to use your choice of HTTP library, ensure that the returned content is parsed, and ads are fetched using the InMobi library only.

SetAdPlacements

---

public function SetAdPlacements(String-Array Placements)

Description

This function sets the ad placement values to be sent to InMobi's Ad Server. The number of arguments sent in this array equals the number of ads requested, irrespective of the number of ads set explicitly using setNumOfAds(int). The ad placement value can be one of the strings top, middle, bottom, or page, depending upon where the publishers want to include the ad on their webpage, where top, middle, and bottom designates the top 20%, middle 60%, and bottom 20% of the page respectively.

The page value designates that an ad can be placed anywhere in the web page. This function takes an array of strings, where each value can be one of the valid placement values described.

The maximum size of the adPlacements array can be 3, which means that in a single ad request, a publisher can only ask for a maximum of three ads. If more than three placement values are provided, then the rest are ignored and no ad is served for those extra placement values.

Parameter

An array of strings where each string is one of the values top, middle, bottom, or page.

Returns

A boolean value indicating whether the placements were successfully set or not.

SetBannerSize

---

public function SetBannerSize(mkBannerSize)

Description

This function sets the banner size of an ad to be served for the ad request. The value for the banner size is to be sent as a request parameter to the function.

Parameter

An integer value specifying the required size of the banner .

The parameter values accepted, and slot sizes supported, are shown here:

Parameter Value	Slot Size	Intended Inventory
1	120x20	All Phones (Feature Phones, iOS, Android)
2	168x28	All Phones (Feature Phones, iOS, Android)
3	216x36	All Phones (Feature Phones, iOS, Android)
4	300x50	All Phones (Feature Phones, iOS, Android)
9	320x48	Smartphones and Tablets (iOS, Android, Others)
10	300x250	Smartphones and Tablets (iOS, Android, Others)
11	728x90	Smartphones and Tablets (iOS, Android, Others)
12	468x60	Smartphones and Tablets (iOS, Android, Others)
13	120x600	Smartphones and Tablets (iOS, Android, Others)
14	320x480	Smartphones and Tablets (iOS, Android, Others) – Interstitial ads
15	320x50	Smartphones and Tablets (iOS, Android, Others) – Rich media expandable ads
16	1024x768	Tablets – Interstitial ads
17	1280x800	Tablets – Interstitial ads

Returns

A boolean value indicating whether the banner size value set is one of the integer values.

SetNumOfAds

---

public function SetNumOfAds(integer numberOfAds)

Description

This function sets the number of ads requested. The numberOfAds argument can have a maximum value of 3. If a value of more than 3 is provided, then this argument is set to 3 on the server side.

This function call matters if and only if the placement values are not specified. If placement values are specified and set, then this function call does not matter, and the number of ads requested are calculated using the placement values provided by the publisher.

Parameter

The integer value specifying the number of ads required by publisher.

Returns

A boolean value indicating whether the number of ads were successfully set or not.

SetPageDescription

---

public function SetPageDescription(String pageDescription)

Description

This function sets the page description of the publisher's web page. For example, if the publisher's web page is an online gaming portal, then the argument provided can be online gaming.

Parameter

The string value describing the type of page.

Returns

A boolean value indicating whether the page description was successfully set or not.

SetPageKeywords

---

public function SetPageKeywords(string pageKeywords)

Description

This function sets the page keywords associated with the publisher's webpage.

Parameter

The string value specifying the page's keywords.

Returns

A boolean value indicating whether the page keywords were successfully set or not.

SetPageType

---

public function SetPageType(String pageType)

Description

This function sets the page type of the publisher's webpage.

Parameter

The string value specifying the page type of the publisher's web page.

Returns

A boolean value indicating whether the placements were successfully set or not.

SetSiteId

---

public function SetSiteId(String SiteId)

Description

This function sets the Site ID of the publisher in the MkhojAd object created. No ads will be returned if the parameter is invalid.

Parameter

The string value specifying the Site ID of the publisher site.

Returns

A boolean value indicating whether the Site ID was successfully set or not.

SetTestMode

---

public function SetTestMode(boolean testMode)

Description

This function sets the test mode while integrating and using InMobi's Ad API. If the test mode is set, then it means that the publisher's webpage will receive ads from InMobi's test server. This means that the impressions served and the clicks on those impressions, while the test mode is set, will not be recorded and monitored.

To set test mode, pass the boolean value true to this function. To go back to live mode, pass the boolean value false to this function. After the publisher is finished integrating the InMobi's Ad Code API, this function can be used for test purposes.

Parameter

The boolean value true to switch on the test mode, and boolean value false to switch on live mode.

Returns

A boolean value indicating whether the test mode was successfully set or not.

TIP

Use the ad code's test mode when testing your site. Testing is inclusive of, but not limited to functionality, performance, and debugging.

SetUserAge

---

public function SetUserAge(int userAge)

Description

This function sets the age of the end user.

Parameters

Integer value specifying the end user's age.

Returns

A boolean value indicating whether the user's age was successfully set or not.

SetUserGender

---

public function SetUserGender(Stringized-char gender)

Description

This function sets the end user's gender. The allowed values are one of the lowercase characters m, f, or t.

Parameter

The lowercase character value specifying user's gender. Possible values being m, f, or t.

Returns

A boolean value indicating whether the user's gender was successfully set or not.

SetUserId

---

public function SetUserId(String userId)

Description

This function sets the unique user ID of the end user on the publisher's website.

Parameter

The string value specifying the end user's unique ID on the publisher's website.

Returns

A boolean value indicating whether the user ID was successfully set or not.

SetUserInterests

---

public function SetUserInterests(String userInterests)

Description

This function sets the end user's interests that they specified while registering or using the publisher's website.

Parameter

The string value specifying the end user's interests.

Returns

A boolean value indicating whether the use's interests were successfully set or not.

SetUserLocation

---

public function SetUserLocation(String userLocation[])

Description

This function sets the end user's location as specified by them while registering or using the publisher's website.

Parameter

The string array value specifying the end user's location details.

Returns

A boolean value indicating whether the user's location was successfully set or not.

Dos and Don'ts

• Do not call the ad requesting (request_ads or requestAds) function multiple times in a single page. The ad code is designed to provide multiple ads in a single request, with a limit imposed on the maximum number of ads per page.
• Do not provide unreal values for demographic or page information as it can affect the ad targeting and site monetization wrongly.
• Do not paste the ad output twice after fetching it using the fetch_ad or the fetchAd function once.
• Multiple ads served in a single request are supposed to be stitched into one single page request on the publisher's side.
• Ads retrieved from InMobi's Ad Server should be stitched into the publisher page. Any decision on whether to stitch an InMobi ad or not has to made before the ad call.
• Ads retrieved from the InMobi Ad Server are not supposed to be cached in any form for later usage.

Avoiding Caching of Ads

Google Wireless Transcoder (GWT) is known to cache publisher pages and serve it to browsers with some common features like carrier and handset capabilities. As a side effect of caching publisher pages, GWT also caches the InMobi ads stitched into it. This results in:

• Opportunity loss for publishers: InMobi doesn’t get to know about page impression and old ads keep rolling.
• Bad targeting.

InMobi’s research suggests that adding the following meta tags in a <HEAD> tag of site pages is effective in avoiding caching.

<META NAME="ROBOTS" CONTENT="NOARCHIVE">
<META NAME="GOOGLEBOT" CONTENT="NOARCHIVE">

It is recommended that publishers use these tags to enhance monetization of their properties.