Integrating With Sociomantic Using

OpenRTB
Introduction
OpenRTB is one of the more popular protocols used to integrate with Sociomantic. This document
is to help SSPs through the technical side of this process. It is assumed you have already read the
OpenRTB specification. If after reading this you still have some questions unanswered then, as
always, speak with your technical contact for assistance.
If you would like to see improvements to this document or anything is unclear, also please give
feedback to your technical contact. This includes if, at the end of the process, there is anything you
would have liked to have known earlier to make the process go more smoothly.

OpenRTB Versions
As of the time of writing this we currently support OpenRTB 2.1 and 2.2. If you wish to use a
different version then please ask.

Geographies
Sociomantic is interested in traffic from all regions. If your SSP only operates in limited geographic
regions then please indicate which regions they are.
For globally distributed traffic we will provide multiple endpoints for bidding requests. It is
expected that bidding requests will be sent to the endpoint closest to/most appropriate for the user to
be bid on. If you are uncertain which endpoint to use, once you have been provided with your
endpoint information, then please ask for clarification.

Currency
Please indicate the currency that auctions will be conducted in.

User Matching
User matching is the process of mapping between a user ID assigned by the SSP and one assigned
by the DSP (i.e. Sociomantic). Sometimes this is called user syncing.
We require user matching to be working for every SSP with whom we work.
The user matching can be performed by either side i.e. by you or by us. Normally we, Sociomantic,
are the ones to perform the user matching but can support either option if required. These two
alternatives are covered in more detail in following sections.
2014-12-10

Page 1/5

SSP Performs User Matching

In this case you will need to provide one or more URLs. One of these URLs will be called by a
user's browser, with the Sociomantic ID inserted in a location you indicate.
If your provided URL was http://um.ssp.com/usermatch?
dspid=[ID]&dsp=sociomantic-us then an example call to your URL might look like
http://um.ssp.com/usermatch?dspid=XXX&dsp=sociomantic-us. The XXX
would be the Sociomantic ID for the user making the call.
It is expected that you will save the provided Sociomantic ID in some sort of table keyed against the
user who made the call. When you subsequently send bidding requests then this Sociomantic ID
should be supplied in the user.buyeruid field.
This URL should always return either:

a 1x1 pixel image, ideally in PNG format

an HTTP 204 No Content response.

Sociomantic Performs User Matching

In this case you will need to provide one or more user matching pixel URLs. One of these user
matching pixel URLs will be called by a user's browser, with a number of arguments in the query
path. One of these arguments will be called url and its value will be itself a (URI-encoded) URL
known as the redirect URL.
If your provided user matching URL was http://um.ssp.com/usermatch then an example
call to your URL might look like http://um.ssp.com/usermatch?url=http%3A%2F
%2Fum.sociomantic.com%2Fusermatch%3Fssp%3Dexample&fpc=31415&e1=a.
You should respond to such a call with a temporary redirect (HTTP code 302) to the redirect URL.
Any other arguments found in the query string (in the above example fpc and e1) should remain
as arguments to the redirect URL. In addition you must add an extra argument, id, whose value is
your user ID for the user who has made the call.
So you would respond to the previous example call with a redirect to
http://um.sociomantic.com/usermatch?
ssp=example&fpc=31415&e1=a&id=XXX. You would replace XXX with your ID for the
user.
When you subsequently send bidding requests to us then you should place your ID in the user.id
field. All bidding requests should have user.id set to a value that has been previously used in a
user matching call. Bids with any other value for user.id are unlikely to attract many bids.

URLs
You must provide at least one user matching pixel URL. You may wish to provide multiple URLs
2014-12-10

Page 2/5

for different geographic regions.

Sociomantic will always initiate the user matching (i.e. we will trigger a user to call your provided
URL when necessary). You do not need to ever call a Sociomantic user matching pixel URL. This is
irregardless of who is doing the user matching.
Any URL you supply must also support being called using HTTPS by simply swapping the protocol
with no other changes required.
The full SSL certificate chain must be able to be validated to avoid security problems. Please check
this, either by using a command line tool like openssl or a web based validation tool. Please
monitor this after deployment to catch, e.g expired certificates, as getting this wrong is very
disruptive and highly visible.
Any URL provided should respond in good time (e.g. less than 200ms when called by a typical
user). It should never return an error code to the user, only ever returning 2xx or 3xx codes as
appropriate. You may wish to front your web service with a simple proxy that can return a dummy
response in case of a back-end failure to keep any errors concealed from users. Please monitor this
service to catch problems quickly.
If your URL returns a pixel then use the correct MIME type. e.g. image/png
If you become aware of problems with user matching after deployment then please let us know as
soon as practicable.

User Matching Rollout

Once URLs have been provided there will be a gradual roll out and you should see calls to them
increase slowly. During this time please watch for any errors or problems you might be
experiencing. It is better for this roll out to be paused early than for an end user to spot a problem.

Protocol Extensions
OpenRTB gives much scope for flexibility. If you require extra fields to be set in bid responses, or
supply information in non-standard or less than usual fields then please let us know. The same for
specific requirements regarding e.g. adm field contents. We will try to accommodate reasonable
requests and knowing these requirements in advance can make the integration process run smoother.

Sizes
Please send us bidding requests for all sizes you support. If you support any non standard sizes then
please let us know.

Test Endpoint
Your technical contact will provide you with a test endpoint to use. The purpose of the test endpoint
is to ensure interoperability at a protocol level. You will need to ensure that you can send requests
2014-12-10

Page 3/5

and successfully parse the responses whilst using the test endpoint before further integration can
proceed.
Note that to be able to use the test endpoint with any degree of success you need to have user
matching set up because the end point will expect your bid request to contain valid user
information. Please review the section on User Matching if you have not already done so.
The test endpoint is configured to always bid on any request if the request is:

syntactically correct (i.e. correctly formatted and valid JSON)

has a valid user ID included

required OpenRTB fields are present and their values look reasonable

If your requests do not result in a bid then please check your formatting using a JSON validation
tool. Make sure you have spelt all field names correctly and used the appropriate (usually lower)
case. Also check that you have correctly populated either the user.id field or the
user.buyeruid field (depending on who is doing the user matching see the earlier section on
user matching).
Note that a bid from the test endpoint will often be a dummy bid. These bids should be
syntactically correct and parseable by an OpenRTB bid response parser however they will not be for
a real campaign. They will always be for 1 Euro cent (regardless of currencies you may have
specified) and the crid field will always contain the string always_bid.
Note also that the test endpoint does not run on port 80. You may need to configure your firewall
appropriately to allow requests to this URL. The test endpoint is also physically hosted in Europe
and so requests from other locations may experience some latency.
If you are having difficulties in accessing the end point or receiving a bid then please speak with
your technical contact for assistance.

Moving to Production
Once you can successfully send bid requests to, and receive bid responses from, the test endpoint
then it is time to move to production. You will be provided with 1 or several production URLs to
which to send bid requests. Each bid request should be sent to the most appropriate/closest end
point for the user who is to be bid on. If you are unsure which endpoint you would use for a given
location then please ask.
For the first few days you should send a limited number of bidding requests. We will make a limited
number of bids. Please expect to see a high rate of no-bids from us. At the end of this trial period if
neither side sees any issues then both the request and bid rate can be increased till it is at the full
rate.

2014-12-10

Page 4/5

Connection Counts
The number of simultaneous connections you make to the production endpoints is something you
must tune to find the correct balance between performance and resource usage. The number will
presumably be dynamic based on the number of bid requests being made at that time. We support
any reasonable number of connections, based on the number of bid requests you are sending. A
rough calculation for the number of connections, n, might be
n = (request rate per second / 5) * 1.1
This calculation assumes you can send and receive at least 5 bids per second (200ms per request)
over a single connection and then increases the number by 10% to allow for bursts. This is not a
hard rule but simply meant as guidance.
If you expect to make a large change in the number of connections, in either direction, then please
let us know in advance.

Users
We would like to see only bid requests for users that have been previously user matched with us. If
this is something you can support then please enable it.

Summary
First please answer the following questions:

Which geographies will you be operating in?

Which currencies will auctions be conducted in?

Who will be performing user matching?

What are your user matching URLs?

Do you provide/require anything unusual in your bid requests or responses?

At this point your test endpoint can be created and you can use it to test your code. To be able to
proceed to production you need to be able to successfully send a bid request, with correct user
information, and receive a bid response. Note that user matching will need to already be correctly
set up for this to happen.
If you require assistance please ask your technical contact.

2014-12-10

Page 5/5