Pedido

A API de colocação de anúncios pode ser chamada a partir de qualquer um dos cliente lado ou servidor lado.

Ao usar cliente a implementação do lado, o navegador pode realizar uma pré-validação requisição. Se quiser evitar isso, no cabeçalho da requisição, use Content-Type: text/plain. Isto garantirá que o navegador classifique a requisição como "simple" e, por isso, ignore a requisição de pré-validação.

Além disso, ao chamar a API no cliente lado, os IPs não são realmente necessários pois pode ser difícil detetar o IP usando o frontend e JavaScript. Em vez disso, a nossa API deteta o IP da ligação quando a requisição é feita.

Ao usar servidor implementação do lado, para garantir a segmentação correta, o IP correto do utilizador deve ser passado explicitamente. Caso contrário, os anúncios serão direcionados para a localização do servidor e isso pode fazer com que as impressões sejam invalidadas mais tarde devido a uma discrepância de IP.

Quer se use cliente ou servidor, se for passado um IP, este terá prioridade sobre o que detetamos.

Para efetuar uma requisição à API de colocação de anúncios, tem de passar dois objetos: utilizador e zonas. A requisição é feita em JSON usando HTTP POST.

utilizador

Parâmetro	Obrigatório?	Descrição
id	Não	O ID do utilizador
ip	Recomendado	O endereço IP do utilizador.
ua	Sim	O User Agent: uma cadeia que contém o navegador/app e o dispositivo/SO do utilizador.
language	Não	Define o idioma da requisição usando o código ISO padrão de dois caracteres mais um código de região opcional de 2 caracteres. p. ex. en-us para inglês dos Estados Unidos.
referer	Não	O endereço do site onde o anúncio será exibido.
el	Não	O e-mail do utilizador codificado em Base64.
screen_resolution	Não	Resolução de ecrã do dispositivo usado pelo utilizador
window_orientation	Não	Deve ser "portrait" se o site tiver um layout móvel e "landscape" se for um de desktop.
gdpr	Não	Extensões aconselhadas para a privacidade (Objeto).

user.gdpr

Parâmetro	Descrição
gdpr	Deve ser 0 se quem faz a chamada acredita que o utilizador não está sujeito ao GDPR, e 1 se o utilizador está sujeito ao GDPR.
consent	Esta é a string de consentimento exigida pelos padrões da IAB.

zonas

Parâmetro	Obrigatório?	Descrição
id	Sim	O ID da zona de anúncios
sub	Não	O Sub ID da zona de anúncios
keywords	Não	Quaisquer keywords associadas ao tráfego que possam corresponder a um tipo específico de publicidade. Se não houver palavras-chave, será usado o URL do site para correspondência
custom_targeting	Não	Valores personalizados da zona (Objeto)

zones.custom_targeting

Parâmetro	Descrição
ex_av	Deve ser 0 se indefinido, 1 se a idade estiver verificada e 2 se a idade não estiver verificada

Exemplo

É possível solicitar muitas zonas de anúncios numa única requisição. Cada zona terá um ID diferente, como pode ver no exemplo abaixo.

{
  "user": {
    "id": "abdef8u9",
    "ip": "10.42.0.1",
    "ua": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.63 Safari/537.36",
    "language": "en-US",
    "referer": "https://blabla.com",
    "gdpr": {
      "gdpr": 1,
      "consent": "CPAoZRHPArq3hBcADBENBJCgAAAAAAAAAAqIHKQAAOUgAAAA"
    }
  },
  "zones": [
    {
      "id": 4031007,
      "sub": 111,
      "keywords": "humour, general"
    },
    {
      "id": 4031015,
      "sub": 222
    },
    {
      "id": 4031019,
      "sub": 222
    }
  ]
}