What is Campsite for Suppliers

Campsite for Suppliers is a supply-side-platform (SSP) for digital-out-of-home (DOOH). The platform includes a web site and an API (Application Program Interface).

There are a number of ways to integrate with Campsite for Suppliers and the preferred method will be dependent on the supplier’s CMS, player and environment:

  • VAST: if the player supports VAST creatives, this is usually the easiest way to integrate;
  • API: direct requests containing information on the player can be made to Campsite SSP API to receive ads to play. Once played, a proof of play must be sent back to the API;
  • HTML: if the player supports HTML, an HTML page can be shown on the player which will load, in real-time, an ad from the Campsite SSP and display it.

All of the integration methods supports the same features and uses the same parameters. These parameters are detailed in the Ad Request section.

Integration process

The process from a new supplier starting to connect to Campsite up to being live and available for the buyers consist of the following steps:

  1. Defining the traffic per player based on a validated source of data, as well as a way to have an activity breakdown by hour;
  2. Integrate the CMS or player with Campsite by requesting an ad and displaying it in a test player;
  3. Configuring the ad request parameters based on the CMS capabilities and the chosen integration method;
  4. Configuring the price and exclusions in the production environment of Campsite SSP;
  5. Deploying the integration to some or all of the real players;
  6. Running a test campaign in some or all on the real players for 2 days;
  7. Validation of a test campaign;
    1. Validation of the traffic and impressions;
    2. Validation of the proof of plays;
  8. Activating the inventory in Campsite Exchange.

HTML player

This integration consists of an HTML webpage that is integrated with the Campsite SSP API and that displays the ad when loaded

The HTML player is usually displayed in the player through an iframe. To function properly, the HTML player needs to have some basic information on the player (a unique identifier, a latitude and a longitude). This information can be passed to the HTML player with querystring parameters or by having a local JSON file containing the information.

Requirements:

  • The player must support HTML and video playback;
  • The player must have access to the domains campsiteproject.com and s3.amazonaws.com (port 443);
  • (optional) If no ad is available, the player must be able to skip the HTML creative. It’s also possible to display a backup video if no ad is available.

VAST

To integrate with Campsite SSP through VAST requests, simply append to the Campsite SSP VAST URL the querystring parameters that describes your player and network. Here is an example of a VAST URL:

https://rtbapi.campsiteproject.com/vast?apiKey=supplier_api_key&player=player_01&environment=offices

Here are the available parameters:

Parameter Description
apiKey (Required) The supplier API key (provided by Campsite).
player (Required) The unique identifier of the player.
environment (Required) The environment of the player (provided by Campsite).
nb The number of screens that will display the ad. The impression URL should be called the same number of times to register the plays.
width The width in pixels of the player.
height The height in pixels of the player.
screenSize The diagonal screen size in inches of the player screen.
latitude The latitude of where the player is installed.
longitude The longitude of where the player is installed.
dwellTime The average dwell time of the persons in the viewability zone in front of the player.

Here is an example of the VAST generated by Campsite:

<?xml version="1.0" encoding="UTF-8"?>
<VAST
  xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vast.xsd" version="2.0">
  <Ad id="SampleAd">
    <InLine>
      <AdSystem>VASTQA</AdSystem>
      <AdTitle>Video Ad</AdTitle>
      <Error>
        <![CDATA[]]>
      </Error>
      <Impression>
        <![CDATA[https://sandboxrtbapi.campsiteproject.com/pop/f547515c-08b7-4313-839b-e4fac97ce064?type=impression]]>
      </Impression>
      <Creatives>
        <Creative id="1115">
          <Linear>
            <Duration>00:00:14</Duration>
            <MediaFiles>
              <MediaFile delivery="progressive" width="1920" height="1080" type="video/webm" bitrate="1200">
                <![CDATA[https://s3.amazonaws.com/campsite-sandbox-creatives/855f10146a8093183bb836b2ca3526bae0324ebde990045486de9d22fb38fe45.webm]]>
              </MediaFile>
            </MediaFiles>
          </Linear>
        </Creative>
      </Creatives>
    </InLine>
  </Ad>
</VAST>

API

How to connect

There is two ways to connect to Campsite API: /adrequest and /loopadrequest. The /loopadrequest is recommended for a player that displays ads in a loop, while the /adrequest is closer to a webpage ad spot. Both ways offers the same functionalities, but wrapped differently.

The workflow is identical for the two endpoints:

  1. The player makes a HTTP request to either /adrequest or /loopadrequest;
  2. Campsite return one or multiple ads in the ad response;
  3. The player plays the ads;
  4. The player makes a HTTP request to /pop to send the proof of play.

If desired, another endpoint is available for the player: /anticipated. This endpoint is useful to download in advance the creatives to the players. Please keep in mind that there is no guarantee that the ads will play in the players.

Campsite manages creative encoding, approvals, exclusions, delivery and a lot more to make sure the delivery is as fast and easy as possible.

Errors

Campsite uses HTTP response codes to differentiate a success from a failure of a request. For a success, a 200 or 204 will be returned.

Bad request (4xx)

These responses contains information as to why the request did not succeed. The response is of the following format:

{
  "errors":[{
      "errorCode":"EnvironmentNotFound",
      "message":"No environment found matching ad request environment: not-a-real-environnement",
      "context":null,
    "link":null
  }]
}

Server error (5xx)

Server errors are unexpected errors by Campsite. For support, please include the id value so that we can trace the origin of the problem.

{
  "errors":[{
    "errorCode":"unexpected",
    "id":"d909d6fb-27bc-4807-a302-d2a26251c177",
    "link":null
  }]
}

/adrequest

The supplier can easily request ads to play on a player with the Ad request. An ad request is specific to a player and contains one or multiple Ad Served.

Each ad served represents an available ad spot for the player. An ad served contains the field playAt which is an estimated date and time at which the ad is expected to play. The playAt field may be anytime between the actual date and time and up to 2 hours later.

When a request is made for an unknown player in a given environment, the player is registered in Campsite SSP. Campsite will begin collecting geocoding and audience data for this player. Until this is done, no ads will be returned in the ad response for that player.

An ad request is a POST HTTP request to [https://sandboxsspapi.campsiteproject.com/adrequest]. The request requires the following http headers. The body of the request is described in the content section.

Below are the HTTP headers required for this request:

Header Description
Authorization: "secret-key" (Required) The supplier API key (provided by Campsite).
Content-type: "application/json" (Required)

Request

Below is an example of an ad request:

{
  "id": "ad-req-1",
  "fill": false,
  "group": false,
  "player": {
    "id": "S-0001",
    "audio": false,
    "environment": "offices",
    "height": 1080,
    "width": 1920,
    "screenSize": 22.5,
    "address": {
      "latitude": 51.07651,
      "longitude": -114.00275,
      "country": "Canada",
      "state": "Quebec",
      "city": "Montreal",
      "streetNumber": "1",
      "street": "Place Ville Marie",
      "suite": null,
      "zip": "H3B 2B6"
    },
    "location": {
      "name": "Place Ville Marie"
    }
  },
  "adsServed": [{
    "id": "1",
    "playAt": "2017-04-01T15:35:00-04:00",
    "minDuration": 5.0,
    "maxDuration": 30.0,
    "trafficPerSecond": 0.0056,
    "floorCPMPerSecond": 0.50,
    "dwellTime": 30.0
  }]
}
Field Description
id (Required) Supplier identifier for logging purpose. This same ‘id’ will be in the ad response.
fill

If set to ‘true’, the ad response may contains more than one ad, up to the ‘maxDuration’ field in the ‘adsServed’. By default it is set to false.

If the same creative is returned more than once, i.e. two creatives with the same id, as a result of setting fill to true, it is the responsibility of the supplier to insure the maximum amount of time between each play of this creative.

group If set to ‘true’, all of the ads served will be packaged in a single bid so all of the ads served have to be bought together. By default it is set to false.
player (Required) Information about the player.
player / id (Required) Unique player identifier for the environment.
player / audio If the player supports audio. By default it is set to false.
player / environment (Required) Environment of the player. It has to match with the available environments in Campsite.
player / height Height part of the resolution of the player.
player / width Width part of the resolution of the player.
player / screenSize Size of the diagonal of the screen in inches.
player / address (Required) It is recommended to specify all the address fields. When a new player contacts Campsite SSP, either the latitude / longitude or the address are required.
player / address / latitude Latitude of the player.
player / address / longitude Longitude of the player.
player / address / country Country of where the player is installed.
player / address / state State of where the player is installed.
player / address / city City of where the player is installed.
player / address / streetNumber Street number of where the player is installed.
player / address / street Street of where the player is installed.
player / address / suite Suite of where the player is installed. Use ‘null’ is not applicable.
player / address / zip Zip code of where the player is installed.
player / location / name The name of the venue. For example, if the venue is a restaurant, that would be the name of the restaurant.
adsServed (Required) A list of ad served. An ad served represents an ad spot for the player.
adsServed / id (Required) Unique identifier for the ad served. This identifier is used as a mapping to the ad response. It only has to be unique within the ad request. The ads ‘id’ will be shared by the corresponding ad response.
adsServed / playAt (Required) Approximate time at which the ad served will occur. The date format is: "YYYY-MM-DDThh:mm:ss±hh:mm". This date can be anytime between the current date and time and 2 hours from now.
adsServed / minDuration (Required) Minimum duration of the creative in seconds.
adsServed / maxDuration (Required) Maximum duration of the creative in seconds. If the field ‘fill’ is set to ‘true’, multiple creatives per ad served may be returned, up to the maximum duration.
adsServed / impressions The approximated number of people that will see the ad.
adsServed / trafficPerSecond The approximated number of people that enters the viewability zone in front of the player per second. This value may be calculated with the number of persons at any given time and the dwell time with: trafficPerSecond = numberOfPersons / dwellTime.
adsServed / floorCPMPerSecond The minimum CPM (Cost per thousand impression) per second of the creative's duration. Example: if this field is 0.50 and the creative duration is 15 seconds, then the floor CPM will be $0.50 * 15 = 7.50$.
adsServed / dwellTime The approximated dwell time of the people in front of the player.

Response

Below is an example of an ad response:

{
  "id": "ad-req-1",
  "ads": [{
    "id": "1",
    "creatives": [{
      "id": "42",
      "proofOfPlayURL": "https://domain.com/pop/1234",
      "video": {
        "width": 1920,
        "height": 1080,
        "duration": 15,
        "encodings": [{
          "mime": "video/webm",
          "url": "https://domain.com/creatives/a9b8c7d6"
        }]
      }
    }]
  }]
}
Field Description
id Supplier provided identifier that matches with the ad request.
ads List of ads that matches the ads served from the ad request.
ads / id Identifier of the ad that matches the ‘id’ of an ad served in the ad request.
ads / creatives List of creatives to display on the screen. More than one creative may be included in the list if the ‘fill’ field is set to ‘true’ in the ad request.
ads / creatives / id Identifier of the creative. This identifier is unique by creative. Supplier may use this field to decide if the player needs to download the creative or if the player already has the creative.
ads / creatives / proofOfPlayURL URL to call once the ad was served.
ads / creatives / video  
ads / creatives / video / width Width of the creative to serve.
ads / creatives / video / height Height of the creative to serve.
ads / creatives / video / duration Duration in seconds of the creative to serve.
ads / creatives / video / encodings Available encodings for the creative. These encoding are tailored on a case by case basis for each supplier.
ads / creatives / video / encodings / mime Mime type of the creative.
ads / creatives / video / encodings / url URL to download the creative.

/loopadrequest

The Loop Ad Request is very similar to the Ad Request, but is easier to use if the requesting player uses a loop to play it's content. The playAt field may be anytime between the actual date and time and up to 2 hours later.

When a request is made for an unknown player in a given environment, the player is registered in Campsite SSP. Campsite will begin collecting geocoding and audience data for this player. Until this is done, no ads will be returned in the ad response for that player.

A loop ad request is a POST HTTP request to [https://sandboxrtbapi.campsiteproject.com/loopadrequest]. The request requires the following http headers. The body of the request is described in the content section.

Below are the HTTP headers required for this request:

Header Description
Authorization: "secret-key" (Required) The supplier API key (provided by Campsite).
Content-type: "application/json" (Required)

Request

Below is an example of a loop ad request:

{
  "id": "loop-ad-req-1",
  "fill": false,
  "group": false,
  "player": {
    "id": "S-0001",
    "audio": false,
    "environment": "offices",
    "height": 1080,
    "width": 1920,
    "screenSize": 22.5,
    "address": {
      "latitude": 51.07651,
      "longitude": -114.00275,
      "country": "Canada",
      "state": "Quebec",
      "city": "Montreal",
      "streetNumber": "1",
      "street": "Place Ville Marie",
      "suite": null,
      "zip": "H3B 2B6"
    },
    "location": {
      "name": "Place Ville Marie"
    }
  },
  "loop": {
    "startDate": "2017-04-01T15:00:00-04:00",
    "endDate": "2017-04-01T16:00:00-04:00",
    "minDuration": 5.0,
    "maxDuration": 30.0,
    "maxAdsServed": 30,
    "trafficPerSecond": 0.056,
    "floorCPMPerSecond": 0.50,
    "dwellTime": 30.0
  }
}
Field Description
id (Required) Supplier identifier for logging purpose. This same ‘id’ will be in the response.
fill If set to ‘true’, the ad response may contains more than one ad, up to the ‘maxDuration’ field in the ‘adsServed’. By default it is set to false.
group If set to ‘true’, all of the ads served will be packaged in a single bid so all of the ads served have to be bought together. By default it is set to false.
player (Required) Information about the player.
player / id (Required) Unique player identifier for the environment.
player / audio If the player supports audio. By default it is set to false.
player / environment (Required) Environment of the player. It has to match with the available environments in Campsite.
player / height Height part of the resolution of the player.
player / width Width part of the resolution of the player.
player / screenSize Size of the diagonal of the screen in inches.
player / address (Required) It is recommended to specify all the address fields. When a new player contacts Campsite SSP, either the latitude / longitude or the address are required.
player / address / latitude Latitude of the player.
player / address / longitude Longitude of the player.
player / address / country Country of where the player is installed.
player / address / state State of where the player is installed.
player / address / city City of where the player is installed.
player / address / streetNumber Street number of where the player is installed.
player / address / street Street of where the player is installed.
player / address / suite Suite of where the player is installed. Use ‘null’ is not applicable.
player / address / zip Zip code of where the player is installed.
player / location / name The name of the venue. For example, if the venue is a restaurant, that would be the name of the restaurant.
loop (Required) Describes the loop that will serve the ads.
loop / startDate (Required) Time at which the availability in the loop will start. The date format is: YYYY-MM-DDThh:mm:ss±hh:mm (±hh:mm representing the timezone). This date can be anytime between the current date and time and 2 hours from now.
loop / endDate (Required) Time at which the availability in the loop will end. The date format is: YYYY-MM-DDThh:mm:ss±hh:mm (±hh:mm representing the timezone). This date can be anytime between the current date and time and 2 hours from now.
loop / minDuration (Required) Minimum duration of the creative in seconds.
loop / maxDuration (Required) Maximum duration of the creative in seconds. If the field ‘fill’ is set to ‘true’, multiple creatives per ad served may be returned, up to the maximum duration.
loop / maxAdsServed (Required) Maximum number of ads served that may occur between the start date and the end date. Example: if the loop is 2 minutes long and the timespan between the start date and end date is 60 minutes, the maximum ads served will be 30 (60 / 2).
loop / impressions The approximated number of people that will see the ad.
loop / trafficPerSecond The approximated number of people that enters the viewability zone in front of the player per second. This value may be calculated with the number of persons at any given time and the dwell time with: trafficPerSecond = numberOfPersons / dwellTime.
loop / floorCPMPerSecond The minimum CPM (Cost per thousand impression) per second of the creative's duration. Example: if this field is 0.50 and the creative duration is 15 seconds, then the floor CPM will be $0.50 * 15 = 7.50$.
loop / dwellTime The approximated dwell time of the people in front of the player.

Response

Below is an example of a loop ad response:

[{
  "id": "42",
  "industry": "Advertising Agencies & Related Services",
  "proofOfPlayURL": "https://domain.com/pop/1234",
  "video": {
    "width": 1920,
    "height": 1080,
    "duration": 15,
    "encodings": [{
      "id": "CS275",
      "mime": "video/webm",
      "url": "https://domain.com/creatives/a9b8c7d6",
      "name": "Encoding-A-webm"
    }]
  }
}]

List of creatives to display on the screen. More than one creative may be included in the list if the ‘fill’ field is set to ‘true’ in the ad request.

Field Description
id Identifier of the creative. This identifier is unique by creative. Supplier may use this field to decide if the player needs to download the creative or if the player already has the creative.
proofOfPlayURL URL to call once the ad was served. Add to the URL the querystring parameter '?count=X' where x is the number of times the ad was played.
video / width Width of the creative to serve.
video / height Height of the creative to serve.
video / duration Duration in seconds of the creative to serve.
video / encodings Available encodings for the creative. These encoding are tailored on a case by case basis for each supplier.
video / encodings / id Identifier of the encoding of the creative.
video / encodings / mime Mime type of the creative.
video / encodings / url URL to download the creative.
video / encodings / name Name corresponding to the encoding.

/pop

A proof of play is required once the ad as been played for the ad served to be registered in Campsite. A GET request should be sent to the url provided in the ad response (proofOfPlayURL). An error will be returned if the proof of play is not recognized or if the proof of play has expired.

/anticipated

It's possible to request the /anticipated endpoint with a HTTP GET request to [https://sandboxrtbapi.campsiteproject.com/anticipated] to have a summary of the creatives that may be booked in the next 24 hours.

Below are the HTTP headers required for this request:

            

Authorization: "secret-key"

            

(Required) The supplier API key (provided by Campsite).

            

Response

{
  "creatives": [
  {
    "id": 42,
    "duration": 15,
    "encodings": [{
      "mime": "video/webm",
      "url": "https://s3.amazonaws.com/campsite-creatives/abc123.webm"
    }]
  }]
}

Glossary

Inventory

TERM DEFINITION
Supplier The entity owning DOOH inventory.
Environment

Type of location such as Restobar, Transit, Office Building, Residential, etc.

Player

The actual device that plays the creative. Different players might have different specifications such as orientation, resolution and capacity to play sound.

Floor Price Minimum price set by the supplier to play a creative (in CPM).
Dwell Time Estimated time a person stays in the viewable area of the screen.

Metric

TERM DEFINITION
Impression

Someone exposed to a creative. Learn more.

CPM

Cost Per Thousand Impressions. The average cost for 1,000 non-unique people exposed to a creative.

Ad Served

A single play of an ad creative. Learn more.