A ponte entre seu site e seu aplicativo.

Um site, com momentos de reconhecimento de aplicativos.

O SDK é um aprimoramento progressivo opcional. Suas páginas ainda possuem conteúdo, roteamento, contas, carrinhos e regras de negócios. O shell nativo possui integrações de aplicativos e dispositivos cromados. O SDK passa mensagens pequenas e validadas entre os dois.

Não há nenhum serviço REST público SiteTo.App envolvido. Os sites não precisam de uma chave SiteTo.App e o SDK nunca deve conter credenciais de loja, segredos de clientes ou tokens de contas privilegiadas.

Um script, com versão explícita.

Adicione o script CDN a um site comum ou instale o pacote npm em um aplicativo incluído. Ambos expõem o mesmo comportamento e versão do protocolo.

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

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

As versões principais residem no URL e no contrato do pacote. Adições ininterruptas podem ser enviadas dentro v1; métodos renomeados, cargas alteradas ou comportamento de fallback diferente exigem v2.

Detecte recursos, não agentes de usuário.

SiteToApp.ready() inicia um aperto de mão com o shell nativo e resolve para um AppContext. Ele também deve ser resolvido em um navegador normal, para que o código do aplicativo nunca seja interrompido enquanto aguarda uma ponte que não 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');

Mantenha o cabeçalho nativo no contexto.

Uma página pode alterar o cabeçalho do aplicativo conforme os clientes navegam pelos produtos, artigos, seções da conta ou finalização da compra. Por padrão, setTitle atualiza o cabeçalho nativo e document.title portanto, o histórico do navegador também permanece ú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();

Mostre a contagem que importa agora.

Os itens de navegação usam IDs estáveis ​​configurados no construtor SiteTo.App, como cart, inbox, ou bookings. Os rótulos podem mudar, mas esses IDs continuam sendo o contrato entre o site e o aplicativo.

Defina um valor conhecido

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

Atualizar a partir de um URL

Um observador busca no contexto do site, não em um serviço SiteTo.App separado. URLs relativos e de mesma origem são recomendados porque mantêm intactos os cookies normais do site e as regras de segurança.

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

• Os valores numéricos são exibidos de 1 a 99; valores maiores usam o nativo 99+ treatment.
• Os valores de texto são cortados, limpos e limitados a quatro caracteres visíveis.
• A pesquisa é pausada enquanto o aplicativo está em segundo plano e é retomada com uma atualização imediata.
• Solicitações sobrepostas são canceladas; a resposta válida mais recente vence.
• Falhas de HTTP, análise e mapeamento são emitidas sdk:error sem quebrar a página.

Faça a navegação nativa entender o URL.

A sincronização de rotas monitora links, histórico do navegador, popstate, pushState, e replaceState. Os padrões suportam caminhos exatos, * dentro de um segmento de caminho, e ** entre segmentos. Strings de consulta e hashes são ignorados, a menos que uma regra os aceite.

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.

Alterar ou abrir um item de navegação

// 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 o comportamento do dispositivo onde ele merece seu lugar.

As ações nativas devem melhorar um fluxo da web existente e não se tornar um requisito para o uso do site. Os prompts de permissão devem seguir uma ação clara do usuário e explicar primeiro seu valor na 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');

Deixe o site responder ao ciclo de vida do aplicativo.

Os eventos fluem do shell nativo para o SDK após a validação do esquema e da origem. Os manipuladores recebem cargas públicas mínimas e retornam uma função de cancelamento de assinatura para que sites baseados em componentes possam limpá-los.

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

O site deve permanecer um site.

Não estar dentro do aplicativo é um estado normal, não uma exceção. O SDK deve evitar ruídos de console e retornar resultados previsíveis quando sua contraparte nativa estiver ausente.

Referência completa do método.

Erros de digitação: INVALID_ARGUMENT, UNSUPPORTED, NOT_ALLOWED, TIMEOUT, FETCH_FAILED, PROTOCOL_MISMATCH, e NATIVE_ERROR.

Um envelope de mensagem pequeno e confirmado.

A camada JavaScript normaliza os detalhes de transporte da plataforma. No aplicativo, as mensagens viajam pelo transporte React Native WebView como JSON serializado por meio de window.ReactNativeWebView.postMessage. O envelope é independente desse transporte.

Site para aplicativo

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

Reconhecimento do aplicativo

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

Aplicativo para site

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

• O SDK começa com bridge.hello; o aplicativo responde com versões e recursos de protocolo suportados.
• Cada comando obtém um ID exclusivo. Os comandos que precisam de confirmação recebem uma resposta referenciando esse ID.
• O tempo limite de confirmação padrão é de dois segundos. As respostas tardias são ignoradas depois que o tempo limite é estabelecido.
• As mensagens são apenas JSON, limitadas a 64 KB e analisadas exatamente uma vez em cada lado.
• Mudanças repetidas de títulos e emblemas são rejeitadas; o último valor válido vence.
• __receive é apenas de implementação, não enumerável sempre que possível e rejeita mensagens fora do esquema.

A ponte é estreita por design.

Uma ponte WebView cria autoridade nativa dentro do conteúdo da web, de modo que o shell do aplicativo trata cada mensagem da página como entrada não confiável, mesmo quando a página pertence a você. Ele impõe estas regras:

Teste sua integração.

O SDK altera apenas o comportamento dentro do seu aplicativo. Verifique os dois caminhos para que os usuários do aplicativo tenham a experiência nativa e os visitantes do navegador mantenham o site funcionando exatamente como antes.

• Abra as páginas que chamam o SDK em um navegador móvel normal e confirme que nada quebra quando context.available é falso.
• Teste no aplicativo em iOS e Android, incluindo redes lentas, estado off-line e retomada após muito tempo em segundo plano.
• Verifique títulos, emblemas e navegação ativa após recargas e alterações de rota do lado do cliente.
• Para ações nativas, teste os caminhos de gesto do usuário, permissão negada e sem suporte.
• Se o seu site usa uma Política de Segurança de Conteúdo, permita a origem do script SDK.