Overview and Integration Guide for OOH Networks
Updated Aug 28, 2018
This document is meant to serve as an overview of the integration process between Mira and digital out-of-home networks. It is intended for network administrators, engineers, and other managers responsible for the technical health of their ad serving and content management systesms
What is Mira?
Mira is the crowd analytics platform. Crowd analytics seeks to answer the question: what types of people are in a given place at given time? Mira uses historical and real-time location and behavioral data to place a digital overlay on physical locations. This data can be used to optimize out-of-home campaigns, by informing the decision of which content to show based on the real-time audience.
High-Level Architecture Overview
A Mira campaign is driven by a model, which is essentially a decision tree that can pull from a variety of static or real-time sources. A source is something like the segments that are currently present at a sign, the number of impressions per creative to date, etc.
Mira’s server maintains a real-time ledger of what content every device should be playing for a given campaign. New data from each source is fed through the subscribed models, which in turn update this ledger with the most up-to-date decision.
There are internal relationships that affect how individual screens are matched to their respective decisions. For example, clusters of devices can be grouped together to access the same entry in the ledger, so that they are always using the same decision.
This ledger is updated independently of what the signs are doing. It doesn’t matter if there is a schedule for the content. Our server simply answers the question “what should I play right now?”, where “I” can be an entire network or just one device.
Most of the integration centers around asking that question, and getting the answer to translate into something on the screen. There are a few standard delivery methods (see below), but custom solutions are pretty simple to implement. Something has to hit our server, and the “slot” must be configurable to change what is shown, either directly through the CMS (think RSS feeds for weather), or through a dynamic file type that reads this data.
Integration
There are a few steps in integrating a network with Real-Time Optimization.
Inventory
Mira needs to generate identifiers for each unique screen, so the first step is typically ingesting a list of inventory. This can be done on a per-campaign basis or all at once for the entire network. The only field that is strictly necessary is a name or other unique identifer, but other fields typically included are
- Address
- Bearing/Facing
- Field of View
- Latitude/Longitude
- Format
- Resolution
- Dimensions
- Geopath ID
Inventory is represented in our system as a display unit. However, a display unit does not have to correspond to a single screen or player. A display unit can correspond to an entire mall, or any other arbitrary entity. A display unit is simply the most granular unit for which you can obtain an ad serving decision. So it is possible to allow multiple unique devices to act as the same display unit, but it is important to note that they will be indistinguishable from each other on our server.
Geofences
When using real-time location data in a campaign (which is the case for most RTO campaigns), some specification of a geofence needs to be uploaded as well. This represents the visible area for a particular unit. This can be communicated to us by using a geojson format to specify the polygons for each unit, or by using some generative approach, like combining latitude, longitude, radius, bearing, and field of view to produce a geofence from a flat CSV file.
Delivery Methods
Delivery methods are simply how dyanmic content is pushed through your network. How this happens is usually dictated by the CMS. Note that most of these integrations require the CMS to have the ability to set injectable variables for different screens. An example of this is BroadSign’s Content Variables.
Remote URL
Your CMS “visits a website” that shows the appropriate content. This is the easiest way to integrate if your CMS can fetch HTML content from a remote source. The /screens/play endpoint wraps around the /screens/decide endpoint and renders the asset that is returned. The wrapper responds with an HTML5 page sized appropriately for your device, and the decided content. This also eliminates the need to call the /flights/impressions endpoint. This requires reliable Internet connectivity.
HTML5 Bundle
If your system does not have reliable Internet or cannot fetch remote URLs, but can render HTML5 content (i.e. has a browser/web rendering engine), then an HTML5 bundle might be the best option. In this scenario, we deliver a zip file with the following structure:
.
├── bundle.js
├── assets
│ ├── mira
│ │ ├── 4e3d8c38211d45a9bebba2c2402bf4ef.png
│ │ ├── 7ca9a504814644edb544aae0d558066b.png
│ │ └── e7cdb5609f4e4f5c88458a4ed0501f16.png
│ └── placeholder.png
├── index.html
└── styles
└── css
├── global.css
└── normalize.cssThe index.html file is a container that executes code from bundle.js, which is configured to ping the /screens/decide endpoint with the appropriate parameters for the slot the bundle is to be schedule in. After receiving a response, the container’s DOM is manipulated to show the appropriate content.
If you are using a CDN to deliver assets already with your CMS, the HTML5 bundle can be configured to load its assets from a local directory, such as C:\sync\mira. In this case, the bundle is just the shell that makes the API call, and depending on the CMS configurability, the same bundle file can be used for any and all Mira campaigns.
Alternatively, assets can be included in the HTML5 bundle, in which case a new bundle is minted for each campaign.
Flash Bundle
Same idea as an HTML5 bundle, but the server is pinged from ActionScript. Flash can also use a CDN to read from a local directory, or can have assets directly embedded into the flash movie itself as different scenes.
CMS-Based Triggering System
Many networks and CMSs have their own data fetching and triggering system. One very common use of this is to fetch weather data and trigger different content based on if it’s sunny, raining, etc.
In this method, the CMS itself performs the data fetching and is responsible for triggering the correct asset. Usually, each asset in the campaign will have a simple mapping rule configured in the CMS, each of which is ultimately mapped to a file. The CMS then extracts the decision URI from Mira’s responses, and uses its rules to determine what to play.
Custom
We can work with a variety of custom configurations. These revolve around some system hitting the /screens/decide endpoint for the campaign/device, and making that data available to some container that can alter the default display behavior.
API Documentation
The API is available at https://api.mira.co. Currently, the API is only able to fetch decisions and report ad rolls; it is not used to configure networks and inventory.
Authentication
A valid account is required to access the APIs, which will be configured for you. Authentication can be done in one of two ways.
- Append a valid API key to every request, like
/screens/decide?api_key=abcdef... - Obtain a JWT by
POSTing login information to the/users/loginendpoint, and using that as a bearer auth header, i.e.Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.... This JWT will expire, so has to be periodically refreshed.
Usually the API key is the easier of the two.
GET /screens/decide
Decide is the interface to Mira’s ad server.
It returns either a single decision (for one campaign/device combo), or an array of decisions (for one campaign). The latter can be used in situations where the OOH Network wants to obtain the relevant decisions for all signs in the network corresponding to a particular campaign.
Parameters
campaign_id(required) - the identifier of the campaign being decided, generated by Mira (required). This will throw a400 Bad Requestif absent or invalid.display_unit_id- the identifier of a particular device, generated by Mira
Response Examples
/screens/decide?api_key=780f2f38504c425fbc3fb0284cdb5908&campaign_id=12345&device_id=1928
{
"timestamp": "2018-08-28T19:31:28.671290",
"decision": {
"network_id": null,
"campaign_id": 12345,
"display_unit_id": 1928,
"model_instance": 45093,
"creative_id": 8123094,
"decision_uri": "s3://mira-assets/7e/0a/7e0ac2c9c04a4c37b8253052790e072c.mp4",
}
}/screens/decide?api_key=780f2f38504c425fbc3fb0284cdb5908&campaign_id=12345
{
"campaign_id": 12345,
"decisions": [
{
"network_id": null,
"campaign_id": 12345,
"display_unit_id": 1928,
"model_instance": 45093,
"creative_id": 8123094,
"decision_uri": "s3://mira-assets/7e/0a/7e0ac2c9c04a4c37b8253052790e072c.mp4",
},
{
"network_id": null,
"campaign_id": 12345,
"display_unit_id": 1929,
"model_instance": 45094,
"creative_id": 8123095,
"decision_uri": "s3://mira-assets/d7/e6/d7e6805d6ebe49579335af0d6bfc4b9e.mp4",
},
{
"network_id": null,
"campaign_id": 12345,
"display_unit_id": 1930,
"model_instance": 45095,
"creative_id": 8123094,
"decision_uri": "s3://mira-assets/7e/0a/7e0ac2c9c04a4c37b8253052790e072c.mp4",
}
],
"timestamp": "2018-08-28T19:31:28.671290",
}NB: The creative_id is a different identifier than the unique resource identifier corresponding to the asset.
POST /flights/impressions
The impressions endpoint logs out-of-home impressions. It is called after a decision is made and the asset is rendered.
Parameters
display_id(required) - the identifier of the device that rendered the impression, generated by Mira.creative_id(required) - the identifier of the creative that was rendered, generated by Mira.
/flights/impressions?display_unit_id=1234&creative_id=5678
{
"display_unit_id": 1234,
"campaign_id": 9,
"creative_id": 5678,
"created_at": "2018-08-28T19:36:06+0000"
}