AD, en lo técnico: cómo funciona y cómo se integra

Qué es

Qué es AD y para quién es

AD es un servidor de anuncios directo: sin subasta y sin caja negra. Un publisher vende el espacio publicitario de un sitio que ya opera; un anunciante elige las zonas exactas, fija el targeting y lanza. Una misma cuenta puede jugar cualquiera de los dos papeles — o los dos.

Acceso

Cómo entrar

Inicie sesión en forhosting.com y elija «Administrar mi AD» en el menú de su cuenta. El panel se abre con una sesión corta — una credencial que caduca en minutos (nunca más de 60) y que no deja ninguna clave permanente en el navegador. Cuando caduque, vuelva a abrirlo desde el mismo menú.

Para integraciones, cree una clave de API desde el panel (Perfil) o con POST /tenants/:id/keys. Dos ámbitos: tenant (acceso completo a su propia cuenta) y read (solo lectura, para tableros y bots). La clave se muestra una sola vez; si se pierde, cree otra y revoque la anterior.

Nuestro equipo puede abrir su panel «como cliente» para ayudarle: esa sesión dura como máximo 15 minutos y lleva el nombre de la persona que la abrió. La casa nunca opera su cuenta con una clave permanente.

Anunciantes

Campañas y targeting

La campaña es el contenedor: nombre, fechas, presupuestos opcionales y el targeting que comparten sus creatividades. Nace como draft; usted la pone active, paused o ended cuando termina. Solo se sirven las creatividades activas de una campaña activa — pausar la campaña detiene la entrega al instante.

Entre las campañas elegibles el motor no sortea al azar: va por turnos. Sirve una, después la otra, y solo cuando están igualadas desempata el peso que usted dio a cada creatividad — enseñarle diez veces seguidas la misma campaña al mismo visitante no vende nada. Los turnos se cuentan por visitante y por zona, en el propio navegador del visitante; con las cookies bloqueadas degrada al sorteo ponderado. Una creatividad con tope de entrega lleva además pacing: cada 5 minutos se reajusta su peso para que el presupuesto se reparta entre los días de la campaña en vez de quemarse por la mañana. El pacing solo frena — nunca inventa tráfico.

Una creatividad solo se sirve en una zona donde tenga un pedido pagado (vea «Comprar espacio»). Campaña, creatividad, zona y pedido se ven en el panel (Campañas, Creatividades, Comprar espacios).

Anunciantes

Creatividades: seis tipos, una etiqueta

Toda creatividad tiene una URL de clic, un tamaño fijo opcional y un peso. Los límites de esta tabla son los que el API aplica al subir — se leen del código, no se escriben aquí.

El contrato HTML5

Su index.html se carga en un iframe con el destino del clic en la query como clickTag. Léalo y úselo como href de su área clicable — esa URL va firmada y cuenta el clic; un enlace escrito a mano no lo cuenta.

// index.html — the click goes where the engine says
var clickTag = new URLSearchParams(location.search).get("clickTag");
document.getElementById("ad").href = clickTag;

Si su creatividad necesita crecer, dígale a la página su alto real con postMessage. La etiqueta también le dice a la creatividad el ancho del hueco al cargar y en cada cambio de tamaño, y le manda visible la primera vez que el hueco entra en pantalla — el momento de arrancar una animación. Se aplican altos de hasta 10000 px.

// creative → page: ask for the real height (applied up to 10000 px)
parent.postMessage({ fh: "resize", nh: document.documentElement.scrollHeight }, "*");

// page → creative: { fh: "size" | "visible" }
window.addEventListener("message", function (ev) {
  if (ev.data && ev.data.fh === "visible") { /* start your animation */ }
});

Una creatividad mínima que hace las dos cosas, lista para subir tal cual: descargue el ZIP de ejemplo

Macros de las creatividades script

En una creatividad script el motor sustituye estos marcadores al publicar la zona. Una plantilla del panel es lo mismo con marcadores adicionales que usted rellena en un formulario.

Varios destinos en una misma creatividad

Una creatividad puede llevar hasta 8 destinos con nombre además de su URL de clic principal — un botón de App Store y otro de Google Play en la misma pieza, por ejemplo. Cada uno tiene un id de hasta 20 caracteres en minúscula; main queda reservado para la URL principal.

En una creatividad HTML5 llegan en la query como clickTag_<id>, junto al clickTag de siempre; en una creatividad script se escribe [CLICKTAG:<id>]. Todos pasan por el tracker del clic, así que suman al total y se desglosan por botón en los reportes.

Tracking de terceros y consentimiento

Cualquier creatividad puede llevar un código de tracking (un píxel o script de un proveedor de medición). Se emite después del anuncio con cada src convertido en data-src, de modo que nada carga hasta que la etiqueta lo permite.

Si indica el id IAB TCF v2 del proveedor, el código solo carga tras el consentimiento del visitante para ese proveedor, con ${GDPR} y ${GDPR_CONSENT_n} rellenados. La etiqueta espera hasta 10 segundos al gestor de consentimiento del sitio; sin id de proveedor el código carga como un elemento normal.

Revisión manual

Toda creatividad nace en_revision y la revisa una persona antes de poder servirse. Aprobada, usted la pone active o paused; rechazada, ve el motivo y puede corregirla y volver a enviarla. Nada de una creatividad sin revisar — ni el markup, ni el script, ni el código de tracking — llega jamás a un visitante.

Cambiar la URL de clic, el contenido o el fichero de una creatividad aprobada la devuelve a revisión: lo que se aprobó es lo que se sirve, nunca otra cosa.

Anunciantes

Comprar espacio

El escaparate lista todas las zonas en venta: sitio, tamaño, formatos admitidos, modelo de venta y el precio que fijó el publisher. Usted elige una zona, una creatividad de un formato que la zona admita, un importe y una fecha de inicio. La cotización y el cobro usan la misma fórmula:

El pedido mínimo es $5; la cotización rechaza cualquier importe inferior. Un pedido es una compra prepagada de volumen — el dinero se mueve una vez, al comprar. Mande una idempotencyKey y una petición repetida devuelve el mismo pedido en vez de crear otro.

Cómo se paga

Al marcarse pagado un pedido, el 80% de su precio final se acredita al publisher de la zona — sobre el pedido entero, no prorrateado por entrega. La zona se republica de inmediato y su creatividad empieza a servirse en el minuto siguiente.

Publishers

Sitios, zonas, etiqueta y pagos

Sitios

Registre un sitio por su dominio (Ser publisher). Nace pendiente y se verifica solo: publique el token que le damos en /.well-known/fh-ad-site-verification.txt o en la portada, pida la verificación y el sitio se activa por su cuenta — sin cola y sin que nadie de aquí tenga que mirarlo antes. Un dominio sin verificar no puede cobrar reparto. Retirar un sitio inicia un enfriamiento de 90 días sobre el dominio: nadie más puede registrarlo mientras tanto y heredar su historial.

Zonas

La zona es el hueco vendible: un nombre, un tamaño en píxeles (o -1 para ancho adaptable), los formatos que admite, un modelo de venta con su precio y si está en venta en el escaparate. Puede fijar una creatividad de respaldo propia que se sirve cuando ninguna otra es elegible — se salta targeting y topes.

Dos comportamientos opcionales corren en el navegador del visitante: el autorrefresco (una petición nueva cada N segundos, mínimo 5; una pestaña oculta nunca refresca, y un hueco que vuelve vacío conserva el anuncio anterior) y el reenvío de parámetros (la query de la página viaja con el clic al destino del anunciante).

Cómo se dispara el intersticial

El overlay es una propiedad de la zona, no del sitio: no hay que pegar nada para él —la etiqueta construye lo que necesita— y usted cambia el ritmo desde el panel donde compra. Cuatro modos:

Un ritmo fijo cansa igual al visitante el día 30 que el día 1 — para eso está el calendario escalonado: cobra pronto la primera impresión y después se aparta. La cuenta vive en el propio navegador del visitante; si el almacenamiento está bloqueado, degrada a contar en memoria en vez de romperse.

Cuándo se piden los anuncios — su sitio va primero

Los anuncios no deben frenar su sitio, y el ajuste vive aquí, no en su HTML. Cada sitio elige cuándo pide la etiqueta su primer anuncio:

Y mientras el anuncio va de camino el hueco no queda en blanco: la etiqueta pinta un marcador de posición y aprende el alto — la primera visita reserva un tamaño prudente, y a partir de la segunda el hueco reservado es el exacto, así que la página no salta cuando el anuncio aterriza. Ese salto es lo que Google mide como desplazamiento del diseño, y es el motivo habitual de que una red de anuncios le cueste la puntuación a un sitio.

La etiqueta

Péguela donde deba salir el anuncio — o deje que la zona diga dónde va y sáltese este paso entero (vea «Dónde sale el anuncio», más abajo). El id de zona sale del panel (Sitios y zonas). La misma etiqueta sirve todos los formatos que la zona admita; una zona intersticial usa también la etiqueta estándar.

Estándar (un div y un script, asíncrona):

<div data-fh-ad="zon_XXXXXXXXXXXXXXXXXXXXXXXX"></div>
<script src="https://api.ad.forhosting.com/ad-tag.js" async></script>

Legacy, para CMS que no ejecutan scripts asíncronos:

<script src="https://api.ad.forhosting.com/ad-serve?zone=zon_XXXXXXXXXXXXXXXXXXXXXXXX&mode=js"></script>

Enlace de texto: una URL que cuenta la impresión y redirige al anunciante:

https://api.ad.forhosting.com/ad-serve?zone=zon_XXXXXXXXXXXXXXXXXXXXXXXX&mode=link

La etiqueta se actualiza sola: su URL no lleva versión y no cambia nunca, así que una mejora nuestra llega a todos los sitios en unos 60 minutos y nadie edita ninguna plantilla (hoy sirve v11, en la cabecera x-tag-version). Espera a que su página termine de cargar antes de pedir nada, así que los anuncios nunca compiten con su contenido. Sus únicas marcas en su página son el atributo data-fh-ad y el id del overlay — comprobados contra las listas habituales de bloqueo, con cero coincidencias. Los topes de frecuencia usan una cookie propia.

Si la misma posición se repite a lo largo de una página — «cada N mensajes» en un foro, por ejemplo — la etiqueta pide todas sus copias en una sola petición (hasta 10), y el tope de frecuencia avanza dentro de ese lote, así que una misma creatividad no puede llenar todos los huecos de la página. Si nuestro lado no entiende el lote, la etiqueta vuelve a pedir hueco por hueco antes que dejar la página vacía. Repetir una zona se declara con nosotros: por norma, una zona por emplazamiento, porque la zona es lo que agrupa un reporte.

Dónde sale el anuncio — sin tocar su plantilla

Una zona puede declarar dónde va: un selector CSS (hasta 300 caracteres) y una posición respecto a lo que ese selector encuentre. El hueco lo crea la etiqueta, así que mover un anuncio cuesta un cambio en el panel y no una edición de su tema.

Dos números opcionales gobiernan la repetición: uno coloca el hueco cada N coincidencias (hasta 50) y un tope limita cuántos huecos se crean — 4 por omisión cuando se repite, 20 como máximo. Siempre hay tope: un selector suelto como p casa cientos de veces en un artículo largo, y ese límite no puede depender de que quien configura se acuerde de ponerlo.

Dos cosas que conviene saber. Un div data-fh-ad que usted ponga en la plantilla manda: la etiqueta no añadirá un segundo hueco para esa zona, así que puede pasar de un método al otro sin pagar dos impresiones por una. Y un selector que no casa no da error — su página se ve perfecta sin el anuncio y el panel sigue en verde. Compruebe la colocación en un navegador, en escritorio y en móvil: un selector puede existir en el artículo y no en la portada, o medir 1360 px en escritorio y 0 en el teléfono.

WordPress: nada que pegar

Si su sitio es WordPress hay un complemento, forhosting-ad. Se instala y él se presenta solo: publica un reto en su propio dominio, nosotros lo leemos y la credencial se entrega una sola vez. Usted no teclea ninguna clave, ningún id ni ningún token — y demostrar que controla el dominio no es lo mismo que estar invitado: no se emite nada hasta que el sitio se aprueba.

A partir de ahí las zonas se manejan desde el panel, la colocación incluida. El complemento además le pide a la caché de páginas que tenga su sitio que purgue las páginas cuyo marcado cambió — reconoce las habituales y se lo pide a cada una a su manera. Una página cacheada es el motivo más común de que la etiqueta esté en su HTML y el anuncio siga sin aparecer, y no se ve desde la línea de comandos: la copia vieja sólo se le sirve a un navegador de verdad.

Hay un segundo complemento, forhosting-ad-updater, que recibe un paquete y lo instala. Eso es, por diseño, un canal de ejecución remota, así que sólo lo instalamos en sitios nuestros; en el suyo las actualizaciones llegan por el canal propio de WordPress y usted decide cuándo aplicarlas.

Pagos

Su 80% de cada pedido pagado se acumula en el panel (Pagos). Cuando lo acumulado llega a $10, solicite el pago con el método de su perfil (paypal, bank, other); nuestro equipo paga fuera del panel y anota la referencia.

Estados: accrued → requested → processing → paid; un desembolso fallido vuelve a usted con el motivo para que lo solicite de nuevo con los datos corregidos.

Para todos

Reportes

Impresiones, clics e inicio/fin de vídeo se cuentan en el borde, en cada petición. Antes de contar, el tráfico se filtra: rastreadores conocidos por su agente de usuario, redes de centros de datos, peticiones con una puntuación de bot muy baja y cualquier IP que repita la misma petición en menos de 2 segundos. Una petición filtrada recibe igualmente su anuncio o su redirección — lo que se protege es el contador.

Cada 5 minutos los conteos se consolidan en filas diarias por creatividad, zona y host del referente. El día en curso puede ir hasta ese tiempo por detrás; los días cerrados no cambian nunca.

El panel (Reportes) muestra totales y una serie diaria, el CTR (clics ÷ impresiones × 100) y el eCPM (valor entregado × 1000 ÷ impresiones), para el lado anunciante o el lado publisher, y un ranking agrupado por cualquiera de seis dimensiones:

Cualquiera de estas vistas se puede filtrar además por campaña, creatividad, zona, host del referente o destino, y las mismas cifras están disponibles a través del API.

Antes de contar nada, el tráfico pasa por el filtro de bots, que la casa opera en uno de tres modos: block (el de por defecto: una petición filtrada recibe igualmente su anuncio, simplemente no cuenta), log (cuentan y se registran aparte, para medir antes de decidir) y off.

Integrar

Referencia del API

URL base https://api.ad.forhosting.com. Mande su clave como token Bearer; cuerpos y respuestas son JSON. Toda respuesta tiene la forma {"success":true,"data":…} o {"success":false,"error":{"code","message"}} con el estado HTTP correspondiente.

curl https://api.ad.forhosting.com/me \
  -H "Authorization: Bearer ads_ten_…"

Ámbitos de las credenciales

Una credencial tenant, read o session opera siempre su propia cuenta — un tenantId enviado por el cliente se ignora. Un id que pertenece a otro devuelve 404, no 403: el API nunca confirma que exista.

Rutas

Todas las rutas que anuncia el servicio, con el ámbito que exige el enrutador — derivado del propio enrutador en cada compilación.

pública: sin credencial — el camino de servir · cualquiera: cualquier credencial válida, sobre su propia cuenta · lectura: tenant, session o read · escritura: tenant o session (read se rechaza) · system: solo la casa

Errores que conviene conocer: 401 unauthorized (credencial ausente o caducada), 403 forbidden (el ámbito no puede hacer esto), 404 not_found, 400 bad_request con el motivo en el mensaje, 409 conflict (una transición de estado no permitida), 402 insufficient_balance al pagar un pedido y 503 payments_disabled si las ventas están en pausa.

FAQ

Preguntas técnicas