El puente entre su sitio web y su aplicación.

Un sitio web, con momentos conscientes de la aplicación.

El SDK es una mejora progresiva opcional. Sus páginas aún poseen contenido, enrutamiento, cuentas, carritos y reglas comerciales. El shell nativo posee integraciones de dispositivos y aplicaciones Chrome. El SDK pasa mensajes pequeños y validados entre los dos.

No hay ningún servicio REST público SiteTo.App involucrado. Los sitios web no necesitan una clave SiteTo.App y el SDK nunca debe contener credenciales de tienda, secretos de clientes ni tokens de cuentas privilegiadas.

Un script, versionado explícitamente.

Agregue el script CDN a un sitio web normal o instale el paquete npm en una aplicación incluida. Ambos exponen el mismo comportamiento y versión de protocolo.

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

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

Las versiones principales se encuentran en la URL y en el contrato del paquete. Las adiciones que no se rompen pueden enviarse dentro v1; Los métodos renombrados, las cargas útiles modificadas o un comportamiento alternativo diferente requieren v2.

Detectar capacidades, no agentes de usuario.

SiteToApp.ready() comienza un apretón de manos con el shell nativo y se resuelve en un AppContext. También debe resolverse en un navegador normal, de modo que el código de la aplicación nunca se cuelgue mientras espera un puente que no está 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');

Mantenga el encabezado nativo en contexto.

Una página puede cambiar el encabezado de la aplicación a medida que los clientes avanzan por los productos, artículos, secciones de la cuenta o al finalizar la compra. Por defecto, setTitle actualiza tanto el encabezado nativo como document.title por lo que el historial del navegador también sigue siendo útil.

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

Muestre el recuento que importa ahora.

Los elementos de navegación utilizan ID estables configurados en el generador SiteTo.App, como cart, inbox, o bookings. Las etiquetas pueden cambiar, pero esas identificaciones siguen siendo el contrato entre el sitio web y la aplicación.

Establecer un valor conocido

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

Actualizar desde una URL

Un observador busca en el contexto del sitio web, no desde un servicio SiteTo.App independiente. Se recomiendan URL relativas del mismo origen porque mantienen intactas las cookies normales del sitio y las reglas de seguridad.

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

• Los valores numéricos se muestran del 1 al 99; los valores más grandes usan el nativo 99+ treatment.
• Los valores de texto se recortan, desinfectan y se limitan a cuatro caracteres visibles.
• El sondeo se detiene mientras la aplicación está en segundo plano y se reanuda con una actualización inmediata.
• Las solicitudes superpuestas se cancelan; la respuesta válida más nueva gana.
• Se emiten errores de HTTP, análisis y asignación sdk:error sin romper la página.

Haga que la navegación nativa comprenda la URL.

La sincronización de rutas observa enlaces, historial del navegador, popstate, pushState, y replaceState. Los patrones admiten rutas exactas, * dentro de un segmento de ruta, y ** entre segmentos. Las cadenas de consulta y los hashes se ignoran a menos que una regla opte por utilizarlos.

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.

Cambiar o abrir un elemento de navegación

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

Utilice el comportamiento del dispositivo donde se gane su lugar.

Las acciones nativas deberían mejorar el flujo web existente, no convertirse en un requisito para utilizar el sitio web. Las solicitudes de permiso deben seguir una acción clara del usuario y explicar primero su valor en la página.

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

Deje que el sitio web responda al ciclo de vida de la aplicación.

Los eventos fluyen desde el shell nativo al SDK después de la validación del esquema y del origen. Los controladores reciben cargas útiles públicas mínimas y devuelven una función de cancelación de suscripción para que los sitios basados ​​en componentes puedan limpiarlas.

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

El sitio web debe seguir siendo un sitio web.

No estar dentro de la aplicación es un estado normal, no una excepción. El SDK debe evitar el ruido de la consola y devolver resultados predecibles cuando su contraparte nativa está ausente.

Referencia completa del método.

Errores escritos: INVALID_ARGUMENT, UNSUPPORTED, NOT_ALLOWED, TIMEOUT, FETCH_FAILED, PROTOCOL_MISMATCH, y NATIVE_ERROR.

Un sobre pequeño con mensaje reconocido.

La capa de JavaScript normaliza los detalles del transporte de la plataforma. En la aplicación, los mensajes viajan a través del transporte React Native WebView como JSON serializado a través de window.ReactNativeWebView.postMessage. El sobre es independiente de ese transporte.

Sitio web a aplicación

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

Reconocimiento de la aplicación

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

Aplicación al sitio 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() },
});

• El SDK comienza con bridge.hello; la aplicación responde con capacidades y versiones de protocolo compatibles.
• Cada comando obtiene una identificación única. Los comandos que necesitan confirmación reciben una respuesta que hace referencia a ese ID.
• El tiempo de espera de confirmación predeterminado es de dos segundos. Las respuestas tardías se ignoran una vez transcurrido el tiempo de espera.
• Los mensajes son solo JSON, están limitados a 64 KB y se analizan exactamente una vez en cada lado.
• Los cambios repetidos de título e insignia no rebotan; el último valor válido gana.
• __receive es solo de implementación, no enumerable cuando sea posible y rechaza mensajes fuera del esquema.

El puente es estrecho por diseño.

Un puente WebView crea autoridad nativa dentro del contenido web, por lo que el shell de la aplicación trata cada mensaje de la página como entrada que no es de confianza, incluso cuando la página le pertenece. Hace cumplir estas reglas:

Pruebe su integración.

El SDK solo cambia el comportamiento dentro de tu aplicación. Verifique ambas rutas para que los usuarios de la aplicación obtengan la experiencia nativa y los visitantes del navegador mantengan el sitio web funcionando exactamente como antes.

• Abra las páginas que llaman al SDK en un navegador móvil normal y confirme que nada se rompe cuando context.available es falso.
• Pruebe en la aplicación en iOS y Android, incluidas redes lentas, estado fuera de línea y reanudación después de un largo tiempo en segundo plano.
• Verifique títulos, insignias y navegación activa después de recargas y cambios de ruta del lado del cliente.
• Para acciones nativas, pruebe las rutas de gestos de usuario, permiso denegado y no admitidas.
• Si su sitio utiliza una Política de seguridad de contenido, permita el origen del script del SDK.