NAV

RTB House

Introdução

Olá!
Este documento irá lhe guiar pelas melhores práticas de integração do Prebid para que possa começar a utilizar o bidder RTB House.

A RTB House oferece um trecho de código para ser inserido no cabeçalho da página, antes da chamada do Adserver.
Este código gera uma chamada assíncrona que permite a RTB House identificar o usuário e retornar uma oferta.
Essa oferta, juntamente ao valor do leilão é então enviado para o Adserver e, a partir daí, campanhas da RTB House podem ser então inicializadas de acordo com keywords customizadas

Requisitos

O que você irá receber da RTB House:

O que precisaremos que faça

Scripts de implementação

Prebid.js - adapters e módulos

Código responsável por inicializar as tags da RTB House que são parte do bundle 'prebidA.B.C.js', onde A, B e C compõem o número da versão. Além de carregar a biblioteca do Prebid e seus módulos, o código também inicializa as filas para processamento de eventos que serão usadas mais tarde.
O pacote do Prebid.js irá conter todos os bidders e módulos em um único arquivo JS, e pode ser customizado e baixado em:


URL: http://prebid.org/download.html


Para esse setup em particular, teremos:

Adapters de Bidders:

Adapters de Analytics:

Módulos:

Note que a request de carregamento é assíncrona e cacheada no browser do usuário.
Além da versão do pacote prebid.js, nenhuma mudança no código é necessária nesta seção.

O próximo passo é mapear todos os adunits disponíveis na página e atribuir seus códigos.
Nesta seção você verá como um adunit de display simples é configurado.

Parâmetro Descrição
code Identificador único que você pode criar e atribuir a um adunit. Usado para definir a query string para o anúncio em questão. Se estiver usando GPT, recomendamos definir um identificador similar para o ID do slot.
mediaTypes banner, native ou video
banner.sizes Aqui você pode definir os tamanhos aceitos para o adunit.
bidder Obrigatório, nome do bidder - "rtbhouse"
params.region Obrigatório, tipo: string, região atribuída pelo time de Inventário da RTB House à um publisher específico (-eu, -asia, -us).
params.publisherId Obrigatório, tipo: string, ID definido pelo time de Inventário da RTB House.
params.bidfloor Opcional, tipo: float, Valor de CPM mínimo na moeda definida (por padrão, USD)
URL: http://prebid.org/dev-docs/bidders/rtbhouse.html

Detalhes sobre resposta do servidor

Caso a RTB House tenha uma oferta para o usuário, a requisição ira receber um retorno HTTP STATUS 200 com um vetor de objetos bids conforme descrito a seguir:

Atributo Tipo Descrição Exemplo
id String O adunit enviado na request ad-unit-0
impid String O identificador único da impressão 1958db31f122811
price Float O CPM para a oferta 1.58
adid String o identificador único do creative l2HjtZ8tLkRPAaeVkRk0
adm String O iframe do creative <iframe src=\"https://sin.creativecdn.com/imp-delivery?tkn=EdN...>
adomain Lista de Strings O domínio ["rtbhouse.com"]
cid String O identificador único do deal ...z3XR2NmqbMmZl...
w Integer A largura do creative 300
h Integer A altura do creative 250

A seguir, um exemplo do objeto:

Caso o usuário não seja elegível a nenhuma campanha da RTB House, a resposta será vazia, com código 204.

Implementação no cabeçalho

Desativando o carregamento automático do adserver

As tags originais do AdManager são similares ao descrito a seguir:

Como queremos esperar a chamada para RTB House antes de chamar o Adserver, as funções googletag.pubads().disableInitialLoad() e googletag.pubads().enableSingleRequest(), podem ser definidas em qualquer lugar do código antes de googletag.enableServices(). Vale ressaltar a importancia de incluir o caminho "/CodigoDaRede/CodigoAdUnit/Label" como primeiro parâmetro no método .defineSlot

A função de callback é executada assim que o a resposta é recebida e, em seguida, devem ser processar e enviadas na request para o Adserver. Os exemplos a seguir irão utilizar o Google DFP/AdManager como referencia, mas pode ser adaptado para qualquer Adserver que suporte o mecanismo de seleção de campanhas por keywords.

A chamada do adserver deve aguardar a resposta do bidder RTB House, e isso pode ser alcançado pela combinação de duas funções:

Mais detalhes na documentação do DFP.

Enviando as keywords

Primeiro, devemos inicializar os adunits, depois, implementar a função para inicializar o Adserver. Para isso, podemos usar: pbjs.setTargetingForGPTAsync && pbjs.setTargetingForGPTAsync(); - parte onde incluiremos as keywords da RTB House na chamada do Adserver
googletag.pubads().refresh(); - parte que irá inicializar a chamada para o Adserver

A chamada para o adserver pode ser implementada na função de callback que será disparada assim que a resposta da RTB House for recebida (ou após o timeout). No exemplo anterior usamos a função de nome initAdserver para isso.

Keyword Tipo Descrição Exemplo
hb_pb String A faixa de CPM vencedora hb_pb=0.40
hb_pb_rtbhouse String (opcional) A faixa de CPM ofertada pela RTB House hb_pb_rtbhouse=0.40
hb_bidder String (opcional) O bidder vencedor hb_bidder=rtbhouse

A tabela a seguir apresenta duas maneiras de se configurar keywords:

Módulos do Prebid

Nesta seção módulos adicionais serão descritos. Todos os módulos serão definidos em pbjs.setConfig({})

Módulo de currency (moeda)

Esse módulo permite a conversão de múltiplas moedas de diferentes bidders em uma única moeda utilizada pelo Adserver. O módulo também cobre a atualização automática baseada na flutuação das moedas. O seu funcionamento é descrito a seguir:


O módulo de currency pode ser utilizado para converter a moeda entre adserver e bidder. Se nenhum outro script estiver fazendo essas conversões, é altamente recomendável o uso do módulo de currency.

Parâmetro Tipo Descrição
priceGranularity Dicionário/String Define qual granularidade monetária a ser trabalhada no leilão. Valores aceitos são: "low, "med", "high"m "auto", "dense". Descrição detalhada
currency.adServerCurrency String Código do país no padrão de 3 letras ISO 4217. Se o valor estiver presente, o conversor de moeda é ativado.
currency.granularityMultiplier Decimal Quanto escalar os cálculos de granularidade. 1 é o valor padrão. É utilizado por moedas que estão em razões distantes, como por exemplo YEN para USD [110:1]
currency.defaultRates Object Parâmetro opcional que define o valor padrão de conversão a ser usadoo caso o módulo de currency não possa ser carregado. Essa opção é ignorada caso o parâmetro "rates" seja configurado. Examplo de definição: { USD: { PLN: 4 } }
currency.rates Object Esse parâmetro opcional permite que especifique taxas de conversão de moeda usando um objeto JSON. Quando utilizado, o módulo de currency não é carregado. Exemplo: { ‘USD’: { ‘CNY’: 6.8842, ‘GBP’: 0.7798, ‘JPY’: 110.49 } }
currency.conversionRateFile URL Parâmetro opcional com o caminho para um arquivo contendo informações de conversão de moeda. O Prebid.org hospeda um arquivo conforme descrito na próxima seção.

A seguir você encontra um exemplo de conversão para Google AdManager usando a moeda PLN:

URL: http://prebid.org/dev-docs/modules/currency.html

Módulo de Consent Management

O módulo de Consent Management foi desenhado para suportar a General Data Protection Regulation (GDPR/Europa) e a California Consumer Privacy Act (CCPA/Estados Unidos). Vale notar que a IAB generalizou as orientações de maneira a cobrir regulamentações futuras, chamando o conjunto de "US Privacy".
O módulo trabalha com Plataformas de Gestão de Consentimento (CMPs em inglês) buscando uma string codificada que representa as escolhas de consentimento do usuário e então repassa para os adapters consumirem durante o processo de leilão. Para utiliza-lo, é necessário implantar uma CMP compatível com a especificação IAB 1.1 TCF e permitir sua interação com usuário para coletar as definições de consentimento. Nós recomendamos que coloque a implementação da CMP antes do código do Prebid.js, no cabeçalho da página, de maneira a garantir que a ferramenta seja carregada antes da execução do Prebid.

Parâmetro Tipo Descrição
cmpApi String Definido por padrão como 'iab' ou 'static' para integrações fora do padrão IAB
timeout Integer Timeout de resposta da CMP, 5000ms por padrão
allowAuctionWithoutConsent Boolean Define o que ocorre em caso de falha na obtenção das informações de consentimento com o CMP. Caso "false" o leilão é cancelado. O exemplo a seguir não é conectado a nenhuma CMP e, portanto, o valor é definido como "true"
usp.timeout Integer O timeout para a política US Privacy. 100ms por padrão.

Publishers que não estão usando uma CMP em conformidade com a IAB - por favor acesse a URL a seguir:

URL: http://prebid.org/dev-docs/modules/consentManagement.html

Módulo User ID: PubCommon ID

O módulo de User ID armazena um ID de usuário único em um domínio primário e o torna acessível a todos os adapters. Similar ao IDFA e AAID, o User ID é um UUID simples, leve e auto-contido que pode ser utilizado para melhorar a identificação de usuários, principalmente em browsers iOS e MacOs, e é compatível com ITP (Intelligent Tracking Prevention). Adapters que suportam o Publisher Common ID são capaz de extrair o identificador e enviar para o servidor, permitindo o mapeamento do usuário em diversos dispositivos. Não é necessário nenhuma configuração ou cadastro especial para o PubCommon ID, cabendo a você levar o módulo dem configuração enquanto prepara sua política de privacidade.

Parâmetro Tipo Descrição
storage Object Você pode especificar um storage (seja o local storage do HTML5 ou um cookie) para armazenar o resultado das chamadas que buscam o user ID.Isso não é necessário quando o atributo value é especificado ou o sistema de ID está gerenciando o seu próprio storage.
storage.type String Obrigatório, "cookie" ou "html5"
storage.name String O nome do cookie ou entrada do local storage em que o usuário será armazenado
storage.expires Integer Por quanto tempo o ID será armazenado
storage.refreshInSeconds Integer O tempo (em segundo) que o ID pode ser cacheado no storage antes de verificar por um valor atualizado. Se definido, pode receber qualquer valor menor que o número de dias definido em storage.expires. Por padrão, não é buscado atualizações até que se expire
value Object Use apenas se a página possuir um mecanismo separado para armazenar o ID. Recebe um objeto contendo as informações que serão enviadas aos adapters
URL: http://prebid.org/dev-docs/modules/userId.html#pubcommon-id

Configuração do AdServer

Configurar um adserver para utilização do Prebid requer 5 passos. São eles:

Nota: para o detalhamento dos passos a seguir consideraremos a versão em Inglês do AdServer Google AdManager.

Key/values

Vá até Inventory > Key-values, clique em New Key e defina como a seguir:

DFP keywords

Order

Va até Delivery > Orders e clique em New Order. Preencha com os dados solicitados para definir a primeira order da campanha.

DFP keywords

Primeiro Line item

Você pode criar o primeiro line item na mesma página ou simplesmente entrando em qualquer order criada. O objetivo é criar um line item para cada faixa de preço diferente. Para melhor performance, recomendamos que crie um a cada centavo.

Nós iremos definir um CPM único para o primeiro line item:

Line items

Line items

Line items

Line items

Por fim, selecione o inventário para a campanha e inclua os seguintes critérios de ativação:

Line items

Finalize clicando em save e siga os passos a seguir para definição do creative:

Creatives

Por favor, observe a seguir um exemplo de creative:



Para criar um novo creative, entre em Delivery > Creatives > e clique em Add creative . Em seguida, digite e selecione o mesmo nome de anunciante para adicionar o creative (no exemplo, Prebid (Anunciante)). Clique em "Select" e defina:

Clique em Save.

Volte ao primeiro line item, clique na aba Creatives e em seguida Add creative - Existing creative.

Selecione o creative que acabou de criar.

O último passo é duplicar o creative para que sua quantidade equivalha ao número de ad units únicos que você tem na pagina. Exemplo: Caso uma página possua 5 posições de anúncio, você deve possuir ao menos 5 creatives no seu line item.

A maneira mais simples de alcançar o resultado é selecionar um ou mais creatives e clicar em Copy creative, repetindo até atingir o mínimo desejado.

Demais line items

Agora que você tem o primeiro line item configurado, você pode duplica-lo e reutilizar os creatives existentes. Para fazer isso, vá a página de line items, selecione o criado e clique no botão Copy and share creatives que irá aparecer na barra azul. Repita para as diferentes faixas de preço que possuir.

Por favor não esqueça de atualizar:

Você pode alterar esses valores diretamente pela página que lista os line items, clicando no icone ao canto de cada campo:

Line items

Quando terminar, selecione todos os line items e clique em Resume.

Para acessar o guia oficial do prebid: URL: http://prebid.org/adops/step-by-step.html

Criação automática de line items

A RTB House pode auxiliar com a criação automática de todos os line items e creatives usando nossa Ferramenta de Criação de Line items.
Por favor entre em contato com nosso time Inventory Support inventory_support@rtbhouse.com para entender como prosseguir.

Anúncios Native

Placement de native

Para ativar a demanda de Native, você deve primeiro declarar o ad unit apropriado. Um pequeno exemplo demostrando como defini-lo é demonstrado a seguir:

Todos os outros parâmetros que podem ser utilizados e integrados ao native podem ser encontrados em:
URL: http://prebid.org/dev-docs/show-native-ads.html

Objeto native

A seguir, você encontra um exemplo de resposta contendo um native:



Quando uma demanda estiver disponível, a RTB House irá retornar um objeto native com a seguinte estrutura:

Objeto Native

Atributo Tipo Descrição
product Vetor de objetos produto Lista de assets do produto
advertiser Objeto Advertiser Inclui o nome e logo do anunciante
impression_pixels Vetor de pixels de impressão Uma lista com pixels de impressão

Objeto Product

Atributo Tipo Descrição
title String Título do produto
description String Descriçaõ do produto
click_url String Landing page do produto
call_to_action String Chamada do produto
image Objeto Image Imagem do produto (LarguraxAltura em px)

Objeto Image

Atributo Tipo Descrição
url String URL da imagem
height Integer Altura da imagem
width Integer Largura da imagem

Objeto Advertiser

Atributo Tipo Descrição
description String Nome do anunciante
domain String Website do anunciante
logo Objeto Image Logo do anunciante (LarguraxAltura px)

Objeto Privacy

Atributo Tipo Descrição
optout_click_url String URL da página de Opt-out
optout_image_url String URL do ícone de Adchoices

Objeto Pixels de Impressão

Atributo Tipo Descrição
url String URL de disparo do pixel de impressão

Integração no AdServer

As campanhas de native podem ser configuradas da mesma forma que anúncios padrão, apenas mudando a definição de tamanhos no ad unit para 1x1 e "fluid". A seguir você pode conferir um exemplo da estrutura de um criativo native:



Orientações gerais para natives RTB House:

Exemplos completos

Você pode encontrar um exemplo funcional de banners display e native nesta página.
Observe o código fonte proximo ao texto:
<!-- RTB House bidder -->

Demais exemplos podem ser encontrados em:



Caso deseje incluir A RTB House no seu ads.txt, por favor use a linha:

RTBHOUSE.COM, {PUBLISHER ID}, DIRECT

Substitua {PUBLISHER ID} pelo identificador entregue pela RTB House