Invoking the Streaem platform

Once the above steps are complete a retailer can send requests to the Streaem platform.
The following are the distinct types of request currently supported:

Request a sponsored product keyword search auction
Request a sponsored product category auction
Request a display ad keyword search auction
Request a display ad category search auction
Request a display ad page auction
Request a click attribution event is recorded
Request an add-to-cart attribution event is recorded
Request a purchase/conversion attribution event is recorded

In addition an optional endpoint is provided for retailers who do not provide product stock level data in their inventory feed:

Record product shown events

The definitive description of the endpoints is in the OpenAPI documentation that will be shared by Streaem, the following sections seek to give a narrative explanation of how these APIs can be used.
Several Software Development Kit (SDK) packages will be made available in a variety of programming languages to ease the process of communicating with the Streaem platform.

Request authentication

All request types must be sent as HTTPS requests as described in the following specific sections.
All endpoints have the same authentication mechanism which requires a signature to be sent in a custom header called X-STREAEM-HASH.

Pseudo-code for the signature algorithm is below and this functionality is included in the Streaem SDKs.

Order the body parameters of the request alphabetically by lower-cased parameter name.
Create an empty string
Concatenate the values of all parameters into the string.
Use a currently active encryption key to sign the string using the HMAC-SHA256 algorithm
Encode the generated bytes into a string using the Base64 mechanism
Send the generated encoded string in the X-STREAEM-HASH header

Signature examples

Given a POST request of the following for a category request by retailer id 5:

+https://api.streaem.com/api/auction/sp/category/5+

{  
  "platform_type": "WEB_DESKTOP",  
  "category": 3,  
  "uid": "123456789"  
}

The sorted attributes will be ordered category, platform_type and uid.
Adding these to the string gives +3WEB_DESKTOP123456789+

The hashed value of this string using the key TEST-KEY and after Base64 encoding will be: +k+OWP4Ma3U+6BEEopquZzqunnB+w7/vCuAbGdl7iJwg=+

Making a sponsored product category request

A sponsored product category request is performed through a POST request of the following form: +https://api.streaem.com/api/auction/sp/category/<retailer_id>+

{
  "platform_type": "<platform type>",
  "category": <category id or name>,
  "uid": "<uuid>"
}

Where:

Field	Type	Description
retailer_id	integer	The retailer unique id in the Streaem platform
platform_type	string	Platform type, one of `WEB_DESKTOP`, `WEB_MOBILE` or `APP_MOBILE`
category	String or integer	The string name or integer identifier for the category page in question
uid	string	The unique identifier of the user visiting the category page

For example a request from retailer id 7 for category id 3 from user 123456789 on a mobile browser would look like the following:

https://api.streaem.com/api/auction/sp/category/7

{
  "platform_type": "WEB_MOBILE",
  "category": 3,
  "uid": "123456789"
}

The response will be a JSON document that contains some data for the overall request plus data for each winning product.
An example response with 2 products is below:

{
  "auction_group_id": "979b8474-bde2-459f-b161-1b4dfcf0cb33",
  "winning_bids": [
    {
      "auction_id": "0ac07ae3-7d80-47e7-a69f-b0812fbc262f-3",
      "ranking": 1,
      "advertiser_id": 1,
      "campaign_id": 1,
      "adgroup_id": 3,
      "product_ids": [  "EAN004" ]
    },
    {
      "auction_id": "0ac07ae3-7d80-47e7-a69f-b0812fbc262f-12",
      "ranking": 2,
      "advertiser_id": 3,
      "campaign_id": 4,
      "adgroup_id": 12,
      "product_ids":[  "EAN00113" ]
    }
  ]
}

Two of these fields relate to the overall response:

auction_group_id the UUID referring to this particular overall request
winning_bids - an array of products to be displayed

Within the winning_bids array the following fields relate to each product to be displayed:

auction_id - the unique id of this specific winning product, this will be used in any subsequent click or add to cart attribution requests
ranking - the ordering of the product in the list of winners, position 1 is the top slot, 2 the second etc
advertiser_id - the numeric id of the winning advertiser
campaign_id - the numeric id of the winning campaign
adgroup_id - the numeric id of the winning adgroup
product_ids - the product ids (or alternatively if configured the retailer specific product identifiers) of the winning bid

Category request response codes

The following HTTP response codes can be returned from a category auction request:

200 successful invocation of the auction
400 the request was malformed, the X-STREAEM-HASH header was missing or incorrect or a mandatory parameter was missing
404 there were no winners for the auction

Making a sponsored product keyword request

Given a POST request of the following for a category request by retailer id 5:

https://api.streaem.com/api/auction/sp/keyword/<retailer_id>

{
  "platform_type": "<platform type>",
  "search_term": "<search term>",
  "uid": "123456789"
}

Where:

Field	Type	Description
retailer_id	integer	The retailer unique id in the Streaem platform
platform_type	string	Platform type, one of `WEB_DESKTOP`, `WEB_MOBILE` or `APP_MOBILE`
search_term	String	The search text from the user that resulted in the search
uid	string	The unique identifier of the user performing the search

For example, a request from retailer id 11 on the search term cola by the user with uid 123456789 on a desktop browser would look like the following:

https://api.streaem.com/api/auction/sp/keyword/11

{
  "platform_type": "WEB_DESKTOP",
  "search_term": "cola",
  "uid": "123456789"
}

The response will be a JSON document that contains some data for the overall request plus data for each winning product. An example response with 2 products is below:

{
  "auction_group_id": "979b8474-bde2-459f-b161-1b4dfcf0cb33",
  "winning_bids": [
    {
      "auction_id": "0ac07ae3-7d80-47e7-a69f-b0812fbc262f-3",
      "ranking": 1,
      "advertiser_id": 1,
      "campaign_id": 1,
      "adgroup_id": 3,
      "product_ids": [ "EAN004" ]
    },
    {
      "auction_id": "0ac07ae3-7d80-47e7-a69f-b0812fbc262f-4",
      "ranking": 2,
      "advertiser_id": 3,
      "campaign_id": 4,
      "adgroup_id": 4,
      "product_ids": [ "EAN00113" ]
    }
  ]
}