rtbkit.js

Access RTBkit APIs easily with Node.js

Installation

rtbkit.js is available on npm. To install it, type:

$ npm install rtbkit-js

Usage

const rtbkit = require('rtbkit-js');

Now we can :

• launch an HTTP bidding agent, or
• connect to an RTBkit instance to work with its RESTful APIs

HTTP Bidding Agent

You may create an HTTP Bidding Agent just typing a few strings:

const bidder = rtbkit.biddingAgent();
 
var PORT = 7654;
var PATH = '/auctions';
 
bidder.bid(function(campaign, creatives, bidRequest, imp) {
    if (campaign == 111) {
        return null;            // no-bid
    }
    return { 
        price: 0.1,             // bid CPM
        crid: creatives[0],     // bid with the first allowed creative
        ext: { priority: 1 }    // (optional)
    };
});
 
bidder.listen(PORT, PATH);

This bidder will response with no-bids for the campaign 111 (external-id from the bidding agent config) and will bid with 0.1 CPM for all other campaigns.

The library will automatically fill down bid.id, bid.impid, and bid.ext.external-id fields.

The function will be called once for each imp item and each allowed campaign that have been specified by RTBkit in the bid request.

RTBkit RESTful APIs

To connect to an RTBkit inststance type:

const rtb_test = rtbkit.instance("127.0.0.1");
const banker = rtb_test.banker;
const acs = rtb_test.acs;

Async/await

rtbkit.js might be used with the await operator in async functions:

async function main() {
    try {   
        var pong = await banker.ping();
        console.log(pong);
 
    } catch (err) {
        console.log(`ERR: ${err}`);
    }
}
main();

Callbacks

Or you can use a traditional callback approach. In this case you will have access to the HTTP Response object:

!function main() {
    banker.ping(function(res) {
        console.log(`OK (${res.statusCode}): ${res.data}`);
    }).on('error', function(err) {
        console.log(`FAIL: ${err}`);
    });
}();

APIs

Banker API

Budgets management:

var pong = await banker.ping();
var summary = await banker.summary(); //gets information about all accounts
await banker.budget('hello', newValue); // sets a new value for a top-level account
var accounts = await banker.accounts(); // lists all accounts
var account = banker.account('hello:world');    // makes a reference to the specified account. 
                                                // It's an ordinary synchronous method, you don't need use await here.
var hello_world = banker.account(['hello', 'world']) // the same as the previous call
await account.balance(newValue);   // transfers budget from the parent account to set the new value. Unacceptable for top-level accounts.
var childrens = await account.children(); // gets descendants of the account
await account.close(); // closes the account and all its childs.

Agent Configuration Service (ACS) API

var agents = await acs.agents(); // lists all agents
var agent = acs.agent(agents[0]);   // makes a reference to the specified agent. 
                                    //It's an ordinary synchronous method, you don't need use await here.
var config = await agent.config();  //gets the bidding agent's config
await agent.config(newAgentConfig); // sets the new configuration for the bidding agent

Post Auction Events (a-ka Standard Ad Server Protocol)

With the API we may implement a win notification proxy that recieves GET requests from the browser and sends POST requests into the RTBkit's via Standard Ad Server Protocol:

const app = require('express')();
const rtbkit = require('rtbkit-js');
 
const PORT = 888;
 
const RTBKIT_HOST = '127.0.0.1';
 
const adserver = rtbkit.instance(RTBKIT_HOST).adserver;
 
app.get('/win', function (req, response) {
    var data = {
        timestamp: Date.now() / 1000,
        bidRequestId: req.query.brid,
        impid: req.query.impid,
        price: parseFloat(req.query.price)
    };
 
    adserver.win(data, function(res) {
        console.log(`win notice (${res.statusCode}): '${JSON.stringify(data)}'`);
        response.status(res.statusCode).end();
    }).on('error', function(err) {
        console.log(`win notice error '${err.message}': '${JSON.stringify(data)}'`);
        response.status(500).end();
    });
});
 
 
app.listen(PORT, function(){
    console.log(`nurl proxy server listing on: http://localhost:${PORT}`);
});
 

Other events (clicks, conversions) will be implemented later.

Exchange Endoints

Will be implemented later. Will help to send bid requsts into the system and check responses.

RTBkit Mock-up

There is a mock server that emulates all implemented APIs. It starts locally always.

 
async function main() {
    try {   
        rtbkit.mockup.start();
 
        const banker = rtbkit.instance('127.0.0.1').banker
 
        var pong = await banker.ping();
        console.log(pong);
 
    } catch (err) {
        console.log(`ERR: ${err}`);
    }
}
 
main().then(res => { 
    rtbkit.mockup.stop(); 
});