Choisir son intégration

Le widget offre quatre surfaces d’intégration. Celle qui s’applique est dictée par ce dont vous disposez déjà — une page, une page avec du JavaScript, ou seulement une URL — plutôt que par une préférence.

Les quatre surfaces

Vous avez	Intégration	Le contexte arrive par	Identité	Événements
Une page dans un CMS, sans JavaScript	Balise de script	data-*	—	—
Une page où vous écrivez du JavaScript	API JavaScript	setContext()	setGuestToken()	Oui
Seulement un lien — e-mail, SMS, QR	Lien profond	Chaîne de requête	?t=	—
Rien où intégrer quoi que ce soit	La page de réservation, en lien	—	—	—

Les deux premières placent le widget sur votre page. Les deux dernières envoient le client vers la page de réservation autonome, sur book.useservice.app.

Ce qui tranche

L’identité exige du JavaScript ou un lien

Un jeton signé atteint le widget par setGuestToken() ou par ?t= sur un lien profond. Il n’existe volontairement aucun attribut data-token.

Un attribut fait partie du HTML de la page : il est servi à tous les lecteurs, mis en cache par le CMS et par tout ce qui se trouve devant, et visible dans le code source. Un jeton vit 15 minutes et identifie un client : une copie gravée dans une page est donc à la fois expirée et fausse pour presque tous ceux qui la reçoivent.

Si l’intégration doit savoir qui réserve, il lui faut une page capable d’exécuter setGuestToken(), ou un lien généré pour un client au moment où il est envoyé.

Les verrous appliqués exigent un jeton ; les verrous affichés, non

N’importe quelle surface peut verrouiller un champ pour que le client le voie fixe : un attribut, un paramètre d’URL ou un appel JavaScript le font tous.

Ce qui exige le jeton signé, c’est l’application. Le serveur ne refuse une réservation contradictoire que si le verrou est arrivé dans le jeton, seule version qu’il puisse tenir pour vraie. Un verrou non signé est affiché, pas appliqué.

Cette différence ne détermine la surface que lorsque la valeur doit réellement tenir — un bon cadeau valable un seul jour, un créneau prépayé. Pour refléter simplement un choix déjà fait sur votre page, rien n’est nécessaire.

Les événements exigent une page

reservation:created et reservation:confirmed sont livrés à la page qui a créé l’instance. Un lien profond n’a pas de telle page : le client est sur book.useservice.app, et votre site n’est pas dans le navigateur du tout.

Les réservations issues d’un lien profond se récupèrent comme celles prises par téléphone — via l’API ou un webhook, sur votre serveur. Ce chemin fonctionne aussi pour les cas intégrés, et c’est celui à utiliser quand l’enregistrement compte : un événement navigateur n’est pas livré si le client ferme l’onglet.

La présentation est un choix distinct

inline, sticky et popover décident de la façon dont le widget apparaît sur une de vos pages. Ces modes s’appliquent aux deux surfaces intégrées et sont indépendants de tout ce qui précède : une balise de script dans un CMS peut être un popover, et une intégration JavaScript peut être en ligne.

Mode	Apparaît comme	Convient à
inline	Une partie de la page, dans votre conteneur.	Une section ou une page dédiée à la réservation.
sticky	Un bouton flottant que le widget affiche lui-même.	Un site sans emplacement évident.
popover	Rien, jusqu’à ce qu’un déclencheur ou open() l’ouvre.	Votre bouton, votre style.

Plusieurs restaurants sur une même page

Un site de groupe qui liste huit restaurants crée une instance par restaurant :

const instances = restaurants.map((r) => ServiceWidget.create({ slug: r.slug, mode: "popover" }));

Chaque instance s’adresse séparément. ServiceWidget.open() et ServiceWidget.close() sur l’objet global ne peuvent pas en désigner une parmi plusieurs — close() les ferme toutes, volontairement, pour qu’aucune instance ne reste ouverte sans que rien ne puisse l’atteindre.

Avec les déclencheurs déclaratifs, chaque déclencheur porte le restaurant qu’il ouvre :

<button data-service-widget-open data-slug="chez-marie">Réserver</button>
<button data-service-widget-open data-slug="le-comptoir">Réserver</button>

Par où commencer

• Le site d’un restaurant, sans développeur. La balise de script, depuis le back-office. Elle se suffit à elle-même : aucune intégration supplémentaire n’est nécessaire pour prendre des réservations.
• Un site de groupe ou un espace client où le visiteur est connecté. L’API JavaScript avec un jeton : le parcours s’ouvre en sachant qui réserve, et tout ce que le séjour fixe déjà peut être verrouillé.
• Une campagne, une confirmation de séjour, une carte de chambre. Un lien profond. N’ajoutez ?t= que là où le lien est généré par client et envoyé immédiatement — jamais sur un support imprimé.