Le pont entre votre site Web et son application.

Un site Web, avec des moments compatibles avec les applications.

Le SDK est une amélioration progressive facultative. Vos pages possèdent toujours le contenu, le routage, les comptes, les paniers et les règles métier. Le shell natif possède les applications Chrome et les intégrations d'appareils. Le SDK transmet de petits messages validés entre les deux.

Aucun service REST public SiteTo.App n’est impliqué. Les sites Web n'ont pas besoin d'une clé SiteTo.App et le SDK ne doit jamais contenir d'informations d'identification de magasin, de secrets clients ou de jetons de compte privilégié.

Un script, explicitement versionné.

Ajoutez le script CDN à un site Web ordinaire ou installez le package npm dans une application groupée. Les deux exposent le même comportement et la même version de protocole.

<script
  src="https://cdn.siteto.app/sdk/v1/sitetoapp.min.js"
  defer
></script>

import { SiteToApp } from '@sitetoapp/web-sdk';

Les versions majeures se trouvent dans l'URL et le contrat de package. Les ajouts ininterrompus peuvent être expédiés dans les v1; des méthodes renommées, des charges utiles modifiées ou un comportement de repli différent nécessitent v2.

Détectez les capacités, pas les agents utilisateurs.

SiteToApp.ready() commence une poignée de main avec le shell natif et se résout en un AppContext. Il doit également être résolu dans un navigateur normal, afin que le code de l'application ne se bloque jamais en attendant un pont qui n'est pas présent.

const context = await SiteToApp.ready({ timeout: 1500 });

if (!context.available) {
  // Normal browser: keep using your existing web behavior.
  return;
}

await SiteToApp.page.setTitle('Order details');
await SiteToApp.navigation.setActive('orders');

Gardez l'en-tête natif dans son contexte.

Une page peut modifier l'en-tête de l'application à mesure que les clients parcourent les produits, les articles, les sections du compte ou le paiement. Par défaut, setTitle met à jour à la fois l'en-tête natif et document.title l'historique du navigateur reste donc également utile.

// Update both the document title and the app header.
await SiteToApp.page.setTitle('Your cart');

// Change only the native header.
await SiteToApp.page.setTitle('Checkout', {
  document: false,
  native: true,
});

// Return to the title derived from the page or app configuration.
await SiteToApp.page.resetTitle();

Montrez le décompte qui compte maintenant.

Les éléments de navigation utilisent des ID stables configurés dans le générateur SiteTo.App, tels que cart, inbox, ou bookings. Les étiquettes peuvent changer, mais ces identifiants restent le contrat entre le site Web et l'application.

Définir une valeur connue

// Numbers are formatted by the native app: 100 becomes “99+”.
await SiteToApp.navigation.setBadge('cart', 3);

// Zero, null, or false hides the badge.
await SiteToApp.navigation.setBadge('cart', 0);

// Short status labels are also allowed.
await SiteToApp.navigation.setBadge('inbox', 'NEW');

Mettre à jour à partir d'une URL

Un observateur récupère dans le contexte du site Web, et non à partir d'un service SiteTo.App distinct. Les URL relatives de même origine sont recommandées car elles conservent intacts les cookies normaux du site et les règles de sécurité.

const cartBadge = SiteToApp.navigation.watchBadge('cart', {
  url: '/cart.js',
  jsonPath: 'item_count',
  interval: 30_000,
  refreshOn: ['ready', 'resume', 'focus', 'urlchange'],
  hideWhenZero: true,
  stale: 'keep',
});

// Refresh after a local add-to-cart action.
await cartBadge.refresh();

// Stop fetching when this page no longer owns the badge.
cartBadge.stop();

• Les valeurs numériques s'affichent de 1 à 99 ; les valeurs plus grandes utilisent le natif 99+ treatment.
• Les valeurs de texte sont tronquées, nettoyées et limitées à quatre caractères visibles.
• L'interrogation s'interrompt pendant que l'application est en arrière-plan et reprend avec une actualisation immédiate.
• Les demandes qui se chevauchent sont annulées ; la réponse valide la plus récente l'emporte.
• Les échecs HTTP, d'analyse et de mappage émettent sdk:error sans casser la page.

Faites en sorte que la navigation native comprenne l'URL.

La synchronisation des itinéraires surveille les liens, l'historique du navigateur, popstate, pushState, et replaceState. Les modèles prennent en charge les chemins exacts, * dans un segment de chemin, et ** à travers les segments. Les chaînes de requête et les hachages sont ignorés, sauf si une règle les accepte.

const stopSync = SiteToApp.navigation.syncWithLocation([
  { itemId: 'home', match: '/' },
  { itemId: 'shop', match: ['/collections/**', '/products/**'] },
  { itemId: 'cart', match: '/cart*' },
  { itemId: 'account', match: '/account/**' },
]);

// Works with links, popstate, pushState, and replaceState.
// Call stopSync() only if your router takes over this responsibility.

Modifier ou ouvrir un élément de navigation

// Adapt native navigation after sign-in without sharing identity data.
await SiteToApp.navigation.setItem('account', {
  label: 'Account',
  visible: true,
  enabled: true,
});

await SiteToApp.navigation.open('/account/orders');
await SiteToApp.navigation.back();

Utilisez le comportement de l’appareil là où il mérite sa place.

Les actions natives doivent améliorer un flux Web existant et non devenir une condition nécessaire à l'utilisation du site Web. Les invites d'autorisation doivent suivre une action claire de l'utilisateur et expliquer d'abord leur valeur dans la page.

await SiteToApp.share({
  title: 'Spring collection',
  text: 'These just arrived.',
  url: window.location.href,
});

// Must be called from a user click or tap.
const permission = await SiteToApp.notifications.requestPermission();

// Use sparingly for confirmation, not decoration.
await SiteToApp.haptics.impact('light');

Laissez le site Web répondre au cycle de vie des applications.

Les événements circulent du shell natif vers le SDK après validation du schéma et de l’origine. Les gestionnaires reçoivent des charges utiles publiques minimales et renvoient une fonction de désabonnement afin que les sites basés sur des composants puissent les nettoyer.

const unsubscribe = SiteToApp.on('app:resume', () => {
  cartBadge.refresh();
});

SiteToApp.on('navigation:reselect', ({ itemId }) => {
  if (itemId === 'home') window.scrollTo({ top: 0, behavior: 'smooth' });
});

SiteToApp.on('notification:opened', ({ url }) => {
  if (url) window.location.assign(url);
});

// Remove a listener when its owning component unmounts.
unsubscribe();

Le site Internet doit rester un site Internet.

Ne pas être à l’intérieur de l’application est un état normal et non une exception. Le SDK doit éviter le bruit de la console et renvoyer des résultats prévisibles lorsque son homologue natif est absent.

Référence complète de la méthode.

Erreurs de frappe : INVALID_ARGUMENT, UNSUPPORTED, NOT_ALLOWED, TIMEOUT, FETCH_FAILED, PROTOCOL_MISMATCH, et NATIVE_ERROR.

Une petite enveloppe de message reconnu.

La couche JavaScript normalise les détails du transport de la plateforme. Dans l'application, les messages transitent via le transport React Native WebView sous forme de JSON sérialisé via window.ReactNativeWebView.postMessage. L'enveloppe est indépendante de ce transport.

Du site Web à l'application

{
  "channel": "sitetoapp",
  "protocolVersion": 1,
  "id": "sta_01J8ZQ6JY1",
  "type": "navigation.badge.set",
  "payload": {
    "itemId": "cart",
    "value": 3
  },
  "timestamp": 1789584000000
}

Reconnaissance de l'application

{
  "channel": "sitetoapp",
  "protocolVersion": 1,
  "type": "response",
  "replyTo": "sta_01J8ZQ6JY1",
  "ok": true,
  "payload": null
}

Application vers le site Web

// Native shell → website. Internal SDK method; not public surface.
window.SiteToApp.__receive({
  channel: 'sitetoapp',
  protocolVersion: 1,
  type: 'event',
  event: 'app:resume',
  payload: { occurredAt: Date.now() },
});

• Le SDK commence par bridge.hello; l'application répond avec les versions et capacités de protocole prises en charge.
• Chaque commande reçoit un identifiant unique. Les commandes qui nécessitent une confirmation reçoivent une réponse faisant référence à cet ID.
• Le délai d'expiration d'accusé de réception par défaut est de deux secondes. Les réponses tardives sont ignorées une fois le délai d'attente écoulé.
• Les messages sont uniquement au format JSON, limités à 64 Ko et analysés exactement une fois de chaque côté.
• Les changements répétés de titre et de badge sont annulés ; la dernière valeur valide gagne.
• __receive est uniquement implémenté, non énumérable lorsque cela est possible et rejette les messages en dehors du schéma.

Le pont est étroit de par sa conception.

Un pont WebView crée une autorité native dans le contenu Web, de sorte que le shell de l'application traite chaque message de page comme une entrée non fiable, même lorsque la page vous appartient. Il applique ces règles :

Testez votre intégration.

Le SDK modifie uniquement le comportement au sein de votre application. Vérifiez les deux chemins afin que les utilisateurs de l'application bénéficient de l'expérience native et que les visiteurs du navigateur continuent de fonctionner exactement comme avant.

• Ouvrez les pages qui appellent le SDK dans un navigateur mobile normal et confirmez que rien ne se casse lorsque context.available est faux.
• Testez dans l'application sur iOS et Android, y compris les réseaux lents, l'état hors ligne et la reprise après une longue période en arrière-plan.
• Vérifiez les titres, les badges et la navigation active après les rechargements et les changements d'itinéraire côté client.
• Pour les actions natives, testez les chemins de geste de l’utilisateur, d’autorisation refusée et non pris en charge.
• Si votre site utilise une politique de sécurité du contenu, autorisez l'origine du script SDK.