API Example Advanced Ad Reqeust

From InClickAdServer

Advanced Advertisement Request

This API Service Request allows for retrieval of a list of targeted advertisements from which you could further filter based on your project requirements. For example, you could retrieve five ads from the system, apply your own filtering to get the single result to show reporting back the ad server which of the five were delivered. By utilizing this advanced method on post-request modifications, you allow the ad server to provide accurate reporting and yield optimization.

The Code Example

Breaking Down the Code

This require references the local inClick Ad Server deployment configuration files allowing your code to utilize the pre-packaged API Objects as well as the bundled PHPOlait services.

These requires (includes) contain the API Objects and Classes needed for this API Service Request.

The $base_url is the URL to your inClick Ad Server deployment, the ad server root URL. For local host API usage, the constant of INCLICK_WEB_URL is defined in the globals.php file referenced earlier. Remote deployments, deployments where the ad server and API Request Location are not on the same server, would change this to the fully qualified URL to the ad server root directory.

The $service_key is one of the the api_service_keys values you created for your ad server. (more information)

This is where we create an instance of the classes needed to request advertisements from the ad server.

These objects set the filter criteria for the advertisement request.

ObjectName Required Value Type Description
setUserIPAddressYesIP AddressThe IP address of the user viewing the request.
setReferringURLYesTextThe URL where the advertisement(s) are requested.
setChannelIDYesNumericThe channel ID for the ad request.
setPublisherIDYesNumericThe account number for the publisher.
setAdCountYesNumericThe number of results to return.
setKeyword NoTextThe keyword to match to ads.
setLimitToKeywordMatches NoTrue / FalseWhen set to true, the result set will only include matched results (no Run of Channel). When set to false, the system will also consider Run of Channel ads for inclusion.
setAdOffset NoNumericThe number of ads to offset. Typically used for search.
setPublisherChannelIDList NoArrayThe Publisher Channel ID's for the request provided as an array.
setRegionCode No--
setRegionCode No--
setUseContextualYesTrue / FalseThis will instruct the ad server to either automatically match ads to content (true) or use the keyword provided (false) in the setKeyword object.
setParentRegionCode No--
setRequestID No--
setSEMURL No--

This line is the API Service Request that sends the request for qualified advertisements to your inClick Ad Server deployment. The $advertisement_list is the object that contains the qualified results.

The following are the objects for each advertisement returned:

Object Description
headlineThe headline of the advertisement.
description_line1Line 1 of the advertisement description.
description_line2Line 2 of the advertisement description.
display_urlThe display URL for the advertisement.
urlThe destination URL (Do not use this for the click-through as it is not tracked here).
advertiser_idThe account number of the advertisers ad.
campaign_idThe campaign number for this result.
publisher_idThe publisher ID for the request.
click_cpcThe adjusted cost for this ad.
channel_idThe channel for this request.
requested_ad_countThe number of ads requested. This does not represent the number returned.
click_through_parameterThis value is the click-through payload and contains the information for tracking the click. The click-through URL is constructed as: http://ADSERVER_ROOT/c/adclick.php?ad=click_through_parameter
publisher_channel_idsThe publisher channel ID(s) used in this request.
keywordThe keyword in the campaign this request matched.
user_ip_addressThe IP address provided for the request.
referring_urlThe URL where the ad was delivered.

This section of code is provided to give you a visual confirmation of the initial advertisement request.

$impression_result is the advertisement we decided to deliver, the first record returned in the result set.

This section of code sets the parameters for the impression. This allows you to modify values where necessary. IE: Adjusting the CPC value or adjusting the position. Below is a list of available objects: These objects set the filter criteria for the advertisement request.

Object Required Value Type Description
setCampaignIDYesNumericThe campaign id of the ad.
setAdvertiserIDYesNumericThe advertiser ID for the ad.
setChannelIDYesNumericThe channel ID for the ad request.
setClickCPCYesNumericThe amount to to be billed for this ad if clicked.
setTimestampYesNumericThe timestamp of the delivery.
setPositionYesTextThe position of this delivered ad. Can be adjusted as needed.
setUserIPAddressYesIP AddressThis is the IP address of the person viewing the ad.
setRequestHashNoMD5This is the unique hash generated for this impression.
setSearchQueryNoTextThis is the search query as provided in the request.
setKeywordNoTextThis is the keyword that triggered the match.
setPublisherIDYesNumericThis is the publishers account number for the request.
setPublisherChannelIDsNoNumeric ArrayThis is the array of Publisher Channel ID's, if provided, for this request.
setReferrerURLNoTextThis represents the referring URL, the URL where the advertisement was delivered.
setRegionCodeNoFormatted String-

This sends the information to the ad server to record this impression.

This section of code is provided to give you a visual confirmation of the impression.