Thursday, August 27, 2009

OpenX API bindings for .Net

I've been working for the last month on a library that implements API bindings for OpenX in .Net. The OpenX API is quite big and I recently finished mapping all available methods so I decided to call it an early alpha release.

With this you can do:

  • CRUD operations on all OpenX entities (Advertiser, Banner, Campaign, Manager, Publisher, User, Zone)
  • Configure banner targeting
  • Link/unlink zones with banners and campaigns
  • Get various stats with strongly typed results

It relies on Charles Cook's XML-RPC.NET library (which is the de-facto standard xml-rpc library for .Net) which I had to modify slightly due to some irregularities in the OpenX XML-RPC server. Hopefully Charles will make xml-rpc.net more tolerant to these glitches soon so I can kill off my fork and use the standard xml-rpc.net.

Anyway here's a sample snippet querying for an advertiser's daily stats:

[Test]
public void AdvertiserDailyStats() {
    using (ISession session = new SessionImpl("user", "password", "http://localhost:10002/openx/api/v2/xmlrpc/")) {
        DailyStats[] r = session.GetAdvertiserDailyStatistics(1, DateTime.Now.AddYears(-1), DateTime.Now);
        Console.WriteLine("got {0} stats", r.Length);
        foreach (DailyStats stat in r) {
            Console.WriteLine("Stats for day {0}:", stat.Day.ToShortDateString());
            Console.WriteLine("Impressions: {0}", stat.Impressions);
            Console.WriteLine("Clicks: {0}", stat.Clicks);
            Console.WriteLine("Requests: {0}", stat.Requests);
            Console.WriteLine("Revenue: {0}", ((decimal) stat.Revenue).ToString("C"));
        }
    }
}

I wanted to release this as as early as possible because it's feature-complete but barely tested so I need people to try it and help me stabilize it by reporting any bugs and hopefully also contribute patches!

You can browse the code and fork it on github.

Binaries are available here.

PS: It seems that both Roger Dickey and I have been working independently on this at the same time, a situation that always sucks. I pinged him when I discovered this and he agreed to work together with me on this one.

31 comments:

Milind Kansagara said...

Hi!!

I am milind kansagara and i have to integrate the openx adserver into my .net web application. Is there any way to integrate this ?

Regards,
Milind Kansagara
http://milindkansagara1984.blogspot.com

Mauricio Scheffer said...

Milind, yes, that's exactly what this article is about. However you don't need this if you only want to show ads on your web app. In that case you can just use the javascript code that openx provides.

adam said...

Does this code need to run local to openx, as in on the same server? I tried to run this code from my home computer and my openx install is on a remote webserver. I get a "Forbidden" error message when I try to run the code.

Mauricio Scheffer said...

OpenX can be anywhere accessible over http. Double check the URL, username and password in OpenXNet.Tests/App.config.sample and don't forget to copy it as app.config.

adam said...

Got it working now. Thanks!

ufoloko said...

Hi, i need to use your library or something similar to generate custom scripts or server scripts to show in mobile apps. Maybe I can do it with your component?

Regards

Mauricio Scheffer said...

@ufoloko: you probably don't need the API for that. Just configure OpenX zones, targets, etc and put the js code in your code.

ufoloko said...

I cant use the javascript tags because mobile devices doesnt support scripts

Other reason is i want to port banner images throw some handler to adjust to device model, i already have a system for this

For all of this i need to customize ad server from asp.net

Mauricio Scheffer said...

I don't know if that's possible with OpenX... try asking in their forums.

Unknown said...

Did you two able to work together on this one? I just take a look at Roger Dickey's blog a while ago.

Mauricio Scheffer said...

DucDigital: don't know what happened, we exchanged a couple of emails and he agreed to work on the library hosted at github, but it seems he has continued development on his own without any public code repository.

Unknown said...

thats sad, but thanks for the library. Im implementing it :P

Unknown said...

Hola, excelente trabajo, me ha funcionado muy bien, no tienes considerada la estadística por hora?
Gracias

Mauricio Scheffer said...

Hola Juan, solamente están las funciones que provee la API de OpenX y no creo que tenga estadísticas por hora. Pero si hay y me faltan, avisame.

Desmondo said...

Nice work fella. Had started doing something similar when I stumbled across this. What sort of license are you making this available under?

Also, Do you know of a way of retrieving the invocation code from OpenX so I can automagically update the zone on the target website?

Mauricio Scheffer said...

@Desmondo: it's Apache v2.

Anonymous said...

Hi,


How do I create a Publisher/Website using OpenXNet?


Thanks & Regards
Indrani

Mauricio Scheffer said...

@Indrani: it seems that I forgot about Publisher operations. It'd be great if you could fork and implement them!

Anonymous said...

Hi,

With regard to Banner, could you please help me to map attributes like Alt Text / Keywords / Text below / Status Text etc.

Banner banner = new Banner();
banner. // I DON’T FIND ANY APPROPRIATE PROPERTIES TO MAP THE AFORESAID ATTRIBUTES

Thanks & Regards,

Indrani

Mauricio Scheffer said...

@Indrani: I just implemented Banner.Alt. The other properties don't seem to be available through the API.

Howard said...

We are developing a .NET based system which will use OpenX to create and schedule ads. We need the complete API available to .NET including Publisher functionality. Has anyone implemented this part of the API?

Thanks,

Howard

Mauricio Scheffer said...

@Howard: it's an open source project. You can fork and implement the Publisher operations. It's very easy to do so, take a look at the code, it's trivial.

blogspot.com said...

sir How to use open x API ( php) in our site step by step

i don't have knowldge about APi

Mauricio Scheffer said...

I recommend posting your question with all relevant details on stackoverflow.com.

Tim Bass said...

Here is some example OpenX API code on how to get booked impressions using the campaign ID:

http://www.unix.com/unix-linux-applications/167900-openx-api-example-xml-rpc-code-get-campaign-impressions.html

Mauricio Scheffer said...

@Tim Bass: I don't understand what's your point. The code you link is PHP, this is about .NET. And OpenX.NET supports getting a campaign's impressions in 1/5 the lines of code.

MillionLinesOfCode said...

Is there any documentation and examples on how to work with your API? I am new to OpenX and I've been asked to implement it on our Web Service but I'm clueless at where to begin. I'd appreciate if you could link me to some documentation, thanks.

Mauricio Scheffer said...

@MillionLinesOfCode: start with the OpenX API docs: http://www.openx.com/community/developers

This .NET API is a 1-to-1 mapping of those entities (Advertiser,Campaign,etc) and methods. See some tests https://github.com/mausch/OpenX.Net/blob/master/OpenXNet.Tests/OpenXServiceTests.cs

OpenX said...

@Mausch, is there any way to retrieve Banners by Zone? I didn't find a method on your API that allows that to happen.
Also, is the randomize by weight function available through your API?

Mauricio Scheffer said...

To previous commenter: This library simply maps what's described in http://www.openx.com/community/developers . I don't see any methods to retrieve banners by zone there. If the OpenX API docs list some method that is not mapped in this library, please file a new issue on github, fork the repository and implement it.

Anonymous said...

Hi Mauricio
May I know how can I use OrderBy ascending for list Advertisers name in below code;

var advys = session.GetAdvertisersByManager(1);
foreach (var ady in advys)
{
< p >@ady.AdvertiserName

}