Guides
Intégrer les apps Navo sur le site d'un client
Intégrez le suivi de conteneurs, les tarifs de fret, les horaires maritimes et le mode IA sous votre marque avec une balise script et une clé liée au domaine.
Vous pouvez intégrer le suivi de conteneurs sur le site web d’un client, avec les tarifs de fret et les horaires de navigation. Ce sont les mêmes apps que celles visibles sur le site transitaire d’exemple : un widget de recherche pour la page d’accueil, plus une page complète pour chaque app. Chaque app est affichée au nom du client, avec son logo et sa couleur. Chaque vue a son propre lien, ce qui permet à un visiteur d’envoyer à un collègue un conteneur, une recherche de tarif, un tarif, une navigation, un navire ou un port, qui s’ouvre sur le site du client.
Aucune clé API ni aucun serveur n’est nécessaire côté client. La clé d’intégration est publique et ne fonctionne que sur les domaines que nous lui associons.
Ce que le client nous envoie
| Élément | Exemple | Obligatoire |
|---|---|---|
| Nom de l’entreprise tel qu’il doit apparaître aux visiteurs | Acme Logistics | Oui |
| Domaines sur lesquels les apps seront utilisées (production, staging) | acme.com, www.acme.com, staging.acme.com | Oui |
| Logo, SVG ou PNG, pictogramme carré ou horizontal | https://acme.com/logo.svg | Oui |
| Couleur de marque, une valeur hex | #0e6ba8 | Oui |
| Couleurs supplémentaires, polices, arrondi des angles | voir Apparence | Facultatif |
| E-mail qui reçoit les demandes de réservation | [email protected] | Pour les tarifs de fret |
| URL de webhook pour les demandes de réservation (vers leur CRM/TMS) | https://acme.com/hooks/navo | Facultatif |
| Apps souhaitées | au choix parmi suivi, fret, horaires; mode AI activé ou désactivé | Oui |
| Limite d’utilisation par app, par mois ou par an | suivi : 300 expéditions uniques par mois | Oui |
| Pages où chaque app sera placée | /track, /rates, /schedules | Recommandé |
| “Propulsé par Navo” affiché ou masqué | affiché | Par défaut : affiché |
Nous créons la clé et renvoyons les extraits ci-dessous, avec la clé renseignée.
Ce qu’une clé peut contenir
Une clé ouvre une ou plusieurs apps, et le mode AI est un interrupteur séparé :
| Package | Apps sur la clé | Ce que le visiteur obtient |
|---|---|---|
| Suivi uniquement | tracking | Page de suivi; le widget de recherche affiche le champ de suivi, sans onglets ni interrupteur AI |
| Suivi avec AI | tracking, ai | La même chose, plus le mode AI dans le widget de recherche et “Demander à l’AI” sur les expéditions |
| Tarifs et horaires | freight, schedules | Deux onglets dans le widget de recherche, les pages tarifs et horaires |
| Tout | tracking, freight, schedules, ai | Les trois onglets, le mode AI, toutes les pages |
Le widget est construit à partir de la clé : un onglet, une page ou un bouton AI que la clé n’ouvre pas n’est pas rendu du tout, et notre serveur refuse ses données même si quelqu’un force la requête.
Limites d’utilisation
Chaque app sur une clé a sa propre limite, par mois civil ou par année civile (UTC). Ce qui compte comme une unité :
| App | Une unité | Répétitions gratuites |
|---|---|---|
tracking | Une expédition unique (numéro de conteneur, de booking ou de B/L) | La même expédition pour le reste de la période |
freight | Une recherche de tarif (lane et équipement) | La même recherche le même jour |
schedules | Une recherche d’horaire (route, navire ou port) | La même recherche le même jour |
ai | Une question à l’assistant AI | Aucune |
Exemple : suivi à 300 expéditions uniques par mois. Les visiteurs du client peuvent ouvrir et actualiser ces 300 expéditions aussi souvent qu’ils le souhaitent pendant tout le mois; l’expédition 301 est refusée jusqu’au 1 du mois suivant. Quand une app atteint sa limite, les visiteurs voient “Ce service est temporairement suspendu sur ce site. Veuillez contacter
Installation
Ajoutez le loader une fois sur chaque page qui affiche une app :
<script src="https://navo24.com/embed.js" async></script>
Puis un conteneur à l’endroit où l’app doit apparaître.
Widget de recherche (hero de la page d’accueil, ou n’importe quelle page). Un champ avec un onglet pour chaque app de la clé (suivi, tarifs, horaires) et le mode AI si la clé l’inclut. Avec une seule app, il n’y a pas d’onglets :
<div
data-navo-app="search"
data-navo-key="nve_YOUR_KEY"
data-navo-pages='{"tracking":"/track","freight":"/rates","schedules":"/schedules"}'
></div>
Avec data-navo-pages, le widget envoie les visiteurs vers les propres pages du client. Sans cet attribut, le résultat s’ouvre directement dans le cadre du widget.
Page de suivi (/track) :
<div data-navo-app="tracking" data-navo-key="nve_YOUR_KEY"></div>
Page des tarifs de fret (/rates) :
<div data-navo-app="freight" data-navo-key="nve_YOUR_KEY"></div>
Page des horaires de navigation (/schedules), avec trois onglets : par route, par navire, par port :
<div data-navo-app="schedules" data-navo-key="nve_YOUR_KEY"></div>
Utilisez la même valeur data-navo-pages sur chaque app pour que les liens croisés (par exemple “Afficher les tarifs” sur une navigation, ou “Horaire du navire” sur une expédition) arrivent sur la bonne page du site du client.
Options
| Attribut | Rôle |
|---|---|
data-navo-app | search, tracking, freight ou schedules. |
data-navo-key | La clé d’intégration du site. |
data-navo-pages | Map JSON entre app et chemin de page sur le site du client. |
data-navo-height | Hauteur fixe en px. Par défaut, le cadre grandit avec son contenu; le suivi est une carte complète, 680 px. |
data-navo-sync | off garde l’URL de la page inchangée pendant que le visiteur navigue. |
data-navo-theme | JSON avec couleurs, polices et angles, voir Apparence. |
Sites avec une Content Security Policy
Si le site envoie un en-tête Content-Security-Policy (ou un <meta http-equiv>) avec script-src ou frame-src, ajoutez navo24.com aux deux, sinon le navigateur bloque le loader ou le cadre et le conteneur reste vide :
script-src ... https://navo24.com;
frame-src ... https://navo24.com;
Avec child-src au lieu de frame-src, ajoutez-le à cet endroit. Rien d’autre n’est nécessaire : les apps chargent leurs données, polices et cartes dans le cadre, sous notre propre politique. La console du navigateur indique la directive bloquée s’il en manque une.
Événements pour l’analytics et le CRM
Le conteneur émet des événements DOM quand un visiteur fait une action, afin que le site puisse les envoyer à Google Analytics, à un gestionnaire de tags ou à son CRM. Ils remontent dans le DOM, donc un seul listener sur document intercepte toutes les apps de la page.
| Événement | Quand | event.detail |
|---|---|---|
navo:search | Une recherche a renvoyé des résultats | app (tracking, freight, schedules) et la requête : ref, ou origin, destination, container |
navo:booking | Une demande de réservation a été envoyée | reference, origin, destination, container, quantity, carrier, price, currency |
navo:limit | Une limite a bloqué une recherche | app, code (par exemple 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>
Les coordonnées du visiteur ne sont pas dans les événements : elles vont uniquement vers l’e-mail de réservation et le webhook.
Apparence
Par défaut, les apps prennent la couleur de marque du client depuis la clé. Pour mieux correspondre au site, ajoutez data-navo-theme au conteneur : couleurs, polices, arrondi des angles et mode sombre.
<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>
Chaque clé est facultative. Une valeur non valide est ignorée, le reste continue de s’appliquer.
| Clé | Ce qu’elle modifie | Exemple |
|---|---|---|
accent | Boutons, liens, onglets actifs, interrupteurs, focus ring. Les nuances au survol et à l’appui sont calculées à partir de cette couleur | "#e4002b" |
text | Texte principal | "#1a1a1a" |
muted | Texte secondaire : libellés, aides, dates | "#6b7280" |
heading | Titres, noms de transporteurs et de navires, lignes de carte | "#002f6c" |
background | Arrière-plan de la page de l’app. "transparent" laisse apparaître l’arrière-plan propre au client | "#ffffff" |
surface | Cartes, champs, lignes alternées des tableaux | "#f5f7fa" |
border | Bordures et séparateurs | "#e5e7eb" |
success | États positifs : livré, à l’heure, le moins cher | "#15803d" |
radius | Arrondi des angles des cartes et panneaux, px (0 à 40) | 8 |
buttonRadius | Arrondi des angles des boutons et champs, px. 999 donne des pastilles (par défaut) | 6 |
font | Police du corps de texte. Toute famille Google Fonts est chargée pour vous; "system" utilise la police système du visiteur | "Inter" |
headingFont | Police des titres, mêmes règles. Sans elle, les titres utilisent font | "Playfair Display" |
fontCss | Votre propre feuille de style de police (URL https:// avec règles @font-face), pour les polices qui ne sont pas sur Google Fonts. Ensuite font et headingFont nomment les familles de ce fichier | "https://acme.com/fonts/brand.css" |
mode | "dark" pour les sites au design sombre | "dark" |
Les couleurs sont en hex : #rgb, #rrggbb ou #rrggbbaa.
Points de départ prêts à l’emploi :
<!-- 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 thème pour toutes les pages. Nous pouvons aussi stocker le thème sur la clé. Chaque conteneur de chaque page le reçoit alors sans attribut, et nous pouvons l’ajuster plus tard sans modification sur le site du client. data-navo-theme sur un conteneur reste prioritaire sur le thème de la clé, clé par clé.
Le thème n’atteint que l’app à l’intérieur du cadre : il ne modifie jamais la page du client elle-même.
React et Next.js, avec indexation de recherche
Utilisez ceci lorsque le site du client est construit avec React ou Next.js et que le contenu de l’app doit être indexé comme page du client (par exemple, une page par lane, “horaire de navigation Shanghai vers Hamburg”).
Il y a deux parties :
- Snapshot. Le serveur du client récupère chez nous les données de la lane en HTML simple (tableau d’horaires ou de tarifs, titre, résumé en une ligne et balisage schema.org), puis les insère dans sa propre page. Les moteurs de recherche l’indexent comme contenu du client, sur l’URL du client.
- App. Dans le navigateur, l’app interactive se monte au-dessus, avec recherche, filtres, détails et réservation. Le snapshot reste sur la page sous forme de tableau repliable sous l’app, afin que les crawlers et les visiteurs voient le même contenu.
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
Sans format=html, la réponse est en 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"
}
}
Utilisez title et description pour le <title> de la page et la meta description, html pour le corps. La réponse peut être mise en cache pendant 30 minutes (Cache-Control: max-age=1800). Un snapshot compte comme une recherche dans la limite de l’app; la même lane le même jour est gratuite. Le suivi n’a pas de snapshot : les expéditions sont privées pour le visiteur.
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>
)}
</>
);
}
Ce que voit un moteur de recherche : le titre et la description propres à la page, un titre et un tableau complet des navigations (ou tarifs) dans le HTML, avec un balisage Dataset. Ce que voit un visiteur : l’app en direct, déjà ouverte sur cette lane, avec les mêmes résultats dans un tableau replié en dessous. Les visiteurs sans JavaScript voient le tableau ouvert. Le tableau est replié, pas masqué, donc la page ne montre aux crawlers rien qu’un visiteur ne puisse pas ouvrir.
Le HTML du snapshot vient de notre serveur avec chaque valeur échappée, il peut donc être inséré en toute sécurité. Stylisez-le avec les classes .navo-snapshot et .navo-snapshot-table s’il est affiché.
Les autres frameworks serveur (Remix, Astro, Nuxt, PHP, WordPress) fonctionnent de la même manière : récupérez le snapshot sur le serveur, imprimez html dans la page, placez le conteneur à côté.
React simple (sans rendu serveur)
Quand l’indexation de recherche n’est pas importante (une page de suivi derrière un menu, un intranet), le composant sans snapshot suffit :
Le loader fonctionne de la même manière dans une single-page app (React, Vue, Svelte) : rendez le conteneur, puis appelez 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' }} />
Dans Next.js, placez-le dans un composant client ('use client').
Pourquoi un cadre
Le loader rend chaque app dans un cadre depuis navo24.com. C’est ainsi que fonctionnent Stripe Checkout, les intégrations Google Maps et les lecteurs YouTube, pour les mêmes raisons :
- Verrouillage de domaine. Le navigateur lui-même refuse d’afficher l’app sur un site qui n’est pas dans la liste de la clé (
frame-ancestors). Un composant script chargé dans la page du client ne peut pas être verrouillé de cette façon. - Aucun conflit de styles. Le CSS du client ne peut pas casser l’app et notre CSS ne peut pas toucher leur site.
- Mises à jour sans le client. Nouveaux transporteurs, correctifs et fonctionnalités arrivent sur chaque site le même jour; rien à mettre à niveau côté client.
- Moteurs de recherche. Le contenu dans un cadre n’est pas indexé comme page du client, comme avec n’importe quelle intégration de carte ou de vidéo. Quand c’est important, ajoutez le snapshot rendu côté serveur, voir React et Next.js, avec indexation de recherche.
Les visiteurs ne se connectent pas dans le cadre, donc le blocage des cookies tiers par les navigateurs ne l’affecte pas.
Liens vers une vue exacte
Pendant qu’un visiteur utilise une app, l’URL de la page le suit : ?navo_app=<app>&navo=<view>. Les boutons Copier le lien dans les apps produisent le même type de lien. Exemples sur une page client /rates :
| Vue | Lien |
|---|---|
| Un conteneur | /track?navo_app=tracking&navo=ref%3DZMOU8956106 |
| Recherche de tarif sur une lane | /rates?navo_app=freight&navo=origin%3DCNSHA%26destination%3DDEHAM%26container%3D40HC |
| Un tarif | la recherche ci-dessus plus %26quote%3D<id> |
| Recherche d’horaire sur une lane | /schedules?navo_app=schedules&navo=origin%3DCNSHA%26destination%3DDEHAM |
| Une navigation | la recherche ci-dessus plus %26sailing%3D<id> |
| Un navire | /schedules?navo_app=schedules&navo=by%3Dvessel%26imo%3D9893890 |
| Un port | /schedules?navo_app=schedules&navo=by%3Dport%26port%3DSGSIN |
Un tarif ou une navigation partagés continuent de s’ouvrir après avoir quitté les résultats en direct; ils sont affichés avec la date à laquelle leurs données ont été prises.
Demandes de réservation
Réserver sur un tarif ouvre un formulaire de demande (contact, entreprise, e-mail, téléphone, nombre de conteneurs, date de disponibilité de la marchandise, marchandise, notes). À l’envoi :
- un e-mail part à l’adresse de réservation du client, avec la route, l’équipement, le transporteur, le prix vu par le visiteur et les coordonnées du visiteur. Reply-To est le visiteur, le client peut donc répondre directement depuis sa boîte mail;
- si un webhook est configuré, la même demande lui est envoyée en POST sous forme de 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" }
}
}
Le visiteur voit une confirmation avec la référence. Rien n’est facturé et aucune réservation transporteur n’est créée : le client confirme l’espace et répond.
Sans e-mail de réservation ni webhook, le formulaire reste une démo et l’indique.
Ce que les visiteurs voient, et ce qu’ils ne voient pas
- Noms et logos des transporteurs, prix, temps de transit, validité et ce qu’un tarif inclut.
- Les tarifs sans transporteur nommé sont affichés comme ”
Select”, avec le logo du client. - Les sources de tarifs et les plateformes ne sont jamais affichées. Elles sont supprimées sur notre serveur avant que les données n’atteignent le navigateur.
Sécurité
Verrouillage de domaine. Les pages d’app répondent avec Content-Security-Policy: frame-ancestors listant uniquement les domaines de la clé, donc un navigateur refuse de les afficher ailleurs. Les requêtes de données transportent la clé et l’hôte de la page parente, et sont refusées lorsque l’hôte n’est pas dans la liste. Une clé copiée dans un autre site n’y fonctionne pas.
Limites. Chaque app sur une clé a sa propre limite mensuelle ou annuelle (voir Limites d’utilisation). En plus, chaque clé a un plafond de sécurité de 50,000 requêtes par mois, un plafond de 600 requêtes par minute pour tout le site (afin qu’un pic de trafic d’un site ne ralentisse pas les apps des autres; augmenté sur demande) et des limites par visiteur contre les abus scriptés; au-delà, l’app affiche un court message “réessayez” et émet navo:limit.
Messages. Le cadre et le loader communiquent via postMessage, et chaque côté envoie uniquement vers l’origine exacte de l’autre : le cadre vers la page du client, le loader vers navo24.com. Les détails de recherche ne vont jamais vers *.
Rotation. Si une clé fuite ou si un site change de propriétaire, nous émettons une nouvelle clé et l’ancienne cesse immédiatement de fonctionner.
Tests avant lancement
Envoyez-nous le domaine de staging avec celui de production, ou localhost:<port> pour une machine de développement. Les deux peuvent être sur la même clé.
Checklist
- Le client envoie le nom, les domaines, le logo, la couleur, l’e-mail de réservation, les apps achetées (mode AI activé ou désactivé) et la limite de chaque app (et éventuellement le webhook, les chemins de pages).
- Nous créons la clé et envoyons les extraits.
- Le client ajoute
embed.jset les conteneurs, d’abord sur staging. - Le client vérifie : recherche → suivi, tarifs → détails → réservation (un e-mail de test arrive), un lien partagé s’ouvre sur son site. Avec une CSP stricte, vérifiez dans la console du navigateur les blocages de
navo24.com. - Le client ajoute le domaine de production (s’il n’est pas encore dans la liste) et met en ligne.