De brug tussen uw website en zijn app.

Eén website, met app-bewuste momenten.

De SDK is een optionele progressieve verbetering. Uw pagina's zijn nog steeds eigenaar van inhoud, routing, accounts, winkelwagentjes en bedrijfsregels. De native shell is eigenaar van app-chrome en apparaatintegraties. De SDK geeft kleine, gevalideerde berichten door tussen de twee.

Er is geen openbare SiteTo.App-REST-service bij betrokken. Websites hebben geen SiteTo.App-sleutel nodig en de SDK mag nooit winkelreferenties, klantgeheimen of geprivilegieerde accounttokens bevatten.

Eén script, expliciet versiebeheer.

Voeg het CDN-script toe aan een gewone website of installeer het npm-pakket in een gebundelde applicatie. Beide vertonen hetzelfde gedrag en dezelfde protocolversie.

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

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

De belangrijkste versies staan ​​in de URL en het pakketcontract. Niet-brekende toevoegingen kunnen binnen worden verzonden v1; hernoemde methoden, gewijzigde payloads of ander terugvalgedrag vereisen v2.

Detecteer mogelijkheden, geen user agents.

SiteToApp.ready() begint een handdruk met de oorspronkelijke shell en besluit tot een AppContext. Het moet ook in een normale browser worden opgelost, zodat applicatiecode nooit blijft hangen tijdens het wachten op een bridge die niet aanwezig is.

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

Houd de native header in context.

Een pagina kan de app-koptekst wijzigen terwijl klanten door producten, artikelen, accountsecties of afrekenen gaan. Standaard, setTitle werkt zowel de native header als document.title dus de browsergeschiedenis blijft ook nuttig.

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

Toon de telling die er nu toe doet.

Navigatie-items gebruiken stabiele ID's die zijn geconfigureerd in de SiteTo.App-builder, zoals cart, inbox, of bookings. Labels kunnen veranderen, maar die ID's blijven het contract tussen de website en de app.

Stel een bekende waarde in

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

Updaten vanaf een URL

Een watcher haalt op in de websitecontext, niet uit een afzonderlijke SiteTo.App-service. Relatieve URL's van dezelfde oorsprong worden aanbevolen omdat ze de normale sitecookies en beveiligingsregels intact houden.

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

• Numerieke waarden worden weergegeven van 1–99; grotere waarden gebruiken de native 99+ treatment.
• Tekstwaarden zijn ingekort, opgeschoond en beperkt tot vier zichtbare tekens.
• De peiling wordt onderbroken terwijl de app op de achtergrond staat en wordt hervat met één onmiddellijke vernieuwing.
• Overlappende verzoeken worden geannuleerd; het nieuwste geldige antwoord wint.
• Er worden HTTP-, parserings- en toewijzingsfouten uitgezonden sdk:error zonder de pagina te breken.

Zorg ervoor dat native navigatie de URL begrijpt.

Routesynchronisatie bekijkt links, browsergeschiedenis, popstate, pushState, En replaceState. Patronen ondersteunen exacte paden, * binnen één padsegment, en ** over segmenten heen. Queryreeksen en hashes worden genegeerd, tenzij een regel hiervoor toestemming geeft.

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.

Wijzig of open een navigatie-item

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

Gebruik apparaatgedrag waar het zijn plaats verdient.

Native acties moeten een bestaande webflow verbeteren en geen vereiste worden voor het gebruik van de website. Toestemmingsprompts moeten een duidelijke gebruikersactie volgen en eerst hun waarde op de pagina uitleggen.

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

Laat de website reageren op de levenscyclus van de app.

Gebeurtenissen stromen van de systeemeigen shell naar de SDK na validatie van het schema en de oorsprong. Handlers ontvangen openbare, minimale payloads en retourneren een afmeldingsfunctie, zodat op componenten gebaseerde sites deze kunnen opruimen.

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

De website moet een website blijven.

Het niet aanwezig zijn in de app is een normale toestand en geen uitzondering. De SDK moet consoleruis vermijden en voorspelbare resultaten retourneren wanneer de oorspronkelijke tegenhanger afwezig is.

Volledige methodereferentie.

Getypte fouten: INVALID_ARGUMENT, UNSUPPORTED, NOT_ALLOWED, TIMEOUT, FETCH_FAILED, PROTOCOL_MISMATCH, En NATIVE_ERROR.

Een kleine, bevestigde berichtenvelop.

De JavaScript-laag normaliseert platformtransportdetails. In de app reizen berichten via het React Native WebView-transport als geserialiseerde JSON door window.ReactNativeWebView.postMessage. De envelop is onafhankelijk van dat transport.

Website naar app

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

App-bevestiging

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

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

• De SDK begint met bridge.hello; de app reageert met ondersteunde protocolversies en -mogelijkheden.
• Elke opdracht krijgt een unieke ID. Commando's die bevestiging nodig hebben, ontvangen een antwoord dat naar die ID verwijst.
• De standaardtime-out voor bevestiging is twee seconden. Late reacties worden genegeerd nadat een time-out is verstreken.
• Berichten zijn alleen JSON, beperkt tot 64 KB, en worden aan elke kant precies één keer geparseerd.
• Herhaalde titel- en badgewijzigingen worden ongedaan gemaakt; de laatste geldige waarde wint.
• __receive is alleen voor implementatie, waar mogelijk niet opsombaar, en weigert berichten buiten het schema.

De brug is smal van opzet.

Een WebView-bridge creëert native autoriteit binnen webinhoud, zodat de app-shell elk paginabericht als niet-vertrouwde invoer behandelt, zelfs als de pagina van u is. Het handhaaft deze regels:

Test uw integratie.

De SDK verandert alleen het gedrag binnen uw app. Controleer beide paden, zodat app-gebruikers de native ervaring krijgen en browserbezoekers de website precies zo laten werken als voorheen.

• Open de pagina's die de SDK aanroepen in een normale mobiele browser en controleer of er niets kapot gaat context.available is vals.
• Test in de app op iOS en Android, inclusief trage netwerken, offline status en hervatten na lange tijd op de achtergrond.
• Controleer titels, badges en actieve navigatie na herlaadbeurten en routewijzigingen aan de klantzijde.
• Voor systeemeigen acties test u de paden voor gebruikersgebaren, geweigerde rechten en niet-ondersteunde paden.
• Als uw site gebruikmaakt van een inhoudsbeveiligingsbeleid, sta dan de oorsprong van het SDK-script toe.