Die Brücke zwischen Ihrer Website und ihrer App.

Eine Website mit App-Erlebnissen.

Das SDK ist eine optionale progressive Erweiterung. Ihre Seiten besitzen weiterhin Inhalte, Routing, Konten, Warenkörbe und Geschäftsregeln. Die native Shell verfügt über App-Chrome- und Geräteintegrationen. Das SDK leitet kleine, validierte Nachrichten zwischen den beiden weiter.

Es ist kein öffentlicher SiteTo.App-REST-Dienst beteiligt. Websites benötigen keinen SiteTo.App-Schlüssel und das SDK darf niemals Anmeldeinformationen für den Shop, Kundengeheimnisse oder Token für privilegierte Konten enthalten.

Ein Skript, explizit versioniert.

Fügen Sie das CDN-Skript zu einer normalen Website hinzu oder installieren Sie das npm-Paket in einer gebündelten Anwendung. Beide weisen das gleiche Verhalten und die gleiche Protokollversion auf.

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

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

Hauptversionen sind im URL- und Paketvertrag enthalten. Geschützte Ergänzungen können innerhalb von 24 Stunden versandt werden v1; Umbenennte Methoden, geänderte Payloads oder ein anderes Fallback-Verhalten erfordern v2.

Erkennen Sie Fähigkeiten, nicht Benutzeragenten.

SiteToApp.ready() beginnt einen Handshake mit der nativen Shell und wird zu einem AppContext. Es muss auch in einem normalen Browser aufgelöst werden, damit der Anwendungscode niemals hängen bleibt, während er auf eine Brücke wartet, die nicht vorhanden ist.

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');

Behalten Sie den Kontext des nativen Headers bei.

Eine Seite kann den App-Header ändern, wenn Kunden Produkte, Artikel, Kontoabschnitte oder den Checkout durchlaufen. Standardmäßig ist setTitle Aktualisiert sowohl den nativen Header als auch document.title Daher bleibt auch der Browserverlauf nützlich.

// 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();

Zeigen Sie die Anzahl an, auf die es jetzt ankommt.

Navigationselemente verwenden stabile IDs, die im SiteTo.App-Builder konfiguriert sind, z cart, inbox, oder bookings. Bezeichnungen können sich ändern, diese IDs bleiben jedoch der Vertrag zwischen der Website und der App.

Legen Sie einen bekannten Wert fest

// 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');

Update von einer URL

Ein Watcher ruft im Website-Kontext ab – nicht von einem separaten SiteTo.App-Dienst. Relative URLs mit demselben Ursprung werden empfohlen, da sie die normalen Website-Cookies und Sicherheitsregeln beibehalten.

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();

• Numerische Werte werden von 1–99 angezeigt; Größere Werte verwenden den nativen Wert 99+ treatment.
• Textwerte werden gekürzt, bereinigt und auf vier sichtbare Zeichen beschränkt.
• Die Abfrage wird angehalten, während die App im Hintergrund läuft, und mit einer sofortigen Aktualisierung fortgesetzt.
• Überlappende Anfragen werden storniert; Die neueste gültige Antwort gewinnt.
• Es werden HTTP-, Parsing- und Mapping-Fehler ausgegeben sdk:error ohne die Seite zu zerstören.

Sorgen Sie dafür, dass die native Navigation die URL versteht.

Routensynchronisierung überwacht Links, Browserverlauf, popstate, pushState, Und replaceState. Muster unterstützen exakte Pfade, * innerhalb eines Pfadsegments und ** segmentübergreifend. Abfragezeichenfolgen und Hashes werden ignoriert, es sei denn, eine Regel aktiviert sie.

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.

Navigationselement ändern oder öffnen

// 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();

Nutzen Sie das Geräteverhalten dort, wo es seinen Platz verdient.

Native Aktionen sollen einen bestehenden Webfluss verbessern und nicht zur Voraussetzung für die Nutzung der Website werden. Berechtigungsaufforderungen müssen einer klaren Benutzeraktion folgen und ihren Wert zuerst auf der Seite erläutern.

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');

Lassen Sie die Website auf den App-Lebenszyklus reagieren.

Ereignisse fließen nach der Schema- und Ursprungsvalidierung von der nativen Shell in das SDK. Handler empfangen öffentliche, minimale Nutzlasten und geben eine Abmeldefunktion zurück, damit komponentenbasierte Websites diese bereinigen können.

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();

Die Website muss eine Website bleiben.

Nicht in der App zu sein ist ein normaler Zustand und keine Ausnahme. Das SDK muss Konsolenrauschen vermeiden und vorhersehbare Ergebnisse liefern, wenn sein natives Gegenstück fehlt.

Vollständige Methodenreferenz.

Tippfehler: INVALID_ARGUMENT, UNSUPPORTED, NOT_ALLOWED, TIMEOUT, FETCH_FAILED, PROTOCOL_MISMATCH, Und NATIVE_ERROR.

Ein kleiner, quittierter Nachrichtenumschlag.

Die JavaScript-Schicht normalisiert Plattformtransportdetails. In der App werden Nachrichten über den React Native WebView-Transport als serialisiertes JSON übertragen window.ReactNativeWebView.postMessage. Der Umschlag ist unabhängig von diesem Transport.

Von der Website zur App

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

App-Bestätigung

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

App zur Website

// 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() },
});

• Das SDK beginnt mit bridge.hello; Die App antwortet mit unterstützten Protokollversionen und -funktionen.
• Jeder Befehl erhält eine eindeutige ID. Befehle, die eine Bestätigung benötigen, erhalten eine Antwort mit Verweis auf diese ID.
• Das Standard-Bestätigungs-Timeout beträgt zwei Sekunden. Verspätete Antworten werden nach Ablauf einer Zeitüberschreitung ignoriert.
• Nachrichten sind nur JSON, auf 64 KB begrenzt und werden auf jeder Seite genau einmal analysiert.
• Wiederholte Titel- und Abzeichenänderungen werden entprellt; der letzte gültige Wert gewinnt.
• __receive ist nur für die Implementierung gedacht, nach Möglichkeit nicht aufzählbar und lehnt Nachrichten außerhalb des Schemas ab.

Die Brücke ist konstruktionsbedingt schmal.

Eine WebView-Bridge schafft native Autorität innerhalb von Webinhalten, sodass die App-Shell jede Seitennachricht als nicht vertrauenswürdige Eingabe behandelt – selbst wenn die Seite Ihnen gehört. Es erzwingt die folgenden Regeln:

Testen Sie Ihre Integration.

Das SDK ändert nur das Verhalten innerhalb Ihrer App. Überprüfen Sie beide Pfade, damit App-Benutzer das native Erlebnis erhalten und Browser-Besucher dafür sorgen, dass die Website genauso funktioniert wie zuvor.

• Öffnen Sie die Seiten, die das SDK aufrufen, in einem normalen mobilen Browser und vergewissern Sie sich, dass nichts kaputt geht context.available ist falsch.
• Testen Sie in der App auf iOS und Android, einschließlich langsamer Netzwerke, Offline-Status und Wiederaufnahme nach langer Zeit im Hintergrund.
• Überprüfen Sie Titel, Abzeichen und aktive Navigation nach Neuladungen und clientseitigen Routenänderungen.
• Testen Sie für native Aktionen die Pfade „Benutzergeste“, „Berechtigung verweigert“ und „Nicht unterstützt“.
• Wenn Ihre Site eine Inhaltssicherheitsrichtlinie verwendet, lassen Sie den SDK-Skriptursprung zu.