Frequently Asked Questions and Their Answers

Do you support GDPR?

RTB4FREE implements the IAB guidelines on GDPR support as located here.

If you set the bidder to GDPR mode, it will delete the user object from the bid request if the ext.gdpr == 1 and the user.ext.consent field is absent. We also provide an Elastic Search query that will delete user objects from the database based on the value of the or user.buyerid fields. Note. Adx has no support for GDPR.

What is the form of the pixel fire and click trackers in RTB4FREE

Pixel fire handling in RTB4FREE is handled by the following string in your creative as an img src:


The {pixel_url} is set forth in the Docker payday.json file AS $EXTERNAL/callback?type=pixel. $EXTERNAL is the domain name of your bidder, or your load balancer if you have more than one bidder.

The VAST callbacks are of the form: {event_url}&ad_id={ad_id}&creative_id={creative_id}&impression_id={impression_id}&event=XXX&domain={domain}

The event=XXX is the VAST video event, where XXX is the event.

The click handler, which ends up on the landing page is of the form:


The order is not important except the url= must be last. If you leave off url= then it will just count, it won't do the 301 redirect.

Important! If your url contains quotes or spaces you must encode it, otherwise your redirect will fail.

Here's an example image tag for a click:

<img src="{redirect_url}&exchange={exchange}&ad_id={ad_id}&creative_id={creative_id}&lat={lat}&lon={lon}&bid_id={bid_id}&ip={ip}&site_domain={site_domain}&url=' w='0' h='0'">

Creating a win callback - normally you don't do this. First the SSP will do this for you, it is specified as "nurl" part of the bid, and it is specified in payday.json. If the SSP does not provide a win notification, RTB4FRREE will create one for you IF you specify a pixel fire in your creative AND you specify the SSP uses "piggy-backed" wins in the payday.json file. All of the SSPs we support that do not support win notifications are preconfigured to piggyback. Here's an example in payday.json of an SSP that uses piggybacked wins:

    "name" : "vertamedia",
    "id" : "vertamedia-id",
    "bid" : "/rtb/bids/vertamedia=com.jacamars.dsp.rtb.exchanges.Generic&!usesEncodedAdm&usesPiggyBackWins"

My Campaign Isn't Bidding. Why Not?

Your bidder is connected to the SSP, and receiving requests - but your campaign is not bidding. The Admin web application will help you tune your campaign Look here for the documentation.

Some Percentage of My Wins Are not Resulting in Impressions?

Your ad server is reporting far less impressions than the number of wins reported by the SSP. What's wrong?

When you say you aren't seeing X% of the wins as impressions, are you saying that you aren't getting the win notification, but are being charged anyway by the SSP, or, is that you are getting the win notices, but your ad server isn't getting called to serve the ads on X% of the wins. Two very different scenarios.

If you are not receiving the wins, this usually means an overloaded bidder.

More likely you are seeing the second case. Bear in mind, the bidder has no role in serving the ad, once the bid is made, it's up to the SSP to send the ad to the publisher. So, it is not the bidder if you are receiving the win notice.

Three possible scenarios:

  1. Are you serving bad html or javascript? If none of the ads are served as impressions, make sure you don't have any errors in your script, or in the markup that goes in the bid. This is the number one leading problem in failures. The bidder cannot sanity check your mark-up.
  2. If some of the ads are served, then you have either a problem with the SSP or your ad server.
  3. If your answer is (2), are you using pixel fires? A pixel fire is called when the ad loads in the user's browser. The number of pixel fires should be roughly equal to the number of wins, say within 90%. If your pixel fires do not match your wins within 90% then it is the SSP causing the error and you should let them know.

Is it possible to modify campaign parameters in real time through an API?

RTB4FREE provides a command/response mechanism using publish/subscribe over ZeroMQ. The command structure is documented here: Read the details here.

How does Campaign Selection Work?

RTB4FREE uses Campaigns and creatives defined as a JSON object. The JSON object can be manipulated with a simple web page called the Campaign Manager which is documented here

Key to the Campaigns definitions is the use of Rules. Rules are applied against bid request values to filter out only those requests you are looking for. How rules processing works within the RTB4FREE bidder is documented here: Read the details here.

How do I identify a new SSP to the bidder?

Adding a generic openRTB 2.x compliant SSP is quite easy, it's just a configuration item in the Seats sub-section of the Configuration tab in the System Console. For a step by step guide look here.

Does RTB4FREE Support Gzipped bid request?

RTB4FREE does support GZipped bid requests. If the SSP sets the Content-Encoding header to gzip, it will be properly handled. RTB4FREE however does not gzip responses, as it is more expensive to compress the smaller messages.

How do you add a tracking pixel for VAST tags so RTB4FREE can process it?

This is done through the VAST <Impression> tag. Simply add this impression to your VAST xml file:

<Impression><! [CDATA[{pixel_url}&exchange={exchange}&ad_id={ad_id}&creative_id={creative_id}&price=${AUCTION_PRICE}&lat={lat}&lon={lon}&bid_id={bid_id}]]> </Impression>

If you are hard coding the url, then [pixel_url} would be http://hostname:port/pixel/...

This presumes that RTB4FREE is handling the VAST tag directly, it's not wrapped. This allows RTB4FREE to do macro processing. If you are wrapping the tag, or you don't want macro substitution, do the substitutions directly yourself. For lat and lon values just use 0.

What SSPs has RTB4FREE worked with?

Currently the list includes: AdMedia, Adventurefeeds, Appcoach, Appnexus, Atomx, Axonix, Cappture, Citenko, C1X, Epomx, Fyber, Google Ad Exchange, Gotham, Intango, Kadam, MedianexusNetwork, Nexage, Openssp, Openx, Pokkt, Pubmatic, Pubnative, Republer, Smaato, Smartyads, SmartAdServer, Spotx, SSPHwy, Stroer, Taggify, Tappix, Vdopia, Ventuno, Vertamedia, Vmax, Waardx, Wideorbit

What macros are available with RTB4FREE (besides the standard RTB ones...)?

A rich set of macros are available for you to use in the construction of your creatives, see here.

Does RTB4FREE support SSL?

RTB4FREE depends on a load balancer to receive all the bid requests. Your SSL certificates must be loaded into your the load balancer.

How to Create Display Ads in RTB4FREE

In this tutorial you see how to change the Campaign database (database.json in the demo) and the startup file (Campaigns/payday.json in the demo) to construct your own display advertising markup.

What VAST video player do you use?

For our demo page, we use the open source VAST player from NPM (Nutrient Packed Morsels) located here.

How to Use CURL To Test RTB4FREE

In this section you will learn how to send an RTB bid request and win notification to RTB4FREE using the 'curl' program. The example is here.

How to Implement a new Exchange

First of all, if it is a pure openRTB based exchange then you Simply add a new item in payday.json in the exchanges section, using the Generic class. Foe example, INTANGO is a pure openRTB exchange. It's definition is in the "seats" in payday.json and looks like:

	"name": "intango",
	"id": "intango-id",
	"bid": "/rtb/bids/intango=com.xrtb.exchanges.Generic"
So, if NewExchange is like intango, simply do this:
	"name": "newexchange",
	"id": "newexchange-id",
	"bid": "/rtb/bids/newexchange=com.xrtb.exchanges.Generic"

Restart the bidders and you are ready to go.

However, what if the exchange is not completely openRTB...

In this post we show how to implement a JAVA class to handle a new exchange. For details look here.