The bridge between your website and its app.

One website, with app-aware moments.

The SDK should be an optional progressive enhancement. Your pages still own content, routing, accounts, carts, and business rules. The native shell owns app chrome and device integrations. The SDK passes small, validated messages between the two.

There is no SiteTo.App public REST service in this design. Websites do not need a SiteTo.App key, and the SDK must never contain store credentials, customer secrets, or privileged account tokens.

A future script, explicitly versioned.

The first release should support a small CDN script for ordinary websites and an npm package for bundled applications. Both must expose the same behavior and protocol version.

<!-- Planned CDN address — not live yet -->
<script
  src="https://cdn.siteto.app/sdk/v1/sitetoapp.min.js"
  defer
></script>

// Planned package — not published yet
import { SiteToApp } from '@sitetoapp/web-sdk';

Major versions live in the URL and package contract. Non-breaking additions can ship within v1; renamed methods, changed payloads, or different fallback behavior require v2.

Detect capabilities, not user agents.

SiteToApp.ready() begins a handshake with the native shell and resolves to an AppContext. It must also resolve in a normal browser, so application code never hangs while waiting for a bridge that is not present.

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

Keep the native header in context.

A page can change the app header as customers move through products, articles, account sections, or checkout. By default, setTitle updates both the native header and document.title so browser history remains useful too.

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

Show the count that matters now.

Navigation items use stable IDs configured in the SiteTo.App builder, such as cart, inbox, or bookings. Labels may change, but those IDs remain the contract between the website and app.

Set a known value

// 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 from a URL

A watcher fetches in the website context—not from a separate SiteTo.App service. Relative, same-origin URLs are recommended because they keep normal site cookies and security rules intact.

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

• Numeric values display from 1–99; larger values use the native 99+ treatment.
• Text values are trimmed, sanitized, and limited to four visible characters.
• Polling pauses while the app is backgrounded and resumes with one immediate refresh.
• Overlapping requests are cancelled; the newest valid response wins.
• HTTP, parsing, and mapping failures emit sdk:error without breaking the page.

Make native navigation understand the URL.

Route synchronization watches links, browser history, popstate, pushState, and replaceState. Patterns support exact paths, * within one path segment, and ** across segments. Query strings and hashes are ignored unless a rule opts into them.

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.

Change or open a navigation 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();

Use device behavior where it earns its place.

Native actions should improve an existing web flow, not become a requirement for using the website. Permission prompts must follow a clear user action and explain their value in the page first.

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

Let the website respond to app lifecycle.

Events flow from the native shell into the SDK after schema and origin validation. Handlers receive public, minimal payloads and return an unsubscribe function so component-based sites can clean them up.

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

The website must remain a website.

Not being inside the app is a normal state, not an exception. The SDK must avoid console noise and return predictable results when its native counterpart is absent.

Complete method reference.

Initial typed errors: INVALID_ARGUMENT, UNSUPPORTED, NOT_ALLOWED, TIMEOUT, FETCH_FAILED, PROTOCOL_MISMATCH, and NATIVE_ERROR.

A small, acknowledged message envelope.

The JavaScript layer normalizes platform transport details. The first app implementation should use the React Native WebView transport and send serialized JSON through window.ReactNativeWebView.postMessage. The envelope stays independent of that transport so a future native WebView adapter can reuse it.

Website to app

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

App acknowledgement

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

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

• The SDK starts with bridge.hello; the app responds with supported protocol versions and capabilities.
• Every command gets a unique ID. Commands that need confirmation receive a response referencing that ID.
• The default acknowledgement timeout is two seconds. Late responses are ignored after a timeout settles.
• Messages are JSON only, limited to 64 KB, and parsed exactly once on each side.
• Repeated title and badge changes are debounced; the latest valid value wins.
• __receive is implementation-only, non-enumerable where possible, and rejects messages outside the schema.

The bridge is narrow by design.

A WebView bridge creates native authority inside web content, so the shell must treat every page message as untrusted input—even when the page belongs to the customer.

Ship the dependable core first.

The first implementation should stay deliberately small. Later capabilities only belong in the SDK after both app platforms can support the same contract and browser behavior is documented.

Release checklist

• Test iOS, Android, Safari, Chrome, slow networks, offline state, and app resume after a long background period.
• Publish TypeScript definitions and keep the global script and module exports behaviorally identical.
• Add an SDK compatibility matrix to each generated app build.
• Replace every “planned” notice on this page only after the matching artifact is publicly available.