Una vez que tu aplicación procesa la solicitud de oferta de Google, debe compilarse y enviar una respuesta. En esta guía, se explica cómo codificar tu aplicación para compilar la respuesta.
Crear mensaje de BidResponse
Authorized Buyers envía el BidRequest
como el cuerpo del mensaje de una POST
HTTP. La respuesta que envía tu aplicación debe tener el encabezado Content-Type
configurado como application/octet-stream
y un cuerpo del mensaje que contenga un búfer de protocolo serializado. El búfer de protocolo es un mensaje BidResponse
, como se define en realtime-bidding.proto
. Tu aplicación debe mostrar un BidResponse
analizable en respuesta a cada BidRequest
. Los tiempos de espera y las respuestas que no se pueden analizar se consideran errores y Google limita a los ofertantes con tasas de error altas.
Si no deseas realizar una oferta por una impresión, puedes configurar el campo processing_time_ms
solo y dejar todos los demás campos vacíos. Puedes obtener realtime-bidding.proto
de la página de datos de referencia.
ID de la creatividad
Tu BidResponse
especifica una creatividad en el campo buyer_creative_id
(límite de 64 bytes). Incluso las creatividades similares deben tener valores únicos para buyer_creative_id
si difieren en cualquier característica destacada, incluidos, sin limitaciones, el tamaño, la URL declarada, los atributos de la creatividad y los tipos de proveedores. En otras palabras, debes asignar diferentes ID de creatividad a dos anuncios cualesquiera, lo que:
- Se ven o se comportan de manera diferente.
- Renderiza a diferentes imágenes.
- Renderizarse por diferentes medios (por ejemplo, un anuncio consiste en una imagen y el otro contiene Flash)
Cuando diseñas tu aplicación, debes decidir una forma sistemática de generar identificadores que tengan sentido para los tipos de creatividades que planeas enviar.
Atributos del anuncio
Debes declarar los atributos de la creatividad que describen en detalle las características del anuncio y su segmentación en BidResponse.Ad.attribute
. Se deben declarar los siguientes atributos (consulta también la lista completa de atributos admitidos en buyer-declarable-creative-attributes.txt):
7 Tagging: IsTagged
El anuncio contiene un píxel o baliza web con el fin de crear una lista de ID de cookies para su posterior comercialización.8 Remarketing: IsRemarketing
El anuncio se orienta a los consumidores según su ID de cookie o ID de dispositivo, en los que la lista de IDs de cookies o IDs de dispositivos representan un conjunto de consumidores que anteriormente interactuaron con un sitio que pertenecía al comprador o estaba representado.9 UserInterestTargeting: IsUserInterestTargeted
El anuncio se orienta a los consumidores según su ID de cookie o ID de dispositivo, en los que la lista de ID de cookies o ID de dispositivo representa un conjunto de consumidores que el comprador definió como un grupo de interés común.30 InstreamVastVideoType: Vpaid
El anuncio requiere compatibilidad con VPAID para renderizarse.32 MraidType: MRAID
El anuncio requiere que se renderice la API de MRAID.
Además, se admiten los siguientes atributos, pero su declaración no es obligatoria, ya que Authorized Buyers los detecta automáticamente y bloqueará (o permitirá) tus creatividades en función de los valores detectados, en lugar de tu declaración. Consulta la API de Creatives para obtener una explicación sobre cómo obtener comentarios sobre las propiedades detectadas de tus creatividades.
34 RichMediaCapabilityType: RichMediaCapabilityFlash
El anuncio requiere compatibilidad con Flash para renderizarse.50 RichMediaCapabilityType: RichMediaCapabilityNonFlash
El anuncio no requiere Flash para renderizarse.47 RichMediaCapabilityType: RichMediaCapabilitySSL
El anuncio se puede renderizar en una página SSL. Ten en cuenta que Authorized Buyers considera las creatividades con valores declarados diferentes para este atributo como distintas (se revisarán por separado y tendrán un estado de aprobación distinto). Por lo tanto, si realiza una oferta con versiones SSL y no SSL de la misma creatividad, debe declarar este atributo según corresponda para que esta distinción se refleje correctamente en AdX.
Campos de Open Bidding
Las respuestas a las ofertas enviadas por los ofertantes de intercambio y red que participan en Open Bidding son similares a las de los ofertantes de Authorized Buyers que participan en las ofertas estándar en tiempo real. Los clientes de Open Bidding pueden especificar una pequeña cantidad de campos adicionales, y es posible que algunos campos existentes tengan usos alternativos. Estos son algunos ejemplos:
OpenRTB | Authorized Buyers | Detalles |
---|---|---|
BidResponse.imp[].pmp.deals[].id |
BidResponse.ad[].adslot[].exchange_deal_id |
Es el ID de acuerdo del espacio de nombres del intercambio asociado con esta oferta y que se informa a los publicadores. |
BidResponse.seatbid[].bid[].ext.exchange_deal_type |
BidResponse.ad[].adslot[].exchange_deal_type |
Es el tipo de acuerdo que se informa a los publicadores y que afecta la forma en que se trata en la subasta. |
BidResponse.seatbid[].bid[].ext.third_party_buyer_token |
BidResponse.ad[].adslot[].third_party_buyer_token |
El token que se usa para identificar la información del comprador externo si el intercambio como ofertantes de Open Bidding es un intermediario. Estos datos se obtienen del comprador externo y se deben pasar a Google sin cambios en la respuesta a la oferta. |
Recomendaciones
- Habilita conexiones HTTPS persistentes (también conocidas como “keep-alive” o “reutilización de la conexión”) en tus servidores. Establece el tiempo de espera en 10 segundos como mínimo. En muchos casos, los valores más altos son beneficiosos. Google verifica esto durante las pruebas de latencia iniciales de tu aplicación, ya que Authorized Buyers envía solicitudes a una velocidad alta y necesita evitar la sobrecarga de latencia que supone establecer una conexión TCP separada para cada solicitud.
Incluye la URL de seguimiento de impresiones opcional para hacer un seguimiento de cuándo se renderiza la impresión en lugar de cuando gana el ofertante. Debido al abandono entre las victorias y las renderizaciones, esto produce estadísticas de seguimiento más precisas.
- Mantén tu código de ofertante libre de dependencias en campos obsoletos, ya que esto puede provocar errores en tus ofertas.
- Incluye
BidResponse.Ad.width
yBidResponse.Ad.height
en tuBidResponse
. UnaBidResponse
para una solicitud que incluye varios tamaños de anuncios debe incluir los valoreswidth
yheight
; de lo contrario, se descartará de la subasta. - Limita el tamaño de las respuestas a menos de 8K. Las respuestas muy grandes pueden aumentar la latencia de red y causar tiempos de espera.
- Sigue los lineamientos para las ofertas en el inventario de iOS que requieren atribución de SKAdNetwork.
Ejemplo de respuesta a la oferta
Los siguientes ejemplos representan muestras legibles de las solicitudes de Protobuf y JSON.
JSON de OpenRTB
OpenRTB Protobuf
Importante: Los mensajes de Protobuf que se muestran en las muestras se representan aquí como texto legible. Sin embargo, no es así como se envían los mensajes por cable. Cuando se usa el formato OpenRTB Protobuf o Google, solo se aceptarán mensajes de BidResponse serializados.
Puedes crear y serializar un mensaje BidResponse
con el siguiente código de C++:
BidResponse bid_response; // fill in bid response with bid information string post_response; if (bid_response.SerializeToString(&post_response)) { // respond to the POST with post_response as the content } else { // return an error to the POST }
Especificar creatividad
Su respuesta a la oferta especifica la creatividad que se publicará si su oferta gana. Tu oferta debe incluir uno de los formatos de anuncios admitidos (AMP, video o nativo). En este
ejemplo, especificamos la creatividad con el campo html_snippet
.
Como alternativa, puedes especificar tu creatividad mediante uno de los siguientes campos, según el formato del anuncio:
- Anuncio renderizado por SDK
BidResponse.Ad.sdk_rendered_ad
- AMP
BidResponse.Ad.amp_ad_url
- Video
BidResponse.Ad.video_url
oBidResponse.Ad.video_vast_xml
- Nativo
BidResponse.Ad.native_ad
Especifica un anuncio alojado en tus propios servidores con un fragmento HTML en el campo html_snippet
de BidResponse
. El fragmento se encierra en un iframe insertado en la página web, lo que hace que el anuncio se recupere y renderice cuando se carga la página. Debes crear el fragmento HTML de modo que el anuncio (de banner o intersticial) se renderice correctamente dentro de un iframe y tenga un tamaño apropiado para el espacio publicitario en el que realices ofertas.
Además, el tamaño del anuncio declarado en la respuesta a la oferta debe coincidir exactamente con una de las combinaciones de tamaños en la solicitud de oferta en los siguientes casos:
- Los anuncios son banners normales (no de video, nativos ni intersticiales).
- El ofertante declaró el tamaño en la respuesta a la oferta. Es obligatorio declarar el tamaño cuando hay más de un tamaño en la solicitud.
- Se hace una excepción para los anuncios intersticiales. En el caso de los anuncios intersticiales, el ancho debe ser de al menos el 50% del ancho de la pantalla y el alto debe ser de, al menos, el 40% de la altura de la pantalla.
El campo html_snippet
admite cualquier código HTML válido que se renderice correctamente, pero ten en cuenta las restricciones para especificar el campo buyer_creative_id
en la sección Create BidResponse message. Puedes usar esta opción para colocar información adicional en los argumentos de las URLs que se recuperan de tus servidores como parte del procesamiento del anuncio. Esto te permite pasar datos arbitrarios sobre la impresión a tus propios servidores.
La mayoría de las políticas para fragmentos HTML que se muestran en las respuestas a la oferta son las mismas que para anuncios de terceros. Para obtener más información, consulta los Lineamientos del programa Authorized Buyers, los Requisitos para la publicación de anuncios mediante servidor de terceros y Declara las URLs de clic en anuncios.
Cómo especificar macros
El fragmento HTML que define una creatividad puede incluir una o más construcciones especiales llamadas macros. Durante la publicación de anuncios, se sustituyen los valores por las macros. Por ejemplo, tu aplicación de ofertas cliente podría usar la macro WINNING_PRICE
para determinar cuánto pagó el anuncio, si gana la subasta. Para analizar esta macro, deberás implementar una aplicación que desencripte las confirmaciones de precios. Consulta la página Desencriptación de confirmaciones de precios para obtener más información.
Especifica una macro como parte de un fragmento HTML en el formato %%MACRO%%
, en el que MACRO
es una de las macros compatibles que se enumeran en la siguiente tabla.
Google requiere que uses las macros CLICK_URL_UNESC
o CLICK_URL_ESC
en la creatividad del anuncio publicado por un tercero. Google utiliza las macros de CLICK_URL
para el seguimiento de clics.
Para usar una macro, inclúyela en el anuncio para que se recupere la URL cuando alguien haga clic en ella. El valor que se muestra de la recuperación es un redireccionamiento a otra URL que agregas a CLICK_URL
.
Macro | Descripción |
---|---|
ADVERTISING_IDENTIFIER |
Permite que los compradores reciban el IDFA de iOS o el ID de publicidad de Android en el procesamiento de impresiones. Consulta Desencriptación de identificadores de anunciantes para obtener más información. |
CACHEBUSTER |
Representación de string de un número entero aleatorio de cuatro bytes sin firma. |
CLICK_URL_UNESC |
Es la URL de clic sin escape del anuncio. En el fragmento, una versión con escape de la URL de clic de terceros debería seguir directamente a la macro. Por ejemplo, si la URL de clic de terceros es <a href="%%CLICK_URL_UNESC%%http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a> En el momento de la publicación de anuncios, está expandido a: <a href="http://google-click-url?...&ad_url=http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a> La URL primero registrará el clic con Google y, luego, redireccionará a la URL de clic de terceros. |
CLICK_URL_ESC |
Es la URL de clic con escape del anuncio. Usa esto en lugar de Por ejemplo, se podría usar el siguiente código en un fragmento HTML: <a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC%%"></a> En el momento de la publicación de anuncios, está expandido a: <a href="http://my.adserver.com/click?google_click_url=http://google-click- url%3F...%26ad_url%3D"></a> Esto registrará el clic con Puedes agregar una URL con escape doble después de |
CLICK_URL_ESC_ESC |
Es la URL con escape doble para el anuncio. Usa esto en lugar de Por ejemplo, se podría usar el siguiente código en un fragmento HTML: <a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC_ESC%%"></a> En el momento de la publicación de anuncios, está expandido a: <a href="http://my.otheradserver.com/click?google_click_url=http%3A%2F%2Fmy.adserver.com%2Fclick%3Fgoogle_click_url%3Dhttp%3A%2F%2Fgoogle-click-%20url%253F...%2526ad_url%253D"></a> |
SCHEME |
Se expande a http: si la solicitud de oferta no requiere SSL o a https: si la solicitud de oferta requiere SSL. |
SITE |
El dominio con escape de URL de la URL de contenido o el ID anónimo para el inventario anónimo. |
SITE_URL |
Ya no está disponible. Se reemplazó por la macro SITE que proporciona la misma funcionalidad. |
TZ_OFFSET |
Desfase de zona horaria. |
VERIFICATION |
Los diferentes valores para producción y cuándo se analiza la creatividad en la canalización
de verificación. El formato es %%?VERIFICATION:true-val:false-val%% , en el que cualquier valor, excepto las macros, se puede usar para true-val y false-val , incluidas las strings vacías. Para Open Bidding, recomendamos que los intercambios usen esta macro.
Una vez que lo hagan, las plataformas orientadas a la demanda no necesitarán realizar cambios.Por ejemplo, si una creatividad incluyera %%?VERIFICATION:-1:5000%% , el reemplazo de texto sería 5000 en la publicación y -1 en la canalización de verificación. Esto es para ayudar a diferenciar entre estos dos conjuntos de pings. |
WINNING_PRICE |
El costo de las impresiones codificadas (es decir, CPI en lugar del CPM) en
microsegundos de la moneda de la cuenta. Por ejemplo, un CPM ganador de USD 5 corresponde a un CPM de 5,000,000 micros, o un CPI de 5,000 micros. En este caso, el valor decodificado de WINNING_PRICE sería 5,000.
El precio ganador se especifica en CPI.
|
WINNING_PRICE_ESC |
WINNING_PRICE con escape de URL. |
El escape de URL en macros utiliza el siguiente esquema:
- El carácter de espacio se reemplaza por un signo más (
+
). - Los caracteres alfanuméricos (0-9, a-z, A-Z) y los caracteres del conjunto !()*,-./:_~ no se modifican.
- Todos los demás caracteres se reemplazan por
%XX
, en el queXX
es el número hexadecimal que representa el carácter.
Restricciones para publicadores
Los editores usan el BidRequest
para pasar restricciones sobre los anuncios que permitirán. Debes aplicar las restricciones en estos campos:
allowed_vendor_type
excluded_attribute
excluded_sensitive_category
Un campo especifica las funciones permitidas del anuncio y el otro especifica las funciones no permitidas. Nunca mostrar un anuncio con una función no permitida. Para las funciones permitidas, como el tipo de proveedor, muestra un anuncio solo si su tipo de proveedor está en la lista allowed_vendor_type
de BidRequest
. Consulta los comentarios de estos campos en la definición del búfer de protocolo BidRequest
para obtener más detalles.
Si se muestra un fragmento HTML en BidResponse
, debes configurar con precisión los campos attribute
, category
y click_through_url
en BidResponse
.
Si un anuncio tiene varios valores aplicables para estos campos, debes incluir todos los valores. Consulta los comentarios de estos campos en la definición del búfer de protocolo BidResponse
para obtener más detalles.
Las respuestas que no tienen estos campos configurados se descartan.
Los valores posibles de BidRequest.excluded_attribute
son los siguientes (consulta publisher-excludable-creative-attributes.txt):
7 Tagging: IsTagged
No se permiten los anuncios si contienen un píxel o un píxel contador web con el fin de crear una lista de ID de cookies para nuevos tipos de remarketing.8 CookieTargeting: IsCookieTargeted
No se permiten los anuncios si se segmentan para consumidores según su ID de cookie. La lista correspondiente representa un conjunto de consumidores que interactuaron anteriormente con un sitio que pertenecía al comprador o estaba representado.9 UserInterestTargeting: IsUserInterestTargeted
No se permiten los anuncios si se segmentan para consumidores según su ID de cookie, y la lista de IDs de cookies representa un conjunto de consumidores que el comprador definió como un grupo de interés común.21 CreativeType: Html
No se permite que los anuncios usen los camposhtml_snippet
osnippet_template
enBidResponse.Ad
.22 CreativeType: VastVideo
No se permite que los anuncios utilicen el campovideo_url
enBidResponse.Ad
.30 InstreamVastVideoType: Vpaid
No se permite que los anuncios requieran compatibilidad con VPAID para renderizarse.32 MraidType: MRAID
No se permite que los anuncios requieran la renderización de la API de MRAID.34 RichMediaCapabilityType: RichMediaCapabilityFlash
No se permite que los anuncios requieran compatibilidad con Flash para su renderización.39 RichMediaCapabilityType: RichMediaCapabilityHTML5
No se permite que los anuncios requieran funciones HTML5 para su renderización.48 RichMediaCapabilityType: RichMediaCapabilityNonSSL
No está permitido que los anuncios realicen solicitudes que no sean SSL.
Por lo tanto, si el campo excluded_attribute
contiene el valor 7, no debes mostrar un anuncio que utilice un píxel o un pixel contador web para crear una lista. Ten en cuenta que si un anuncio hace esto, debe establecer el valor 7 en el campo de atributo de BidResponse
.
Del mismo modo, si el campo excluded_attribute
contiene el valor 48, solo debes mostrar anuncios que se puedan renderizar en una página SSL (y, según corresponda, declarar el atributo 47 RichMediaCapabilityType: RichMediaCapabilitySSL).
Además, el campo excluded_sensitive_category
de BidRequest
usa códigos del archivo ad-sensitive-categories.txt
disponible en la página de datos de referencia. A continuación, se incluyen descripciones extendidas de algunos de estos códigos:
3 Politics
Incluye temas políticos o sociales polémicos; no incluye anuncios de organizaciones de noticias que no suelen estar asociadas con un punto de vista partidario sobre ciertos temas.4 Dating
Incluye servicios de citas y comunidades de citas en línea.5 Religion
Incluye anuncios religiosos y anuncios que abogan a favor o en contra de opiniones religiosas; no incluye la astrología ni la espiritualidad no confesional.7 Video Games (Casual & Online)
Incluye videojuegos, juegos en línea y juegos descargables; no incluye consolas de juegos.8 Ringtones & Downloadables
Complementos para dispositivos móviles, como tonos y otros accesorios descargables, como protectores de pantalla y fondos de pantalla para computadoras de escritorio, así como diseños de perfil y gráficos para redes sociales10 Get Rich Quick
Esquemas que prometen ingresos rápidos18 Weight Loss
Incluye productos y programas relacionados con la pérdida de peso y las dietas; no incluye anuncios sobre alimentación saludable ni ejercicio físico general.19 Cosmetic Procedures & Body Modification
Incluye elevadores, succiones, láseres, depilación y restauración, tatuajes y modificaciones corporales.23 Drugs & Supplements:
Incluye minoristas de productos farmacéuticos, vitaminas, suplementos y productos relacionados; no incluye recursos que proporcionan información sobre medicamentos.24 Sexual & Reproductive Health
Incluye anuncios sobre función sexual y fertilidad, pero no incluye recursos sobre embarazo normal.35 Social Casino Games
Incluye juegos de apuestas simulados (incluidos, sin limitarse a ello, póquer, tragamonedas, bingo, loterías, apuestas deportivas, apuestas en carreras y otros juegos de cartas y casino) en los que no hay oportunidad de ganar ningún artículo de valor (como dinero o premios).36 Significant Skin Exposure
Imágenes de anuncios en las que cualquier parte del cuerpo humano, desde el esternón hasta la mitad del muslo, no esté cubierta, o bien en las que el cuerpo esté cubierto con ropa interior, trajes de baño, lencería, prendas transparentes o artículos que no sean prendas de vestir, como una toalla o una sábana37 Sensationalism
Anuncios que tienen como objetivo inducir a los usuarios a hacer clic en ellos. Para ello, apelan a su curiosidad, a menudo a través de un mensaje engañoso que utiliza imágenes o texto exagerados. Incluye anuncios que se centran en temas sensacionalistas (como muertes, divorcios o detenciones de celebridades) o que pretenden causar un impacto.
Open Measurement
Open Measurement te permite especificar proveedores de terceros que proporcionan servicios independientes de medición y verificación para anuncios que se publican en entornos de apps para dispositivos móviles.Los formatos de anuncios admitidos actualmente incluyen anuncios intersticiales, de video y de banner. Si deseas obtener más información para usar Open Measurement en una respuesta a la oferta que contiene estos formatos, consulta el artículo del Centro de ayuda sobre el SDK de Open Measurement.
Ejemplos de respuestas a ofertas
Las siguientes secciones muestran ejemplos de respuestas a ofertas para diferentes tipos de anuncios.