Page tree
Skip to end of metadata
Go to start of metadata

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.

Contenido

Subasta

Lo que normalmente se refiere como subasta, consiste en:

  1. Un bid request enviado a E-Planning SSP (entre otros compradores) por otro SSP
  2. E-Planning SSP respondiendo con un bid response
  3. El SSP elegiendo un ganador
  4. El SSP mostrando el anuncio de la fuente ganadora

Protocolo RTB

  • E-Planning SSP utiliza como formato de transporte JSON y el metodo HTTP POST.
  • E-Planning SSP devuelve un mensaje HTTP 204 en caso de que no participe en la subasta.
  • El protocolo utilizado por E-Planning SSP es OpenRTB 2.3. Sin embargo, algunas características de OpenRTB 2.5 son soportadas (como por ejemplo Banner.format)

Bid Request

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.

Importante

  • Los campos obligatorios siempre deben ser incluidos.
  • Los campos recomendados tienen un impacto positivo en la subasta si son enviados.
  • Los campos opcionales tienen un impacto positivo en la operación y reportes, pero no influyen de forma directa en el resultado de la subasta.

Nivel superior del Bid Request

CampoTipoEstadoComentarios
idStringObligatorioUn identificador para el request. Puede ser utilizado para relacionar el bid request al bid response fuera del protocolo HTTP
tmaxIntegerRecomendadoEn milisegundos, el tiempo máximo de respuesta para participar de la subasta
atIntegerObligatorioTipo de subasta, donde 1 = First Price, 2 = Second Price Plus
impObject ArrayObligatorioVer objeto Imp
allimpsIntegerRecomendadoIndica si todas las impresiones del contexto están disponibles o no
userObjectObligatorioVer objeto User
deviceObjectObligatorioVer objeto Device
siteObjectObligatorioVer objeto Site
sourceObjectObligatorioVer objeto Source
regsObjectObligatorio para Europa
(Recomendado para el resto)
Ver objeto Regs
badvString ArrayRecomendadoListado de dominios de anunciantes bloqueados
bcatString ArrayRecomendadoListado de categorías IAB bloqueadas

Ejemplo

{
	"id": "bfebe4d6f24efacd",
	"tmax": 300,
	"at": 1,
	"cur": ["USD"],
	"imp": [{ "...": "..." }],
	"user": { "...": "..." },
	"device": { "...": "..." },
	"site": { "...": "..." },
	"source": { "...": "..." },
	"regs": { "...": "..." },
	"badv": ["ford.com","bmw.com"],
	"bcat":, ["IAB8-1","IAB8-2"]
}

Objeto Imp

CampoTipoEstadoComentarios
idStringObligatorioIdentificador único para la impresión dentro del Bid Request.
Habitualmente comienza en "1" y se incrementa progresivamente.
bannerObjectObligatorioVer objeto Banner
bidfloorcurStringObligatorioDivisa a utilizar en los precios, tanto en el bid response como en los precios mínimos.
Utiliza códigos ISO-4217, por ejemplo "USD".
bidfloorFloatObligatorioEl precio mínimo al cual la impresión puede ser vendida, expresado en la divisa especificada en bidfloorcur
secureIntegerObligatorioIndica "1" si el anuncio en el bid response debe utilizar HTTPS
instlIntegerRecomendadoIndica "1" cuando la impresión corresponde a un anuncio de página completa (Full page o Interstitial)

Ejemplo

{
	"id": "1",
	"bidfloor": 0.4286,
	"bidfloorcur": "USD",
	"secure": 1,
	"instl": 0,
	"banner": {
		"w": 300,
		"h": 250,
		"pos": 1,
		"topframe": 0
	},
	"tagid": "79a4e192e54cc0d9"
}

Objeto Banner

CampoTipoEstadoComentarios
formatObject ArrayObligatorio si no estan presentes "w" y "h"

Ver objeto Format. Tamaños soportados en la subasta.

wIntegerObligatorio si no esta presente "Format"Ancho en pixeles del banner
hIntegerObligatorio si no esta presente "Format"Alto en pixeles del banner
wminIntegerRecomendado si no esta presente "Format"

Mínimo ancho en pixeles del banner

wmaxIntegerRecomendado si no esta presente "Format"Máximo ancho en pixeles del banner
hminIntegerRecomendado si no esta presente "Format"

Mínimo alto en pixeles del banner

hmaxIntegerRecomendado si no esta presente "Format"Máximo alto en pixeles del banner
posIntegerRecomendadoPosición del anuncio en la pagina según Ad Position IAB standard
topframeIntegerRecomendado0 = El banner se encuentra dentro de un iframe, 1 = El banner se encuentra en el marco superior de la página
apiIntegerRecomendadoListado de las APIs soportadas según están descriptas en OpenRTB 2.5
battrInteger ArrayRecomendadoAtributos del creativo bloqueadas
btypeInteger ArrayRecomendadoTipos de banner bloqueados
expdirInteger ArrayOpcionalDirecciones en las cuales el banner puede ser expandido

Notas

  • Tanto el formato de tamaño de OpenRTB 2.3 como de 2.5 son soportados. Recomendamos no definir ambos a la vez, pero en caso de suceder, se ignorará el formato de OpenRTB 2.5.
    • OpenRTB 2.3: Utiliza w y h
    • OpenRTB 2.5: Utiliza format
  • Si lo que se desea vender son dos espacios separados en la misma página, por ejemplo un 728x90 en la parte superior y un 300x250 a la derecha, dos objetos Imp deben ser enviados con un tamaño independiente cada uno.
  • Si el objetivo es vender un único espacio que soporta mas de un tamaño, entonces un solo objeto Imp debe ser enviado con los tamaños soportados.

Ejemplo

Utilizando format

{
	"pos": 1,
	"format": [
		{
			"w": 300,
			"h": 600
		},
		{
			"w": 300,
			"h": 250
		}
	],
	"battr": [ 11, 12 ],
	"btype": [ 4 ]
}

Utilizando w y h

{
	"pos": 1,
	"w": 300,
	"h": 250,
	"wmin": 300,
	"wmax": 300,
	"hmin": 50,
	"hmax": 600,
	"battr": [ 11, 12 ],
	"btype": [ 4 ]
}

Objeto Format

CampoTipoEstadoComentarios
wIntegerObligatorioAncho en pixeles del tamaño
hIntegerObligatorioAlto en pixeles del tamaño

Objeto Site

CampoTipoEstadoComentarios
idStringObligatorioID del sitio en el SSP
pageStringObligatorioURL de la página donde se mostrará la impresión.
Si es desconocido, el campo no debe ser enviado o estar en blanco.
publisherObjectObligatorioVer objeto Publisher
domainStringRecomendadoDominio de la página donde se mostrará la impresión
catString ArrayRecomendadoArray de categorías IAB del sitio
refStringRecomendadoURL de la página desde donde se llego a la página actual

Ejemplo

{
	"id": "123",
	"page": "http://example.com/section/page.html",
	"cat": [ "IAB1-2" ],
	"publisher": {
		"id": "456",
		"domain": "example.com",
		"name": "Example Inc"
	}
}

Objeto Publisher

CampoTipoEstadoComentarios
idStringObligatorioEl ID del publisher. Debe ser suficiente para identificar a la parte finalmente pagada
domainStringRecomendadoDominio del publisher
nameStringRecomendadoNombre del publisher

Ejemplo

{
	"id": "456",
	"domain": "example.com",
	"name": "Example Inc"
}

Objeto User

CampoTipoEstadoComentarios
idStringRecomendadoID del usuario en el DSP
buyeruidStringRecomendadoID del usuario en E-Planning SSP. Ver sección Sincronización de usuarios

Ejemplo

{
	"id": "1234567",
	"buyeruid": "e3cf38b549b50e01",
	"consent": "BOEFEAyOEFEAyAHABDENAI4AAAB9vABAASA"
}

Objeto Device

CampoTipoEstadoComentarios
uaStringObligatorioEl valor de user-agent para el navegador
ipStringObligatorioDirección IP del usuario
dntIntegerRecomendadoEl consentimiento del usuario para ser seguido (tracked). Si el usuario no desea ser seguido este campo debe valer 1.
languageStringOpcionalEl idioma del navegador del usuario utilizando ISO- 639-1-alpha-2
carrierStringRecomendadoProveedor de servicios de Internet del usuario
connectiontypeIntegerRecomendadoTipo de conexión
osStringRecomendadoSistema operativo del dispositivo
geoObjectRecomendadoVer objeto Geo

Ejemplo

{
	"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"
	}
}

Objeto Geo

CampoTipoEstadoComentarios
countryStringObligatorioPaís del usuario en ISO- 3166-1-alpha-3
cityStringRecomendadoCiudad del usuario
latitudeFloatRecomendadoLatitud desde -90.0 hasta +90.0, donde negativo significa sur
longitudeFloatRecomendadoLongitud desde -180.0 hasta +180.0, donde negativo es oeste

Ejemplo

{
	"latitude": 37.4194,
	"longitude": -122.164,
	"country": "USA",
	"city": "Stanford”
}

Objeto Regs

CampoTipoEstadoComentarios
coppaIntegerRecomendadoIndica si la petición esta sujeta a regulaciones de COPPA, donde 0 = no, 1 = si
gdprInteger

Obligatorio para Europa
(Recomendado para el resto)

Indica si la petición esta sujeta a regulaciones de GDPR, donde 0 = no, 1 = si
ext.consentStringRecomendadoSi la petición esta sujeta a regulaciones de GDPR, indica el Consent String del usuario
us_privacyStringRecomendadoIndica 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í.

Ejemplo

{
	"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"
	}
}

Objeto Source

CampoTipoEstadoComentarios
fdIntegerObligatorioEntidad responsable de la decisión final sobre la impresión, donde 0 = SSP, 1 = la siguiente fuente
pchainStringRecomendado si schain no esta presenteCadena TAG Payment ID
ext.schainStringRecomendado si pchain no esta presenteSegún propuesta de IAB, Supply Chain Object

Nota

Para implementaciones con pchain soportamos tanto TAG ID como identificación por dominio.

Ejemplo

Utilizando pchain

{
	"fd": 1,
	"pchain": "directseller.com:12345"
}

Utilizando schain

{
	"fd": 1,
	"ext": {
		"schain": {
			"complete": 1,
			"nodes": [
				{
					"asi":"directseller.com",
					"pid":"12345",
					"rid":"c7ecc1f7b1628d49"
				}
			]
		}
	}
}

Ejemplo de Bid Request

Ejemplo para banner (web)

{
	"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"]
}

Bid Response

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.

Nivel superior del Bid Response

CampoTipoComentarios
idStringE-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.
seatbidObject ArrayVer objeto Seatbid. Es un array para compatibilidad con OpenRTB, pero E-Planning SSP siempre devolverá un solo objeto dentro
curStringLa divisa de la oferta utilizando códigos alfanumericos ISO-4217

Objeto Seatbid

CampoTipoComentarios
seatStringUn identificador, usualmente utilizado para reflejar los requerimientos de facturación de E-Planning
bidObject ArrayVer objeto Bid

Objeto Bid

CampoTipoComentarios
idStringUn identificador del bid para assistir con el registro y seguimiento
impidStringValor del identificador envíado en el objeto Imp
priceFloatOferta hecha en CPM (1 significa que E-Planning SSP esta dispuesto a pagar 0.001 por la impresión)
admStringEl 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.
adomainString ArrayEl dominio del anunciante de la creatividad
wIntegerEl ancho del anuncio en pixeles
hIntegerEl alto del anuncio en pixeles

Nota

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.


Ejemplo de Bid Response

Ejemplo para banner (web)

{
	"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"]
				}
			]
		}
	]
}


Macros

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

Importante

E-Planning SSP utiliza la macro codificada en base64 por default. Por favor, notifique a su contacto técnico en caso de no soportarla.

Sincronización de usuarios

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).

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

Formato de buyeruid

El formato utilizado por E-Planning para los buyeruids es de 16 caracteres alfanuméricos, por ejemplo e3cf38b549b50e01

Compresión

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.

  • Para que los requests comprimidos utilizando gzip sean manejados adecuadamente debe agregar la cabecera HTTP Content-Encoding: gzip en el envio del bid request.
  • Para que los bid requests sean enviados comprimidos mediante gzip debe agregar la cabecera HTTP Accept-Encoding: gzip en el envío del bid request.

Por default los bid responses no estarán comprimidos.

Conexiones persistentes

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.

  • No labels