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, la pausa o la termina. Solo se sirven las creatividades activas de una campaña activa — pausar la campaña detiene la entrega al instante.

Entre las creatividades elegibles el motor elige al azar, ponderado por el peso que usted da a cada una. Una creatividad con tope de entrega lleva 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.

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 una persona lo verifica antes de que sus zonas puedan venderse — un dominio sin verificar no puede cobrar reparto. Retirar un sitio inicia un enfriamiento de 90 días sobre el dominio: mientras tanto nadie más puede registrarlo 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). Una zona intersticial declara además qué enlaces disparan la capa — por defecto p a, nav a, h2 a — y los segundos antes de poder cerrarla.

La etiqueta

Péguela donde deba salir el anuncio. 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 undefined minutos y nadie edita ninguna plantilla (hoy sirve v6, 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.

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 por creatividad, zona, campaña, sitio u host del referente. Solo se guarda el host del referente, nunca la URL.

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