The bridge between your website and its app.

One website, with app-aware moments.

The SDK is 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 involved. Websites do not need a SiteTo.App key, and the SDK must never contain store credentials, customer secrets, or privileged account tokens.

One script, explicitly versioned.

Add the CDN script to an ordinary website, or install the npm package in a bundled application. Both expose the same behavior and protocol version.

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

npm install @sitetoapp/web-sdk

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.setBadge('/orders', 2);

What works where

Keep the native header in context.

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

// Updates the app's header and document.title together.
await SiteToApp.page.setTitle('Your cart');

// Return to your app's name.
await SiteToApp.page.resetTitle();

Show the count that matters now.

A menu item is addressed by the path of its link, so the tab linking to your cart page is '/cart'. Your website already knows its paths, and changing a label or translating it changes nothing. The same link in two menus stays in step. Badges appear on bottom tabs, side menu items, and header icons, and a path no menu links to is rejected with NOT_ALLOWED.

Set a known value

// A menu item is addressed by the path of its link.
// Numbers are formatted by the 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',
  select: (cart) => cart.item_count,
  interval: 30_000,
});

// 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.
• After a failed request the last valid badge stays up, and sdk:error fires without breaking the page. Requests time out after five seconds.

The app already understands the URL.

The app highlights a tab from the current URL by itself, including route changes in single-page applications, so most websites need no code here. The longest matching link wins: a page at /shop/shirt highlights the tab linking to /shop. The tab linking to / matches only the home page, and stays highlighted on pages no other tab matches.

Choose the tab yourself

// Show a product page under the Shop tab.
await SiteToApp.navigation.setActive('/collections');

// Return to automatic highlighting.
await SiteToApp.navigation.setActive(null);

Let your router handle tabs

// Without this, a tab or notification loads its page.
// With it, your router handles the change and the page doesn't reload.
const stop = SiteToApp.navigation.handleOpen((url) => {
  router.push(new URL(url).pathname);
});

// Call stop() if your router stops handling this.

Change or open a menu item

// Adapt the app's menus 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 app into the SDK after validation. on returns an unsubscribe function so component-based sites can clean up. For connectivity and color scheme, use the browser’s own online events and prefers-color-scheme, which work in the app too.

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

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

// The app opens the notification's page itself. Use this for analytics.
SiteToApp.on('notification:opened', ({ url }) => {
  analytics.track('push_opened', { 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.

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

A small, acknowledged message envelope.

In the app, messages travel over the React Native WebView transport as serialized JSON through window.ReactNativeWebView.postMessage. The envelope is independent of that transport.

Website to app

{
  "channel": "sitetoapp",
  "protocolVersion": 1,
  "id": "sta_01J8ZQ6JY1",
  "type": "navigation.badge.set",
  "payload": {
    "path": "/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.
• Each page starts unconnected: the app sends it no events until it says hello.
• 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 app shell treats every page message as untrusted input—even when the page belongs to you. It enforces these rules:

Test your integration.

The SDK only changes behavior inside your app. Check both paths so app users get the native experience and browser visitors keep the website working exactly as before.

• Open the pages that call the SDK in a normal mobile browser and confirm nothing breaks when context.available is false.
• Test in the app on iOS and Android, including slow networks, offline state, and resuming after a long time in the background.
• Check titles, badges, and the highlighted tab after reloads and client-side route changes.
• For native actions, test the user-gesture, permission-denied, and unsupported paths.
• If your site uses a Content Security Policy, allow the SDK script origin.