Jembatan antara situs web Anda dan aplikasinya.

Satu situs web, dengan momen sadar aplikasi.

SDK adalah penyempurnaan progresif opsional. Halaman Anda masih memiliki konten, perutean, akun, keranjang, dan aturan bisnis. Shell asli memiliki aplikasi chrome dan integrasi perangkat. SDK meneruskan pesan kecil yang tervalidasi di antara keduanya.

Tidak ada layanan REST publik SiteTo.App yang terlibat. Situs web tidak memerlukan kunci SiteTo.App, dan SDK tidak boleh berisi kredensial toko, rahasia pelanggan, atau token akun istimewa.

Satu skrip, diversi secara eksplisit.

Tambahkan skrip CDN ke situs web biasa, atau instal paket npm dalam aplikasi yang dibundel. Keduanya memperlihatkan perilaku dan versi protokol yang sama.

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

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

Versi utama ada di URL dan kontrak paket. Penambahan non-breaking dapat dikirimkan dalam v1; mengganti nama metode, mengubah payload, atau memerlukan perilaku fallback yang berbeda v2.

Deteksi kemampuan, bukan agen pengguna.

SiteToApp.ready() memulai jabat tangan dengan shell asli dan memutuskan untuk an AppContext. Itu juga harus diselesaikan di browser normal, sehingga kode aplikasi tidak pernah hang saat menunggu jembatan yang tidak ada.

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

Pertahankan tajuk asli dalam konteks.

Halaman dapat mengubah header aplikasi saat pelanggan menelusuri produk, artikel, bagian akun, atau pembayaran. Secara default, setTitle memperbarui header asli dan document.title jadi riwayat browser juga tetap berguna.

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

Tunjukkan hitungan yang penting sekarang.

Item navigasi menggunakan ID stabil yang dikonfigurasi di pembuat SiteTo.App, seperti cart, inbox, atau bookings. Label dapat berubah, namun ID tersebut tetap merupakan kontrak antara situs web dan aplikasi.

Tetapkan nilai yang diketahui

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

Perbarui dari URL

Pengamat mengambil dalam konteks situs web—bukan dari layanan SiteTo.App terpisah. URL relatif dengan asal yang sama direkomendasikan karena menjaga cookie situs normal dan aturan keamanan tetap utuh.

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

• Nilai numerik ditampilkan dari 1–99; nilai yang lebih besar menggunakan yang asli 99+ treatment.
• Nilai teks dipangkas, dibersihkan, dan dibatasi hingga empat karakter yang terlihat.
• Jajak pendapat dijeda saat aplikasi berada di latar belakang dan dilanjutkan dengan satu penyegaran langsung.
• Permintaan yang tumpang tindih dibatalkan; respons valid terbaru menang.
• Kegagalan HTTP, penguraian, dan pemetaan terjadi sdk:error tanpa merusak halamannya.

Jadikan navigasi asli memahami URL-nya.

Tautan jam tangan sinkronisasi rute, riwayat browser, popstate, pushState, Dan replaceState. Pola mendukung jalur yang tepat, * dalam satu segmen jalur, dan ** lintas segmen. String dan hash kueri akan diabaikan kecuali ada aturan yang mengizinkannya.

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.

Mengubah atau membuka item navigasi

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

Gunakan perilaku perangkat yang sesuai dengan tempatnya.

Tindakan asli harus meningkatkan aliran web yang ada, bukan menjadi persyaratan untuk menggunakan situs web. Perintah izin harus mengikuti tindakan pengguna yang jelas dan menjelaskan nilainya di halaman terlebih dahulu.

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

Biarkan situs web merespons siklus hidup aplikasi.

Peristiwa mengalir dari shell asli ke SDK setelah validasi skema dan asal. Penangan menerima muatan publik dan minimal dan mengembalikan fungsi berhenti berlangganan sehingga situs berbasis komponen dapat membersihkannya.

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

Situs web harus tetap menjadi situs web.

Tidak berada di dalam aplikasi adalah keadaan normal, tidak terkecuali. SDK harus menghindari gangguan konsol dan mengembalikan hasil yang dapat diprediksi ketika versi aslinya tidak ada.

Referensi metode lengkap.

Kesalahan yang diketik: INVALID_ARGUMENT, UNSUPPORTED, NOT_ALLOWED, TIMEOUT, FETCH_FAILED, PROTOCOL_MISMATCH, Dan NATIVE_ERROR.

Amplop pesan kecil yang diakui.

Lapisan JavaScript menormalkan detail transportasi platform. Di aplikasi, pesan dikirim melalui transportasi React Native WebView sebagai serial JSON window.ReactNativeWebView.postMessage. Amplop tidak bergantung pada pengangkutan itu.

Situs web ke aplikasi

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

Pengakuan aplikasi

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

Aplikasi ke situs 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() },
});

• SDK dimulai dengan bridge.hello; aplikasi merespons dengan versi dan kemampuan protokol yang didukung.
• Setiap perintah mendapat ID unik. Perintah yang memerlukan konfirmasi menerima respons yang merujuk pada ID tersebut.
• Batas waktu pengakuan default adalah dua detik. Respons yang terlambat akan diabaikan setelah batas waktu habis.
• Pesan hanya berupa JSON, dibatasi hingga 64 KB, dan diurai tepat satu kali di setiap sisi.
• Perubahan judul dan lencana yang berulang akan dibatalkan; nilai valid terbaru menang.
• __receive hanya untuk implementasi, tidak dapat dihitung jika memungkinkan, dan menolak pesan di luar skema.

Jembatan ini sempit secara desain.

Jembatan WebView menciptakan otoritas asli di dalam konten web, sehingga shell aplikasi memperlakukan setiap pesan halaman sebagai masukan yang tidak tepercaya—bahkan ketika halaman tersebut milik Anda. Ini menegakkan aturan-aturan ini:

Uji integrasi Anda.

SDK hanya mengubah perilaku di dalam aplikasi Anda. Periksa kedua jalur sehingga pengguna aplikasi mendapatkan pengalaman asli dan pengunjung browser menjaga situs web tetap berfungsi persis seperti sebelumnya.

• Buka halaman yang memanggil SDK di browser seluler normal dan konfirmasikan tidak ada kerusakan saat itu context.available adalah salah.
• Uji dalam aplikasi di iOS dan Android, termasuk jaringan lambat, keadaan offline, dan dilanjutkan kembali setelah sekian lama di latar belakang.
• Periksa judul, lencana, dan navigasi aktif setelah memuat ulang dan perubahan rute sisi klien.
• Untuk tindakan asli, uji jalur gestur pengguna, ditolak izin, dan tidak didukung.
• Jika situs Anda menggunakan Kebijakan Keamanan Konten, izinkan asal skrip SDK.