Skip to content
Navo24Navo24

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émentExempleObligatoire
Nom de l’entreprise tel qu’il doit apparaître aux visiteursAcme LogisticsOui
Domaines sur lesquels les apps seront utilisées (production, staging)acme.com, www.acme.com, staging.acme.comOui
Logo, SVG ou PNG, pictogramme carré ou horizontalhttps://acme.com/logo.svgOui
Couleur de marque, une valeur hex#0e6ba8Oui
Couleurs supplémentaires, polices, arrondi des anglesvoir ApparenceFacultatif
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/navoFacultatif
Apps souhaitéesau choix parmi suivi, fret, horaires; mode AI activé ou désactivéOui
Limite d’utilisation par app, par mois ou par ansuivi : 300 expéditions uniques par moisOui
Pages où chaque app sera placée/track, /rates, /schedulesRecommandé
“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é :

PackageApps sur la cléCe que le visiteur obtient
Suivi uniquementtrackingPage de suivi; le widget de recherche affiche le champ de suivi, sans onglets ni interrupteur AI
Suivi avec AItracking, aiLa même chose, plus le mode AI dans le widget de recherche et “Demander à l’AI” sur les expéditions
Tarifs et horairesfreight, schedulesDeux onglets dans le widget de recherche, les pages tarifs et horaires
Touttracking, freight, schedules, aiLes 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é :

AppUne unitéRépétitions gratuites
trackingUne 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
freightUne recherche de tarif (lane et équipement)La même recherche le même jour
schedulesUne recherche d’horaire (route, navire ou port)La même recherche le même jour
aiUne question à l’assistant AIAucune

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 .” Les autres apps de la clé continuent de fonctionner. Nous voyons l’utilisation par app et pouvons augmenter une limite à tout moment, sans modification sur le site du client.

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

AttributRôle
data-navo-appsearch, tracking, freight ou schedules.
data-navo-keyLa clé d’intégration du site.
data-navo-pagesMap JSON entre app et chemin de page sur le site du client.
data-navo-heightHauteur fixe en px. Par défaut, le cadre grandit avec son contenu; le suivi est une carte complète, 680 px.
data-navo-syncoff garde l’URL de la page inchangée pendant que le visiteur navigue.
data-navo-themeJSON 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énementQuandevent.detail
navo:searchUne recherche a renvoyé des résultatsapp (tracking, freight, schedules) et la requête : ref, ou origin, destination, container
navo:bookingUne demande de réservation a été envoyéereference, origin, destination, container, quantity, carrier, price, currency
navo:limitUne limite a bloqué une rechercheapp, 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 modifieExemple
accentBoutons, liens, onglets actifs, interrupteurs, focus ring. Les nuances au survol et à l’appui sont calculées à partir de cette couleur"#e4002b"
textTexte principal"#1a1a1a"
mutedTexte secondaire : libellés, aides, dates"#6b7280"
headingTitres, noms de transporteurs et de navires, lignes de carte"#002f6c"
backgroundArrière-plan de la page de l’app. "transparent" laisse apparaître l’arrière-plan propre au client"#ffffff"
surfaceCartes, champs, lignes alternées des tableaux"#f5f7fa"
borderBordures et séparateurs"#e5e7eb"
successÉtats positifs : livré, à l’heure, le moins cher"#15803d"
radiusArrondi des angles des cartes et panneaux, px (0 à 40)8
buttonRadiusArrondi des angles des boutons et champs, px. 999 donne des pastilles (par défaut)6
fontPolice du corps de texte. Toute famille Google Fonts est chargée pour vous; "system" utilise la police système du visiteur"Inter"
headingFontPolice des titres, mêmes règles. Sans elle, les titres utilisent font"Playfair Display"
fontCssVotre 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 :

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

VueLien
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 tarifla recherche ci-dessus plus %26quote%3D<id>
Recherche d’horaire sur une lane/schedules?navo_app=schedules&navo=origin%3DCNSHA%26destination%3DDEHAM
Une navigationla 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

  1. 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).
  2. Nous créons la clé et envoyons les extraits.
  3. Le client ajoute embed.js et les conteneurs, d’abord sur staging.
  4. 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.
  5. Le client ajoute le domaine de production (s’il n’est pas encore dans la liste) et met en ligne.