O que você precisa saber para configurar sua implementação.
Nossas equipes de Integração e Launch Management trabalharão em estreita colaboração com suas equipes durante a implementação da API de Anúncios Patrocinados de Hospedagem. Com estreita colaboração, a implementação é geralmente estimada em 8 semanas, incluindo 2 semanas para testes do end-to-end.
>> Saiba mais sobre atribuição de reservas 4. Decida onde, nos resultados da pesquisa, você exibirá os anúncios patrocinados e crie o design do seu selo. Observação: Não altere a ordem em que os anúncios foram classificados na resposta de Listagens Patrocinadas de Hospedagem. Consulte as informações sobre os requisitos da interface do usuário. >> Saiba mais requisitos de interface do usuário 5. Teste sua implementação antes de publicá-la.
A cada pesquisa elegível, você nos enviará uma lista pré-selecionada de IDs com a hashtag Expedia Group propriedade. Aproveite esta oportunidade para controlar quais propriedades seriam elegíveis para anúncios patrocinados em seu site.
Em linhas gerais, esta é a sequência do que acontece do lado do viajante e o que o seu sistema fará:
Etapa 1: Envie uma chamada para a API de Anúncios Patrocinados de Hospedagem usando os dados de contexto da pesquisa.
Nota: Esta chamada não está de forma alguma relacionada com as chamadas de comparação de tarifas que você possa estar fazendo e pode ser feita antes, durante ou depois que as tarifas e a disponibilidade forem obtidas.
Agregue e classifique os resultados de disponibilidade como faria normalmente.
Garanta que o ID do cliente seja o mesmo em todas as solicitações.
Nota sobre o ID do cliente: Os anunciantes que investem em cliques esperam informações claras sobre o valor gerado pelo seu investimento. Para anúncios patrocinados de hospedagem, esse valor é medido pelas reservas resultantes de uma visualização ou clique no anúncio. No entanto, não podemos fornecer dados completos de atribuição de reservas quando o estoque de hospedagem é proveniente de vários canais, por isso exigimos um ID de cliente persistente em todas as solicitações de anúncios. Esse ID deve ser mantido durante todo o processo de rastreamento de anúncios e incluído nas informações de atribuição de reservas para que possamos vincular com precisão as interações com os anúncios às reservas resultantes.
Etapa 2: Encontre o propriedade associado nos resultados de disponibilidade.
Para obter a máxima visibilidade dos anúncios e a monetização ideal, é fundamental que você mapeie seus IDs propriedade para os IDs propriedade da Expedia, mesmo para as propriedades que você não anuncia na Expedia. É improvável que haja um mapeamento completo entre os dois conjuntos de propriedades, pois nem todas as propriedades participam do programa de anúncios patrocinados.
Compare os IDs Expedia propriedade retornados na resposta de entrega do anúncio com seus resultados de disponibilidade.
Combine o conteúdo do anúncio com a hashtag propriedade com o anúncio patrocinado. Os resultados da API de Anúncios Patrocinados de Hospedagem retornam apenas o ID propriedade e o conteúdo do anúncio, nenhum outro conteúdo.
Etapa 3: Intercale os anúncios patrocinados nos resultados de disponibilidade (opcional)
Os imóveis anunciados como patrocinados podem aparecer no topo dos resultados da pesquisa ou distribuídos pelos resultados orgânicos. Não há exigência quanto ao local onde os anúncios são veiculados, desde que a ordem seja mantida.
Escolha como deseja exibir os anúncios patrocinados.
Certifique-se de que a ordem em que os anúncios patrocinados aparecem não seja alterada.
Embora tanto a classificação do anúncio quanto a posição do anúncio estejam relacionadas ao posicionamento de um anúncio, elas não são a mesma coisa.
A classificação do anúncio determina a posição do anúncio após o lance. O anúncio vencedor recebe a classificação 1, o segundo colocado a classificação 2 e assim por diante, sequencialmente, até a classificação 25 (o número máximo de anúncios retornados).
A posição do anúncio, por outro lado, refere-se à colocação real do anúncio na página, normalmente numerada de 1 (superior) para baixo. Nos resultados paginados, as posições continuam sequencialmente ao longo das páginas. Por exemplo, se você exibir 10 anúncios com a hashtag propriedade por página e colocar anúncios nas posições 1 e 10 em cada página, o primeiro anúncio da página 2 deverá ser atribuído à posição 11. É importante incluir a posição do anúncio em todos os beacons de rastreamento para garantir medições e relatórios precisos.
|
Definição de anúncios OpenAPI
openapi: 3.0.1
info:
title: Ad Delivery API
version: v1
description: Retrieves ads.
contact:
name: 'Media Solutions'
email: 'MediaSolutionsAPI1@expedia.com'
url: 'https://test.developers.expediagroup.com/docs/'
tags:
- name: Ad Delivery
description: API to retrieve ads
servers:
- url: https://test.ean.com/v1
- url: https://api.ean.com/v1
paths:
/ads:
post:
tags:
- Ad Delivery
description: Returns relevant ads.
operationId: getAds
parameters:
- name: Accept
in: header
description: Specifies the response format that the client would like to receive back. This must be application/json
required: true
schema:
type: string
example: 'application/json'
- name: Authorization
in: header
description: EAN token, format is <pre>EAN APIKey=<APIKey>,Signature=<Encoded Signature>,timestamp=<timestamp></pre>
required: true
schema:
type: string
- name: Accept-Encoding
in: header
description: Specifies the response encoding that the client would like to receive back. This must be gzip.
required: true
schema:
type: string
example: 'gzip'
- name: User-Agent
in: header
description: The User-Agent header string from the customer's request, as captured by your integration.
required: true
schema:
type: string
example: 'Mozilla/5.0 (Linux; Android 13; SM-S901B) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/112.0.0.0 Mobile Safari/537.36'
- name: Customer-Ip
in: header
description: IP address of the customer, as captured by your integration.
Ensure your integration passes the customer's IP, not your own. Used for fraud recovery and other important analytics.
required: false
schema:
type: string
example: '192.168.123.132'
- name: Customer-Session-Id
in: header
description: Insert your own unique value for each user session, beginning with the first API call.
Continue to pass the same value for each subsequent API call during the user's session, using a new value for every new customer session.
required: false
schema:
type: string
example: '7f9a24ea-2145-4819-a7b7-2a4cbe1165ab'
- name: Customer-Id
in: header
description: An obfuscated unique identifier for each customer. This should not contain any personal information such as email, first or last name.
required: true
schema:
type: string
example: '7f9a24ea-2145-4819-a7b7-2a4cbe1165ab'
- name: Test
in: header
description: Ads calls have a test header that can be used to return set responses with the following keywords:<br>
* `standard`
* `service_unavailable`
* `unknown_internal_error`
schema:
type: string
enum:
- standard
- service_unavailable
- unknown_internal_error
- name: billing_terms
in: query
description: This parameter is to specify the terms of how a resulting booking should be billed. If this field is
needed, the value for this will be provided to you separately.
schema:
type: string
- name: partner_point_of_sale
in: query
description: This parameter is to specify what point of sale is being used to shop and book. If this field is needed,
the value for this will be provided to you separately.
schema:
type: string
- name: payment_terms
in: query
description: This parameter is to specify what terms should be used when being paid for a resulting booking. If this
field is needed, the value for this will be provided to you separately.
schema:
type: string
- name: platform_name
in: query
description: This parameter is to specify what platform is being used to shop and book. If this field is needed, the
value for this will be provided to you separately.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdsRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdsResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
type: 'invalid_input'
message: 'An invalid request was sent in, please check the nested errors for details.'
errors:
- type: 'language.required'
message: 'A language is required. Supported languages are:
[ar-SA, cs-CZ, da-DK, de-DE, el-GR, en-US, es-ES, es-MX, fi-FI, fr-CA, fr-FR, hr-HR, hu-HU, id-ID,
is-IS, it-IT, ja-JP, lt-LT, ko-KR, ms-MY, nb-NO, nl-NL, pl-PL, pt-BR, pt-PT, ru-RU, sk-SK, sv-SE,
th-TH, tr-TR, uk-UA, vi-VN, zh-CN, zh-TW]'
fields:
- name: 'language'
type: 'request'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
type: 'request_unauthenticated'
message: 'Data required to authenticate your request is missing or inaccurate.
Ensure that your request follows the guidelines in our documentation.'
fields:
- name: 'apikey'
type: 'header'
value: 'jaj3982k239dka328e'
- name: 'signature'
type: 'header'
value: '129d75332614a5bdbe0c7eb540e95a65f9d85a5b53dabb38d19b37fad6312a2bd25c12ee5a82831d55112087e1b'
- name: 'timestamp'
type: 'header'
value: '198284729'
- name: 'servertimestamp'
type: 'server'
value: '198284729'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
type: 'request_unauthorized'
message: 'Your request could not be authorized.'
'426':
description: Upgrade Required
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
type: 'upgrade_required'
message: 'This service requires the use of TLS.'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
type: 'too_many_requests'
message: 'You have reached your capacity for this type of request.'
'500':
description: Unknown Internal Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
type: 'unknown_internal_error'
message: 'An internal server error has occurred.'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
type: 'service_unavailable'
message: 'This service is currently unavailable.'
components:
schemas:
PageType:
type: string
enum:
- other
- search_results
- details
- confirmation
example: 'search_results'
description: The type of page the ads will be rendered on.
SortType:
type: string
enum:
- default
example: default
description: The sort type selected for the organic results.
ProductLine:
type: string
enum:
- car
- flight
- lodging
example: lodging
description: The different types of travel product lines a traveler can search for.
SalesChannel:
type: string
enum:
- website
- mobile_app
- mobile_web
example: 'mobile_app'
description: The sales channel for the request.
GuestCounts:
type: object
required:
- adult_count
properties:
adult_count:
type: integer
format: int32
example: 2
child_count:
type: integer
format: int32
example: 1
AdsRequest:
type: object
required:
- sales_channel
- language
- country_code
- page_type
- search_product_lines
- checkin
- checkout
- occupancies
- property_ids
properties:
country_code:
type: string
example: 'US'
pattern: '^[A-Z]{2}$'
description: "The country code of the traveler's point of sale, in ISO 3166-1 alpha-2 format.
This should represent the country where the shopping transaction is taking place.
For more information see: https://www.iso.org/obp/ui/#search/code/"
language:
type: string
example: 'en-US'
pattern: '^[a-z]{2}-[A-Z]{2}$'
description: 'Desired language for the response as a subset of BCP47 format that only uses hyphenated pairs of two-digit language and country codes.
Use only ISO 639-1 alpha-2 language codes and ISO 3166-1 alpha-2 country codes.
See https://www.w3.org/International/articles/language-tags/
Language Options: https://developers.expediagroup.com/docs/rapid/resources/reference/language-options'
sales_channel:
$ref: '#/components/schemas/SalesChannel'
page_type:
$ref: '#/components/schemas/PageType'
sort_type:
$ref: '#/components/schemas/SortType'
search_product_lines:
example: [ 'lodging', 'flight' ]
description: The product lines the traveler is searching for. lodging indicates hotel_standalone. lodging and
flight would indicate a lodging_package.
type: array
items:
$ref: '#/components/schemas/ProductLine'
checkin:
type: string
description: Check-in date, in ISO 8601 format (YYYY-MM-DD).
pattern: '^\d{4}-\d{2}-\d{2}$'
example: '2025-01-01'
checkout:
type: string
description: Check-out date, in ISO 8601 format (YYYY-MM-DD).
pattern: '^\d{4}-\d{2}-\d{2}$'
example: '2025-01-05'
occupancies:
type: array
items:
$ref: '#/components/schemas/GuestCounts'
description: Each array item represents guests of one room.
focused_property_id:
type: string
description: The property id the ranking of ads should be based on. Examples of a focused property are a
customer searching for a specific property and it being pinned to the top of a page or the property
recommendation carousel based on the currently or previously viewed property. The focused_property_id itself
will be excluded from the ranking.
example: '23433'
property_ids:
type: array
items:
type: string
example: [ '2717582', '16159546', '2025453' ]
description: The list of property ids eligible for returning sponsored listings. These are the potential
candidates that could be included in the auction. The maximum number of property_ids that can be sent in a
request is 700.
experiment_ids:
description: A list of experiment ids that can be used for testing different behavior. The ids can be associated
with different tests ran by the publisher and are completely arbitrary. The experiment ids will
be included reports back to the publisher.
type: array
items:
type: string
example: [ '324324.1', '2423423.3', '3242343.5' ]
additionalProperties: false
Image:
type: object
properties:
caption:
type: string
description: The image caption.
example: 'Hotel Lobby'
link:
type: object
additionalProperties:
$ref: '#/components/schemas/Link'
description: The url to retrieve the image.
example:
"70px":
method: GET
href: https://i.travelapi.com/hotels/1000000/20000/15300/15237/bef1b976_t.jpg
description: An individual image.
Creative:
type: object
properties:
image:
$ref: '#/components/schemas/Image'
description: The image to be rendered for the sponsored listing.
additionalProperties: false
Link:
type: object
properties:
method:
type: string
description: The request method used to access the link.
example: 'POST'
href:
type: string
description: The URL for the link. This can be absolute or relative. Placeholders will be need to be populated by the client.
example: 'https://advertising.expedia.com/sponsoredcontent/v1/View?position=[position]&data=AAAAAQAAAAEAAA'
expires:
type: string
description: If the link expires, this will be the UTC date the link will expire, in ISO 8601 format.
example: '2025-07-10 15:00:00.000'
description: An individual link.
Beacons:
type: object
required:
- view
- render
- click
properties:
view:
$ref: '#/components/schemas/Link'
render:
$ref: '#/components/schemas/Link'
click:
$ref: '#/components/schemas/Link'
SponsoredListing:
description: The sponsored listing which advertises a specific property.
type: object
required:
- rank
- property_id
- beacons
properties:
rank:
type: integer
pattern: int32
minimum: 0
example: 1
description: The sponsored listing should adhere to the rank and not be re-ranked. This field is 0-based.
property_id:
type: string
example: '13243534'
creative:
$ref: '#/components/schemas/Creative'
beacons:
$ref: '#/components/schemas/Beacons'
ad_transparency_url:
type: string
example: 'https://advertising.expedia.com/sponsoredcontent/dsa/id=123'
description: The url used to retrieve digital services act information regarding why the ad was selected.
additionalProperties: false
AdsResponse:
type: object
properties:
sponsored_listings:
type: array
items:
$ref: '#/components/schemas/SponsoredListing'
additionalProperties: false
Error:
type: object
properties:
type:
type: string
description: The error type.
message:
type: string
description: A human readable message giving details about this error.
fields:
type: array
description: Details about the specific fields that had an error.
items:
$ref: '#/components/schemas/Field'
errors:
type: array
description: An array of all the actual errors that occured.
items:
$ref: '#/components/schemas/ErrorIndividual'
description: The overall class of error that occured.
Field:
type: object
properties:
name:
type: string
description: The field that had an error.
type:
type: string
description: The type of the field that had an error.
value:
type: string
description: The value of the field that had an error.
description: An individual field that had an error.
ErrorIndividual:
type: object
properties:
type:
type: string
description: The error type.
message:
type: string
description: A human readable message giving details about this error.
fields:
type: array
description: Details about the specific fields that had an error.
items:
$ref: '#/components/schemas/Field'
description: An individual error.
propriedade IDs: Somente os IDs propriedade da Expedia serão reconhecidos ao chamar a API de Listagens Patrocinadas de Hospedagem. Qualquer ID de grupo com a hashtag non-Expedia não retornará estoque de anúncios ou poderá corresponder erroneamente a um grupo diferente e irrelevante com a hashtag Expedia Group propriedade..
Limite de contagem de propriedade: Você pode incluir até 700 IDs propriedade em uma única solicitação.
Tarifas e disponibilidade de propriedade: A API de Anúncios Patrocinados de Hospedagem não presume nem verifica a disponibilidade, pois você pode optar por exibir as tarifas com o código Expedia Group ou tarifas provenientes de outras fontes nos anúncios patrocinados nos resultados da pesquisa. É por isso que você faz uma solicitação tanto para a API de Anúncios Patrocinados de Hospedagem quanto para a API de Disponibilidade de Compras e combina os resultados.
Processamento em lote e armazenamento em cache: A API de Anúncios Patrocinados de Hospedagem não suporta solicitações em lote, e Expedia Group desencoraja o armazenamento em cache do estoque de anúncios patrocinados.
O lance de anúncios patrocinados precisa ser executado para cada pesquisa e não pode ser reutilizado; portanto, faça uma solicitação de endpoint de Anúncios Patrocinados de Hospedagem sempre que um cliente realizar uma pesquisa. Se os critérios de pesquisa do cliente mudarem (por exemplo, datas de viagem ou número de quartos), faça solicitações adicionais para garantir que as informações sejam up-to-date.
Embora você possa armazenar em cache suas tarifas e disponibilidade para busca orgânica, as chamadas da API de Anúncios Patrocinados de Hospedagem devem ser feitas em tempo real. As plataformas de publicidade geralmente definem orçamentos diários máximos que são gastos em tempo real. Se os detalhes do anúncio não forem atualizados com frequência, quando o clique ocorrer, o anunciante poderá ficar sem orçamento. Isso se chama gasto excessivo, e mesmo que um anúncio seja exibido e um cliente clique nele, nenhuma receita será gerada.
Ordem de classificação dos anúncios: Você pode escolher quais posições nos seus resultados de pesquisa deseja reservar para anúncios patrocinados, mas não pode usar a hashtag re-sort nem aplicar um algoritmo de seleção, como faria para as respostas da API de Compras. Isso ocorre porque a ordem dos anúncios patrocinados entregues na API representa os resultados do lance ao vivo, com os imóveis oferecendo determinados valores em cost-per-click para serem exibidos.
Se você não quiser que um ID específico com a hashtag propriedade seja exibido em um anúncio patrocinado, você pode excluir esse ID propriedade da sua solicitação à API de Anúncios Patrocinados de Hospedagem.
Cobertura publicitária: Parâmetros de pesquisa adicionais, como filtros, limitam o número de propriedades que podem ser elegíveis para uma determinada pesquisa. Recomendamos que você inclua o máximo de propriedades possível em sua solicitação. A aplicação de filtros adicionais além dos fornecidos pelo viajante pode levar à perda de oportunidades de receita publicitária.
propriedade imagem principal: Não é obrigatório usar as imagens de destaque property-selected enviadas pela resposta da API, mas recomendamos que você o faça.
propriedade Duplicação em anúncios patrocinados e resultados orgânicos: É prática comum no setor que os imóveis apresentados em anúncios patrocinados também apareçam em um segundo resultado orgânico nos buscas. Os proprietários estão dispostos a fazer lances mais altos em troca de maior visibilidade nos resultados de busca.
Por exemplo, você reserva a posição 1 dos resultados de pesquisa para um anúncio patrocinado e Hotel A ganha o lance e é exibido na posição 1 como um anúncio patrocinado. Na sua seleção e ordenação de estoque orgânico, Hotel A aparece uma segunda vez nos resultados de pesquisa na posição 7, mais abaixo na página.
É raro um anúncio patrocinado aparecer diretamente acima ou abaixo do seu resultado orgânico correspondente nos resultados de pesquisa — isso acontece no topo dos resultados de pesquisa em apenas 2% a 3% das buscas. Quando isso acontece, uma opção é empurrar a classificação orgânica para baixo em algumas posições, ajustando o deslocamento para um nível que mantenha uma boa experiência do usuário.
Exemplo de um anúncio patrocinado em formato de classificação
Como os bloqueadores de anúncios às vezes detectam e removem anúncios patrocinados dos resultados de pesquisa, remover a duplicação orgânica significaria que as propriedades com a hashtag high-quality não seriam exibidas para os viajantes.
Alinhamento com solicitações da API de Compras: A API de Anúncios Patrocinados de Hospedagem foi projetada para ser usada em conjunto com a API de Compras de Hospedagem Rápida. A ordem das solicitações à API não importa — as solicitações à API de Anúncios Patrocinados de Hospedagem e à API de Disponibilidade de Compras podem ser feitas em paralelo ou sequencialmente.
O último passo antes de implementar a API de Anúncios Patrocinados de Hospedagem é garantir a migração dos endpoints de teste para os de produção:
Altere a API de entrega de anúncios de https://test.ean.com/v1/ads para https://api.ean.com/v1/ads.
Altere o endpoint de Notificação de Reserva (se estiver usando) de https://test.ean.com/v1/ads/booking-notification para https://api.ean.com/v1/ads/booking-notification.
