function toggle(elementId) { var ele = document.getElementById(elementId); if( == "block") { = "none"; } else { = "block"; } }

Creating Your Ad Markup in RTB4FREE

Of critical importance, of course, is to construct what your ad markup will be on the web page when user's web browser loads the web publisher's page. In the case of VAST video, that's real simple, because you are just providing a VAST XML document in the ADM. And likewise for native content your ADM is constructed from the native ad parts. T he hardest part is actually dealing with banner ads.

In general an RTB based display ad has 3 parts: 1. The anchor, 2. the pixel image, 3, the click address. It might look like this:

Sample Anchor Structure

<a href="your-ad-goes-here"> <img src='your-pixel-tracker-goes-here" width=1 height=1> <img src='your-display.gif'> </a> In this tutorial you will see how the configuration file (Campaigns/payday.json in the demo) and the creative defined in your campaign (in database.json and loaded into REDIS) are used to construct advertisements.

The Creative

The creative that shows up in the ad is defined by the campaign and creative. As an example here's a snippet from database.json

"campaigns" : [ {
    "isAdx" : false,
    "owner" : "ben",
    "adId" : "smaato-test",
    "adomain" : "",
    "attributes" : [ ],      
        "creatives" : [ {
        "forwardurl" : "http://localhost:8080/contact.html?site_id={site_id}&adid={ad_id}&crid={creative_id}",
        "imageurl" : "http://localhost:8080/images/320x50.jpg?adid={ad_id}&bidid={bid_id}",
        "impid" : "image-test",
        "w" : 320,
        "h" : 50,

What will be shown to the user is what is in the "forwardurl" field. This is the "ADM" part of the bid response. Here is a forward url showing a gif image, along a 301 redirect that will just show the image:

"forwardurl": "<a href='{redirect_url}/exchange={pub}/ad_id={ad_id}/creative_id={creative_id}/price=${AUCTION_PRICE}/lat={lat}/lon={lon}/bid_id={bid_id}?url={ad_id}/{creative_id}'><img src='{creative_image_url}' height='{creative_ad_height}' width='{creative_ad_width}'></a><img src='{pixel_url}/exchange={pub}/ad_id={ad_id}/creative_id={creative_id}/{bid_id}/price=${AUCTION_PRICE}/lat={lat}/lon={lon}/bid_id={bid_id}' height='1' width='1'>"

First off, notice the href for the anchor tag. This is a conventional form for RTB4FREE. It's a good idea to keep this entire structure for your owner tags. Notice ther {redirect_url}. This tells RTB4FREE where the redirect is sent when the user clicks the ad. It is defined in the Campaigns/payday.json file. This is what handles the redirect and most likely is the same address as your bidder.

The other macros like {pub} and {ad_id} etc, substitute key parts from the campaign and bid request

The next thing to pay attention to is ?url={ad_id}/{creative_id}. This is your landing page. Here we will pass the ad id, and creative id to it when the user clicks the ad. It's form is up to you. Pass whatever you need.

The next thing to pay attention to is the form of the first image's src tag. The actual image to be served is in the "imageurl" field in the campaign in database.json. It could have been coded here, but we can use a macro reference too. We also provide the width and height with a macro.

The second image is the actual "pixel fire". This form is standard form for RTB4FREE, simply copy it and use it. If you use another pixel service, then you will need to encode it however they need it. But beware, some exchanges do not provide WIN notifications. In order to handle wins, a pixel fire is used. In this case if you are using another pixel service you have to provide 2 pixel fires - one for the other service, and one for RTB4FREE to use to construct a "faked" win. It's probably better to just let RTB4FREE handle your pixel fires.


If you are serving up VAST Video, then things are a little simpler. Here the ADM is specified directly. Here is a VAST video specification:

"creative": { "impid" : "iAmVideo", "w" : 400, "h" : 200, "attributes" : [ ], "adm" : [ "http://localhost:8080/vast/onion270.xml" ], "currency" : "", "cur" : "USD", "videoProtocol" : 2, "videoDuration" : 30, "videoLinearity" : 1, "videoMimeType" : "application/x-shockwave-flash", ...

The key things to note is the "adm" field, which is an array of strings. Note in this example the vast video is stored on disk of the localhost. So when the ADM is constructed for the bid request it will be retrieved from disk. And, then, any macro substitutions needed in the XML is then done.

You can place the VAST tags directly into the adm, as the adm field is an array. Here's a short example

A Pixel event is defined in the XML with this:


An event postback is shown here:

    <Tracking event="complete"><![CDATA[ {event_url}/adid={ad_id}/crid={creative_id}/domain={domain}/exchange={exchange}/event=complete ]]></Tracking>

This event is in standard RTB4FREE form. If you want to track postback events, use this format.

Finally, if this had been placed directly into the adm it would look like this:

    "adm": ["<VAST xmlns:xsi=\"\" version=\"2.0\" xsi:noNamespaceSchemaLocation=\"vast.xsd\">",
            "<Ad id=\"270\" >",

Macro Substitutions

You can see macro substitutions throughout the examples and in database.json with the use of the {} specification. The ${AUCTION_PRICE} is a standard RTB macro, and will cause the markup to be replaced with the actual price of the auction being subbed in.

The other macros are subbed by RTB4FREE and define the pieces of information derived from campaigns, creatives and the bid request being used. In this manner key information is passed to the RTB4FREE server when the markup is loaded into the user's browser

Here are the RTB4FREE standard macro substitutions:

        {ad_id}					Substituted from the campaign id.
        {ad_size}				Substituted using the actual ad size WxH form.
        {app_id}				The id of the app in the bid request.
        {app_name}				The name of the app in the bid request.
        {app_bundle}				The app.bundle of the bid request.
        {app_domain}				The domain of the app.
        {adsize}				Size of the creative, hxw
        {bid_id}				Substituted from the bid's object id field.
        {bidder_ip}				Gives you the bidder ip address that handled the bid request.
        {brand}					The device brand.
        {cachebuster}				A random number.
        {creative_ad_height}			The height of the creative bid.
        {creative_ad_price}			The price that was bid.
        {creative_ad_width}			The creative width of the bid.
        {creative_forward_url}			The forward url (the actual markup sent on the bid.
        {creative_id}           		Substituted from campaign's creative's id.
        {deal_id}				The private/preferred deal id, if one was used in the bid.
        {dnt}					The value of device.dnt (do not track) in the bid request.
        {exchange}				The exchange where the bid came from
        {gps}					Device GPS coordinates lat,lon
        {ifa}					The value of device.ifa in the bid request.
        {impression_height}			The size of the impression height.
        {impression_width}			The size of the impression width.
        {imp}					The creative id.
        {ip}					The IP address of the user device.
        {isp}					The ISP name if the device identifies it.
        {lat}					Latitude of the device
        {lon}					Longitude of the device
        {make}					The device make
        {model}					The device model
        {nurl}					The fully formed "nurl" for this impression.
        {os}					The device operating system
        {osv}					The device operating system version
        {page_url}				The page url, contents of site.content.url or if undefined site.pahe, or if app: app,content.url
        {pixel_url}				The pixel fire url of this bid request
        {pub}					The publisher from the bid request
        {publisher}				The publisher from the bid request.
        {redirect_url}				The redirect url used on this bid
        {site_domain}				Substituted from the bid request's site domain
	{site_id}				Substituted from the bid request's site id.
        {site_name}				Substituted from the bid request's site name.
        {timestamp}				Timestamp of the bid
        {tid}                                   The 'transaction id' cid:crid:deviceid
        {ua}					Device user agent
        {uid}                                   The DSP (RTB4FREE) specific cookie id.
        {win_url}				The basic win fire url of the bid response (see also {nurl}).

Note, the RTB exchange can make substitutions in the ADM field as it delivers it to the web site. The RTB exchange will reflect the ADM back on the win notification, and you can ask for the RTB exchange to also substitute fields as well. See the RTB 2.3 specification for supported macro names.

These are the macros substituted by the Exchange, not the bidder. so these will return via the RTB win notification and as the ad is delivered into the web page.

        {AUCTION_ID}        ID of the bid request; from “id” attribute.
        {AUCTION_BID_ID}    ID of the bid; from “bidid” attribute.
        {AUCTION_IMP_ID}    ID of the impression just won; from “impid” attribute.
        {AUCTION_SEAT_ID}   ID of the bidder’s seat for whom the bid was made.
        {AUCTION_AD_ID}     ID of the ad markup the bidder wishes to serve; from “adid” attribute.
        {AUCTION_PRICE}     Settlement price using the same currency and units as the bid.
        {AUCTION_CURRENCY}  The currency used in the bid (explicit or implied); for confirmation only.