Guide
Integrare le app Navo sul sito di un cliente
Incorpora il tracking container nel tuo sito: tariffe, partenze nave e modalità AI nel tuo brand, con un tag script e chiave bloccata sul dominio.
Puoi incorporare il tracciamento container nel sito web del cliente, insieme a tariffe di trasporto e schedule di navigazione. Sono le stesse app che vedi sul sito spedizioniere di esempio: un widget di ricerca per la home page, più una pagina completa per ogni app. Ogni app viene mostrata con nome, logo e colore del cliente. Ogni vista ha un proprio link, quindi un visitatore può inviare a un collega un container, una ricerca tariffa, una tariffa, una partenza, una nave o un porto, e il link si apre sul sito del cliente.
Non servono API key o server lato cliente. La chiave di embed è pubblica e funziona solo sui domini che associamo a quella chiave.
Cosa ci invia il cliente
| Elemento | Esempio | Obbligatorio |
|---|---|---|
| Nome azienda come deve essere visto dai visitatori | Acme Logistics | Sì |
| Domini su cui gireranno le app (produzione, staging) | acme.com, www.acme.com, staging.acme.com | Sì |
| Logo, SVG o PNG, marchio quadrato o orizzontale | https://acme.com/logo.svg | Sì |
| Colore del brand, un valore hex | #0e6ba8 | Sì |
| Altri colori, font, arrotondamento angoli | vedi Look and feel | Facoltativo |
| E-mail che riceve le richieste di booking | [email protected] | Per le tariffe di trasporto |
| URL webhook per le richieste di booking (verso il loro CRM/TMS) | https://acme.com/hooks/navo | Facoltativo |
| Quali app vogliono | una qualsiasi tra tracking, freight, schedules; modalità AI attiva o disattiva | Sì |
| Limite di utilizzo per app, per mese o per anno | tracking: 300 spedizioni uniche al mese | Sì |
| Pagine in cui vivrà ogni app | /track, /rates, /schedules | Consigliato |
| “Powered by Navo” mostrato o nascosto | mostrato | Predefinito: mostrato |
Creiamo la chiave e restituiamo gli snippet qui sotto, con la chiave già inserita.
Cosa può contenere una chiave
Una chiave apre una o più app, e la modalità AI è uno switch separato:
| Pacchetto | App sulla chiave | Cosa ottiene il visitatore |
|---|---|---|
| Solo tracking | tracking | Pagina di tracking; il widget di ricerca mostra il box di tracking senza tab e senza switch AI |
| Tracking con AI | tracking, ai | Lo stesso, più la modalità AI nel widget di ricerca e “Chiedi all’AI” sulle spedizioni |
| Tariffe e schedule | freight, schedules | Due tab nel widget di ricerca, le pagine tariffe e schedule |
| Tutto | tracking, freight, schedules, ai | Tutti e tre i tab, modalità AI, tutte le pagine |
Il widget viene costruito a partire dalla chiave: un tab, una pagina o un pulsante AI che la chiave non abilita non viene proprio disegnato, e il nostro server rifiuta i relativi dati anche se qualcuno forza la richiesta.
Limiti di utilizzo
Ogni app su una chiave ha il proprio limite, per mese solare o per anno solare (UTC). Cosa conta come una unità:
| App | Una unità | Ripetizioni gratuite |
|---|---|---|
tracking | Una spedizione unica (container, booking o numero B/L) | La stessa spedizione per il resto del periodo |
freight | Una ricerca tariffa (lane e equipment) | La stessa ricerca nello stesso giorno |
schedules | Una ricerca schedule (rotta, nave o porto) | La stessa ricerca nello stesso giorno |
ai | Una domanda all’assistente AI | Nessuna |
Esempio: tracking a 300 spedizioni uniche al mese. I visitatori del cliente possono aprire e aggiornare quelle 300 spedizioni tutte le volte che vogliono per tutto il mese; la spedizione 301 viene rifiutata fino al 1° del mese successivo. Quando una app raggiunge il limite, i visitatori vedono “Questo servizio è sospeso su questo sito per il momento. Contatta
Installazione
Inserisci il loader una volta su ogni pagina che mostra una app:
<script src="https://navo24.com/embed.js" async></script>
Poi un container nel punto in cui deve comparire l’app.
Widget di ricerca (hero della home page, o qualsiasi pagina). Un unico box con un tab per ogni app sulla chiave (tracking, tariffe, schedule) e modalità AI se la chiave la include. Con una sola app non ci sono tab:
<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 il widget manda i visitatori alle pagine del cliente. Senza questo attributo, il risultato si apre direttamente dentro il frame del widget.
Pagina di tracking (/track):
<div data-navo-app="tracking" data-navo-key="nve_YOUR_KEY"></div>
Pagina tariffe di trasporto (/rates):
<div data-navo-app="freight" data-navo-key="nve_YOUR_KEY"></div>
Pagina schedule di navigazione (/schedules), con tre tab: per rotta, per nave, per porto:
<div data-navo-app="schedules" data-navo-key="nve_YOUR_KEY"></div>
Usa lo stesso valore data-navo-pages su ogni app, così i cross-link (per esempio “Mostra tariffe” su una partenza, o “Schedule nave” su una spedizione) atterrano sulla pagina corretta del sito del cliente.
Opzioni
| Attributo | Cosa fa |
|---|---|
data-navo-app | search, tracking, freight o schedules. |
data-navo-key | La chiave di embed del sito. |
data-navo-pages | Mappa JSON da app a percorso pagina sul sito del cliente. |
data-navo-height | Altezza fissa in px. Per impostazione predefinita il frame cresce con il contenuto; il tracking è una mappa completa, 680 px. |
data-navo-sync | off mantiene invariato l’URL della pagina mentre il visitatore naviga. |
data-navo-theme | JSON con colori, font e angoli, vedi Look and feel. |
Siti con Content Security Policy
Se il sito invia un header Content-Security-Policy (o uno <meta http-equiv>) con script-src o frame-src, aggiungi navo24.com a entrambi, altrimenti il browser blocca il loader o il frame e il container resta vuoto:
script-src ... https://navo24.com;
frame-src ... https://navo24.com;
Con child-src al posto di frame-src, aggiungilo lì. Non serve altro: le app caricano dati, font e mappe dentro il frame, sotto la nostra policy. La console del browser indica la direttiva bloccata se ne manca una.
Eventi per analytics e CRM
Il container emette eventi DOM quando un visitatore fa qualcosa, così il sito può inviarli a Google Analytics, a un tag manager o al suo CRM. Gli eventi fanno bubbling, quindi un solo listener su document intercetta ogni app sulla pagina.
| Evento | Quando | event.detail |
|---|---|---|
navo:search | Una ricerca ha restituito risultati | app (tracking, freight, schedules) e la query: ref, oppure origin, destination, container |
navo:booking | È stata inviata una richiesta di booking | reference, origin, destination, container, quantity, carrier, price, currency |
navo:limit | Un limite ha fermato una ricerca | app, code (per esempio 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>
I dati di contatto del visitatore non sono negli eventi: vanno solo all’e-mail di booking e al webhook.
Look and feel
Per impostazione predefinita le app prendono il colore del brand del cliente dalla chiave. Per allinearle meglio al sito, aggiungi data-navo-theme al container: colori, font, arrotondamento angoli e modalità scura.
<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>
Ogni chiave è facoltativa. Un valore non valido viene ignorato, il resto continua ad applicarsi.
| Chiave | Cosa cambia | Esempio |
|---|---|---|
accent | Pulsanti, link, tab attivi, switch, focus ring. Le tonalità hover e pressed vengono calcolate a partire da questo colore | "#e4002b" |
text | Testo principale | "#1a1a1a" |
muted | Testo secondario: label, suggerimenti, date | "#6b7280" |
heading | Titoli, nomi di carrier e navi, linee sulla mappa | "#002f6c" |
background | Sfondo pagina dell’app. "transparent" lascia intravedere lo sfondo del sito del cliente | "#ffffff" |
surface | Card, input, righe alternate delle tabelle | "#f5f7fa" |
border | Bordi e divisori | "#e5e7eb" |
success | Stati positivi: consegnato, puntuale, più economico | "#15803d" |
radius | Arrotondamento angoli di card e pannelli, px (0 a 40) | 8 |
buttonRadius | Arrotondamento angoli di pulsanti e input, px. 999 crea pillole (il valore predefinito) | 6 |
font | Font del corpo. Qualsiasi famiglia Google Fonts viene caricata per te; "system" usa il font di sistema del visitatore | "Inter" |
headingFont | Font per i titoli, stesse regole. Senza questo valore i titoli usano font | "Playfair Display" |
fontCss | Il tuo foglio stile font (https:// URL con regole @font-face), per font che non sono su Google Fonts. Poi font e headingFont indicano famiglie da quel file | "https://acme.com/fonts/brand.css" |
mode | "dark" per siti con design scuro | "dark" |
I colori sono hex: #rgb, #rrggbb o #rrggbbaa.
Punti di partenza pronti all’uso:
<!-- 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 solo tema per tutte le pagine. Possiamo salvare il tema anche sulla chiave. In questo modo ogni container su ogni pagina lo riceve senza l’attributo, e possiamo modificarlo in seguito senza cambiamenti sul sito del cliente. data-navo-theme su un container continua ad avere priorità sul tema della chiave, chiave per chiave.
Il tema raggiunge solo l’app dentro il frame: non modifica mai la pagina del cliente.
React and Next.js, with search indexing
Usa questa modalità quando il sito del cliente è costruito con React o Next.js e il contenuto dell’app deve essere indicizzato come pagina del cliente (per esempio, una pagina per lane, “Shanghai to Hamburg sailing schedule”).
È composta da due parti:
- Snapshot. Il server del cliente recupera da noi i dati della lane come HTML semplice (tabella schedule o tabella tariffe, un titolo, un riepilogo di una riga e markup schema.org) e li inserisce nella propria pagina. I motori di ricerca lo indicizzano come contenuto del cliente, sull’URL del cliente.
- App. Nel browser l’app interattiva viene montata sopra, con ricerca, filtri, dettagli e booking. Lo snapshot resta sulla pagina come tabella comprimibile sotto l’app, così crawler e visitatori vedono lo stesso contenuto.
Snapshot endpoint
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
Senza format=html la risposta è 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 e description per il <title> della pagina e la meta description, html per il body. La risposta può essere mantenuta in cache per 30 minuti (Cache-Control: max-age=1800). Uno snapshot conta come una ricerca contro il limite dell’app; la stessa lane nello stesso giorno è gratuita. Il tracking non ha snapshot: le spedizioni sono private per il visitatore.
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>
)}
</>
);
}
Come appare a un motore di ricerca: title e description propri della pagina, un titolo e una tabella completa di partenze (o tariffe) nell’HTML, con markup Dataset. Come appare a un visitatore: l’app live, già aperta su quella lane, con gli stessi risultati in una tabella ripiegata sotto. I visitatori senza JavaScript vedono la tabella aperta. La tabella è ripiegata, non nascosta, quindi la pagina non mostra ai crawler nulla che un visitatore non possa aprire.
L’HTML dello snapshot arriva dal nostro server con ogni valore già escapato, quindi è sicuro da inserire. Se mai viene mostrato, stilizzalo con le classi .navo-snapshot e .navo-snapshot-table.
Altri framework server (Remix, Astro, Nuxt, PHP, WordPress) funzionano allo stesso modo: recupera lo snapshot sul server, stampa html nella pagina, metti il container accanto.
Plain React (no server rendering)
Quando l’indicizzazione non è importante (una pagina di tracking dietro un menu, una intranet), il componente senza snapshot è sufficiente:
Il loader funziona allo stesso modo in una single-page app (React, Vue, Svelte): renderizza il container, poi chiama 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' }} />
In Next.js inseriscilo in un client component ('use client').
Perché un frame
Il loader disegna ogni app dentro un frame da navo24.com. È lo stesso funzionamento di Stripe Checkout, degli embed di Google Maps e dei player YouTube, per le stesse ragioni:
- Blocco per dominio. Il browser stesso rifiuta di mostrare l’app su un sito che non è nella lista della chiave (
frame-ancestors). Un componente script caricato nella pagina del cliente non può essere bloccato in questo modo. - Nessun conflitto di stile. Il CSS del cliente non può rompere l’app e il nostro CSS non può toccare il loro sito.
- Aggiornamenti senza il cliente. Nuovi carrier, fix e funzionalità arrivano su ogni sito lo stesso giorno; nulla da aggiornare lato cliente.
- Motori di ricerca. Il contenuto dentro un frame non viene indicizzato come pagina del cliente, come per qualsiasi embed di mappa o video. Quando questo è importante, aggiungi lo snapshot renderizzato server-side, vedi React and Next.js, with search indexing.
I visitatori non fanno login dentro il frame, quindi il blocco dei cookie di terze parti da parte del browser non ha effetti.
Link a una vista esatta
Mentre un visitatore usa una app, l’URL della pagina lo segue: ?navo_app=<app>&navo=<view>. I pulsanti Copia link dentro le app producono lo stesso tipo di link. Esempi su una pagina cliente /rates:
| Vista | Link |
|---|---|
| Un container | /track?navo_app=tracking&navo=ref%3DZMOU8956106 |
| Ricerca tariffa su una lane | /rates?navo_app=freight&navo=origin%3DCNSHA%26destination%3DDEHAM%26container%3D40HC |
| Una tariffa | la ricerca sopra più %26quote%3D<id> |
| Ricerca schedule su una lane | /schedules?navo_app=schedules&navo=origin%3DCNSHA%26destination%3DDEHAM |
| Una partenza | la ricerca sopra più %26sailing%3D<id> |
| Una nave | /schedules?navo_app=schedules&navo=by%3Dvessel%26imo%3D9893890 |
| Un porto | /schedules?navo_app=schedules&navo=by%3Dport%26port%3DSGSIN |
Una tariffa o una partenza condivisa continua ad aprirsi anche dopo essere uscita dai risultati live; viene mostrata con la data in cui i dati sono stati acquisiti.
Richieste di booking
Prenota su una tariffa apre un modulo di richiesta (contatto, azienda, e-mail, telefono, numero di container, data cargo-ready, merce, note). All’invio:
- un’e-mail va all’indirizzo booking del cliente, con rotta, equipment, carrier, il prezzo visto dal visitatore e i dati di contatto del visitatore. Reply-To è il visitatore, così il cliente risponde direttamente dalla propria casella;
- se è impostato un webhook, la stessa richiesta viene inviata con POST come 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" }
}
}
Il visitatore vede una conferma con la reference. Non viene addebitato nulla e non viene effettuata alcuna prenotazione con il carrier: il cliente conferma lo spazio e risponde.
Senza e-mail di booking o webhook il modulo resta una demo e lo dichiara.
Cosa vedono i visitatori, e cosa non vedono
- Nomi e loghi dei carrier, prezzi, transit time, validità e cosa include una tariffa.
- Le tariffe senza carrier indicato vengono mostrate come ”
Select”, con il logo del cliente. - Fonti delle tariffe e piattaforme non vengono mai mostrate. Vengono rimosse sul nostro server prima che i dati raggiungano il browser.
Sicurezza
Blocco per dominio. Le pagine dell’app rispondono con Content-Security-Policy: frame-ancestors che elenca solo i domini della chiave, quindi un browser rifiuta di mostrarle altrove. Le richieste dati includono la chiave e l’host della pagina padre e vengono rifiutate quando l’host non è nella lista. Una chiave copiata su un altro sito non funziona lì.
Limiti. Ogni app su una chiave ha il proprio limite mensile o annuale (vedi Limiti di utilizzo). In aggiunta, ogni chiave ha un safety cap di 50,000 richieste al mese, un tetto di 600 richieste al minuto per l’intero sito (così il picco di traffico di un sito non può rallentare le app per gli altri; aumentabile su richiesta) e limiti per visitatore contro abusi via script; oltre questi limiti l’app mostra un breve messaggio “riprova” ed emette navo:limit.
Messaggi. Il frame e il loader comunicano tramite postMessage, e ciascun lato invia solo all’origine esatta dell’altro: il frame alla pagina del cliente, il loader a navo24.com. I dettagli di ricerca non vanno mai a *.
Rotazione. Se una chiave viene esposta o un sito cambia proprietario, emettiamo una nuova chiave e quella vecchia smette subito di funzionare.
Test prima del lancio
Inviaci il dominio di staging insieme a quello di produzione, oppure localhost:<port> per una macchina di sviluppo. Entrambi possono stare sulla stessa chiave.
Checklist
- Il cliente invia nome, domini, logo, colore, e-mail di booking, le app acquistate (modalità AI attiva o disattiva) e il limite per ogni app (e, facoltativamente, webhook e percorsi pagina).
- Creiamo la chiave e inviamo gli snippet.
- Il cliente aggiunge
embed.jse i container, prima in staging. - Il cliente verifica: ricerca → tracking, tariffe → dettagli → booking (arriva una e-mail di test), un link condiviso si apre sul suo sito. Con una CSP restrittiva, controlla nella console del browser eventuali blocchi di
navo24.com. - Il cliente aggiunge il dominio di produzione (se non è già in lista) e va live.