Guías
Integrar las apps de Navo en el sitio de un cliente
Inserta seguimiento de contenedores en tu web, tarifas, itinerarios marítimos y modo IA, con tu marca, una etiqueta script y clave bloqueada por dominio.
Puedes incrustar el seguimiento de contenedores en el sitio web propio de un cliente, junto con tarifas de flete e itinerarios marítimos. Son las mismas apps que ves en el sitio de ejemplo de un transitario: un widget de búsqueda para la página de inicio y una página completa para cada app. Cada una se muestra con el nombre, el logo y el color del cliente. Cada vista tiene su propio enlace, de modo que un visitante puede enviar a un compañero un contenedor, una búsqueda de tarifa, una tarifa, una salida, un buque o un puerto, y se abre en el sitio del cliente.
No se necesita ninguna clave API ni servidor en el lado del cliente. La clave de incrustación es pública y solo funciona en los dominios que indiquemos para ella.
Qué nos envía el cliente
| Elemento | Ejemplo | Obligatorio |
|---|---|---|
| Nombre de la empresa tal como deben verlo los visitantes | Acme Logistics | Sí |
| Dominios donde se ejecutarán las apps (producción, staging) | acme.com, www.acme.com, staging.acme.com | Sí |
| Logo, SVG o PNG, marca cuadrada u horizontal | https://acme.com/logo.svg | Sí |
| Color de marca, un valor hex | #0e6ba8 | Sí |
| Más colores, fuentes, redondeo de esquinas | ver Apariencia | Opcional |
| E-mail que recibe las solicitudes de reserva | [email protected] | Para tarifas de flete |
| URL de webhook para solicitudes de reserva (a su CRM/TMS) | https://acme.com/hooks/navo | Opcional |
| Qué apps quiere | cualquiera de tracking, freight, schedules; modo AI activado o desactivado | Sí |
| Límite de uso por app, al mes o al año | tracking: 300 envíos únicos al mes | Sí |
| Páginas donde vivirá cada app | /track, /rates, /schedules | Recomendado |
| “Con tecnología de Navo” mostrado u oculto | mostrado | Predeterminado: mostrado |
Creamos la clave y devolvemos los snippets de abajo, con la clave ya incluida.
Qué puede incluir una clave
Una clave abre una app o varias, y el modo AI es un interruptor aparte:
| Paquete | Apps en la clave | Qué obtiene el visitante |
|---|---|---|
| Solo tracking | tracking | Página de tracking; el widget de búsqueda muestra la caja de tracking sin pestañas y sin interruptor de AI |
| Tracking con AI | tracking, ai | Lo mismo, más modo AI en el widget de búsqueda y “Preguntar a AI” en los envíos |
| Tarifas e itinerarios | freight, schedules | Dos pestañas en el widget de búsqueda, las páginas de tarifas e itinerarios |
| Todo | tracking, freight, schedules, ai | Las tres pestañas, modo AI, todas las páginas |
El widget se construye a partir de la clave: una pestaña, una página o un botón de AI que la clave no abre no se dibuja en absoluto, y nuestro servidor rechaza sus datos aunque alguien fuerce la solicitud.
Límites de uso
Cada app de una clave tiene su propio límite, por mes natural o por año natural (UTC). Qué cuenta como una unidad:
| App | Una unidad | Repeticiones gratuitas |
|---|---|---|
tracking | Un envío único (contenedor, reserva o número B/L) | El mismo envío durante el resto del periodo |
freight | Una búsqueda de tarifa (ruta y equipo) | La misma búsqueda el mismo día |
schedules | Una búsqueda de itinerario (ruta, buque o puerto) | La misma búsqueda el mismo día |
ai | Una pregunta al asistente de AI | Ninguna |
Ejemplo: tracking con 300 envíos únicos al mes. Los visitantes del cliente pueden abrir y refrescar esos 300 envíos tantas veces como quieran durante todo el mes; el envío 301 se rechaza hasta el día 1 del mes siguiente. Cuando una app alcanza su límite, los visitantes ven “Este servicio está pausado en este sitio por ahora. Ponte en contacto con
Instalación
Pon el loader una vez en cada página que muestre una app:
<script src="https://navo24.com/embed.js" async></script>
Después, un contenedor donde deba aparecer la app.
Widget de búsqueda (hero de la página de inicio, o cualquier página). Una caja con una pestaña por cada app de la clave (tracking, tarifas, itinerarios) y modo AI si la clave lo incluye. Con una sola app no hay pestañas:
<div
data-navo-app="search"
data-navo-key="nve_YOUR_KEY"
data-navo-pages='{"tracking":"/track","freight":"/rates","schedules":"/schedules"}'
></div>
Con data-navo-pages, el widget envía a los visitantes a las páginas propias del cliente. Sin él, el resultado se abre dentro del propio frame del widget.
Página de tracking (/track):
<div data-navo-app="tracking" data-navo-key="nve_YOUR_KEY"></div>
Página de tarifas de flete (/rates):
<div data-navo-app="freight" data-navo-key="nve_YOUR_KEY"></div>
Página de itinerarios marítimos (/schedules), con tres pestañas: por ruta, por buque, por puerto:
<div data-navo-app="schedules" data-navo-key="nve_YOUR_KEY"></div>
Usa el mismo valor de data-navo-pages en cada app para que los enlaces cruzados (por ejemplo “Mostrar tarifas” en una salida, o “Itinerario del buque” en un envío) aterricen en la página correcta del sitio del cliente.
Opciones
| Atributo | Qué hace |
|---|---|
data-navo-app | search, tracking, freight o schedules. |
data-navo-key | La clave de incrustación del sitio. |
data-navo-pages | Mapa JSON de app a ruta de página en el sitio del cliente. |
data-navo-height | Altura fija en px. Por defecto, el frame crece con su contenido; tracking es un mapa completo, 680 px. |
data-navo-sync | off mantiene la URL de la página sin cambios mientras el visitante navega. |
data-navo-theme | JSON con colores, fuentes y esquinas, ver Apariencia. |
Sitios con una Content Security Policy
Si el sitio envía una cabecera Content-Security-Policy (o una <meta http-equiv>) con script-src o frame-src, añade navo24.com a ambas, de lo contrario el navegador bloquea el loader o el frame y el contenedor queda vacío:
script-src ... https://navo24.com;
frame-src ... https://navo24.com;
Con child-src en lugar de frame-src, añádelo ahí. No hace falta nada más: las apps cargan sus datos, fuentes y mapas dentro del frame, bajo nuestra propia política. La consola del navegador indica la directiva bloqueada si falta alguna.
Eventos para analítica y CRM
El contenedor dispara eventos DOM cuando un visitante hace algo, para que el sitio pueda enviarlos a Google Analytics, a un gestor de etiquetas o a su CRM. Hacen bubble, así que un único listener en document captura todas las apps de la página.
| Evento | Cuándo | event.detail |
|---|---|---|
navo:search | Una búsqueda devolvió resultados | app (tracking, freight, schedules) y la consulta: ref, o origin, destination, container |
navo:booking | Se envió una solicitud de reserva | reference, origin, destination, container, quantity, carrier, price, currency |
navo:limit | Un límite detuvo una búsqueda | app, code (por ejemplo site_busy, rate_limited) |
<script>
document.addEventListener('navo:search', (e) => gtag('event', 'navo_search', e.detail));
document.addEventListener('navo:booking', (e) => gtag('event', 'generate_lead', { value: e.detail.price, currency: e.detail.currency, transaction_id: e.detail.reference }));
</script>
Los datos de contacto del visitante no van en los eventos: solo se envían al e-mail de reservas y al webhook.
Apariencia
Por defecto, las apps toman el color de marca del cliente desde la clave. Para ajustarlas mejor al sitio, añade data-navo-theme al contenedor: colores, fuentes, redondeo de esquinas y modo oscuro.
<div
data-navo-app="freight"
data-navo-key="nve_YOUR_KEY"
data-navo-theme='{"accent":"#e4002b","text":"#1a1a1a","heading":"#002f6c","font":"Inter","radius":6,"buttonRadius":6}'
></div>
Todas las claves son opcionales. Un valor que no sea válido se ignora, el resto sigue aplicándose.
| Clave | Qué cambia | Ejemplo |
|---|---|---|
accent | Botones, enlaces, pestañas activas, interruptores, anillo de foco. Los tonos hover y pulsado se calculan a partir de él | "#e4002b" |
text | Texto principal | "#1a1a1a" |
muted | Texto secundario: etiquetas, ayudas, fechas | "#6b7280" |
heading | Encabezados, nombres de navieras y buques, líneas de mapa | "#002f6c" |
background | Fondo de página de la app. "transparent" deja ver el fondo propio del cliente | "#ffffff" |
surface | Tarjetas, inputs, franjas de tabla | "#f5f7fa" |
border | Bordes y separadores | "#e5e7eb" |
success | Estados positivos: entregado, puntual, más barato | "#15803d" |
radius | Redondeo de esquinas de tarjetas y paneles, px (0 a 40) | 8 |
buttonRadius | Redondeo de esquinas de botones e inputs, px. 999 crea píldoras (el valor predeterminado) | 6 |
font | Fuente del cuerpo. Cualquier familia de Google Fonts se carga por ti; "system" usa la fuente del sistema del visitante | "Inter" |
headingFont | Fuente para encabezados, mismas reglas. Sin ella, los encabezados usan font | "Playfair Display" |
fontCss | Tu propia hoja de estilos de fuentes (URL https:// con reglas @font-face), para fuentes que no están en Google Fonts. Entonces font y headingFont nombran familias de ese archivo | "https://acme.com/fonts/brand.css" |
mode | "dark" para sitios con diseño oscuro | "dark" |
Los colores son hex: #rgb, #rrggbb o #rrggbbaa.
Puntos de partida listos para usar:
<!-- Corporate: square corners, navy headings -->
data-navo-theme='{"accent":"#003a70","heading":"#003a70","font":"Source Sans 3","radius":2,"buttonRadius":2}'
<!-- Soft: rounded, light grey cards -->
data-navo-theme='{"accent":"#0f766e","surface":"#f3f4f6","font":"Nunito","radius":16,"buttonRadius":999}'
<!-- Dark site -->
data-navo-theme='{"mode":"dark","accent":"#f59e0b","background":"#0b1220","surface":"#111a2e","border":"#1f2a44","text":"#e5e7eb","muted":"#94a3b8"}'
<!-- Blend into the page: the app draws no background of its own -->
data-navo-theme='{"background":"transparent","font":"system"}'
Un tema para todas las páginas. También podemos guardar el tema en la clave. Entonces todos los contenedores de todas las páginas lo reciben sin el atributo, y podemos ajustarlo después sin cambios en el sitio del cliente. data-navo-theme en un contenedor sigue teniendo prioridad sobre el tema de la clave, clave por clave.
El tema solo llega a la app dentro del frame: nunca cambia la propia página del cliente.
React y Next.js, con indexación de búsqueda
Usa esto cuando el sitio del cliente esté creado con React o Next.js y el contenido de la app deba indexarse como página del cliente (por ejemplo, una página por ruta, “itinerario marítimo de Shanghai a Hamburg”).
Consta de dos partes:
- Snapshot. El servidor del cliente obtiene de nosotros los datos de la ruta como HTML plano (tabla de itinerarios o tabla de tarifas, un encabezado, un resumen de una línea y marcado schema.org) y los pone en su propia página. Los motores de búsqueda lo indexan como contenido del cliente, en la URL del cliente.
- App. En el navegador, la app interactiva se monta encima, con búsqueda, filtros, detalles y reserva. El snapshot permanece en la página como una tabla plegable bajo la app, de modo que crawlers y visitantes ven el mismo contenido.
Endpoint de snapshot
GET https://api.navo24.com/v1/demo/embed/snapshot
?key=nve_YOUR_KEY
&app=schedules schedules | freight
&origin=CNSHA UN/LOCODE
&destination=DEHAM UN/LOCODE
&container=40HC freight only: 20GP | 40GP | 40HC
&host=acme.com the client's domain, must be on the key
&format=html optional: the HTML block only
Sin format=html, la respuesta es JSON:
{
"data": {
"app": "schedules",
"title": "Sailing schedule Shanghai to Hamburg",
"description": "153 sailings from Shanghai (CNSHA) to Hamburg (DEHAM) in the next 6 weeks, 10 carriers, transit from 34 days.",
"items": [{ "carrier": "Yang Ming", "vessel": "MSC OLIVIA", "voyage": "GL642W", "etd": "2026-10-24T00:00:00", "eta": "2026-12-03T00:00:00", "transit_days": 40, "direct": true }],
"html": "<section class=\"navo-snapshot\">…</section>",
"as_of": "2026-10-22T08:52:51Z"
}
}
Usa title y description para el <title> de la página y la meta description, html para el cuerpo. La respuesta puede cachearse durante 30 minutos (Cache-Control: max-age=1800). Un snapshot cuenta como una búsqueda contra el límite de la app; la misma ruta el mismo día es gratis. Tracking no tiene snapshot: los envíos son privados para el visitante.
Next.js (App Router)
// app/schedules/[lane]/page.tsx e.g. /schedules/cnsha-deham
import NavoApp from './NavoApp';
const KEY = 'nve_YOUR_KEY';
const API = 'https://api.navo24.com/v1/demo/embed/snapshot';
async function snapshot(lane: string) {
const [origin, destination] = lane.toUpperCase().split('-');
const q = new URLSearchParams({ key: KEY, app: 'schedules', origin, destination, host: 'acme.com' });
const r = await fetch(`${API}?${q}`, { next: { revalidate: 1800 } });
return r.ok ? (await r.json()).data : null;
}
export async function generateMetadata({ params }: { params: { lane: string } }) {
const s = await snapshot(params.lane);
return s ? { title: `${s.title} | Acme Logistics`, description: s.description } : {};
}
export default async function Page({ params }: { params: { lane: string } }) {
const s = await snapshot(params.lane);
const [origin, destination] = params.lane.toUpperCase().split('-');
return (
<main>
<NavoApp
app="schedules"
embedKey={KEY}
view={{ origin, destination }}
snapshotHtml={s?.html}
theme={{ accent: '#e4002b', font: 'Inter' }}
/>
</main>
);
}
// app/schedules/[lane]/NavoApp.tsx
'use client';
import { useEffect, useRef, useState } from 'react';
const SRC = 'https://navo24.com/embed.js';
function loadNavo(): Promise<void> {
const w = window as any;
if (w.NavoEmbed) return Promise.resolve();
return new Promise((ok) => {
let s = document.querySelector<HTMLScriptElement>(`script[src="${SRC}"]`);
if (!s) { s = document.createElement('script'); s.src = SRC; s.async = true; document.head.appendChild(s); }
s.addEventListener('load', () => ok(), { once: true });
});
}
type Props = {
app: 'search' | 'tracking' | 'freight' | 'schedules';
embedKey: string;
view?: Record<string, string>; // opens this lane right away
pages?: Record<string, string>;
theme?: Record<string, string | number>;
snapshotHtml?: string; // server-rendered data for search engines
};
export default function NavoApp({ app, embedKey, view, pages, theme, snapshotHtml }: Props) {
const box = useRef<HTMLDivElement>(null);
const [live, setLive] = useState(false); // until the app is up, the table is open
useEffect(() => {
if (view && !new URLSearchParams(location.search).get('navo')) {
const u = new URL(location.href);
u.searchParams.set('navo_app', app);
u.searchParams.set('navo', new URLSearchParams(view).toString());
history.replaceState(history.state, '', u);
}
loadNavo().then(() => { (window as any).NavoEmbed.mount(); setLive(true); });
}, [app, embedKey]);
return (
<>
<div
ref={box}
data-navo-app={app}
data-navo-key={embedKey}
data-navo-pages={pages ? JSON.stringify(pages) : undefined}
data-navo-theme={theme ? JSON.stringify(theme) : undefined}
/>
{snapshotHtml && (
<details open={!live}>
<summary>All results as a table</summary>
<div dangerouslySetInnerHTML={{ __html: snapshotHtml }} />
</details>
)}
</>
);
}
Cómo lo ve un motor de búsqueda: el título y la descripción propios de la página, un encabezado y una tabla completa de salidas (o tarifas) en el HTML, con marcado Dataset. Cómo lo ve un visitante: la app en vivo, ya abierta en esa ruta, con los mismos resultados como tabla plegada debajo. Los visitantes sin JavaScript ven la tabla abierta. La tabla está plegada, no oculta, así que la página no muestra a los crawlers nada que un visitante no pueda abrir.
El HTML del snapshot viene de nuestro servidor con todos los valores escapados, así que es seguro insertarlo. Dale estilo con las clases .navo-snapshot y .navo-snapshot-table si alguna vez se muestra.
Otros frameworks de servidor (Remix, Astro, Nuxt, PHP, WordPress) funcionan igual: obtén el snapshot en el servidor, imprime html en la página y pon el contenedor junto a él.
React sencillo (sin renderizado de servidor)
Cuando la indexación de búsqueda no importa (una página de tracking detrás de un menú, una intranet), el componente sin snapshot es suficiente:
El loader funciona igual en una aplicación de una sola página (React, Vue, Svelte): renderiza el contenedor y después llama a window.NavoEmbed.mount().
import { useEffect } from 'react';
const SRC = 'https://navo24.com/embed.js';
function loadNavo() {
if (window.NavoEmbed) return Promise.resolve();
return new Promise((ok) => {
let s = document.querySelector(`script[src="${SRC}"]`);
if (!s) { s = document.createElement('script'); s.src = SRC; s.async = true; document.head.appendChild(s); }
s.addEventListener('load', ok, { once: true });
});
}
export function NavoApp({ app, embedKey, pages }) {
useEffect(() => { loadNavo().then(() => window.NavoEmbed.mount()); }, [app, embedKey]);
return (
<div
data-navo-app={app}
data-navo-key={embedKey}
data-navo-pages={pages ? JSON.stringify(pages) : undefined}
/>
);
}
// <NavoApp app="tracking" embedKey="nve_YOUR_KEY" pages={{ tracking: '/track' }} />
En Next.js, ponlo en un componente cliente ('use client').
Por qué un frame
El loader dibuja cada app dentro de un frame desde navo24.com. Así funcionan Stripe Checkout, los embeds de Google Maps y los reproductores de YouTube, por las mismas razones:
- Bloqueo por dominio. El propio navegador se niega a mostrar la app en un sitio que no esté en la lista de la clave (
frame-ancestors). Un componente de script cargado en la página del cliente no puede bloquearse de esta forma. - Sin conflictos de estilos. El CSS del cliente no puede romper la app y nuestro CSS no puede tocar su sitio.
- Actualizaciones sin el cliente. Nuevas navieras, correcciones y funciones llegan a todos los sitios el mismo día; no hay nada que actualizar en el lado del cliente.
- Motores de búsqueda. El contenido dentro de un frame no se indexa como página del cliente, igual que con cualquier embed de mapa o vídeo. Cuando eso importe, añade el snapshot renderizado en servidor, ver React y Next.js, con indexación de búsqueda.
Los visitantes no inician sesión dentro del frame, así que el bloqueo de cookies de terceros por parte del navegador no le afecta.
Enlaces a una vista exacta
Mientras un visitante trabaja en una app, la URL de la página le sigue: ?navo_app=<app>&navo=<view>. Los botones Copiar enlace dentro de las apps producen el mismo tipo de enlace. Ejemplos en una página de cliente /rates:
| Vista | Enlace |
|---|---|
| Un contenedor | /track?navo_app=tracking&navo=ref%3DZMOU8956106 |
| Búsqueda de tarifa en una ruta | /rates?navo_app=freight&navo=origin%3DCNSHA%26destination%3DDEHAM%26container%3D40HC |
| Una tarifa | la búsqueda anterior más %26quote%3D<id> |
| Búsqueda de itinerario en una ruta | /schedules?navo_app=schedules&navo=origin%3DCNSHA%26destination%3DDEHAM |
| Una salida | la búsqueda anterior más %26sailing%3D<id> |
| Un buque | /schedules?navo_app=schedules&navo=by%3Dvessel%26imo%3D9893890 |
| Un puerto | /schedules?navo_app=schedules&navo=by%3Dport%26port%3DSGSIN |
Una tarifa o salida compartida sigue abriéndose después de haber salido de los resultados en vivo; se muestra con la fecha en que se tomaron sus datos.
Solicitudes de reserva
Reservar en una tarifa abre un formulario de solicitud (contacto, empresa, e-mail, teléfono, número de contenedores, fecha de carga lista, carga, notas). Al enviarlo:
- se envía un e-mail a la dirección de reservas del cliente, con la ruta, el equipo, la naviera, el precio que vio el visitante y los datos de contacto del visitante. Reply-To es el visitante, así que el cliente responde directamente desde su buzón;
- si hay un webhook configurado, se envía la misma solicitud por POST como JSON:
{
"type": "booking.requested",
"data": {
"reference": "BR-261020-4F2A1",
"received_at": "2026-10-20T14:05:11Z",
"site": "acme.com",
"contact": { "name": "…", "company": "…", "email": "…", "phone": "…" },
"shipment": { "origin": "Shanghai (CNSHA)", "destination": "Hamburg (DEHAM)", "container": "40ft HC", "quantity": "2", "ready_date": "2026-11-03", "cargo": "…", "notes": "…" },
"rate": { "id": "…", "carrier": "…", "price": 2140, "currency": "USD", "transit_days": 34, "departure": "2026-11-06", "valid_until": "2026-11-15" }
}
}
El visitante ve una confirmación con la referencia. No se cobra nada y no se hace ninguna reserva con la naviera: el cliente confirma espacio y responde.
Sin e-mail de reservas ni webhook, el formulario queda como demo y lo indica.
Qué ven los visitantes y qué no ven
- Nombres y logos de navieras, precios, tiempos de tránsito, validez y qué incluye una tarifa.
- Las tarifas sin naviera nombrada se muestran como “Selección de
”, con el logo del cliente. - Las fuentes y plataformas de tarifas no se muestran nunca. Se eliminan en nuestro servidor antes de que los datos lleguen al navegador.
Seguridad
Bloqueo por dominio. Las páginas de la app responden con Content-Security-Policy: frame-ancestors listando solo los dominios de la clave, así que un navegador se niega a mostrarlas en cualquier otro lugar. Las solicitudes de datos llevan la clave y el host de la página padre, y se rechazan cuando el host no está en la lista. Una clave copiada en otro sitio no funciona allí.
Límites. Cada app de una clave tiene su propio límite mensual o anual (ver Límites de uso). Además, cada clave tiene un tope de seguridad de 50,000 solicitudes al mes, un techo de 600 solicitudes por minuto para todo el sitio (para que un pico de tráfico de un sitio no ralentice las apps de otros; se aumenta bajo petición) y límites por visitante contra abuso automatizado; por encima de ellos, la app muestra un breve mensaje de “inténtalo de nuevo” y dispara navo:limit.
Mensajes. El frame y el loader se comunican mediante postMessage, y cada lado envía solo al origen exacto del otro: el frame a la página del cliente, el loader a navo24.com. Los detalles de búsqueda nunca se envían a *.
Rotación. Si una clave se filtra o un sitio cambia de manos, emitimos una clave nueva y la antigua deja de funcionar al instante.
Pruebas antes del lanzamiento
Envíanos el dominio de staging junto con el de producción, o localhost:<port> para una máquina de desarrollo. Ambos pueden estar en la misma clave.
Checklist
- El cliente envía nombre, dominios, logo, color, e-mail de reservas, las apps que compró (modo AI activado o desactivado) y el límite de cada app (y, opcionalmente, webhook y rutas de página).
- Creamos la clave y enviamos los snippets.
- El cliente añade
embed.jsy los contenedores, primero en staging. - El cliente comprueba: búsqueda → tracking, tarifas → detalles → reserva (llega un e-mail de prueba), un enlace compartido se abre en su sitio. Con una CSP estricta, revisa la consola del navegador por
navo24.combloqueado. - El cliente añade el dominio de producción (si aún no está en la lista) y sale a producción.