Skip to content
Navo24Navo24

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

ElementoEsempioObbligatorio
Nome azienda come deve essere visto dai visitatoriAcme LogisticsSì
Domini su cui gireranno le app (produzione, staging)acme.com, www.acme.com, staging.acme.comSì
Logo, SVG o PNG, marchio quadrato o orizzontalehttps://acme.com/logo.svgSì
Colore del brand, un valore hex#0e6ba8Sì
Altri colori, font, arrotondamento angolivedi Look and feelFacoltativo
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/navoFacoltativo
Quali app voglionouna qualsiasi tra tracking, freight, schedules; modalità AI attiva o disattivaSì
Limite di utilizzo per app, per mese o per annotracking: 300 spedizioni uniche al meseSì
Pagine in cui vivrà ogni app/track, /rates, /schedulesConsigliato
“Powered by Navo” mostrato o nascostomostratoPredefinito: 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:

PacchettoApp sulla chiaveCosa ottiene il visitatore
Solo trackingtrackingPagina di tracking; il widget di ricerca mostra il box di tracking senza tab e senza switch AI
Tracking con AItracking, aiLo stesso, più la modalità AI nel widget di ricerca e “Chiedi all’AI” sulle spedizioni
Tariffe e schedulefreight, schedulesDue tab nel widget di ricerca, le pagine tariffe e schedule
Tuttotracking, freight, schedules, aiTutti 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à:

AppUna unitàRipetizioni gratuite
trackingUna spedizione unica (container, booking o numero B/L)La stessa spedizione per il resto del periodo
freightUna ricerca tariffa (lane e equipment)La stessa ricerca nello stesso giorno
schedulesUna ricerca schedule (rotta, nave o porto)La stessa ricerca nello stesso giorno
aiUna domanda all’assistente AINessuna

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 .” Le altre app sulla chiave continuano a funzionare. Vediamo l’utilizzo per app e possiamo aumentare un limite in qualsiasi momento, senza modifiche sul sito del cliente.

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

AttributoCosa fa
data-navo-appsearch, tracking, freight o schedules.
data-navo-keyLa chiave di embed del sito.
data-navo-pagesMappa JSON da app a percorso pagina sul sito del cliente.
data-navo-heightAltezza fissa in px. Per impostazione predefinita il frame cresce con il contenuto; il tracking è una mappa completa, 680 px.
data-navo-syncoff mantiene invariato l’URL della pagina mentre il visitatore naviga.
data-navo-themeJSON 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.

EventoQuandoevent.detail
navo:searchUna ricerca ha restituito risultatiapp (tracking, freight, schedules) e la query: ref, oppure origin, destination, container
navo:bookingÈ stata inviata una richiesta di bookingreference, origin, destination, container, quantity, carrier, price, currency
navo:limitUn limite ha fermato una ricercaapp, 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.

ChiaveCosa cambiaEsempio
accentPulsanti, link, tab attivi, switch, focus ring. Le tonalità hover e pressed vengono calcolate a partire da questo colore"#e4002b"
textTesto principale"#1a1a1a"
mutedTesto secondario: label, suggerimenti, date"#6b7280"
headingTitoli, nomi di carrier e navi, linee sulla mappa"#002f6c"
backgroundSfondo pagina dell’app. "transparent" lascia intravedere lo sfondo del sito del cliente"#ffffff"
surfaceCard, input, righe alternate delle tabelle"#f5f7fa"
borderBordi e divisori"#e5e7eb"
successStati positivi: consegnato, puntuale, più economico"#15803d"
radiusArrotondamento angoli di card e pannelli, px (0 a 40)8
buttonRadiusArrotondamento angoli di pulsanti e input, px. 999 crea pillole (il valore predefinito)6
fontFont del corpo. Qualsiasi famiglia Google Fonts viene caricata per te; "system" usa il font di sistema del visitatore"Inter"
headingFontFont per i titoli, stesse regole. Senza questo valore i titoli usano font"Playfair Display"
fontCssIl 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:

  1. 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.
  2. 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.

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:

VistaLink
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 tariffala ricerca sopra più %26quote%3D<id>
Ricerca schedule su una lane/schedules?navo_app=schedules&navo=origin%3DCNSHA%26destination%3DDEHAM
Una partenzala 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

  1. 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).
  2. Creiamo la chiave e inviamo gli snippet.
  3. Il cliente aggiunge embed.js e i container, prima in staging.
  4. 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.
  5. Il cliente aggiunge il dominio di produzione (se non è già in lista) e va live.