Impressions#

This API implements the impressions sections of the Adshares protocol.

First, read about error handling.

Register#

GET /supply/register#

The response will return scripts to run on the client side (optional).

Query Parameters:

iid – the impression ID (unique, eg. UUID v4)
stid – optional transaction ID seed (eg., internal user ID, wallet account address)

Request Headers:

Accept – application/html
User-Agent – the user agent originating the request

Status Codes:

302 Found – and then redirects to AdUser service
200 OK – no error

Example request:

GET /supply/register?iid=8ac04a70-886c-4d25-a8f8-10f1c5ed22f7 HTTP/1.1
Host: app.example.com
Accept: application/html
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3865.90 Safari/537.36

Example response:

HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8

<!DOCTYPE html>
<html lang="en">
<head>
</head>
<body>
    <script type="text/javascript">
        parent.postMessage({"insertElem":[{"type": "iframe", "url": "https://au.example.com/fg/30b05fd441208ed758307bfd2e293b71/27b35445.html"}]}, "*");
    </script>
</body>
</html>

Find creatives#

POST /supply/find#

Finds creatives that fit the placements.

Request Headers:

Accept – application/json
User-Agent – the user agent originating the request

Response Headers:

Content-Type – application/json

Status Codes:

200 OK – no error

Request JSON Object:

context (object) – the impression’s context
placements (array) – a list of placement requests with mandatory placementId attributes

Response JSON Object:

data (Creative[]) – creative list. Creative and placement can be matched by the request ID. If response does not contain entry for request ID, AdServer does not have suitable creative.

Example request:

POST /supply/find HTTP/1.1
Host: app.example.com
Accept: application/json
Content-Type: application/json
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3865.90 Safari/537.36

{
    "context": {
        "iid": "8ac04a70-886c-4d25-a8f8-10f1c5ed22f7",
        "url": "https://mysite.com"
    },
    "placements": [
        {
            "id": "1234",
            "placementId": "2c81e9ed531b70c8ced43b19245aa3c3"
        }
    ]
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": [
        {
            "id": "1234",
            "creativeId": "32a79fb61103aa3ef230d524cbd93e4f",
            "placementId": "2c81e9ed531b70c8ced43b19245aa3c3",
            "siteId": "ccc0c4b6109a4fe2ee2eb103a20c2d5d",
            "publisherId": "d64bf2a15c5de2e33b20c4b6100c2d5d",
            "demandServer": "0001-00000001-8B4E",
            "supplyServer": "0001-00000002-BB2D",
            "type": "image",
            "mime": "image/png",
            "scope": "300x250",
            "hash": "56436e1fdcb42f406760ccc9a4fe2e0519c36f46",
            "serveUrl": "https://app.example.com/serve/xed20914d13ed416ec91eb4be7b640a49.doc?v=67f4",
            "viewUrl": "https://app.example.com/l/n/view/32a79fb61103aa3ef230d524cbd93e4f?r=aHR0cHM6Ly9hcHAuZXhhbXBsZS5jb20vdmlldy9lZDIwOTE0ZDEzZWQ0MTZlYzkxZWI0YmU3YjY0MGE0OQ",
            "clickUrl": "https://app.example.com/l/n/click/32a79fb61103aa3ef230d524cbd93e4f?r=aHR0cHM6Ly9hcHAuYWRhcm91bmQubmV0L3ZpZXcvZWM5MWViNGJlN2I2NDBhNDllZDIwOTQxNjE0ZDEzZWQ",
            "rpm": 2.13
        }
    ]
}

Dynamic find creatives#

POST /supply/find#

Finds creatives that match the query with automatic creation of users (if enabled) and placements.

Request Headers:

Accept – application/json
User-Agent – the user agent originating the request

Response Headers:

Content-Type – application/json

Status Codes:

200 OK – no error

Request JSON Object:

context (object) – the impression’s context with mandatory publisher, medium and uid attributes
placements (array) – a list of placement requests with mandatory width, and height attributes

Response JSON Object:

data (Creative[]) – creative list. Creative and placement can be matched by the request ID. If response does not contain entry for request ID, AdServer does not have suitable creative.

Example request:

POST /supply/find HTTP/1.1
Host: app.example.com
Accept: application/json
Content-Type: application/json
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3865.90 Safari/537.36

{
    "context": {
        "iid": "8ac04a70-886c-4d25-a8f8-10f1c5ed22f7",
        "url": "https://mysite.com",
        "publisher": "ads:0001-00000000-9B6F"
        "medium": "metaverse",
        "vendor": "my-metaverse",
        "uid": "0x2dc37ed4780c5b826d8D71f629581791F9f36e7a",
        "metamask": true
    },
    "placements": [
        {
            "id": "1234",
            "name": "Main gallery",
            "width": 300,
            "height": 225,
            "types": [
                "image",
                "video"
            ],
            "mimes": [
                "image/jpeg",
                "image/png",
                "video/mp4"
            ],
        }
    ]
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": [
        {
            "id": "1234",
            "creativeId": "32a79fb61103aa3ef230d524cbd93e4f",
            "placementId": "2c81e9ed531b70c8ced43b19245aa3c3",
            "siteId": "ccc0c4b6109a4fe2ee2eb103a20c2d5d",
            "publisherId": "d64bf2a15c5de2e33b20c4b6100c2d5d",
            "demandServer": "0001-00000001-8B4E",
            "supplyServer": "0001-00000002-BB2D",
            "type": "image",
            "mime": "image/png",
            "scope": "300x250",
            "hash": "56436e1fdcb42f406760ccc9a4fe2e0519c36f46",
            "serveUrl": "https://app.example.com/serve/xed20914d13ed416ec91eb4be7b640a49.doc?v=67f4",
            "viewUrl": "https://app.example.com/l/n/view/32a79fb61103aa3ef230d524cbd93e4f?r=aHR0cHM6Ly9hcHAuZXhhbXBsZS5jb20vdmlldy9lZDIwOTE0ZDEzZWQ0MTZlYzkxZWI0YmU3YjY0MGE0OQ",
            "clickUrl": "https://app.example.com/l/n/click/32a79fb61103aa3ef230d524cbd93e4f?r=aHR0cHM6Ly9hcHAuYWRhcm91bmQubmV0L3ZpZXcvZWM5MWViNGJlN2I2NDBhNDllZDIwOTQxNjE0ZDEzZWQ",
            "rpm": 2.13
        }
    ]
}

Data structures#

Impression context object#

iid (string) - the impression ID
publisher (string) - (optional) the publisher ID or account address (ADS or BSC)
url (string) - the site URL
medium (string) - (optional) the site medium
vendor (string) - (optional) the site vendor
uid (string) - (optional) the user ID (eg. a wallet address)
metamask (boolean) - (optional) is the MetaMask enabled

Placement request object#

id (string) - the request ID
placementId (string) - the placement ID (omit if width and height are provided)
name (string) - (optional) name of the placement
width (int) - width of the placement (omit if placementId is provided)
height (int) - height of the placement (omit if placementId is provided)
depth (int) - (optional) depth of the placement
types (string[]) - (optional) a list of accepted types
mimes (string[]) - (optional) a list of accepted MIME types
topframe (boolean) - (optional) indicates if placement is in the top frame (true) as opposed to an iframe (false)

Creative object#

id (string) – the request ID
creativeId (string) – the creative ID
placementId (string) – the placement ID
siteId (string) – the site ID
publisherId (string) – the publisher ID
demandServer (string) – the demand server account address
supplyServer (string) – the supply server account address
type (string) – the creative type.
mime (string) – the creative MIME type.
scope (string) – the creative scope (size).
hash (string) – checksum of the creative content
serveUrl (string) – URL to download the content of the creative
viewUrl (string) – view event URL
clickUrl (string) - click event URL
rpm (float) – average campaign’s RPM