For the complete documentation index, see llms.txt. This page is also available as Markdown.

Zonas da Resposta

O JSON de resposta da API de colocação de anúncios contém o zonas array e os renderizadores e utilizador objetos.

Nesta página vamos explicar o zonas array, que contém todos os detalhes relativos ao anúncio que venceu o seu pedido de anúncio.

O array contém um objeto com os dados do anúncio para cada ID de zona solicitado.

Propriedade
Descrição

idzone

O ID da zona do anúncio.

type

O formato de anúncio utilizado, por exemplo banner.

data

Os dados do anúncio (Objeto)

Abaixo encontrará uma lista detalhada das propriedades devolvidas para cada data objeto de acordo com os formatos de anúncio disponíveis.

Propriedade
Descrição

url

O URL para o qual o anúncio direciona.

impression

O URL de impressão

image

A imagem original carregada para o anúncio.

optimum_image

Se o criativo carregado for um GIF animado, esta é a versão MP4 otimizada dele, criada para ser usada no anúncio.

width

A largura do anúncio em pixels.

height

A altura do anúncio em pixels.

media

Isto mostra que tipo de banner é este: imagem, HTML ou vídeo: Deve ser img_banner, html_banner ou video_banner, respetivamente.

Exemplos de resposta de banner

Banner de imagem:

Banner HTML:

Banner de vídeo:

Propriedade
Descrição

url

O URL de clique

impression

O URL de impressão

image

A imagem original carregada para o anúncio.

optimum_image

Num banner fixo, se o criativo carregado for um GIF animado, esta é a versão MP4 otimizada dele, criada para ser usada no anúncio.

width

A largura do anúncio em pixels.

height

A altura do anúncio em pixels.

frequency_period

Com que frequência, em minutos, o anúncio é mostrado.

v_pos

A posição vertical do anúncio.

h_pos

A posição horizontal do anúncio.

media

Isto mostra que tipo de banner é este: imagem, HTML ou vídeo: Deve ser img_banner, html_banner, ou video_banner respetivamente.

Exemplo de resposta de banner fixo

Mensagens instantâneas

Propriedade
Descrição

url

O URL de clique

impression

O URL de impressão

image

O URL da imagem

optimum_image

Se o criativo carregado for um GIF animado, esta é a versão MP4 otimizada dele, criada para ser usada no anúncio.

width

A largura do anúncio em pixels.

height

A altura do anúncio em pixels.

frequency_period

Com que frequência o anúncio é mostrado, em minutos.

media

Isto mostra que tipo de banner é utilizado: imagem, HTML ou vídeo: Deve ser img_banner, html_banner, ou video_banner respetivamente.

Exemplo de resposta de mensagem instantânea

Anúncios nativos

Quando a resposta devolver um anúncio nativo, zones.data devolverá dois objetos: layout e ad_items

data.layout

Propriedade
Descrição

widgetHeaderContentHtml

O URL da marca 'Powered by' que é apresentada.*

branding_logo

O URL do logótipo da marca que é apresentado, se ativado.*

branding_logo_hover

O URL do logótipo da marca que é apresentado quando o utilizador passa o rato por cima.*

itemsPerRow

O número de anúncios que são mostrados em cada linha do widget.

itemsPerCol

O número de anúncios que são mostrados em cada coluna do widget.

font_family

A família de tipos de letra usada no anúncio.

header_font_size

O tamanho do tipo de letra usado no cabeçalho da marca.

header_font_color

A cor do tipo de letra usada no cabeçalho da marca.

widget_background_color

O código hexadecimal da cor de fundo usado para o widget.

widget_width

A largura de todo o widget.

minimum_width_for_full_sized_layout

A largura mínima para uma disposição em tamanho completo, em pixels.

item_height

A altura de cada anúncio individual.

item_padding

O espaçamento entre cada anúncio.

image_height

A altura da imagem em cada anúncio.

image_width

A largura da imagem em cada anúncio.

text_margin_top

O tamanho, em pixels, da margem superior do texto.

text_margin_bottom

O tamanho, em pixels, da margem inferior do texto.

text_margin_left

O tamanho, em pixels, da margem esquerda do texto.

text_margin_right

O tamanho, em pixels, da margem direita do texto.

title_font_size

O tamanho do tipo de letra do título de cada anúncio.

title_font_color

A cor do tipo de letra do título de cada anúncio.

title_font_weight

O peso do tipo de letra do título de cada anúncio.

title_decoration

Se o título está sublinhado ou não.

title_hover_color

A cor do tipo de letra quando se passa o rato por cima do título.

title_hover_font_weight

O peso do tipo de letra quando se passa o rato por cima do título.

title_hover_decoration

Se o título é sublinhado ao passar o rato por cima ou não.

description_font_size

O tamanho do tipo de letra da descrição de cada anúncio.

description_font_color

A cor do tipo de letra da descrição de cada anúncio.

description_font_weight

O peso do tipo de letra da descrição de cada anúncio.

description_decoration

Se a descrição está sublinhada ou não.

description_hover_color

A cor do tipo de letra quando se passa o rato por cima da descrição.

description_hover_font_weight

O peso do tipo de letra quando se passa o rato por cima da descrição.

description_hover_decoration

Se a descrição é sublinhada ao passar o rato por cima ou não.

open_in_new_window

Se o anúncio deve ser aberto numa nova janela quando clicado. 1=sim, 0=não.

mobile_responsive_type

O tipo de responsividade quando se utiliza um dispositivo móvel (ou seja, nenhum ou compacto). 1=compacto, 0=não.

header_is_on_top

Se a marca deve ser apresentada acima ou abaixo dos anúncios. 1=sim, 0=não.

header_text_align

O alinhamento horizontal do cabeçalho da marca.

title_enabled

Se o título está ativado ou não. 1=sim, 0=não.

description_enabled

Se a descrição está ativada ou não. 1=sim, 0=não.

image_border_size

O tamanho, em pixels, da borda da imagem.

image_border_color

O código hexadecimal da cor da borda da imagem.

text_align

O alinhamento do texto: esquerda, centro ou direita.

customcss_enabled

Se o CSS personalizado está ativado ou não. 1=sim, 0=não.

customcss

Se ativado, o CSS personalizado será apresentado aqui.

header_enabled

Se o cabeçalho está ativado ou não. 1=sim, 0=não.

mobile_breakpoint

O ponto de quebra, em pixels, entre as vistas de desktop e mobile da zona do anúncio.

spacing_v

O espaçamento vertical, em pixels, entre os anúncios, definido nas Opções Avançadas.

spacing_h

O espaçamento horizontal, em pixels, entre os anúncios, definido nas Opções Avançadas.

zoom

Se o anúncio deve ampliar/reduzir ao passar o rato por cima.

mobile_rows

O número de linhas de anúncios no widget móvel.

mobile_cols

O número de colunas de anúncios no widget móvel.

use_v2_script

Se a zona de anúncios foi criada com a configuração V2 mais recente ou com a v1 anterior.

text_enabled

Se o título e a descrição do texto devem ser apresentados. 1=sim, 0=não.

mobile_image_width

A largura da imagem em cada anúncio no mobile.

mobile_text_box_size

O tamanho da caixa de texto em mobile. Intervalo válido 50-500.

mobile_text_enabled

Se o título está ativado ou não no mobile. 1=sim, 0=não.

mobile_text_position

A posição do texto no mobile: em baixo ou à direita.

item_spacing_on_each_side

O espaçamento em cada lado dos anúncios, se tiverem sido configurados usando a configuração antiga v1.

text_position

Se o texto é posicionado no lado esquerdo ou direito.

text_box_size

O tamanho da caixa de texto em pixels. Intervalo 50-500.

widget_height

A altura de todo o widget.

brand_enabled

Se a marca está ativada ou não.

brand_font_size

O tamanho do tipo de letra da marca.

brand_font_color

A cor do tipo de letra da marca.

brand_font_weight

O peso do tipo de letra da marca.

brand_decoration

Se o tipo de letra está sublinhado ou não.

mobile_image_height

A altura da imagem em cada anúncio no mobile.

publisherAdType

Que tipo de anúncio nativo é este, ou seja, recomendação, saída ou intersticial: native-recommendation, native-interstitial.

data.ad_items

Propriedade
Descrição

idvariation

O ID da variação.

image

A imagem original carregada para o anúncio.

url

O URL de clique.

impression

O URL de impressão.

title

O texto do título do anúncio.

description

O texto da descrição do anúncio.

brand

O texto da marca do anúncio.

original_url

O URL original da página de destino.

image_position

A posição da imagem do anúncio (como a imagem será recortada).

size

O tamanho do formato de anúncio selecionado

iframe_url

Se for usado um iframe como variação, este será o URL do iframe.

video_thumb_id

O identificador do recurso miniatura de vídeo (se presente) associado ao criativo do anúncio.

video_thumb_url

O URL do recurso miniatura de vídeo (se presente).

video_thumb_enabled

O estado do recurso miniatura de vídeo (se presente).

Exemplo de resposta de anúncios nativos

Vídeo Outstream

Propriedade
Descrição

url

O URL de clique

rastreamento

Um objeto com informações de rastreamento.

vídeo

O ficheiro do anúncio em vídeo ou o link VAST a carregar.

brandingEnabled

Sinalizador para ativar a marca. Este valor não é usado atualmente

frequencyPeriod

Com que frequência, em minutos, o anúncio é mostrado.

maximumWidth

Tamanho da largura do vídeo.

isVast

Indica se a campanha vencedora é um anúncio em vídeo normal (false) ou uma campanha com link VAST (true).

ctaEnabled

Sinalizador para exibir uma CTA no anúncio

cta

Um objeto contendo os detalhes da CTA

impression

O URL de impressão

data.tracking

Neste momento, o data.tracking objeto apenas devolve um progresso array com objetos destinados a rastrear a reprodução do vídeo. Desses objetos, aquele com "offset": "00:00:10.000" é o que deve ser chamado para registar a visualização do vídeo. As propriedades de cada objeto são explicadas abaixo:

Propriedade
Descrição

offset

Marcador de progresso em segundos ou como percentagem do anúncio em vídeo reproduzido

url

URL de rastreamento

data.cta

Propriedade
Descrição

URL de exibição

URL relacionada com a página de destino do anúncio

texto

Texto a ser usado no elemento CTA

Exemplo de resposta de vídeo Outstream

Vídeo Slider

Propriedade
Descrição

url

O URL de clique

rastreamento

Um objeto com informações de rastreamento.

vídeo

O ficheiro do anúncio em vídeo ou o link VAST a carregar.

screenDensity

Inteiro que indica a parcela do espaço máximo do ecrã ocupada pelo anúncio no dispositivo do utilizador

onComplete

Indica o comportamento do anúncio depois de o vídeo terminar de ser reproduzido. "hide" significa que o anúncio deve ser ocultado, enquanto "repeat" significa que o anúncio deve permanecer na página para permitir ao utilizador reproduzi-lo novamente

closeAfter

Indica a quantidade de segundos necessária antes de o botão de fechar ser mostrado no anúncio

brandingEnabled

Sinalizador para ativar a marca. Esta propriedade atualmente não é usada

frequencyPeriod

Com que frequência, em minutos, o anúncio é mostrado.

impression

O URL de impressão

isVast

Indica se a campanha vencedora é um anúncio em vídeo normal (false) ou uma campanha com link VAST (true).

ctaEnabled

Sinalizador para exibir uma CTA no anúncio

cta

Um objeto contendo os detalhes da CTA

data.tracking

Neste momento, o data.tracking objeto apenas devolve um progresso array com objetos destinados a rastrear a reprodução do vídeo. Desses objetos, aquele com "offset": "00:00:10.000" é o que deve ser chamado para registar a visualização do vídeo. As propriedades de cada objeto são explicadas abaixo:

Propriedade
Descrição

offset

Marcador de progresso em segundos ou como percentagem do anúncio em vídeo reproduzido

url

URL de rastreamento

data.cta

Propriedade
Descrição

URL de exibição

URL relacionada com a página de destino do anúncio

texto

Texto a ser usado no elemento CTA

Exemplo de resposta de Vídeo Slider

Interstitials de página inteira

Propriedade
Descrição

url

O URL de clique

impression

O URL de impressão

image

A imagem original carregada para o anúncio.

optimum_image

Se o criativo carregado for um GIF animado, esta é a versão MP4 otimizada dele, criada para ser usada no anúncio.

width

A largura do anúncio em pixels.

height

A altura do anúncio em pixels.

frequency_count

Quantas vezes o anúncio pode ser exibido

frequency_period

Com que frequência, em minutos, o anúncio é exibido

frequency_trigger_type

Sinalizador para indicar se a frequência deste anúncio se baseia em impressões (0) ou cliques (1)

ad_trigger_method

Método de disparo ativado para esta zona de anúncio

ad_trigger_classes

Classes que devem disparar o anúncio, se houver

first_trigger_clicks

Número de cliques necessários na visita inicial do utilizador para disparar o anúncio

next_trigger_clicks

Número de cliques necessários após o primeiro disparo do anúncio para o exibir novamente

chrome_enabled

Sinalizador para indicar se esta zona de anúncio está ativada para Chrome (1), desativada (0) ou ativada exclusivamente para este navegador (2)

capping_enabled

Sinalizador para indicar se o capping deve ser aplicado a esta zona de anúncio ou não

media

Isto mostra que tipo de banner é este: imagem, HTML ou vídeo: Deve ser img_banner, html_banner ou video_banner, respetivamente.

Nota: Nota: a maioria das propriedades da resposta do intersticial de página inteira está relacionada com o capping e o disparo do anúncio. Como é responsável por renderizar o anúncio, cabe-lhe decidir se quer ou não prestar atenção a estas propriedades.

Exemplo de resposta de intersticial de página inteira

Note que, embora o exemplo mostre um intersticial de página inteira para Desktop, a resposta para um intersticial de página inteira para Mobile deve ser a mesma, exceto por zone.type.

Push In-Page

Propriedade
Descrição

url

O URL de clique

impression

A URL de impressão

image

A imagem original carregada para o anúncio.

optimum_image

Se o criativo carregado for um GIF animado, esta é a versão MP4 otimizada dele, criada para ser usada no anúncio.

title

Título da notificação

description

Descrição da notificação

horizontal_position

Indica a posição horizontal na página (esquerda, centro, direita)

vertical_position

Indica a posição vertical na página (topo, meio, inferior)

delay

Número de segundos antes de a notificação aparecer após o carregamento da página

max_notifications_on_page

Número de notificações que podem aparecer na página ao mesmo tempo

once_closed_hide_for

Duração, em segundos, durante a qual o anúncio fica oculto depois de fechado (necessita de consentimento de cookies do utilizador)

user_session_capping

Número de vezes que o anúncio é mostrado ao utilizador (necessita de consentimento de cookies do utilizador)

delay_between_notifications

Número de segundos antes de a próxima notificação aparecer após o carregamento da anterior

Exemplo de resposta de notificação push In-Page

Multi-formato

Uma resposta para um pedido Multi-formato pode devolver resultados diferentes:

  • Se o anúncio vencedor for uma campanha Native, a resposta conterá um objeto de dados Native normal.

  • Se o anúncio vencedor for uma campanha Banner e tiver um Zona única no layout, a resposta conterá um objeto de dados Banner normal.

  • Se o anúncio vencedor for uma campanha Banner e escolheu um layout com vários anúncios, então a resposta conterá um grupo objeto com as seguintes propriedades:

Propriedade
Descrição

orientação

A orientação da disposição multi-zona, que pode ser "horizontal" ou "vertical"

ad_items

Array contendo os dados do anúncio para cada espaço no layout.

Independentemente do resultado, a propriedade multizoneid será adicionada à resposta, indicando o ID da zona do anúncio multi-formato a que esta resposta corresponde.

Exemplo de resposta multi-formato

O exemplo seguinte mostra o zonas objeto para uma zona de anúncio multi-formato com um Horizontal x 3 layout:

Anúncios de display responsivos

Alguns formatos, como Banners e intersticiais de página inteira, podem ativar Anúncios de display responsivos para receber demanda de campanhas de anúncios nativos, além da demanda dos seus formatos de anúncio originais. Nessas situações, a resposta conterá o original_zone objeto que indica o tipo e os dados do formato original.

Aqui está um exemplo de um formato de anúncio Banner:

Rastreamento de impressões

Certifique-se de fazer uma chamada GET para a URL de impressão para registar as impressões das suas solicitações de anúncios. Uma forma de conseguir isso é criar um ficheiro de imagem invisível usando a URL de impressão como origem na página onde o anúncio será exibido, por exemplo:

Última atualização

Isto foi útil?