E-Planning SSP puede recibir impresiones mediante una conexión de servidor a servidor (server to server) utilizando el protocolo OpenRTB.
Este documento describe como se realizará la conexión, como deben ser enviados las impresiones y como serán devueltos los anuncios entre otros puntos operativos importantes como la sincronización de usuarios.
Lo que normalmente se refiere como subasta, consiste en:
Para comenzar la conexión el SSP será provisto de una serie de URLs (Endpoints), cada una apuntando a diferentes datacenters de E-Planning. El objetivo de esto es utilizar el datacenter mas cercano al utilizado por el SSP para realizar la subasta.
Solo un bid request debe ser enviado para cada subasta. Sin embargo, múltiples impresiones pueden ser enviadas en un mismo bid request.
|
Campo | Tipo | Estado | Comentarios |
---|---|---|---|
id | String | Obligatorio | Un identificador para el request. Puede ser utilizado para relacionar el bid request al bid response fuera del protocolo HTTP |
tmax | Integer | Recomendado | En milisegundos, el tiempo máximo de respuesta para participar de la subasta |
at | Integer | Obligatorio | Tipo de subasta, donde 1 = First Price, 2 = Second Price Plus |
imp | Object Array | Obligatorio | Ver objeto Imp |
allimps | Integer | Recomendado | Indica si todas las impresiones del contexto están disponibles o no |
user | Object | Obligatorio | Ver objeto User |
device | Object | Obligatorio | Ver objeto Device |
site | Object | Obligatorio para Web | Ver objeto Site |
app | Object | Obligatorio para In-App | Ver objeto App |
source | Object | Obligatorio | Ver objeto Source |
regs | Object | Obligatorio para Europa (Recomendado para el resto) | Ver objeto Regs |
badv | String Array | Recomendado | Listado de dominios de anunciantes bloqueados |
bcat | String Array | Recomendado | Listado de categorías IAB bloqueadas |
{ "id": "bfebe4d6f24efacd", "tmax": 300, "at": 1, "cur": ["USD"], "imp": [{ "...": "..." }], "user": { "...": "..." }, "device": { "...": "..." }, "site": { "...": "..." }, "source": { "...": "..." }, "regs": { "...": "..." }, "badv": ["ford.com","bmw.com"], "bcat":, ["IAB8-1","IAB8-2"] } |
Campo | Tipo | Estado | Comentarios |
---|---|---|---|
id | String | Obligatorio | Identificador único para la impresión dentro del Bid Request. Habitualmente comienza en "1" y se incrementa progresivamente. |
banner | Object | Obligatorio para display | Ver objeto Banner |
video | Object | Obligatorio para video | Ver objeto Video |
bidfloorcur | String | Obligatorio | Divisa a utilizar en los precios, tanto en el bid response como en los precios mínimos. Utiliza códigos ISO-4217, por ejemplo "USD". |
bidfloor | Float | Obligatorio | El precio mínimo al cual la impresión puede ser vendida, expresado en la divisa especificada en bidfloorcur |
secure | Integer | Obligatorio | Indica "1" si el anuncio en el bid response debe utilizar HTTPS |
instl | Integer | Recomendado | Indica "1" cuando la impresión corresponde a un anuncio de página completa (Full page o Interstitial) |
clickbrowser | Integer | Obligatorio para In-App | Indica el tipo de navegador a abrirse al realizar click en el anuncio. 0 = Interno de la App, 1 = Nativo |
{ "id": "1", "bidfloor": 0.4286, "bidfloorcur": "USD", "secure": 1, "instl": 0, "banner": { "w": 300, "h": 250, "pos": 1, "topframe": 0 }, "tagid": "79a4e192e54cc0d9" } |
Campo | Tipo | Estado | Comentarios |
---|---|---|---|
format | Object Array | Obligatorio si no estan presentes "w" y "h" | Ver objeto Format. Tamaños soportados en la subasta. |
w | Integer | Obligatorio si no esta presente "Format" | Ancho en pixeles del banner |
h | Integer | Obligatorio si no esta presente "Format" | Alto en pixeles del banner |
wmin | Integer | Recomendado si no esta presente "Format" | Mínimo ancho en pixeles del banner |
wmax | Integer | Recomendado si no esta presente "Format" | Máximo ancho en pixeles del banner |
hmin | Integer | Recomendado si no esta presente "Format" | Mínimo alto en pixeles del banner |
hmax | Integer | Recomendado si no esta presente "Format" | Máximo alto en pixeles del banner |
pos | Integer | Recomendado | Posición del anuncio en la pagina según Ad Position IAB standard |
topframe | Integer | Recomendado | 0 = El banner se encuentra dentro de un iframe, 1 = El banner se encuentra en el marco superior de la página |
api | Integer | Recomendado | Listado de las APIs soportadas según están descriptas en OpenRTB 2.5. Si se encuentra enviando tráfico inApp, por favor considere indicar si soporta OMID-1 (7) |
battr | Integer Array | Recomendado | Atributos del creativo bloqueadas |
btype | Integer Array | Recomendado | Tipos de banner bloqueados |
expdir | Integer Array | Opcional | Direcciones en las cuales el banner puede ser expandido |
|
{ "pos": 1, "format": [ { "w": 300, "h": 600 }, { "w": 300, "h": 250 } ], "battr": [ 11, 12 ], "btype": [ 4 ] } |
{ "pos": 1, "w": 300, "h": 250, "wmin": 300, "wmax": 300, "hmin": 50, "hmax": 600, "battr": [ 11, 12 ], "btype": [ 4 ] } |
Campo | Tipo | Estado | Comentarios |
---|---|---|---|
w | Integer | Obligatorio | Ancho en pixeles del reproductor de video |
h | Integer | Obligatorio | Alto en pixeles del reproductor de video |
maxduration | Integer | Obligatorio | Máxima duración del video, en segundos |
minduration | Integer | Obligatorio | Mínima duración del video, en segundos |
mimes | String Array | Obligatorio | Listado de MIME types soportados. Los mas comunes son: video/mp4, video/webm, video/ogg. Para VPAID, por favor especifique application/javascript |
protocols | Integer Array | Obligatorio | Protocolos soportados. Al menos un protocolo debe ser soportado, ejemplos: 2 = VAST 2.0, 3 = VAST 3.0, 5 = VAST 2.0 Wrapper, 6 = VAST 3.0 Wrapper |
pos | Integer | Recomendado | Posición del anuncio en la pagina según Ad Position IAB standard |
api | Integer | Recomendado | Listado de las APIs soportadas según están descriptas en OpenRTB 2.5. Si se encuentra enviando tráfico inApp, por favor considere indicar si soporta OMID-1 (7) |
battr | Integer Array | Recomendado | Atributos del creativo bloqueadas |
boxingallowed | Integer | Recomendado | Especifica si es posible insertar contenido de video 4:3 en una ventana de 16:9. 1 = Permitido, 0 = No permitido |
delivery | Integer Array | Opcional | Metodos de entrega soportados. 1 = streaming, 2 = progressive |
linearity | Integer Array | Opcional | Especifica si la impresión es lineal o no-lineal. 1 = linear / in-stream, 2 = non-linear / overlay |
Campo | Tipo | Estado | Comentarios |
---|---|---|---|
w | Integer | Obligatorio | Ancho en pixeles del tamaño |
h | Integer | Obligatorio | Alto en pixeles del tamaño |
Campo | Tipo | Estado | Comentarios |
---|---|---|---|
id | String | Obligatorio | ID del sitio en el SSP |
page | String | Obligatorio | URL de la página donde se mostrará la impresión. Si es desconocido, el campo no debe ser enviado o estar en blanco. |
publisher | Object | Obligatorio | Ver objeto Publisher |
domain | String | Recomendado | Dominio de la página donde se mostrará la impresión |
cat | String Array | Recomendado | Array de categorías IAB del sitio. Máximo 8 categorias. |
ref | String | Recomendado | URL de la página desde donde se llego a la página actual |
ext.inventorypartnerdomain | String | Recomendado | Inventory partner domain. Dominio de terceros autorizado para validar ads.txt |
{ "id": "123", "page": "http://example.com/section/page.html", "cat": [ "IAB1-2" ], "publisher": { "id": "456", "domain": "example.com", "name": "Example Inc" } } |
Campo | Tipo | Estado | Comentarios |
---|---|---|---|
id | String | Obligatorio | ID de la App en el SSP |
name | String | Obligatorio | Nombre de la aplicación |
bundle | String | Obligatorio | Bundle de la aplicación o nombre del paquete (por ejemplo, "com.foo.myapp" en Android o un valor numerico en iOS) |
domain | String | Recomendado | Dominio de la aplicación donde se mostrará la impresión |
storeurl | String | Recomendado | URL de la aplicación en la tienda |
cat | String Array | Recomendado | Array de categorías IAB de la aplicación. Máximo 8 categorias. |
ext.inventorypartnerdomain | String | Recomendado | Inventory partner domain. Dominio de terceros autorizado para validar app-ads.txt |
{ "id": "12345", "name": "My App", "bundle": "com.foo.myapp", "domain": "myapp.com", "storeurl": "https://store.com/app/12345", "cat": [ "IAB1-2" ], "publisher": { "id": "456", "domain": "example.com", "name": "Example Inc" } } |
Campo | Tipo | Estado | Comentarios |
---|---|---|---|
id | String | Obligatorio | El ID del publisher. Debe ser suficiente para identificar a la parte finalmente pagada |
domain | String | Recomendado | Dominio del publisher |
name | String | Recomendado | Nombre del publisher |
{ "id": "456", "domain": "example.com", "name": "Example Inc" } |
Campo | Tipo | Estado | Comentarios |
---|---|---|---|
id | String | Recomendado | ID del usuario en el DSP |
buyeruid | String | Recomendado | ID del usuario en E-Planning SSP. Ver sección Sincronización de usuarios |
{ "id": "1234567", "buyeruid": "e3cf38b549b50e01", "consent": "BOEFEAyOEFEAyAHABDENAI4AAAB9vABAASA" } |
Campo | Tipo | Estado | Comentarios |
---|---|---|---|
ua | String | Obligatorio | El valor de user-agent para el navegador |
ip | String | Obligatorio | Dirección IP del usuario |
dnt | Integer | Recomendado | El consentimiento del usuario para ser seguido (tracked). Si el usuario no desea ser seguido este campo debe valer 1. |
language | String | Opcional | El idioma del navegador del usuario utilizando ISO- 639-1-alpha-2 |
carrier | String | Recomendado | Proveedor de servicios de Internet del usuario |
connectiontype | Integer | Recomendado | Tipo de conexión |
os | String | Recomendado | Sistema operativo del dispositivo |
geo | Object | Recomendado | Ver objeto Geo |
ifa | String | Recomendado | Solo para In-App. El ID para anuncios del dispositivo |
{ "ip": "142.93.199.194", "ua": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10.12; rv:71.0) Gecko\/20100101 Firefox\/71.0", "os": "macOS", "carrier": "verizon", "connectiontype": 6, "dnt": 0, "geo": { "country": "USA", "city": "Stanford" } } |
Campo | Tipo | Estado | Comentarios |
---|---|---|---|
country | String | Obligatorio | País del usuario en ISO- 3166-1-alpha-3 |
city | String | Recomendado | Ciudad del usuario |
latitude | Float | Recomendado | Latitud desde -90.0 hasta +90.0, donde negativo significa sur |
longitude | Float | Recomendado | Longitud desde -180.0 hasta +180.0, donde negativo es oeste |
{ "latitude": 37.4194, "longitude": -122.164, "country": "USA", "city": "Stanford" } |
Campo | Tipo | Estado | Comentarios |
---|---|---|---|
coppa | Integer | Recomendado | Indica si la petición esta sujeta a regulaciones de COPPA, donde 0 = no, 1 = si |
gdpr | Integer | Obligatorio para Europa | Indica si la petición esta sujeta a regulaciones de GDPR, donde 0 = no, 1 = si |
ext.consent | String | Recomendado | Si la petición esta sujeta a regulaciones de GDPR, indica el Consent String del usuario |
us_privacy | String | Recomendado | Indica si la petición esta sujeta a regulaciones de CCPA (California Consumer Privacy Act). Debe contener cuatro caracteres, donde el primero debe ser la versión y los tres siguientes Y, N o - Mas información haciendo click aquí. |
{ "gdpr": 1, "coppa": 1, "us_privacy": "1-N-", "ext": { "consent": "BOq9e8JOq9e8lAHABBESCv- AAAAst7_______9______9uz_Ov_v_f__33e8__9v_l_7_-___u_-3zd4u_1vf99yfm1-7etr3tp_87ues2_Xur__79__3z3_9pxP78k89r7337Ew_v-_v8b7BCIJ" } } |
Campo | Tipo | Estado | Comentarios |
---|---|---|---|
fd | Integer | Obligatorio | Entidad responsable de la decisión final sobre la impresión, donde 0 = SSP, 1 = la siguiente fuente |
pchain | String | Recomendado si schain no esta presente | Cadena TAG Payment ID |
ext.schain | String | Recomendado si pchain no esta presente | Según propuesta de IAB, Supply Chain Object |
ext.omidpn | String | Recomendado si es tráfico inApp | Identificador del OM SDK |
ext.omidpv | String | Recomendado si es tráfico inApp | Versión del OM SDK |
Para implementaciones con pchain soportamos tanto TAG ID como identificación por dominio. |
{ "fd": 1, "pchain": "directseller.com:12345" } |
{ "fd": 1, "ext": { "schain": { "complete": 1, "nodes": [ { "asi":"directseller.com", "pid":"12345", "rid":"c7ecc1f7b1628d49" } ] } } } |
{ "id": "6cb84abfabb2990d", "tmax": 300, "at": 1, "cur": ["USD"], "imp": [{ "id": "1", "bidfloor": 0.4, "secure": 1, "instl": 0, "banner": { "w": 300, "h": 600, "pos": 1, "topframe": 0 } }], "user": { "id": "2e6r4g56ez1hz8er4h", "buyeruid": "e3cf38b549b50e01" }, "device": { "ip": "171.67.194.75", "ua": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10.12; rv:71.0) Gecko\/20100101 Firefox\/71.0", "os": "macOS", "carrier": "verizon", "connectiontype": 1, "dnt": 0, "lmt": 0, "geo": { "country": "USA", "city": "Stanford" } }, "site": { "id": "123", "page": "http://example.com/section/page.html", "cat": [ "IAB1-2" ], "publisher": { "id" : "456", "domain": "example.com", "name": "Example Inc" } } "source": { "fd": 1, "ext": { "sourcetype": 3, "sourceorigin": 7, "schain": { "complete": 1, "nodes": [{ "asi":"directseller.com", "pid":"456", "rid":" c7ecc1f7b1628d49" }] } } }, "regs": { "gdpr": 1, "us_privacy": "1-N-", "coppa": 1, "ext": { "consent": "BOq9e8JOq9e8lAHABBESCv- AAAAst7_______9______9uz_Ov_v_f__33e8__9v_l_7_-___u_-3zd4u_1vf99yfm1- 7etr3tp_87ues2_Xur__79__3z3_9pxP78k89r7337Ew_v-_v8b7BCIJ" } }, "badv": ["ford.com","bmw.com"], "bcat": ["IAB8-7","IAB8-8"] } |
Cada bid response generado por E-Planning SSP es único y debe ser utilizado solo una vez, en el mismo contexto del bid request original.
Campo | Tipo | Comentarios |
---|---|---|
id | String | E-Planning SSP devuelve en este campo el valor del identificador del bid request correspondiente. Esto no es necesario para el protocolo pero permite emparejar el request y el response fuera del protocolo HTTP. |
seatbid | Object Array | Ver objeto Seatbid. Es un array para compatibilidad con OpenRTB, pero E-Planning SSP siempre devolverá un solo objeto dentro |
cur | String | La divisa de la oferta utilizando códigos alfanumericos ISO-4217 |
Campo | Tipo | Comentarios |
---|---|---|
seat | String | Un identificador, usualmente utilizado para reflejar los requerimientos de facturación de E-Planning |
bid | Object Array | Ver objeto Bid |
Campo | Tipo | Comentarios |
---|---|---|
id | String | Un identificador del bid para assistir con el registro y seguimiento |
impid | String | Valor del identificador envíado en el objeto Imp |
price | Float | Oferta hecha en CPM (1 significa que E-Planning SSP esta dispuesto a pagar 0.001 por la impresión) |
adm | String | El código HTML del anuncio a mostrar si la subasta es ganada. El mismo contiene una macro que debe ser reeamplazada con el precio en CPM. |
adomain | String Array | El dominio del anunciante de la creatividad |
w | Integer | El ancho del anuncio en pixeles |
h | Integer | El alto del anuncio en pixeles |
lurl | String | URL llamada por el Exchange cuando se sabe que se ha perdido una puja. Se incluyen las macros ${AUCTION_PRICE} y ${AUCTION_LOSS}. La política específica de cada Exchange puede impedir el llamado de lurl o la divulgación del precio ganador, lo que da lugar a que se eliminen las macros (es decir, se sustituyan por una cadena de longitud cero). |
E-Planning SSP contabiliza la impresión junto con la ejecución del código HTML del anuncio (counting via adm). En consecuencia, nurl no es soportado. |
{ "id": "658cc151efd92b1b", "cur": "USD", "seatbid": [ { "seat": "9ac35426a22738bc", "bid": [ { "id": "9c53f0f503c6a52d", "impid": "1", "price": 1.07, "w": 300, "h": 250, "adm": "<script type='text/javascript' src='https://ads.us.e-planning.net/sample/ad '></script><img src='https://u-iad02-i01.e-planning.net/eli/1/5a1ad71d2d53a0f5?b=018b8f1a3b2a9341&s=9ac35426a22738bc&p =${AUCTION_PRICE:B64}' />", "adomain": ["advertiser.com"] } ] } ] } |
Cuando E-Planning SSP gana una subasta debe informar cual fue el precio final reemplazando las macros correspondientes.
La macro de precio se encuentra en Bidresponse.seatbid[...].bid[...].adm y debe ser reemplazada en el lugar donde se encuentra. Por favor, utilice la misma divisa de la subasta (usualmente USD).
Hay dos tipos de macros diferentes:
${AUCTION_PRICE}: Debe ser reemplazada con el precio final en CPM
${AUCTION_PRICE:B64}: Idem ${AUCTION_PRICE} pero codificada utilizando base64
E-Planning SSP utiliza la macro codificada en base64 por default. Por favor, notifique a su contacto técnico en caso de no soportarla. |
E-Planning proveerá al SSP con una URL de sincronización de usuarios, la cual debe ser insertada en los sitios a subastar utilizando una etiqueta <iframe>. Luego de que la URL sea llamada en el navegador E-Planning creará un nuevo ID de usuario. Luego E-Planning redirigirá a una URL provista por el SSP. En la misma debe existir una macro $UID que será reemplazada por el ID de usuario de E-Planning (buyeruid). Este proceso solo aplica para subastas Web, no siendo necesario en In-App.
Por ejemplo, si la URL del SSP es https://www.test-partner-domain.com/?uid=$UID, E-Planning reemplazará la macro $UID con el correspondiente buyeruid (por ejemplo "e3cf38b549b50e01") y redirigirá al usuario a la URL final. El SSP debe pasar la URL a redirigir en el parametro redir= de la URL de E-Planning:
https://ads.us.e-planning.net/uspd/1/<CLIENT_ID>?ruidm=1&du=<ENCODED_REDIRECT_URL>
Note que <CLIENT_ID> es un valor provisto por E-Planning
Este es un ejemplo de como debe ser insertada la URL:
<iframe src="https://ads.us.e-planning.net/uspd/1/5a1ad71d2d53a0f5?ruidm=1&du=https%3A%2F%2Ftest-partner-domain.com%2F%3Fuid%3D%24UID" width="0" height="0" style="display: none;"></iframe> |
La cual en el ejemplo redirigirá finalmente a:
https://test-partner-domain.com/?uid=e3cf38b549b50e01
El formato utilizado por E-Planning para los buyeruids es de 16 caracteres alfanuméricos, por ejemplo e3cf38b549b50e01
E-Planning puede enviar y recibir bid requests y bid responses comprimidos. Se recomienda el uso de compresión en ambos para disminuir la latencia en la subasta y reducir el uso de ancho de banda.
Por default los bid responses no estarán comprimidos.
E-Planning soporta conexiones HTTP Keep-Alive. Agregando la cabecera HTTP Connection: Keep-Alive múltiples bid requests pueden ser enviados utilizando la misma conexión TCP. Se recomienda su implementación ya que reduce la latencia de la subasta evitando el inicio de una nueva conexión TCP para cada bid request enviado.