Web siteniz ile uygulamanız arasındaki köprü.

Uygulamaya duyarlı anlar sunan tek web sitesi.

SDK isteğe bağlı aşamalı bir geliştirmedir. Sayfalarınız hâlâ içeriğe, yönlendirmeye, hesaplara, alışveriş sepetlerine ve iş kurallarına sahiptir. Yerel kabuk, uygulama kromuna ve cihaz entegrasyonlarına sahiptir. SDK, ikisi arasında küçük, doğrulanmış mesajları iletir.

SiteTo.App genel REST hizmeti söz konusu değildir. Web sitelerinin SiteTo.App anahtarına ihtiyacı yoktur ve SDK hiçbir zaman mağaza kimlik bilgilerini, müşteri sırlarını veya ayrıcalıklı hesap belirteçlerini içermemelidir.

Açıkça sürümlendirilmiş tek bir komut dosyası.

CDN betiğini sıradan bir web sitesine ekleyin veya npm paketini birlikte verilen bir uygulamaya yükleyin. Her ikisi de aynı davranışı ve protokol sürümünü ortaya çıkarır.

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

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

Ana sürümler URL'de ve paket sözleşmesinde bulunur. Kırılmaz eklemeler içinde gönderilebilir v1; yeniden adlandırılan yöntemler, değişen veriler veya farklı geri dönüş davranışları v2.

Kullanıcı aracılarını değil, yetenekleri tespit edin.

SiteToApp.ready() yerel kabuk ile el sıkışmaya başlar ve AppContext. Aynı zamanda normal bir tarayıcıda da çözülmesi gerekir, böylece uygulama kodu, mevcut olmayan bir köprüyü beklerken asla askıda kalmaz.

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

Yerel başlığı bağlamda tutun.

Müşteriler ürünler, makaleler, hesap bölümleri veya ödeme işlemleri arasında dolaşırken sayfa, uygulama başlığını değiştirebilir. Varsayılan olarak, setTitle hem yerel başlığı günceller hem de document.title bu nedenle tarayıcı geçmişi de yararlı olmaya devam ediyor.

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

Şimdi önemli olan sayıyı gösterin.

Gezinme öğeleri, SiteTo.App oluşturucusunda yapılandırılmış kararlı kimlikleri kullanır; örneğin cart, inbox, veya bookings. Etiketler değişebilir ancak bu kimlikler web sitesi ile uygulama arasındaki sözleşme olarak kalır.

Bilinen bir değer ayarlayın

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

Bir URL'den güncelleme

İzleyici, verileri ayrı bir SiteTo.App hizmetinden değil, web sitesi bağlamında getirir. Göreceli, aynı kökenli URL'ler önerilir çünkü normal site çerezlerini ve güvenlik kurallarını olduğu gibi korurlar.

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

• 1'den 99'a kadar sayısal değerler görüntülenir; daha büyük değerler yerel olanı kullanır 99+ treatment.
• Metin değerleri kırpılır, arındırılır ve dört görünür karakterle sınırlandırılır.
• Uygulama arka plandayken oylama duraklatılır ve anında yenilemeyle devam eder.
• Çakışan istekler iptal edilir; en yeni geçerli yanıt kazanır.
• HTTP, ayrıştırma ve eşleme hataları ortaya çıkıyor sdk:error sayfayı bozmadan.

Yerel gezinmenin URL'yi anlamasını sağlayın.

Rota senkronizasyonu bağlantıları, tarayıcı geçmişini izler, popstate, pushState, Ve replaceState. Desenler kesin yolları destekler, * bir yol segmenti içinde ve ** segmentler arasında. Bir kural bunları tercih etmediği sürece sorgu dizeleri ve karmalar yok sayılır.

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.

Gezinme öğesini değiştirme veya açma

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

Yerini aldığı yerde cihaz davranışını kullanın.

Yerel eylemler, web sitesini kullanmak için bir gereklilik haline gelmemeli, mevcut bir web akışını iyileştirmelidir. İzin istemleri net bir kullanıcı eylemini takip etmeli ve öncelikle sayfada bunların değerini açıklamalıdır.

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

Web sitesinin uygulama yaşam döngüsüne yanıt vermesine izin verin.

Olaylar, şema ve kaynak doğrulamasının ardından yerel kabuktan SDK'ya akar. İşleyiciler genel, minimum miktarda veri alır ve bileşen tabanlı sitelerin bunları temizleyebilmesi için bir abonelikten çıkma işlevi döndürür.

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

Web sitesi bir web sitesi olarak kalmalıdır.

Uygulamanın içinde olmamak bir istisna değil normal bir durumdur. SDK, konsol gürültüsünden kaçınmalı ve yerel karşılığı olmadığında öngörülebilir sonuçlar vermelidir.

Tam yöntem referansı.

Yazılan hatalar: INVALID_ARGUMENT, UNSUPPORTED, NOT_ALLOWED, TIMEOUT, FETCH_FAILED, PROTOCOL_MISMATCH, Ve NATIVE_ERROR.

Küçük, onaylanmış bir mesaj zarfı.

JavaScript katmanı platform aktarım ayrıntılarını normalleştirir. Uygulamada mesajlar, React Native WebView aktarımı üzerinden serileştirilmiş JSON olarak seyahat eder. window.ReactNativeWebView.postMessage. Zarf bu aktarımdan bağımsızdır.

Web sitesinden uygulamaya

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

Uygulama onayı

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

Web sitesine uygulama

// 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 şununla başlar: bridge.hello; uygulama, desteklenen protokol sürümleri ve yetenekleriyle yanıt verir.
• Her komut benzersiz bir kimlik alır. Onaylanması gereken komutlar, bu kimliğe atıfta bulunan bir yanıt alır.
• Varsayılan onay zaman aşımı iki saniyedir. Zaman aşımı sona erdikten sonra geç yanıtlar dikkate alınmaz.
• İletiler yalnızca JSON'dur, 64 KB ile sınırlıdır ve her iki tarafta tam olarak bir kez ayrıştırılır.
• Tekrarlanan unvan ve rozet değişiklikleri iptal edilir; en son geçerli değer kazanır.
• __receive yalnızca uygulamaya yöneliktir, mümkün olduğunda numaralandırılamaz ve şema dışındaki iletileri reddeder.

Köprü tasarımı gereği dardır.

Web Görünümü köprüsü, web içeriği içinde yerel yetki oluşturur; böylece uygulama kabuğu, sayfa size ait olsa bile her sayfa iletisini güvenilmeyen giriş olarak değerlendirir. Şu kuralları uygular:

Entegrasyonunuzu test edin.

SDK yalnızca uygulamanızın içindeki davranışı değiştirir. Uygulama kullanıcılarının yerel deneyimi yaşaması ve tarayıcı ziyaretçilerinin web sitesinin tam olarak eskisi gibi çalışmaya devam etmesi için her iki yolu da kontrol edin.

• SDK'yı çağıran sayfaları normal bir mobil tarayıcıda açın ve context.available yanlıştır.
• Yavaş ağlar, çevrimdışı durum ve arka planda uzun süre kaldıktan sonra devam etme dahil olmak üzere iOS ve Android'deki uygulamada test edin.
• Yeniden yüklemelerden ve istemci tarafı rota değişikliklerinden sonra unvanları, rozetleri ve aktif navigasyonu kontrol edin.
• Yerel eylemler için kullanıcı hareketini, izin reddedilen ve desteklenmeyen yolları test edin.
• Siteniz İçerik Güvenliği Politikası kullanıyorsa SDK komut dosyası kaynağına izin verin.