XRTB

NOTE: THIS REPOSITORY IS RETIRED.

RTB4FREE is now completely Dockerized and now comes with a campaign manager and an Elsatic Search based reporting system.

Look here:
https://github.com/RTB4FREE/bidder https://github.com/RTB4FREEE/crosstalk https://github.com/campaignmanager

===============================

A Real Time Bidding (RTB) 2.3 engine written in Java 1.8

This RTB project contains 3 major components: 1) A Real Time Bidding engine; 2) A Test page for sending test bids to the bidder; 3) A campaign manager for creating advertising campaigns.

This project is for those fairly familiar with RTB. With a basic understanding of RTB, this project will get you up and running with a commercial grade bidder in a short period of time.

Note, a major component of a commercial RTB system is a database for doing all those production things like campaign management, bid tracking, win handling and click through accounting. This project doesn't include any of that, However, the XRTB uses a publish/subscribe system (ZeroMQ) that will allow you to connect these functions of the bidder into your own custom database.

A production bidding enterprise would most likely require multiple bidding engines running behind a firewall. This project does not provide NGINX or AWS Load Balancer (or similar) infrastructure for this, you will need to tailor the administration of the XRTB to deal with these production issues. The XRTB comes out of the box ready to run in a multi-server bidding farm, you just need to lash it up and administer it.

BUILDING THE SYSTEM

This is a maven project.

You will need Maven installed to build the system. The libraries required are automatically retrieved by Maven. To see the dependencies, Look in the pom.xml file

If you use Eclipse make sure you use this as a maven project

Note, there is a .gitignore file included.

Build the Site

Now use Maven to build the system

$mvn site

----> This will compile the sources, generate the API docs and the JUNIT tests.

The API documentation in target/site/apidocs/allclasses-frame.html The Surefire reports are in target/site/surefire-report.html

Create the All Inclusive Jar File

Now create the all inclusive jar file:

$mvn assembly:assembly -DdescriptorId=jar-with-dependencies -Dmaven.test.skip=true

Now you have to decide whether to use Aerosspike (for multi-bidder support) or Cache2k (standalone)

MAKE YOUR LOCAL CONFIGURATION FILES

RTB4FREE has three configuration files. The log4j.properties file controls the logging of the application. The sample database is called "database.json" which is used to initialize the Aerospike database, or, if not using Aerospike, to act as the database for a stand a lone bidder. The second configuration file is Campaigns/payday.json which sets up the operational parameters for your bidder. Neither of these files exist after you do the GIT clone (or subsequent GIT pull). You need to make these two files on your instance by copying the samples:

$cd XRTB $mkdir logs $cp sampledb.json database.json $cp Campaigns/samplecfg.json Campaigns/payday.json

If you forget this step, RTB4FREE will not start. These files are kept local on your instance so that changes you make to Campaigns/payday.json and database.json don't block your ability to GIT pull to get updates for the bidder.

THERE ARE 2 VERSIONS OF RTB4FREE

RTB4FREE comes in 2 versions. One is a standalone system, and is intended for running on a single instance. It requires no Aerospike support. Instead it uses an embedded Cache2k cache. Use this version if you just want to play around with the system. If you plan to build a production DSP with multiple bidders, use the Aerospike Enabled.

CACHE2K (NO AEROSPIKE) ENABLED RTB4FREE

This is a stand-alone system, and requires no Aerospike support. Notwithstanding any ability to scale to multiple bidders - it is the fastest version of RTB4FREE.

Instead of a distributed Aerospike-based cache, the Cache2k system is embedded in the bidder.

Step 1

Modify the Campaigns/payday.json file as follows: Look for the "aerospike" object Change it's name to NOaerospike. When done it will look like this:

"NOaerospike": { "host": "localhost", "port": 3000 },

Step 2

Modify localhost in Campaigns/payday.json and ./database.json. If you are going to test everything with localhost, you can skip this step. Otherwise, you need to change pixel-Tracking, winUrl and redirect-url in payday.json and localhost entries in database,json. Fortunately, we have a build in program for that. Presume your IP address is 192.188.62.6. This will change the all files for you:

$cd XRTB $tools/config-website -address 192.188.62.6

Step 3

Start the RTB4FREE FREE bidder and test it:

In one window do:

$cd XRTB $tools/rtb4free

In another window send it a bid request:

$cd XRTB/shell $./curltest.sh

You should see the JSON returned for the bid request. An example is shown here:

{"seatbid":[{"seat":"seat1","bid":[{"impid":"35c22289-06e2-48e9-a0cd-94aeb79fab43-1","id":"35c22289-06e2-48e9-a0cd-94aeb79fab43","price":1.0,"adid":"ben:payday","nurl":"http://localhost:8080/rtb/win/smaato/${AUCTION_PRICE}/42.378/-71.227/ben:payday/23-1-skiddoo/35c22289-06e2-48e9-a0cd-94aeb79fab43","cid":"ben:payday","crid":"23-1-skiddoo","iurl":"http://localhost:8080/images/320x50.jpg?adid=ben:payday&bidid=35c22289-06e2-48e9-a0cd-94aeb79fab43","adomain": ["originator.com"],"adm":"<ad xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="smaato_ad_v0.9.xsd" modelVersion="0.9"><imageAd><clickUrl>http://localhost:8080/redirect/exchange=smaato/ben:payday/creative_id=23-1-skiddoo/price=${AUCTION_PRICE}/lat=42.378/lon=-71.227/bid_id=35c22289-06e2-48e9-a0cd-94aeb79fab43?url=http://localhost:8080/contact.html?99201&adid=ben:payday&crid=23-1-skiddoo</clickUrl><imgUrl>http://localhost:8080/images/320x50.jpg?adid=ben:payday&bidid=35c22289-06e2-48e9-a0cd-94aeb79fab43</imgUrl><width>320</width><height>50</height><toolTip></toolTip><additionalText></additionalText><beacons><beacon>http://localhost:8080/pixel/exchange=smaato/ad_id=ben:payday/creative_id=23-1-skiddoo/35c22289-06e2-48e9-a0cd-94aeb79fab43/price=${AUCTION_PRICE}/lat=42.378/lon=-71.227/bid_id=35c22289-06e2-48e9-a0cd-94aeb79fab43</beacon></beacons></imageAd></ad>"}]}],"id":"35c22289-06e2-48e9-a0cd-94aeb79fab43","bidid":"35c22289-06e2-48e9-a0cd-94aeb79fab43"}

AEROSPIKE (MULTI BIDDER) ENABLED RTB4FREE

This is the multi-bidder enabled version of RTB4FREE. If you plan to run more than one bidder instance, or a separate instance to handle win notifications you need to use this version of RTB4FREE.

Step 1

Get Aerospike up and running somewhere on your network. Look here: www.aerospike.com

Step 2

Modify localhost in Campaigns/payday.json and ./database.json. If you are going to test everything with localhost, you can skip this step. Otherwise, you need to change pixel-Tracking, winUrl and redirect-url in payyday.json and localhost entries in database,json. Fortunately, we have a build in program for that. Presume your IP address is 192.188.62.6 and Aerospike is running on the same bidder: This will change the all files for you:

$cd XRTB $tools/config-website -address 192.188.62.6

Or, if Aerospike is on a different host, add the additional -aero parameter to include that host. For example, presume Aerospike is running on 192.188.62.66:

$cd XRTB $tools/config-website -address 192.188.62.6 -aero 192.188.62.66

Step 3

Load the database.json into Aerospike. If Aerospike is on the same server as the bidder:

$cd XRTB $tools/load-database

Or, if Aerospike is running on a different host, say 192.188.62.66 use:

$cd XRTB $tools/load-database -db database.json -aero 192.188.62.66:3000

Step 5

Start the RTB4FREE bidder and test it:

In one window do:

$cd XRTB $tools/rtb4free

In another window send it a bid request:

$cd XRTB/shell $./curltest.sh

You should see the JSON returned for the bid request. An example is shown here:

{"seatbid":[{"seat":"seat1","bid":[{"impid":"35c22289-06e2-48e9-a0cd-94aeb79fab43-1","id":"35c22289-06e2-48e9-a0cd-94aeb79fab43","price":1.0,"adid":"ben:payday","nurl":"http://localhost:8080/rtb/win/smaato/${AUCTION_PRICE}/42.378/-71.227/ben:payday/23-1-skiddoo/35c22289-06e2-48e9-a0cd-94aeb79fab43","cid":"ben:payday","crid":"23-1-skiddoo","iurl":"http://localhost:8080/images/320x50.jpg?adid=ben:payday&bidid=35c22289-06e2-48e9-a0cd-94aeb79fab43","adomain": ["originator.com"],"adm":"<ad xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="smaato_ad_v0.9.xsd" modelVersion="0.9"><imageAd><clickUrl>http://localhost:8080/redirect/exchange=smaato/ben:payday/creative_id=23-1-skiddoo/price=${AUCTION_PRICE}/lat=42.378/lon=-71.227/bid_id=35c22289-06e2-48e9-a0cd-94aeb79fab43?url=http://localhost:8080/contact.html?99201&adid=ben:payday&crid=23-1-skiddoo</clickUrl><imgUrl>http://localhost:8080/images/320x50.jpg?adid=ben:payday&bidid=35c22289-06e2-48e9-a0cd-94aeb79fab43</imgUrl><width>320</width><height>50</height><toolTip></toolTip><additionalText></additionalText><beacons><beacon>http://localhost:8080/pixel/exchange=smaato/ad_id=ben:payday/creative_id=23-1-skiddoo/35c22289-06e2-48e9-a0cd-94aeb79fab43/price=${AUCTION_PRICE}/lat=42.378/lon=-71.2