2 - Sync Inventory

Overview

In the previous step you learned how to authenticate with the Hivestack API, in this segment you will start putting what you've learned into practice.

For full transparency: during the process of writing this guide, we will be performing every example we provide to you using Postman as our HTTP client.

Creating a network

For the most part, one network per organization makes sense. That means you have a single network, or grouping, of digital displays for your company. However, should you wish to group your inventory into different networks, you are able to do so. Regardless, a network must be created in order to begin syncing.

Example: the company Hooli has an inventory of digital billboards located along driving routes throughout the US. Hooli also owns digital displays that are stationed above urinals in men's and gender neutral bathrooms. It makes sense to create different networks for this decidedly disparate environments to reflect how these different mediums are sold differently. You might, in this case, consider naming the networks "Billboards" and "Restrooms" respectively.

Moving forwards, "Hooli Supplier" will be used as the organization in all examples unless otherwise specified.

Some info about Hooli Supplier

Network - Make the request

• URL

  https://privateurl.com/api/v2/networks/

• Method:

  POST

• Data:

{
  "code": "HOO",
  "name": "Hooli",
  "owner_id": 6
}

• Response:

[
  {
    "network_id": 27,
    "name": "Hooli",
    "owner_id": 6,
    "code": "HOO"
  }
]

Adding sites

Sites are a grouping of screens. A screen is, in general, a playable area on a digital display. Typically a playable area and a display have a one-to-one relationship. Regardless, this relationship is not defined within Hivestack and can be abstracted to "does this area play and ad from an ad server?" -> "it's a screen". These screens can be grouped into sites to enable targeting multiple screens at a time. A real world example would be a mall that has many digital displays installed. It makes sense to group these displays into a site grouping called something along the lines of "Angringnon Shopping Mall".

Note

It is not required to create sites. Screens can exist without sites, however, it is recommended for all Screens to belong to a site in order to benefit from all Hivestack features. Even if you have one screen per site.

Site - Make the request

Most of the fields should be pretty self-explanatory with the exception of external_id. You can optionally provide an external_id as a string to reflect an ID that might make it easier for you to identify the site.

• URL

  https://privateurl.com/api/v2/sites/

• Method:

  POST

• Data:

{
  "name": "Montreal Bell Center",
  "owner_id": 6,
  "description": "Bell Center Outdoor Boards",
  "latitude": 45.49610,
  "longitude": -73.569243,
  "external_id": "mtl_belcen"
}

• Response:

[
  {
    "active": true,
    "custom_attributes": null,
    "description": "Bell Center Outdoor Boards",
    "external_id": "mtl_belcen",
    "latitude": 45.4961,
    "location_id": 12728,
    "longitude": -73.5692,
    "name": "Montreal Bell Center",
    "owner_id": 6,
    "site_id": 4371,
    "uuid": "9722e0ef-753a-4d0e-bdcd-4daea06b6ea2",
    "weekly_impressions": 0
  }
]

Adding screens

As mentioned above, a screen is a digital display where an ad can play. Screens make ad requests to our Ad Server/SSP, and we response with either a VAST response containing details about an ad to play, or an empty VAST tag indicating that the screen has nothing to play for this request. In order to start making ad requests, you need a few components set up. One of those components is at least one screen.

Screen - Make the request

• URL

  https://privateurl.com/api/v2/screens/

• Method:

  POST

• Data:

{
  "name": "Bell Center N/W",
  "owner_id": 6,
  "screen_width": 1920,
  "screen_height": 1080,
  "site_id": 4371,
  "description": "Bell Center - North/West corner on rue de-la-Montagne",
  "latitude": 45.49610,
  "longitude": -73.569243,
  "network_id": 27,
  "spot_length": 10,
  "external_id": "mtl_belcen_nw",
  "timezone": "America/Montreal"
}

• Response:

[
    {
        "active": true,
        "custom_attributes": null,
        "description": "Bell Center - North/West corner on rue de-la-Montagne",
        "external_id": "mtl_belcen_nw",
        "last_heard_from_utc": null,
        "latitude": 45.4961,
        "location_id": 12728,
        "longitude": -73.569243,
        "loop_length": null,
        "mediatype_id": null,
        "min_seconds_between_ad_domain_plays": 0,
        "name": "Bell Center N/W",
        "network_id": 27,
        "operating_hours": "111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111",
        "owner_id": 6,
        "screen_height": 1080,
        "screen_width": 1920,
        "site_id": 4371,
        "spot_length": 10,
        "timezone": "America/Montreal",
        "unit_id": 27799,
        "uuid": "bfbb0c7c-1709-4b45-b8e6-9f1170583580"
    }
]