Revive AdServer (Formerly OpenX Source) API – Introduction: Part 1

We use Revive AdServer (Formerly OpenX Source) frequently at BlackRiver as the most open and customizable ad serving platform both for many of our clients and our own internal projects. When it comes toRevive AdServer (Formerly OpenX Source)  API – there is almost nothing out there but a few blog posts and outdated code samples. We would really like to share our experiences (both positive and negative) withRevive AdServer (Formerly OpenX Source)  API as we strongly believe that theRevive AdServer (Formerly OpenX Source)  platform should remain easy accessible and open to the public.

As you might already know, theRevive AdServer (Formerly OpenX Source) API service allows us to gain remote control of pretty much the entire functionality of the ad serving platform.Revive AdServer (Formerly OpenX Source) provides us with two versions (v1 and v2) of the API. You can still find some minimal documentation on v1 version of the API, but it has been deprecated since OpenX Source 2.7, thus we are going to focus on v2. The API service is based on the RPC (criticized by many as being inferior to REST) protocol, so as an obvious solution, we decided to use the latest PHP XML_RPC2 library provided by PEAR (http://pear.php.net/package/XML_RPC2/). The installation is fairly straight forward, if you have PEAR already installed, simply run pear install XML_RPC2

Now with the XML_RPC2 library setup, let us look into a specific code example:

require_once 'XML/RPC2/Client.php';
$oxLogin = array("username"=>"admin","password"=>"admin_password");
$opts = array('prefix' => 'ox.');
$advertiserId = 3;
 
$client = XML_RPC2_Client::create('http://domain.com/openx/www/api/v2/xmlrpc/', $opts);
 
try {
 
    $sessionId = $client->logon($oxLogin['username'],$oxLogin['password']);
 
    $result = $client->getAdvertiser($sessionId,$advertiserId);
    print_r($result);
 
    $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());
 
}

Even though the above code is fairly self-explanatory, there are a few things to take into consideration. The login credentials MUST be of the main account used on theRevive AdServer (Formerly OpenX Source)  installation, creating a separate administrator account just for the API service is not going to work. The “ox.” prefix for the RPC service is default and does not need to be changed. In this example, we authenticate (login) with the API, and then use the sessionId to retrieve a specific advertiser’s information as well as the daily stats for that specific advertiser. The advertiserDailyStatistics function returns an array of all days in which the advertiser was active, if there is no specific date passed as one of the parameters.

In the next little while, we are going to post more articles on specificRevive AdServer (Formerly OpenX Source)  API functions (perhaps even a full list with explanations – which was never provided by the formerly OpenX Source core team) and how to control Revive AdServer (Formerly OpenX Source) Advertisers, Publishers, Campaigns, Zones and Banners as well as customRevive AdServer (Formerly OpenX Source)  delivery limitations plugins and integration with open-source platforms like WordPress.