Reference

Sponsored ads request

Deliver contextual ads

post

Autorisations

Paramètres d'en-tête

x-retailer-idstringRequisExample: ACME-FR

Corps

visitorstringOptionnel

visitor session identifier

Example: CrAzK0R1Zhf5sfWvguJQI

aliasstringOptionnel

hashed customer identifier

Example: 77963b7a931377ad4ab5ad6a9cd718aa

placementstring · enumRequis

placement according to visited page type

Example: searchValeurs possibles:

search_termsstringOptionnel

search terms used to retrieve products

Example: ice cream with chocolate

categorystringOptionnel

category page identifier

Example: 880

productall ofOptionnel

product detail page information

listed_productsall ofOptionnel

information about the products listed on the page

extraall ofOptionnel

complementary contextual information

Réponses

200

OK.

application/json

400

Bad Request.

401

Unauthorized.

403

Forbidden.

post

POST /v1/_deliver HTTP/1.1
Host: [retailer-endpoint]
x-api-key: YOUR_API_KEY
x-retailer-id: text
Content-Type: application/json
Accept: */*
Content-Length: 878

{
  "visitor": "CrAzK0R1Zhf5sfWvguJQI",
  "alias": "77963b7a931377ad4ab5ad6a9cd718aa",
  "placement": "search",
  "slots": [
    {
      "id": "sp",
      "max": 3
    },
    {
      "id": "slider",
      "max": 10
    },
    {
      "id": "ban-300x125",
      "max": 1
    }
  ],
  "search_terms": "ice cream with chocolate",
  "category": "880",
  "product": {
    "id": "skuProd1",
    "categories": [
      "8",
      "88",
      "880"
    ],
    "offer_id": "off1a7z26ue",
    "seller_id": "sel2ac6",
    "brand": "FAMOUS BRAND",
    "rating": 4.2,
    "reviews": 1690,
    "price": 456.9,
    "availability": "in stock"
  },
  "listed_products": {
    "ids": [
      "skuPos1",
      "skuPos2",
      "skuPos3",
      "..."
    ],
    "page": 2,
    "sort": "price_asc",
    "total": 2873,
    "filters": [
      {
        "code": "color",
        "op": "in",
        "value": [
          "red",
          "blue"
        ]
      },
      {
        "code": "free_delivery",
        "op": "eq",
        "value": true
      },
      {
        "code": "price",
        "op": "lte",
        "value": 99.99
      },
      {
        "code": "rating",
        "op": "gt",
        "value": 4.7
      }
    ],
    "preserve": 2
  },
  "extra": {
    "device": "mobile",
    "store": "380",
    "url": "/webpage-path/?p=2",
    "segments": [
      "male",
      "young",
      "csp+"
    ],
    "search_hint": "ice cream"
  }
}

{
  "slots": [
    {
      "id": "sp",
      "max": 3,
      "fill": 1,
      "products": [
        {
          "id": "skuProd1",
          "oid": "off1a7z26ue",
          "title": "FAMOUS BRAND - Best product",
          "brand": "FAMOUS BRAND",
          "price": "123.90 €",
          "store": "main",
          "rating": 95,
          "reviews": 57,
          "link": "https://retailer.com/pdp/famous-brand-best-product-skuProd1.html",
          "image_link": "https://img.retailer.com/skuProd1/c4e8cfa1-e3ce-4e29-9e00-841510e5a316.jpeg",
          "index": 1,
          "beacon": "tYdH1JZroRdc01NHb5o-b0T9b9kVBHnYTfy1OXoANGhEweHLwIJEN-1W-quaAlHti8pdJZQmE"
        }
      ]
    },
    {
      "id": "ban-300x125",
      "max": 1,
      "fill": 1,
      "banners": [
        {
          "image": "https://m.vzbl.eu/zhlcutkc0x.png",
          "image_picture": [
            {
              "type": "image/webp",
              "srcset": "https://m.vzbl.eu/zhlcutkc0x-h.webp, https://m.vzbl.eu/zhlcutkc0x.webp 2x"
            },
            {
              "type": "image/png",
              "srcset": "https://m.vzbl.eu/zhlcutkc0x-h.png, https://m.vzbl.eu/zhlcutkc0x.png 2x"
            }
          ],
          "image_width": 300,
          "image_height": 100,
          "image_alt_text": "Famous brand new product line",
          "link": "https://retailer.com/brand/famous-brand",
          "link_text": "See offers",
          "index": 1,
          "beacon": "ZF6cbsNb7pKf1FcHcxgKWoHZ2vRK8e_WCJEn1Tq5_6eKzchXGJhApQs09OA-YeQHRXcpoH48my5I"
        }
      ]
    }
  ]
}

To request ads, you need to provide a context. A context refers to a set of filters that campaigns must meet before being displayed. This ensures that only relevant ads are shown.

POST https://[retailer-endpoint]/v1/_deliver
x-api-key: [your_api_key_goes_here]
x-retailer-id: [your_retailer_id_goes_here]
Content-Type: application/json

{
  "visitor": "string",
  "alias": "string",
  "placement": "plp",
  "slots": [
    { "id": "sp", "max": 3 }
  ],
  "category": "catId1",
  "listed_products": {
    "ids": ["id1","id2","id3","id4","id5","id6","id7"],
    "page": 1,
    "sort": "relevance",
    "total": 135
  },
  "extra": {
    "device": "mobile",
    "os": "ios",
    "url": "/cat-pages/cat-corresponding-to-cat-id-1/",
    "store": "141",
    "vz_preview":"xiLvzAwJ9k6K1IrEKfIE"
  }
}

POST https://[retailer-endpoint]/v1/_deliver
x-api-key: [your_api_key_goes_here]
x-retailer-id: [your_retailer_id_goes_here]
Content-Type: application/json

{
  "placement": "search",
  "slots": [
    { "id": "sp", "max": 6 }
  ],
  "search_terms": "your search keywords",
  "extra": {
    "device": "app",
    "os": "ios"
  }
}

POST https://[retailer-endpoint]/v1/_deliver
x-api-key: [your_api_key_goes_here]
x-retailer-id: [your_retailer_id_goes_here]
Content-Type: application/json

{
  "placement": "pdp",
  "slots": [
    { "id": "slider", "max": 15 }
  ],
  "product": {
    "id": "sku910d",
    "categories": ["c290", "c2902", "c29023"],
    "price": 456.90,
    "availability": "in stock",
    "rating": 4.2,
    "reviews": 1690
  }
}

POST https://[retailer-endpoint]/v1/_deliver
x-api-key: [your_api_key_goes_here]
x-retailer-id: [your_retailer_id_goes_here]
Content-Type: application/json

{
  "placement": "home",
  "slots": [
    { "id": "ban-970x250" },
    { "id": "slider", "max": 10 }
  ],
}

Recording of events

Track events (display, view, click)

post

Autorisations

Paramètres d'en-tête

x-retailer-idstringRequisExample: ACME-FR

Corps

displaystring[]Optionnel

collection of beacons from displayed ads

Example:

["tYdH1JZroRdc01NHb5o-b0T9b9kVBHnYTfy1OXoANGhEweHLwIJEN-1W","qSUaO_EYpgShat8p8-bm_wiskKYotoBDbwMVU-8li2lO8KC-J8nFyvB21u"]

viewstring[]Optionnel

collection of beacons from viewed ads

Example: ["qSUaO_EYpgShat8p8-bm_wiskKYotoBDbwMVU-8li2lO8KC-J8nFyvB21u"]

clickstring[]Optionnel

collection of beacons from viewed ads

Example: ["qSUaO_EYpgShat8p8-bm_wiskKYotoBDbwMVU-8li2lO8KC-J8nFyvB21u"]

Réponses

204

No Content.

401

Unauthorized.

403

Forbidden.

post

POST /v1/_event HTTP/1.1
Host: [retailer-endpoint]
x-api-key: YOUR_API_KEY
x-retailer-id: text
Content-Type: application/json
Accept: */*
Content-Length: 274

{
  "display": [
    "tYdH1JZroRdc01NHb5o-b0T9b9kVBHnYTfy1OXoANGhEweHLwIJEN-1W",
    "qSUaO_EYpgShat8p8-bm_wiskKYotoBDbwMVU-8li2lO8KC-J8nFyvB21u"
  ],
  "view": [
    "qSUaO_EYpgShat8p8-bm_wiskKYotoBDbwMVU-8li2lO8KC-J8nFyvB21u"
  ],
  "click": [
    "qSUaO_EYpgShat8p8-bm_wiskKYotoBDbwMVU-8li2lO8KC-J8nFyvB21u"
  ]
}

Aucun contenu

List of Tracked Events

event

Performance metric

Description

display

Display

A display occurs whenever an ad is loaded

view

View

A view occurs whenever an ad becomes visible

click

Click

A click occurs whenever a customer clicks an ad

view_s2

2 second view

The video was watched for at least 2 seconds

view_s5

5 second view

The video was watched for at least 5 seconds

view_q1

Video first quartile

The user watched 25% of the video ad

view_m

Video midpoint

The user reached the midpoint of the video ad

view_q3

Video third quartile

The user watched 75% of the video ad

view_f

Video complete

The video was watched to completion (100%)

unmute

Video unmute

The user manually unmuted the video during playback

POST https://[retailer-endpoint]/v1/_event 
x-api-key: [your_api_key_goes_here]
x-retailer-id: [your_retailer_id_goes_here]
Content-Type: application/json

{
  "display": [
    "tYdH1JZroRdc01NHb5o-b0T9b9kVBHnYTfy1OXoANGhEweHLwIJEN-1W",
    "qSUaO_EYpgShat8p8-bm_wiskKYotoBDbwMVU-8li2lO8KC-J8nFyvB21u"
  ]
}

Report purchase

Report transaction (purchase)

post

Autorisations

Paramètres d'en-tête

x-retailer-idstringRequisExample: ACME-FR

Corps

visitorstringRequis

visitor session identifier

Example: cYFwasdXSlhzqYDpWB0tw

aliasstringOptionnel

hashed customer identifier

Example: 77963b7a931377ad4ab5ad6a9cd718aa

currencystring · enumRequis

currency

Example: EURValeurs possibles:

purchase_idstringRequis

purchase identifier

Example: 123RTA7Z

purchase_datestringRequis

purchase date

Example: 2021-10-05T14:48:00.000Z

Réponses

204

No Content.

401

Unauthorized.

403

Forbidden.

post

POST /v1/_purchase HTTP/1.1
Host: [retailer-endpoint]
x-api-key: YOUR_API_KEY
x-retailer-id: text
Content-Type: application/json
Accept: */*
Content-Length: 314

{
  "visitor": "cYFwasdXSlhzqYDpWB0tw",
  "alias": "77963b7a931377ad4ab5ad6a9cd718aa",
  "currency": "EUR",
  "purchase_id": "123RTA7Z",
  "purchase_date": "2021-10-05T14:48:00.000Z",
  "items": [
    {
      "product_id": "3E4NZE3T12",
      "price": 400,
      "quantity": 1,
      "offer_id": "off1a7z26ue",
      "seller_id": "2ac661",
      "seller": "ACME NG",
      "brand": "FAMOUS BRAND"
    }
  ]
}

Aucun contenu

POST https://[retailer-endpoint]/v1/_purchase 
x-api-key: [your_api_key_goes_here]
x-retailer-id: [your_retailer_id_goes_here]
Content-Type: application/json

{
  "visitor" : "string",
  "alias" : "string",
  "purchase_id" : "string",
  "purchase_date": "string (iso date)" ,
  "currency" : "string (iso currency code)",
  "items": [
    {
      "product_id" : "string",
      "price" : number,
      "quantity": number,
      "offer_id" : "string",
      "seller_id" : "string",
      "seller" : "string",
      "brand" : "string"
    }
  ]
}

Make sure to have your API_KEY ready to use the API.

PrécédentDeveloper notes

Dernière mise à jour il y a 1 mois