Guia de integração do Vungle OpenRTB 2.3

Essa é a versão 2.1.0 (agosto de 2017) do Guia de integração do Vungle OpenRTB 2.3. Este artigo especifica os detalhes da integração com o Vungle Exchange usando o OpenRTB 2.3.

Conteúdo

1. Solicitação e resposta

1.1 Entidade

Todas as entidades nesta seção são um subconjunto das especificações OpenRTB 2.3.1. Se faltarem campos ou requisitos, use os requisitos padrão da especificação.

1.2 Extensão

Para melhor atender a um anúncio, o Vungle Exchange fornece informações além do protocolo OpenRTB padrão. Essas extensões não se sobrepõem a, elas complementam, a implementação OpenRTB existente. As extensões são divididas em objetos individuais quando isso faz sentido.

Todos os campos de extensão são encapsulados em um objeto JSON por um campo de extensão de primeiro nível chamado 'vungle' abaixo do objeto OpenRTB 'ext'. Para simplificar, a documentação nas seções seguintes deste documento omitem o campo 'vungle'. A seguir, uma amostra de um objeto OpenRTB JSON contendo extensões Vungle:

{
...
"ext": {
"vungle": {
// Campos de extensão individuais nas diversas linhas abaixo.
}
}
}

Por exemplo, um objeto de solicitação de proposta de alto nível seria algo assim:

{
"id": "572c3535ab0af400011a721a",
"imp": [{<impression object>}],
"app": {<application object>},
"device": {<device object>},
"user": {<user object>},
"at": 2,
"tmax": 2000,
"cur": ["USD"],
"bcat": ["IAB7-3"],
"badv": ["google.com"],
"ext": {
"vungle": {
"badvid": ["2f00ca35ab0abe4df11da700c"]
}
}
}

1.3 Controle de versão

Com o tempo, alguns campos ficam obsoletos. Logo, para garantir a máxima compatibilidade, o Vungle Exchange respeitará todos os campos "obsoletos" especificados na especificação mais recente do Vungle OpenRTB. Todos os campos "obsoletos" são programados para remoção na próxima atualização de especificação, e então o Vungle Exchange não terá mais a responsabilidade de manter campos obsoletos.

Todos os campos removidos permanecerão na especificação com uma marcação "excluído" para indicar que o campo não é mais suportado. Usamos a marcação "excluído" para garantir uma semântica da especificação: Cada campo, após definido, permanece único no âmbito em que foi definido por toda a duração da especificação. Isso quer dizer que se o campo 'id' tornar-se obsoleto e for removido em determinada especificação, ele nunca voltará em uma revisão futura, com outro significado.

1.3.1 Controle de versão semântico

O Controle de versão de especificação também obedece às Orientações Semver 2.0.0, que são:

  • Uma atualização de versão de número inteiro pode impedir a compatibilidade com versões anteriores. Por exemplo, um campo "obsoleto" na versão X será "removido" na versão X+1.
  • Uma atualização de versão (depois do ponto) não impedirá a compatibilidade com versões anteriores. Por exemplo, um campo em uso sendo marcado como "obsoleto" ou um campo obrigatório marcado como não obrigatório e obsoleto.
  • Um patch de atualização da versão não deve impedir a compatibilidade com versões anteriores. Por exemplo, uma correção ortográfica na descrição da especificação.

1. Solicitação

2.1 Campos obrigatórios e opcionais

Notas sobre a coluna Obrigatório nas seções seguintes:

  • Sim: o uso "adiante" desse campo sempre pode esperar um valor corretamente formatado, não vazio, com base no tipo especificado.
  • Não: o uso "adiante" não deve esperar a existência desse campo, ou a validade do valor. É necessária a validação do valor pelo cliente, desnecessária para o tipo.
  • Padrão: todos os campos não mencionados no OpenRTB 2.3.1 assumem por padrão não obrigatório.

2.2 Negociação de protocolo

O Vungle Exchange suporta a comunicação negociada via protocolo HTTP/2 Se não, o padrão é HTTP/1.1.

2.3 Cabeçalhos de solicitação

Cada solicitação de proposta terá os seguintes cabeçalhos HTTP personalizados, conforme especificado pelo protocolo OpenRTB:

X-OpenRTB-Version: 2.3

Além dos cabeçalhos HTTP personalizados, o Vungle Exchange também anexa os seguintes cabeçalhos padrão:

Content-Type: application/json; charset=utf-8
Accept: application/json 

Finalmente, o Vungle Exchange anexa um cabeçalho personalizado para indicar a revisão de especificação do Vungle OpenRTB:

X-Vungle-OpenRTB-Version: 2

2.4 Objeto BidRequest

Campo Tipo Obrigatório Descrição
id string sim

O ID de solicitação de proposta é gerado pelo Vungle Exchange. Por exemplo, '570b0eb14e67c98f761a0ca0'.

imp

matriz do objeto

sim Veja o objeto Impressão.
app objeto sim Veja o objeto Aplicação.
device objeto sim Veja o objeto Dispositivo.
at inteiro sim

Tipo de leilão. Por exemplo, '2' pelo leilão do segundo preço. O Vungle Exchange só executa leilões de segundo preço, então esse valor é sempre '2'.

tmax inteiro sim

Tempo máximo em milissegundos para enviar uma resposta completa de proposta. Esse valor é sempre '250'.

cur matriz de strings não

Lista das moedas permitidas para o leilão em ISO-4217-alpha. Por exemplo, ["USD", "CNY", "EUR"]. Atualmente só suportamos "USD".

bcat matriz de strings não Consulte, no OpenRTB 2.3.1, a seção 5.1.
regs objeto não Consulte, no OpenRTB 2.3.1, a seção 3.2.16.
test inteiro não

Quer o leilão esteja em modo de teste (1) ou ativo (0), os leilões de teste não são faturáveis.

2.4.1 Objeto Impressão

Campo Tipo Obrigatório Descrição
id string sim O ID de impressão é gerado pelo Vungle Exchange. Por exemplo, '3a06eb14e67c98f761add01'.
displaymanager string sim Gerente de exibição para lado fornecedor. O Vungle usa esse campo para especificar a tecnologia de SDK utilizada, porque diferenciamos os SDK para plataformas móveis. Por exemplo, 'Vungle' for iOS, 'VungleDroid' for Android, and 'VungleWindows' para Windows, com a versão do SDK no campo seguinte.
displaymanagerserver string sim Versão do gerente de exibição para lado fornecedor. O Vungle usa isso para especificar a versão do SDK. Por exemplo, '3.3.1'.
bidfloor flutuante sim Preço mínimo aceito para a proposta, por exemplo, '8.72'.
bidfloorcur string sim Moedas para a impressão em ISO-4217-alpha. Por exemplo, 'USD'.
video objeto não Veja o objeto Vídeo.
tagid string não ID de referência de posicionamento correspondente a determinada impressão, por exemplo, 'placement_name_1af44fda'.
instl inteiro não Quer a impressão represente tela cheia/intersticial (1), ou não (0). Atualmente, o Vungle Exchange suporta apenas tela cheia/intersticial (1).
secure inteiro não Sinalizador para indicar se a impressão exige um URL HTTPS protegido, ativos criativos e marcação, onde 0 = desprotegido e 1 = protegido.
ext objeto não O Vungle sempre exige ativos e marcação protegidos (1).

2.4.2 Objeto Vídeo

Campo Tipo Obrigatório Descrição
mimes matriz de strings sim Tipos de conteúdo MIME suportados. O Vungle Exchange só suporta ["video/mp4"].
h inteiro sim Altura do vídeo.
w inteiro sim Largura do vídeo.
minduration inteiro não Número mínimo de segundos de reprodução do vídeo.
maxduration inteiro não Número máximo de segundos de reprodução do vídeo.
delivery matriz de inteiros não Lista dos métodos de envio de vídeo suportados: (progressivo ou streaming). Consulte, no OpenRTB 2.3.1, a seção 5.13.
minbitrate inteiro não Taxa mínima de bits em kbps. Atualmente o Vungle Exchange só suporta 250.
maxbitrate inteiro não Taxa máxima de bits em kbps, por exemplo, 500.
protocols matriz de inteiros não Consulte, no OpenRTB 2.3.1, a seção 5.8, por exemplo, [2, 5].
boxingallowed inteiro não Se é permitido (1) enquadrar o vídeo ou não (0). Esse valor sempre é '1'.
playbackmethod matriz de inteiros não Consulte, no OpenRTB 2.3.1, a seção 5.9.
startdelay inteiro não Consulte, no OpenRTB 2.3.1, a seção 5.10. Esse valor sempre é '0'.

2.4.3 Objeto Aplicativo

Campo Tipo Obrigatório Descrição
id string sim ID específico do Exchange. Para o Vungle, é o ID na loja de aplicativos, por exemplo, '3709293'.
Esse ID pode não ter significado para o DSP, mas pode ser usado pelo DSP para comparar e reconciliar divergências de relatórios.
bundle string sim O ID de mercado específico, é um identificador do aplicativo específico da plataforma que deve ser exclusivo do aplicativo e independente do Vungle Exchange.
- No Android, isso deve ser um nome de grupo ou pacote (por exemplo, 'com.supercell.hayday').
- No iOS, é um ID numérico.
publisher objeto sim Veja o objeto Editor.
name string não Nome do aplicativo, por exemplo, 'Hay Day'.
storeurl string não URL da loja de aplicativos, por exemplo, 'https://itunes.apple.com/us/app/hay-day/id506627515?mt=8#'.
cat matriz de strings não Consulte, no OpenRTB 2.3.1, a seção 5.1.
privacypolicy inteiro não Se o aplicativo te uma política de privacidade (1) ou não (0). O Vungle Exchange só suporta '1' para esse campo.
paid inteiro não Se o aplicativo é pago (1) ou não (0).
keywords string não Lista de tags separados por vírgula para o aplicativo do editor.
ext objeto não DESCRIÇÃO

2.4.4 Extensão do aplicativo

Campo Tipo Obrigatório Descrição
altid string não Um ID secundário específico do Vungle Exchange que identifica exclusivamente o aplicativo do editor, por exemplo, '3a06eb14e67c98f761add01'.
sdk objeto não Veja o objeto Extensão SDK.
wtags matriz de strings não Lista de permissões (whitelist) de tags do aplicativo do editor.
btags matriz de strings não Lista de negações (blacklist) de tags do aplicativo do editor.
bundleid string não Identificador de grupo ou nome de pacote do aplicativo.
tags matriz de strings não Obsoleto, use palavras-chave.

2.4.5 Extensão SDK

Campo Tipo Obrigatório Descrição
name string sim Uma string que identifica uma família do SDK do agente do SDK instalado no aplicativo host. Por exemplo, 'VungleDroid', 'Vungle' ou 'VungleWindows'
ver string sim Uma string que descreve a versão do agente do SDK instalado no aplicativo host.
plugin string não Nome do plugin SDK que criou o agente SDK, por exemplo, 'native', 'unity'.
pluginver string não Versão do plugin SDK que criou o agente SDK, por exemplo, '1.0'.

2.4.6 Objeto Editor

Campo Tipo Obrigatório Descrição
id string sim ID do editor gerado pelo Vungle Exchange. Por exemplo, '570ffeb14e67998f761a791c'.
name string não Nome do editor, por exemplo, 'Supercell Oy'.
cat matriz de strings não Consulte, no OpenRTB 2.3.1, a seção 5.1.

2.4.7 Objeto Dispositivo

Campo Tipo Obrigatório Descrição
ua string sim String do agente de usuário do navegador do dispositivo, por exemplo 'Mozilla/5.0 (iPhone; CPU iPhone OS 9_1 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13B143 Safari/601.1'.
ip string sim Não é obrigatório quando o campo ipv6 existe. Esse é o endereço IP da impressão. Por exemplo, '212.14.27.104'.
ipv6 string sim Não é obrigatório quando o campo ip existe. É o endereço IPv6 da impressão. Por exemplo, '3ffe:1900:4545:3:200:f8ff:fe21:67cf'.
h inteiro sim Altura da tela do dispositivo em pixels.
w inteiro sim Largura da tela do dispositivo em pixels.
connectiontype string sim Consulte, no OpenRTB 2.3.1, a seção 5.18.
ifa string sim ID sancionado para uso do anunciante em texto não criptografado, por exemplo, 'e4fe9bdecaa047b6908dffba3fa184f2'.
geo objeto não Veja o objeto Geo.
make string não Fabricante do dispositivo.
model string não Modelo do dispositivo.
os string não SO do dispositivo, por exemplo, 'iOS', 'Android'. Valor de enum de:
- 'iOS'
- 'Android'
- 'Windows'
osv string não Versão do SO do dispositivo, por exemplo, '9.1', '8.0'.
dnt inteiro não Se o dispositivo especifica "Não rastrear" (1) ou não (0).
lmt inteiro não Se o dispositivo especifica "Rastreamento de anúncio limitado" (1) ou não (0).
devicetype string não Consulte, no OpenRTB 2.3.1, a seção 5.17.
language string não Idioma do dispositivo em ISO-639-1-alpha-2, por exemplo, 'en'.
carrier string não Operadora ou provedor de internet, por exemplo, 'VERIZON'.
ext objeto não Veja o objeto Extensão do dispositivo.

2.4.8 Extensão do dispositivo

Campo Tipo Obrigatório Descrição
tz string não Configurações de fuso horário do dispositivo formatadas como nome da zona no banco de dados de fuso horário IANA, por exemplo, 'America/Los_Angeles'.
vungleua string não Obsoleto: use Application.ext.vungle.sdk
sdcard inteiro não Se o armazenamento em cartão SD está disponível em dispositivos Android (1) ou não (0).
volume flutuante não Valor de 0 a 1 indicando o volume porcentual do dispositivo.
muted inteiro não 0 = false 1 = true. É necessária a enumeração.
idfv string não

ID do fornecedor em dispositivos iOS, uma string alfanumérica que identifica exclusivamente um dispositivo junto ao fornecedor do aplicativo, por exemplo, '00000000-0001-4d3a-8f98-233623cd8d12'.

O mesmo dispositivo pode conter diferentes valores de IDFV, dependendo se o aplicativo na solicitação de proposta pertence a outro fornecedor.

marketplace string não

O mercado de aplicativos instalado no dispositivo. Os valores possíveis são:

  • 'google'
  • 'apple'
  • 'amazon'
is_sideload_enabled inteiro não Flag booliana indicando se o dispositivo permite instalação de aplicativos de fontes "desconhecidas". Se for '1' (true), permite aplicativos de mercados desconhecidos. Se for '0' (false), não permite.

2.4.9 Objeto Geo

Campo Tipo Obrigatório Descrição
country string sim Código do país do dispositivo em ISO-3166-1-alpha-3, por exemplo, 'USA'.
lat flutuante não Latitude do dispositivo, por exemplo, '[-90, 90]'.
long flutuante não Longitude do dispositivo, por exemplo, '[-180, 180]'.
type inteiro não Consulte, no OpenRTB 2.3.1, a seção 5.16.
region string não Código de região em ISO-3166-2. Sigla de duas letras do estado se for nos EUA, por exemplo, 'CA'.
city string não Nome da cidade sem formatação.
zip string não CEP.
utcoffset inteiro não Hora local como +/- o número de minutos da UTC.

2.4.10 Objeto Regs

Campo Tipo Obrigatório Descrição
coppa inteiro não Flag que indica se essa solicitação está sujeita às regulamentações COPPA estabelecidas pela FTC dos EUA, onde 0 = não e 1 = sim.
ext objeto não Espaço reservado para extensões específicas do Vungle Exchange para o OpenRTB.

2.4.11 Objeto PMP

Campo Tipo Obrigatório Descrição
private_auction inteiro não Indicador de qualificação para leilão para posições indicadas no objeto Transação direta, onde 0 = todas as ofertas são aceitas, 1 = as ofertas são restritas às transações especificadas e aos respectivos termos.
deal matriz do objeto não Objetos de matriz de transação (Seção 3.2.18) que transportam as transações específicas aplicáveis a essa impressão.
ext objeto não Espaço reservado para extensões específicas do Vungle Exchange para o OpenRTB.

3. Resposta

3.1 Campos obrigatórios e opcionais

Notas sobre a coluna Obrigatório na seção Resposta:

  • Sim: o Vungle Exchange assume que um campo obrigatório estará sempre formatado conforme especificado, não vazio, com o tipo especificado, pois valores inválidos podem resultar em desqualificação para o leilão.
  • Recomendado: o Vungle Exchange usará o campo para auxiliar no processo de leilão se o valor do campo estiver com a formatação especificada. Um campo ausente ou inválido não prejudica a qualificação para o leilão.
  • Não: o Vungle Exchange não exige que os campos existam.
  • Padrão: todos os campos não mencionados no OpenRTB 2.3.1 assumem um requisito padrão 'Não'. Além disso, todos os campos devem corresponder ao tipo especificado, ou podem prejudicar a qualificação para o leilão.

3.2 Cabeçalhos de resposta

Os cabeçalhos de resposta devem conter o cabeçalho "Tipo de conteúdo" com um dos valores aceitos dos cabeçalhos de solicitação acima. Por exemplo,

Content-Type: application/json 

3.3 Código de status da resposta

Todas as respostas devem ser 200 ou 204. Qualquer outro código de resposta HTTP pode prejudicar a qualificação para o leilão do DSP.

3.4 Sinalização de motivo de Sem proposta

Os DSPs devem enviar motivos de Sem proposta quando resolverem não enviar propostas. Essa informação pode ajudar o Vungle Exchange a detectar e corrigir potenciais problemas de integração. A Sinalização de Sem proposta deve obedecer à especificação OpenRTB 2.3.1, seção 7.4. Uma sinalização de Sem proposta bem formatada incluindo o motivo da não proposta deve ser assim:


{"id": "1234567890", "seatbid": [], "nbr": 2}

3.5 Objeto BidResponse

Campo Tipo Obrigatório Descrição
id string sim O ID BidRequest é gerado pelo Vungle Exchange. Por exemplo, '570ffeb14e67998f761a791c'. Ele deve corresponder ao ID no objeto BidRequest.
bidid string não Um ID de resposta exclusivo gerado pelo proponente para auxiliar no registro e rastreamento.
cur string não Moeda da proposta usando códigos alfa da ISO-4217. O Vungle Exchange atualmente suporta apenas USD e considera qualquer valor como USD.
seatbid matriz do objeto sim Matriz de objetos seatbid. Deve ser 1 ou mais para fazer uma proposta.
nbr inteiro não Um motivo para não haver proposta, conforme a lista na seção 5.19 de especificação OpenRTB 2.3.1.
ext objeto não  

3.5.1 Objeto SeatBid

Campo Tipo Obrigatório Descrição
seat string não ID da posição do proponente para o qual está sendo feita essa proposta. Consulte o OpenRTB 2.3.1.
bid matriz do objeto sim Veja o objeto Bid. Deve existir pelo menos uma proposta.


3.5.2 Objeto Bid

Campo Tipo Obrigatório Descrição
id string sim ID da proposta gerado por DSPs individuais.
impid string sim ID da impressão em relação à impressão da solicitação da proposta para a qual se faz uma proposta. Ele deve corresponder ao ID no objeto Impressão de solicitação de proposta.
price flutuante sim Preço da proposta expresso na unidade de CPM. Por exemplo, '10.30'.
nurl string não URL de notificação de vencedor chamado pelo Vungle Exchange se a proposta for a vencedora.
adm string sim Marcação do anúncio para atender após o leilão do vencedor. Veja a seção Especificação de marcação de anúncio.
cid string recomendado ID da campanha com proxy do DSP.
crid string recomendado ID de criativo com proxy do DSP.
adomain matriz de strings recomendado Domínios do anunciante para verificação de lista em bloco. Por exemplo, ["supercell.com"].
bundle string recomendado O ID de mercado específico, é um identificador do aplicativo específico da plataforma que deve ser exclusivo do aplicativo e independente do Vungle Exchange.
- No Android, isso deve ser um nome de grupo ou pacote (por exemplo, 'com.supercell.hayday').
- No iOS, é um ID numérico.
h inteiro recomendado Altura do criativo.
w inteiro recomendado Largura do criativo.
cat matriz de strings não Categorias de conteúdo IAB, consulte, no OpenRTB 2.3.1, a seção 5.1.
iurl string não URL de notificação perdida.
dealid string não Referência ao deal.id do objeto BidRequest se essa proposta pertencer a uma transação direta de mercado privado.
adid string não ID de um anúncio previamente carregado a ser enviado se a proposta vencer.
ext objeto não  

4. Exemplos:

4.1 Exemplo de solicitação


{
    "id": "58ed309efa8936087efd1349",
    "imp": [{
        "id": "58ed309efa8936087efd134a",
        "video": {
            "mimes": ["video/mp4"],
            "minduration": 5,
            "maxduration": 30,
            "protocols": [2, 5],
            "w": 1080,
            "h": 1920,
            "startdelay": 0,
            "linearity": 1,
            "minbitrate": 250,
            "maxbitrate": 2500,
            "boxingallowed": 1,
            "playbackmethod": [1, 2, 3, 4],
            "delivery": [1, 2],
            "pos": 7
        },
        "displaymanager": "Vungle",
        "displaymanagerver": "3.3.5",
        "instl": 1,
        "bidfloor": 15,
        "bidfloorcur": "USD"
    }],
    "app": {
        "id": "56b8e577819502560b000033",
        "name": "test-pub-app-name",
        "bundle": "1045826890",
        "storeurl": "https://itunes.apple.com/us/app/id1234567?mt=8",
        "cat": [
            "IAB1"
        ],
        "privacypolicy": 1,
        "publisher": {
            "id": "test-pub-app-id",
            "name": "test-pub-app-name",
            "cat": [
                "IAB1"
            ]
        },
        "ext": {
            "vungle": {
                "altid": "5fff577819502560b000033",
                "btags": ["real money gambling", "social casino"],
                "wtags": ["targeted tag", "social"]
            }
        }
    },
    "device": {
        "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 8_4 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Mobile/12H141",
        "geo": {
            "lat": 47.46,
            "lon": -122.16,
            "type": 1,
            "country": "USA",
            "region": "WA",
            "city": "San Francisco",
            "zip": "94103"
        },
        "dnt": 0,
        "lmt": 0,
        "ip": "192.168.1.1",
        "devicetype": 1,
        "make": "Samsung",
        "model": "SM-J200G",
        "connectiontype": 2,
        "os": "iOS",
        "osv": "8.0",
        "w": 1080,
        "h": 1920,
        "js": 1,
        "language": "en",
        "ifa": "test-ifa",
        "ext": {
            "vungle": {
                "isSdCardAvailable": 1,
                "vungleua": "VungleDroid/3.3.5",
                "tz": "Europe/Kaliningrad",
                "sdcard": 1,
                "volume": 0.13333334,
                "muted": 1
            }
        }
    },
    "bcat": ["IAB7-3", "IAB7-5", "IAB7-28", "IAB7-29", "IAB7-30", "IAB7-39", "IAB7-41", "IAB7-42"],
    "at": 2,
    "cur": ["USD"],
    "tmax": 250
}

4.2 Exemplo de resposta


{
  "id": "58ed309efa8936087efd1349",
  "bidid": "5508",
  "cur": "USD",
  "seatbid": [
    {
      "seat": "7735",
      "bid": [
        {
          "id": "5508",
          "impid": "58ed309efa8936087efd134a",
          "price": 50,
          "nurl": "http://bidder.com/won?price=${AUCTION_PRICE}",
          "adm": "http://bidder.com/vast?id=${AUCTION_ID}",
          "cid": "554d550b418461cc3700014d",
          "crid": "57767c29a63510e75f000073"
        }
      ]
    }
  ]
}

5. Especificação de marcação de anúncio

O Vungle Exchange suporta principalmente três tipos de marcações: VAST, MRAID e a marcação de anúncio proprietária Vungle. Embora cada uma tenha sua especificação de alto nível, para ser considerada uma marcação válida por questões de desempenho, ela também deve atender aos requisitos adicionais abaixo.

5.1 VAST

A tag a seguir deve aparecer nos primeiros 100 bytes do campo 'adm' ou na carga de trabalho da resposta 'nurl':

<VAST version="2.0">

5.2 Substituição de macro

O Vungle Exchange suporta uma substituição de macro para o preço do leilão no campo nurl do objeto Bid na resposta da proposta. Por exemplo:


"nurl": "http://bidder.com/won?price=${AUCTION_PRICE}"
Tem mais dúvidas? Envie uma solicitação

Comentários