Il ponte tra il tuo sito web e la sua app.

Un sito Web, con momenti compatibili con le app.

L'SDK è un miglioramento progressivo facoltativo. Le tue pagine possiedono ancora contenuti, routing, account, carrelli e regole aziendali. La shell nativa possiede il Chrome dell'app e le integrazioni del dispositivo. L'SDK trasmette messaggi piccoli e convalidati tra i due.

Non è coinvolto alcun servizio REST pubblico SiteTo.App. I siti Web non necessitano di una chiave SiteTo.App e l'SDK non deve mai contenere credenziali del negozio, segreti del cliente o token di account privilegiati.

Uno script, con versione esplicita.

Aggiungi lo script CDN a un normale sito Web o installa il pacchetto npm in un'applicazione in bundle. Entrambi espongono lo stesso comportamento e la stessa versione del protocollo.

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

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

Le versioni principali risiedono nell'URL e nel contratto del pacchetto. Le aggiunte non-breaking possono essere spedite all'interno v1; richiedono metodi rinominati, payload modificati o comportamenti di fallback diversi v2.

Rileva le capacità, non gli user agent.

SiteToApp.ready() inizia una stretta di mano con la shell nativa e si risolve in an AppContext. Deve anche risolversi in un normale browser, quindi il codice dell'applicazione non si blocca mai in attesa di un bridge non presente.

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

Mantieni l'intestazione nativa nel contesto.

Una pagina può modificare l'intestazione dell'app mentre i clienti si spostano tra prodotti, articoli, sezioni dell'account o checkout. Per impostazione predefinita, setTitle aggiorna sia l'intestazione nativa che document.title quindi anche la cronologia del browser rimane 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();

Mostra il conteggio che conta adesso.

Gli elementi di navigazione utilizzano ID stabili configurati nel builder SiteTo.App, ad esempio cart, inbox, O bookings. Le etichette possono cambiare, ma tali ID rimangono il contratto tra il sito Web e l'app.

Imposta un valore noto

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

Aggiornamento da un URL

Un osservatore recupera nel contesto del sito Web, non da un servizio SiteTo.App separato. Si consigliano URL relativi della stessa origine perché mantengono intatti i normali cookie del sito e le regole di sicurezza.

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

• I valori numerici vengono visualizzati da 1 a 99; valori più grandi utilizzano il nativo 99+ treatment.
• I valori del testo vengono ritagliati, ripuliti e limitati a quattro caratteri visibili.
• Il polling viene interrotto mentre l'app è in background e riprende con un aggiornamento immediato.
• Le richieste sovrapposte vengono annullate; prevale la risposta valida più recente.
• Vengono generati errori HTTP, di analisi e di mappatura sdk:error senza rompere la pagina.

Fai in modo che la navigazione nativa comprenda l'URL.

La sincronizzazione del percorso guarda i collegamenti, la cronologia del browser, popstate, pushState, E replaceState. I modelli supportano percorsi esatti, * all'interno di un segmento del percorso e ** attraverso i segmenti. Le stringhe di query e gli hash vengono ignorati a meno che una regola non li attivi.

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.

Modifica o apri un elemento di navigazione

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

Utilizza il comportamento del dispositivo dove merita il suo posto.

Le azioni native dovrebbero migliorare un flusso web esistente, non diventare un requisito per l'utilizzo del sito web. Le richieste di autorizzazione devono seguire una chiara azione dell'utente e spiegare prima il loro valore nella pagina.

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

Lascia che il sito web risponda al ciclo di vita dell'app.

Gli eventi fluiscono dalla shell nativa all'SDK dopo la convalida dello schema e dell'origine. I gestori ricevono payload pubblici e minimi e restituiscono una funzione di annullamento dell'iscrizione in modo che i siti basati su componenti possano ripulirli.

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

Il sito web deve rimanere un sito web.

Non essere all'interno dell'app è uno stato normale, non un'eccezione. L'SDK deve evitare il rumore della console e restituire risultati prevedibili quando la sua controparte nativa è assente.

Riferimento completo al metodo.

Errori digitati: INVALID_ARGUMENT, UNSUPPORTED, NOT_ALLOWED, TIMEOUT, FETCH_FAILED, PROTOCOL_MISMATCH, E NATIVE_ERROR.

Una piccola busta del messaggio con conferma.

Il livello JavaScript normalizza i dettagli di trasporto della piattaforma. Nell'app, i messaggi viaggiano sul trasporto React Native WebView come JSON serializzato window.ReactNativeWebView.postMessage. La busta è indipendente da tale trasporto.

Dal sito web all'app

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

Riconoscimento dell'app

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

Dall'app al sito 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() },
});

• L'SDK inizia con bridge.hello; l'app risponde con versioni e funzionalità del protocollo supportate.
• Ogni comando riceve un ID univoco. I comandi che necessitano di conferma ricevono una risposta che fa riferimento a quell'ID.
• Il timeout di riconoscimento predefinito è di due secondi. Le risposte tardive vengono ignorate una volta stabilito il timeout.
• I messaggi sono solo JSON, limitati a 64 KB e analizzati esattamente una volta su ciascun lato.
• Le modifiche ripetute al titolo e al badge vengono rimbalzate; prevale l'ultimo valore valido.
• __receive è di sola implementazione, non enumerabile ove possibile e rifiuta i messaggi esterni allo schema.

Il ponte è stretto per progettazione.

Un bridge WebView crea un'autorità nativa all'interno del contenuto web, quindi la shell dell'app tratta ogni messaggio della pagina come input non attendibile, anche quando la pagina appartiene a te. Fa rispettare queste regole:

Metti alla prova la tua integrazione.

L'SDK modifica solo il comportamento all'interno della tua app. Controlla entrambi i percorsi in modo che gli utenti dell'app ottengano l'esperienza nativa e i visitatori del browser mantengano il sito Web funzionante esattamente come prima.

• Apri le pagine che chiamano l'SDK in un normale browser mobile e conferma che non si interrompe nulla quando context.available è falso.
• Test nell'app su iOS e Android, incluse reti lente, stato offline e ripresa dopo un lungo periodo in background.
• Controlla titoli, badge e navigazione attiva dopo i ricaricamenti e le modifiche al percorso lato client.
• Per le azioni native, testa i percorsi gesto utente, autorizzazione negata e non supportato.
• Se il tuo sito utilizza una politica di sicurezza dei contenuti, consenti l'origine dello script SDK.