Revive AdServer (Formerly OpenX Source) API – Advertisers: Part 2

Share This

Before we start looking into specific components of the Revive AdServer (Formerly OpenX Source) API, let us quickly overview the hierarchy the actual Revive AdServer (Formerly OpenX Source) 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 Revive AdServer (Formerly OpenX Source) 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 Revive AdServer (Formerly OpenX Source)  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 Revive AdServer (Formerly OpenX Source)  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"=>"[email protected]",
                        "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());
 
}

15 Responses to “Revive AdServer (Formerly OpenX Source) API – Advertisers: Part 2”

  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.

  2. Sameer says:

    Hello,

    I went through this. Its very useful and it helped me in some functions.

    Now, I am trying to write a jsp application which will establish the xmlrpc connection with openxapi and return the values. I am using openxapi v1

    Here I get the dates through a datepicker and then convert to date format:

    `String dateStr = request.getParameter(“datum1”);
    SimpleDateFormat formater = new SimpleDateFormat(“dd-MM-yyyy”);
    Date result1 = formater.parse(dateStr);

    String dateStr2 = request.getParameter(“datum2”);
    SimpleDateFormat formater2 = new SimpleDateFormat(“dd-MM-yyyy”);
    Date result2 = formater2.parse(dateStr2);`

    Then I call the service provided by openxapi (Advertiser Daily Statistics)
    (sessionID, advertiserID, from date, to date)

    `Object[] objects1=(Object[])client.execute(“advertiserDailyStatistics”,new Object[]{sessionId,3,result1,result2});`

    Pl help with this weird issue

    Thanks

  3. sameer says:

    Hi ,

    This code is not returning anything –

    `Object[] objects1=(Object[])client.execute(“advertiserDailyStatistics”,new Object[]{sessionId,3,result1,result2});`

    Tried printing the value or even the length of the object, but no success

    Thanks

  4. admin says:

    Check if it works without the date range.

  5. sameer says:

    Hi,

    Thanks for your reply.

    Ya it worked without the date range. I have read about the java date format and xmlrpc date format which takes iso8601. I think this is the issue. I have configured error log files in my netbeans setup, I get this log-

    Fault Code: 3
    Fault Reason: Incorrect parameters passed to method: Wanted dateTime.iso8601, got string at param 3

    Pl help me if you know how to pass the date range from this jsp code to the xmlrepc call to openxapi.

    Thanks

  6. admin says:

    That’s correct – it does require a specific XML_RPC2_Value date object in PHP it looks like this:

    $date = XML_RPC2_Value::createFromNative(“20121212T00:00:00”, ‘datetime’);

  7. sameer says:

    Hi Admin,

    Thanks for quick response and help. I really appreciate it.

    I am a newbie to jsp/java. As you mentioned –
    “That’s correct – it does require a specific XML_RPC2_Value date object in PHP it looks like this:

    $date = XML_RPC2_Value::createFromNative(“20121212T00:00:00″, ‘datetime’);”

    Do you happen to know how to do the same in jsp/java?

    Thanks again

  8. Priyanka says:

    Hi,
    While adding Publisher I want to add oac_country_code ,oac_language_id also . My other attributes are getting added but not these 2 . My code is:-
    ‘oac_country_code’ => new XML_RPC_VALUE($objPublisher->oac_country_code,’string’) ,
    ‘oac_language_id’ => new XML_RPC_VALUE($objPublisher->oac_language_id,’int’),

    I added values:
    $objPublisher->oac_country_code = ‘es’;
    $objPublisher->oac_language_id = 2;
    Please some one let me know.

  9. Priyanka says:

    How to add video banner does any one know..

  10. Jeet says:

    I am writting my own plugin in codeigniter for openx API connection and trying to build an application from where all openX user can login. My problem is openX API v2 only provides access for “admin installation user”. I have “admin” as installation user and “raj” as manager account. Now, from my codeigniter plugin only admin user can login and user “raj” cannot login because API returns message “user is not admin installation user”. Can anybody advise what changes i have to do in my login function in order to make all openX user login successfully from my plugin.

    The below is the function which calls the API and returns the sessionID if login is successful.

    private function _XmlRpcReceiveData(){

    $xmlRpcHost = ‘localhost’;
    $webXmlRpcDir = ‘/openx/www/api/v1/xmlrpc’;
    $logonXmlRpcWebServiceUrl = $webXmlRpcDir . ‘/LogonXmlRpcService.php’;
    $agencyXmlRpcWebServiceUrl = $webXmlRpcDir . ‘/AgencyXmlRpcService.php’;
    $username = ‘admin’;
    $password = ‘xxxxxx’;

    $aParams = array(
    new XML_RPC_Value($username, ‘string’),
    new XML_RPC_Value($password, ‘string’)
    );
    $oMessage = new XML_RPC_Message(‘logon’, $aParams);
    $oClient = new XML_RPC_Client($logonXmlRpcWebServiceUrl, $xmlRpcHost);
    $oResponse = $oClient->send($oMessage);
    if (!$oResponse) {
    die(‘Communication error: ‘ . $oClient->errstr);
    }

    $sessionId = $this->_XmlRpcResponseData($oResponse);

    return $sessionId;
    }

  11. Adnan says:

    Extremely useful. Thankyou.

    Since you did not write further about it. May I know how did you find about fields that are needed to create an Advertiser? Should I look for Implementation file of each section? Also I think adding agencyId and accountId is irrelevant in this case.

    • Ilya Ber says:

      Please review the code in the article it demonstrates exactly how to create a new Advertiser entity.
      You don’t have to use accountId or agencyId – if you are only running a single account/agency.
      We are hoping to release a few more tutorials soon.

  12. songshu says:

    thnx, appreciate the work you put in here…
    trying to use this to create an easier/simpler frontend for the enduser…
    was wondering if you know a way to have the account_id of the newly created advertiser returned on execution

Leave a Reply to Adnan

Recent Revive AdServer (Formerly OpenX Source) Expandable Banners

Revive AdServer (Formerly OpenX Source)  Expandable Banners The following example demonstrates a 600px by 150px banner served by Revive AdServer (Formerly OpenX Source)  and expanded to 600px by 300px on rollover. The flash creative can be either uploaded to creatives directory directly (FTP) or just as an another Revive AdServer (Formerly OpenX Source)  banner (preferred). When uploading the SWF creative, you do not need to replace any hardcoded URLs or indicate a destination URL – that would be done in the HTML banner setup. Essentially, we are just using it as a storage container for our creative, all impressions and clicks will be … read more

 Twitter  LinkedIn  Google+  Skype RSS

Get in Touch

  • r Phone:
    (416) 877 2844 / (647) 258 4847
  • h Email:
    [email protected]
  • m Address:
    1454 Dundas St. East, Suite 124
    Mississauga, Ontario
    L4X1L4, Canada

Any Questions?

    Email

    Message