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
require "../globals/globals.php";
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.
require_once INCLICK_CORE_DIR . "/external/classes/campaigns/IMG_Campaign.php"; require_once INCLICK_CORE_DIR . "/external/classes/campaigns/IMG_CampaignManagerClient.php"; require_once INCLICK_CORE_DIR . "/external/classes/campaigns/IMG_DeliveryManagerClient.php"; require_once INCLICK_CORE_DIR . "/external/classes/campaigns/IMG_FraudDetectionState.php"; require_once INCLICK_CORE_DIR . "/external/classes/campaigns/IMG_BaseFraudDetectionState.php"; require_once INCLICK_CORE_DIR . "/external/classes/campaigns/IMG_AdvertisementDeliveryRequest.php";
These requires (includes) contain the API Objects and Classes needed for this API Service Request.
$base_url = INCLICK_WEB_URL; $service_key = "YOUR_API_SERVICE_KEY";
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)
$delivery_manager = new IMG_DeliveryManagerClient($base_url, $service_key); $delivery_request = new IMG_AdvertisementDeliveryRequest();
This is where we create an instance of the classes needed to request advertisements from the ad server.
$delivery_request->setUserIPAddress("66.98.196.33"); $delivery_request->setReferringURL("http://www.inclick.net"); $delivery_request->setChannelID(2); $delivery_request->setPublisherID(1002); $delivery_request->setAdCount(5); $delivery_request->setKeyword ("broad matches"); $delivery_request->setLimitToKeywordMatches (false); $delivery_request->setAdOffset ( 0 ); $delivery_request->setPublisherChannelIDList (array('1','2')); $delivery_request->setRegionCode (""); $delivery_request->setParentRegionCode (""); $delivery_request->setRequestID (''); $delivery_request->setSEMURL (''); $delivery_request->setUseContextual(false); $delivery_request->setRequestID(''); $delivery_request->setFilter1Code(''); $delivery_request->setFilter1SubCode(''); $delivery_request->setFilter2Code(''); $delivery_request->setFilter2SubCode(''); $delivery_request->setFilter3Code(''); $delivery_request->setFilter3SubCode('');
These objects set the filter criteria for the advertisement request.
| ObjectName | Required | Value Type | Description |
|---|---|---|---|
| setUserIPAddress | Yes | IP Address | The IP address of the user viewing the request. |
| setReferringURL | Yes | Text | The URL where the advertisement(s) are requested. |
| setChannelID | Yes | Numeric | The channel ID for the ad request. |
| setPublisherID | Yes | Numeric | The account number for the publisher. |
| setAdCount | Yes | Numeric | The number of results to return. |
| setKeyword | No | Text | The keyword to match to ads. |
| setLimitToKeywordMatches | No | True / False | When 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 | No | Numeric | The number of ads to offset. Typically used for search. |
| setPublisherChannelIDList | No | Array | The Publisher Channel ID's for the request provided as an array. |
| setRegionCode | No | - | - |
| setRegionCode | No | - | - |
| setUseContextual | Yes | True / False | This 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 | - | - |
| setFilter1Code | No | - | - |
| setFilter1SubCode | No | - | - |
| setFilter2Code | No | - | - |
| setFilter2SubCode | No | - | - |
| setFilter3Code | No | - | - |
| setFilter3SubCode | No | - | - |
$result = $delivery_manager->getAdvertisements($delivery_request, false); $advertisement_list = $result->getReturnValue();
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 |
|---|---|
| headline | The headline of the advertisement. |
| description_line1 | Line 1 of the advertisement description. |
| description_line2 | Line 2 of the advertisement description. |
| display_url | The display URL for the advertisement. |
| url | The destination URL (Do not use this for the click-through as it is not tracked here). |
| advertiser_id | The account number of the advertisers ad. |
| campaign_id | The campaign number for this result. |
| publisher_id | The publisher ID for the request. |
| click_hash | - |
| click_cpc | The adjusted cost for this ad. |
| channel_id | The channel for this request. |
| requested_ad_count | The number of ads requested. This does not represent the number returned. |
| click_through_parameter | This 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 |
| request_hash | - |
| publisher_channel_ids | The publisher channel ID(s) used in this request. |
| keyword | The keyword in the campaign this request matched. |
| user_ip_address | The IP address provided for the request. |
| referring_url | The URL where the ad was delivered. |
if (!$result->succeeded()) { echo "Error Code: " . $result->getErrorCode() . ": "; echo "" . $result->getErrorMessage() . "<br>"; } else { $advertisement_list = $result->getReturnValue(); echo "Successfully retrieved ads!<br>"; echo "Ad Count = ".sizeof($advertisement_list); echo "<br>Advertisment Object Contents:<br>"; ?><pre><? print_r($advertisement_list); ?></pre><? // WE'LL ASSUME ONLY THE FIRST RECORD RETURNED WAS DELIVERED $impression_result = $advertisement_list[0]; //Click Through URL: $click_url = INCLICK_WEB_URL . "c/adclick.php?ad=" . $advertisement_list[0]->getClickThroughParameter() ; }
This section of code is provided to give you a visual confirmation of the initial advertisement request.
// WE'LL ASSUME ONLY THE FIRST RECORD RETURNED WAS DELIVERED $impression_result = $advertisement_list[0]; //Click Through URL: $click_url = INCLICK_WEB_URL . "c/adclick.php?ad=" . $advertisement_list[0]->getClickThroughParameter() ;
$impression_result is the advertisement we decided to deliver, the first record returned in the result set.
$impression->setCampaignID($impression_result->getCampaignID()); $impression->setAdvertiserID($impression_result->getAdvertiserID()); $impression->setChannelID(2); $impression->setClickCPC($impression_result->getClickCPC()); $impression->setTimestamp($impression_result->getTimestamp()); $impression->setPosition(1); $impression->setUserIPAddress($_SERVER['REMOTE_ADDR']); $impression->setRequestHash($impression_result->request_hash); $impression->setSearchQuery(""); $impression->setKeyword($impression_result->getKeyword()); $impression->setPublisherID(1002); $impression->setPublisherChannelIDs(""); $impression->setReferrerURL("http://www.google.com"); $impression->setRegionCode("");
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 |
|---|---|---|---|
| setCampaignID | Yes | Numeric | The campaign id of the ad. |
| setAdvertiserID | Yes | Numeric | The advertiser ID for the ad. |
| setChannelID | Yes | Numeric | The channel ID for the ad request. |
| setClickCPC | Yes | Numeric | The amount to to be billed for this ad if clicked. |
| setTimestamp | Yes | Numeric | The timestamp of the delivery. |
| setPosition | Yes | Text | The position of this delivered ad. Can be adjusted as needed. |
| setUserIPAddress | Yes | IP Address | This is the IP address of the person viewing the ad. |
| setRequestHash | No | MD5 | This is the unique hash generated for this impression. |
| setSearchQuery | No | Text | This is the search query as provided in the request. |
| setKeyword | No | Text | This is the keyword that triggered the match. |
| setPublisherID | Yes | Numeric | This is the publishers account number for the request. |
| setPublisherChannelIDs | No | Numeric Array | This is the array of Publisher Channel ID's, if provided, for this request. |
| setReferrerURL | No | Text | This represents the referring URL, the URL where the advertisement was delivered. |
| setRegionCode | No | Formatted String | - |
$result = $delivery_manager->trackImpressions(array($impression));
This sends the information to the ad server to record this impression.
if ($result->succeeded()) { $temp_list = $result->getReturnValue(); ?><pre><? print_r($temp_list); ?></pre><? } else { echo "Error Code: " . $result->getErrorCode() . ": "; echo "" . $result->getErrorMessage() . "<br>"; } echo "<a href='$click_url'>Ad Link</a>";
This section of code is provided to give you a visual confirmation of the impression.
