OpenX API – Advertisers (PART 2)
Before we start looking into specific components of the OpenX API, let us quickly overview the hierarchy the actual OpenX entities. The following diagram is a gross oversimplification (it does not refer to many other crucial entities like Agency or Channel – those will be covered in later tutorials) but should be enough to quickly grasp the concepts for anyone who is new to OpenX platform.
On one side you have Advertisers, Campaigns and Banners on the other you have Publishers and Zones. Both whole Campaigns and specific Banners can be linked to OpenX Zones. Within the next few tutorials we are going to be looking into each one of these entities in relation to OpenX API, starting with the Advertiser.
Unsurprisingly, the Advertiser entity contains the actual information about your typical advertiser, and OpenX API gives us a few sets of functions to play with.
Let us explore the “mutator” methods first. The methods will allow your application to retrieve, add, update and modify advertiser information.
getAdvertiser($sessionId,$advertiserId) getAdvertiserListByAgencyId($sessionId,$agencyId) addAdvertiser($sessionId,$advertiserData) modifyAdvertiser($sessionId,$advertiserData) deleteAdvertiser($sessionId,$advertiserId)
The advertiser data passed as the second parameter is an array which look similar to this:
Array( [advertiserId] => 3 [accountId] => 6 [agencyId] => 1 [advertiserName] => Henry Fonda [contactName] => Mr. Fonda [emailAddress] => hfonda@hfondafoundation.com [comments] => VIP Client )
It is critical to mention that unlike most basic things we do in PHP, the XML_RPC2 service is data type sensitive. So if, for example, you will try to send a string “1″ instead of an integer 1 as the agencyId, you will receive a type error Exception #801 : Field ‘agencyId’ is not integer. So to resolve this issue, you need to make sure all of your variable have a defined type, a simple (int) $agencyId should do the trick. At this point I am not going to include the explanation of accountId and agencyId fields, these will be described in the next tutorials.
The other methods of the Advertiser class/entity are the the statistical methods. These are used to retrieve advertiser performance statistics based on Campaign, Banner, Publisher or Zone.
getAdvertiserDailyStatistics($sessionId,$advertiserId,$startDate="",$endDate="") getAdvertiserCampaignStatistics($sessionId,$advertiserId,$startDate="",$endDate="") getAdvertiserBannerStatistics($sessionId,$advertiserId,$startDate="",$endDate="") getAdvertiserPublisherStatistics($sessionId,$advertiserId,$startDate="",$endDate="") getAdvertiserZoneStatistics($sessionId,$advertiserId,$startDate="",$endDate="")
The resultant sets of data will always be conveniently arranged into PHP arrays. For the statistical methods, the date parameters are optional, if none are specified an array of all active dates for which some data exists will be returned. A typical resultant array of a advertiserDailyStatistics query without specific dates would look like the following:
Array( [0] => Array( [impressions] => 21 [clicks] => 2 [requests] => 0 [revenue] => 0.105 [day] => stdClass Object( [scalar] => 20111215T00:00:00 [xmlrpc_type] => datetime [timestamp] => 1323907200 ) ) )
The elements of this array are specific days for which there is data available. The day element indicates the exact date, impressions, clicks and requests are self explanatory and the revenue is a monetary value calculated by type of campaign in question (CPM or CPC) and the corresponding costs – again this (as well as eCPM) will be explored further in the Campaign tutorial.
I am going to end this with a PHP sample, which sort of demonstrates the concepts described above.
/* Include the XML_RPC2 library */ require_once 'XML/RPC2/Client.php'; /* Some basic presets */ $oxLogin = array("username"=>"admin","password"=>"admin_password"); $opts = array('prefix' => 'ox.'); $advertiserId = YOUR_ADVERTISER_ID; $agencyId = YOUR_AGENCY_ID; $accountId = YOUR_ACCOUNT_ID; /* Connect to the OpenX API*/ $client = XML_RPC2_Client::create('http://domain.com/openx/www/api/v2/xmlrpc/', $opts); try { /* Authenticate with the OpenX API and retrieve the sessionId required for all other function calls */ $sessionId = $client->logon($oxLogin['username'],$oxLogin['password']); /* Get advertiser info for $advertiserId */ $result = $client->getAdvertiser($sessionId,$advertiserId); print_r($result); /* Create new advertiser for $accountId and $agencyId */ $advertiserData = array( "accountId"=> (int) $accountId, "agencyId"=> (int) $agencyId, "advertiserName"=>"Henry Fonda", "contactName"=>"Mr. Fonda", "emailAddress"=>"hfonda@hfondafoundation.com", "comments"=>"VIP Client"); $result = $client->addAdvertiser($sessionId,$advertiserData); print_r($result); /* Delete advertiser $advertiserId */ $result = $client->deleteAdvertiser($sessionId,$advertiserId); print_r($result); /* Get advertiser daily stats for $advertiserId */ $result = $client->advertiserDailyStatistics($sessionId,$advertiserId); print_r($result); $client->logoff($sessionId); } catch (XML_RPC2_FaultException $e) { // The XMLRPC server returns a XMLRPC error die('Exception #' . $e->getFaultCode() . ' : ' . $e->getFaultString()); } catch (Exception $e) { // Other errors (HTTP or networking problems...) die('Exception : ' . $e->getMessage()); }
Leave a Reply
Comments: 1
I was just seeking this info for a while. After six hours of continuous Googleing, at last I got it in your web site. I wonder what is the lack of Google strategy that don’t rank this kind of informative web sites in top of the list. Usually the top web sites are full of garbage.