Guias
Incorporar as apps Navo no site de um cliente
Incorpore rastreamento de contêineres no seu site, além de cotações de frete, escalas marítimas e modo AI, com sua marca, uma tag de script e chave vinculada ao domínio.
Você pode incorporar o rastreamento de contêineres no próprio site de um cliente, junto com tarifas de frete e programações de embarque. São os mesmos apps que você vê no site de exemplo de um agente de carga: um widget de busca para a página inicial, além de uma página completa para cada app. Cada um aparece com o nome, o logo e a cor do cliente. Cada visualização tem seu próprio link, para que um visitante possa enviar a um colega um contêiner, uma busca de tarifa, uma tarifa, uma programação de embarque, um navio ou um porto, e tudo abre no site do cliente.
Nenhuma API key ou servidor é necessário do lado do cliente. A chave de incorporação é pública e funciona apenas nos domínios que listamos para ela.
O que o cliente nos envia
| Item | Exemplo | Obrigatório |
|---|---|---|
| Nome da empresa como os visitantes devem vê-lo | Acme Logistics | Sim |
| Domínios em que os apps serão executados (produção, staging) | acme.com, www.acme.com, staging.acme.com | Sim |
| Logo, SVG ou PNG, marca quadrada ou horizontal | https://acme.com/logo.svg | Sim |
| Cor da marca, um valor hex | #0e6ba8 | Sim |
| Mais cores, fontes, arredondamento de cantos | veja Aparência | Opcional |
| E-mail que recebe solicitações de reserva | [email protected] | Para tarifas de frete |
| URL de webhook para solicitações de reserva (para o CRM/TMS deles) | https://acme.com/hooks/navo | Opcional |
| Quais apps eles querem | qualquer combinação de tracking, freight, schedules; modo de IA ativado ou desativado | Sim |
| Limite de uso por app, por mês ou por ano | tracking: 300 embarques únicos por mês | Sim |
| Páginas onde cada app ficará | /track, /rates, /schedules | Recomendado |
| “Desenvolvido por Navo” exibido ou oculto | exibido | Padrão: exibido |
Criamos a chave e enviamos de volta os snippets abaixo, com a chave preenchida.
O que uma chave pode carregar
Uma chave abre um app ou vários, e o modo de IA é um switch separado:
| Pacote | Apps na chave | O que o visitante recebe |
|---|---|---|
| Apenas tracking | tracking | Página de tracking; o widget de busca mostra a caixa de tracking sem abas e sem switch de IA |
| Tracking com IA | tracking, ai | O mesmo, mais o modo de IA no widget de busca e “Perguntar à IA” nos embarques |
| Tarifas e programações | freight, schedules | Duas abas no widget de busca, as páginas de tarifas e programações |
| Tudo | tracking, freight, schedules, ai | As três abas, modo de IA, todas as páginas |
O widget é construído a partir da chave: uma aba, uma página ou um botão de IA que a chave não abre não é desenhado, e nosso servidor recusa seus dados mesmo que alguém force a requisição.
Limites de uso
Cada app em uma chave tem seu próprio limite, por mês-calendário ou por ano-calendário (UTC). O que conta como uma unidade:
| App | Uma unidade | Repetições grátis |
|---|---|---|
tracking | Um embarque único (número de contêiner, booking ou B/L) | O mesmo embarque pelo restante do período |
freight | Uma busca de tarifa (rota e equipamento) | A mesma busca no mesmo dia |
schedules | Uma busca de programação (rota, navio ou porto) | A mesma busca no mesmo dia |
ai | Uma pergunta ao assistente de IA | Nenhuma |
Exemplo: tracking em 300 embarques únicos por mês. Os visitantes do cliente podem abrir e atualizar esses 300 embarques quantas vezes quiserem durante todo o mês; o embarque 301 é recusado até o dia 1 do mês seguinte. Quando um app atinge seu limite, os visitantes veem “Este serviço está pausado neste site por enquanto. Entre em contato com
Instalação
Coloque o loader uma vez em cada página que mostra um app:
<script src="https://navo24.com/embed.js" async></script>
Depois, um contêiner onde o app deve aparecer.
Widget de busca (hero da página inicial, ou qualquer página). Uma caixa com uma aba para cada app na chave (tracking, tarifas, programações) e modo de IA se a chave tiver. Com um app só, não há abas:
<div
data-navo-app="search"
data-navo-key="nve_YOUR_KEY"
data-navo-pages='{"tracking":"/track","freight":"/rates","schedules":"/schedules"}'
></div>
Com data-navo-pages, o widget envia os visitantes para as próprias páginas do cliente. Sem ele, o resultado abre dentro do frame do widget.
Página de tracking (/track):
<div data-navo-app="tracking" data-navo-key="nve_YOUR_KEY"></div>
Página de tarifas de frete (/rates):
<div data-navo-app="freight" data-navo-key="nve_YOUR_KEY"></div>
Página de programações de embarque (/schedules), com três abas: por rota, por navio, por porto:
<div data-navo-app="schedules" data-navo-key="nve_YOUR_KEY"></div>
Use o mesmo valor de data-navo-pages em todos os apps para que links cruzados (por exemplo “Mostrar tarifas” em uma programação de embarque, ou “Programação do navio” em um embarque) cheguem à página correta do site do cliente.
Opções
| Atributo | O que faz |
|---|---|
data-navo-app | search, tracking, freight ou schedules. |
data-navo-key | A chave de incorporação do site. |
data-navo-pages | Mapa JSON de app para caminho de página no site do cliente. |
data-navo-height | Altura fixa em px. Por padrão, o frame cresce com seu conteúdo; tracking é um mapa completo, 680 px. |
data-navo-sync | off mantém a URL da página inalterada enquanto o visitante navega. |
data-navo-theme | JSON com cores, fontes e cantos, veja Aparência. |
Sites com Content Security Policy
Se o site envia um cabeçalho Content-Security-Policy (ou um <meta http-equiv>) com script-src ou frame-src, adicione navo24.com a ambos, caso contrário o navegador bloqueia o loader ou o frame e o contêiner fica vazio:
script-src ... https://navo24.com;
frame-src ... https://navo24.com;
Com child-src em vez de frame-src, adicione ali. Nada mais é necessário: os apps carregam seus dados, fontes e mapas dentro do frame, sob nossa própria política. O console do navegador informa a diretiva bloqueada se alguma estiver faltando.
Eventos para analytics e CRM
O contêiner dispara eventos DOM quando um visitante faz algo, para que o site possa enviá-los ao Google Analytics, a um gerenciador de tags ou ao seu CRM. Eles fazem bubble, então um listener em document captura todos os apps na página.
| Evento | Quando | event.detail |
|---|---|---|
navo:search | Uma busca retornou resultados | app (tracking, freight, schedules) e a consulta: ref, ou origin, destination, container |
navo:booking | Uma solicitação de reserva foi enviada | reference, origin, destination, container, quantity, carrier, price, currency |
navo:limit | Um limite interrompeu uma busca | app, code (por exemplo 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>
Os dados de contato do visitante não ficam nos eventos: eles vão apenas para o e-mail de reserva e para o webhook.
Aparência
Por padrão, os apps pegam a cor da marca do cliente a partir da chave. Para combinar melhor com o site, adicione data-navo-theme ao contêiner: cores, fontes, arredondamento de cantos e modo escuro.
<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 as chaves são opcionais. Um valor inválido é ignorado, o restante ainda é aplicado.
| Chave | O que altera | Exemplo |
|---|---|---|
accent | Botões, links, abas ativas, switches, anel de foco. Tons de hover e pressionado são calculados a partir dela | "#e4002b" |
text | Texto principal | "#1a1a1a" |
muted | Texto secundário: rótulos, dicas, datas | "#6b7280" |
heading | Títulos, nomes de transportadoras e navios, linhas do mapa | "#002f6c" |
background | Fundo da página do app. "transparent" deixa o fundo do próprio cliente aparecer | "#ffffff" |
surface | Cards, inputs, listras de tabela | "#f5f7fa" |
border | Bordas e divisores | "#e5e7eb" |
success | Estados positivos: entregue, no prazo, mais barato | "#15803d" |
radius | Arredondamento de cantos de cards e painéis, px (0 a 40) | 8 |
buttonRadius | Arredondamento de cantos de botões e inputs, px. 999 cria pílulas (o padrão) | 6 |
font | Fonte do corpo. Qualquer família do Google Fonts é carregada para você; "system" usa a fonte do sistema do visitante | "Inter" |
headingFont | Fonte para títulos, mesmas regras. Sem ela, os títulos usam font | "Playfair Display" |
fontCss | Sua própria folha de estilos de fontes (URL https:// com regras @font-face), para fontes que não estão no Google Fonts. Então font e headingFont nomeiam famílias desse arquivo | "https://acme.com/fonts/brand.css" |
mode | "dark" para sites com design escuro | "dark" |
As cores são hex: #rgb, #rrggbb ou #rrggbbaa.
Pontos de partida prontos:
<!-- 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"}'
Um tema para todas as páginas. Também podemos armazenar o tema na chave. Então todo contêiner em toda página recebe esse tema sem o atributo, e podemos ajustá-lo depois sem mudança no site do cliente. data-navo-theme em um contêiner ainda prevalece sobre o tema da chave, chave por chave.
O tema só chega ao app dentro do frame: ele nunca altera a própria página do cliente.
React e Next.js, com indexação de busca
Use isto quando o site do cliente é construído com React ou Next.js e o conteúdo do app deve ser indexado como a página do cliente (por exemplo, uma página por rota, “Shanghai to Hamburg sailing schedule”).
São duas partes:
- Snapshot. O servidor do cliente busca os dados da rota conosco como HTML simples (tabela de programação ou tabela de tarifas, um título, um resumo de uma linha e marcação schema.org) e coloca isso em sua própria página. Mecanismos de busca indexam como conteúdo do cliente, na URL do cliente.
- App. No navegador, o app interativo é montado acima disso, com busca, filtros, detalhes e reserva. O snapshot permanece na página como uma tabela recolhível sob o app, para que crawlers e visitantes vejam o mesmo conteúdo.
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
Sem format=html, a resposta é 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"
}
}
Use title e description para o <title> da página e a meta description, html para o corpo. A resposta pode ser armazenada em cache por 30 minutos (Cache-Control: max-age=1800). Um snapshot conta como uma busca contra o limite do app; a mesma rota no mesmo dia é grátis. Tracking não tem snapshot: embarques são privados para o 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>
)}
</>
);
}
Como isso aparece para um mecanismo de busca: o próprio título e a descrição da página, um título e uma tabela completa de programações de embarque (ou tarifas) no HTML, com marcação Dataset. Como aparece para um visitante: o app ao vivo, já aberto naquela rota, com os mesmos resultados como uma tabela recolhida abaixo dele. Visitantes com JavaScript desligado veem a tabela aberta. A tabela é recolhida, não oculta, então a página não mostra aos crawlers nada que um visitante não possa abrir.
O HTML do snapshot vem do nosso servidor com todos os valores escapados, então é seguro inseri-lo. Estilize com as classes .navo-snapshot e .navo-snapshot-table se ele algum dia for mostrado.
Outros frameworks de servidor (Remix, Astro, Nuxt, PHP, WordPress) funcionam da mesma forma: busque o snapshot no servidor, imprima html na página, coloque o contêiner ao lado.
React puro (sem renderização no servidor)
Quando a indexação de busca não importa (uma página de tracking atrás de um menu, uma intranet), o componente sem o snapshot é suficiente:
O loader funciona da mesma forma em um app de página única (React, Vue, Svelte): renderize o contêiner, depois chame 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' }} />
No Next.js, coloque em um componente cliente ('use client').
Por que um frame
O loader desenha cada app dentro de um frame de navo24.com. É assim que Stripe Checkout, incorporações do Google Maps e players do YouTube funcionam, pelos mesmos motivos:
- Bloqueio por domínio. O próprio navegador se recusa a mostrar o app em um site que não está na lista da chave (
frame-ancestors). Um componente de script carregado na página do cliente não pode ser bloqueado dessa forma. - Sem conflitos de estilo. O CSS do cliente não pode quebrar o app e nosso CSS não pode tocar no site dele.
- Atualizações sem o cliente. Novas transportadoras, correções e recursos chegam a todos os sites no mesmo dia; nada para atualizar do lado do cliente.
- Mecanismos de busca. Conteúdo dentro de um frame não é indexado como página do cliente, assim como qualquer mapa ou vídeo incorporado. Quando isso importa, adicione o snapshot renderizado no servidor, veja React e Next.js, com indexação de busca.
Visitantes não fazem login dentro do frame, então o bloqueio de cookies de terceiros pelo navegador não o afeta.
Links para uma visualização exata
Enquanto um visitante trabalha em um app, a URL da página o acompanha: ?navo_app=<app>&navo=<view>. Os botões Copiar link dentro dos apps produzem o mesmo tipo de link. Exemplos em uma página de cliente /rates:
| Visualização | Link |
|---|---|
| Um contêiner | /track?navo_app=tracking&navo=ref%3DZMOU8956106 |
| Busca de tarifa em uma rota | /rates?navo_app=freight&navo=origin%3DCNSHA%26destination%3DDEHAM%26container%3D40HC |
| Uma tarifa | a busca acima mais %26quote%3D<id> |
| Busca de programação em uma rota | /schedules?navo_app=schedules&navo=origin%3DCNSHA%26destination%3DDEHAM |
| Uma programação | a busca acima mais %26sailing%3D<id> |
| Um navio | /schedules?navo_app=schedules&navo=by%3Dvessel%26imo%3D9893890 |
| Um porto | /schedules?navo_app=schedules&navo=by%3Dport%26port%3DSGSIN |
Uma tarifa ou programação compartilhada continua abrindo depois de sair dos resultados ao vivo; ela é mostrada com a data em que seus dados foram obtidos.
Solicitações de reserva
Reservar em uma tarifa abre um formulário de solicitação (contato, empresa, e-mail, telefone, número de contêineres, data de carga pronta, carga, observações). Ao enviar:
- um e-mail vai para o endereço de reservas do cliente, com a rota, equipamento, transportadora, o preço que o visitante viu e os dados de contato do visitante. Reply-To é o visitante, então o cliente responde direto da própria caixa de e-mail;
- se um webhook estiver configurado, a mesma solicitação é enviada via POST para ele 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" }
}
}
O visitante vê uma confirmação com a referência. Nada é cobrado e nenhuma reserva com transportadora é feita: o cliente confirma espaço e responde.
Sem e-mail de reserva ou webhook, o formulário permanece como demonstração e informa isso.
O que os visitantes veem, e o que não veem
- Nomes e logos de transportadoras, preços, tempos de trânsito, validade e o que uma tarifa inclui.
- Tarifas sem transportadora nomeada são mostradas como ”
Select”, com o logo do cliente. - Fontes e plataformas de tarifas nunca são mostradas. Elas são removidas em nosso servidor antes que os dados cheguem ao navegador.
Segurança
Bloqueio por domínio. As páginas do app respondem com Content-Security-Policy: frame-ancestors listando apenas os domínios da chave, então um navegador se recusa a mostrá-las em qualquer outro lugar. Requisições de dados carregam a chave e o host da página pai, e são recusadas quando o host não está na lista. Uma chave copiada para outro site não funciona lá.
Limites. Cada app em uma chave tem seu próprio limite mensal ou anual (veja Limites de uso). Além disso, toda chave tem um limite de segurança de 50,000 requisições por mês, um teto de 600 requisições por minuto para o site inteiro (para que um pico de tráfego de um site não deixe os apps mais lentos para outros; aumentado sob solicitação) e limites por visitante contra abuso automatizado; acima disso, o app mostra uma mensagem curta de “tente novamente” e dispara navo:limit.
Mensagens. O frame e o loader conversam por postMessage, e cada lado envia apenas para a origem exata do outro: o frame para a página do cliente, o loader para navo24.com. Detalhes de busca nunca vão para *.
Rotação. Se uma chave vazar ou um site mudar de mãos, emitimos uma nova chave e a antiga para de funcionar imediatamente.
Testes antes do lançamento
Envie-nos o domínio de staging junto com o de produção, ou localhost:<port> para uma máquina de desenvolvimento. Ambos podem ficar na mesma chave.
Checklist
- Cliente envia nome, domínios, logo, cor, e-mail de reserva, os apps comprados (modo de IA ativado ou desativado) e o limite de cada app (e, opcionalmente, webhook, caminhos de página).
- Criamos a chave e enviamos os snippets.
- Cliente adiciona
embed.jse os contêineres, primeiro em staging. - Cliente verifica: busca → tracking, tarifas → detalhes → reserva (um e-mail de teste chega), um link compartilhado abre no site dele. Com uma CSP estrita, verifique no console do navegador se há
navo24.combloqueado. - Cliente adiciona o domínio de produção (se ainda não estiver na lista) e publica.