geliştirici belgeleri

Uygulama vekili, yönetim paneli sayfası ve arayüz uzantıları

Vitrinde /apps/ altında uygulama sayfaları, yönetim panelinde gömülü uygulama sayfası (App Bridge, sayfa parçaları), arayüz uzantıları ve web pikselleri.

Bir uygulamanın mağazada görünebileceği dört yer vardır: vitrinde uygulama vekili, yönetim panelinde gömülü sayfası, platformun kendi sayfalarının içindeki arayüz uzantıları ve vitrinde ziyaretçi olaylarını dinleyen web pikselleri.

Uygulama vekili

Vitrindeki /apps/<subpath>/… adresleri uygulamanın sunucusundan getirilir. Böylece uygulama, mağazanın alan adı altında sayfa ve veri sunar.

[app_proxy]
subpath = "downloads"
url = "/proxy"

/apps/downloads/a/b?x=1 isteği <url>/a/b?x=1 adresine gider: yöntem, yol, sorgu ve gövde (en çok 1 MiB) iletilir.

İmzalı sorgu. Platform sorguya şunları ekler; ziyaretçinin aynı adlarla gönderdiği değerler değiştirilir:

Parametre Değer
store Mağazanın ana makine adı.
store_id Mağazanın sayısal kimliği. Kaydınızı bununla bulun.
logged_in_customer_id Giriş yapmış müşterinin kimliği; ziyaretçi için boş.
path_prefix /apps/<subpath>.
timestamp Unix saniyesi.
signature Aşağıdaki imza.

signature, diğer sorgu parametrelerinin gizli anahtarla hex HMAC-SHA256'sıdır: parametreler ada göre sıralanır, her biri ad=değer olarak yazılır (yinelenen adın değerleri virgülle birleşir) ve aralarına hiçbir şey konmadan birleştirilir. GET ve POST için aynıdır; gövde imzalanmaz. timestamp 5 dakikadan eskiyse reddedin.

Örnek: hush anahtarıyla, extra=1&extra=2&logged_in_customer_id=1000000003042&path_prefix=/apps/loyalty&store=acme.localhost&timestamp=1792317600 sorgusu şu metin üzerinden imzalanır:

extra=1,2logged_in_customer_id=1000000003042path_prefix=/apps/loyaltystore=acme.localhosttimestamp=1792317600

ve signature=8c30aea8e44a07efc83114e2d5bab975e9bf9cc23800f848804c7af10eab1cf4 olur.

Go'da Verifier.VerifyProxy bunu denetler: Go SDK.

Ne geçer, ne geçmez.

Temanın içinde çizmek. Content-Type: application/liquid ile dönen yanıt, mağazanın temasının düzeni içinde Liquid olarak çizilir.

Yönetim panelinde uygulama sayfası

[admin_embedded] olan bir uygulama, yönetim panelinde kendi sayfasını bir çerçevede (iframe) gösterir.

[admin_embedded]
entry_url = "/admin"
navigation = [
  { label = "Değerlendirmeler", path = "/" },
  { label = "KVKK talepleri", path = "/privacy-requests" },
]

navigation en çok 10 öğe alır ve birden çok öğe varsa çerçevenin üstünde sekme olarak görünür.

Çerçeve. Platform entry_url adresini, uygulamayı açarken kullandığı imzalı sorguya embedded=1 ve host (yönetim panelinin kökeni) ekleyerek açar; imza 5 dakika geçerlidir. Sayfanız yönetim panelinin çerçevelemesine izin vermelidir:

Content-Security-Policy: frame-ancestors https://admin.biticaret.com.tr

App Bridge. Sayfa, platformun istemci kitaplığı app-bridge.js ile yönetim paneliyle konuşur. Kitaplığı kendi kökeninizden sunun (Go SDK'da appsdk.ServeAppBridge):

<script src="/app-bridge.js?v={{.BridgeVersion}}"></script>

Platform kitaplığı genel bir adreste sunmaz. Go dışı bir uygulama dosyayı kendi sunucusundan sunar: Go şablonunun başlangıç deposunda sdk/pkg/appsdk/app-bridge.js olarak durur, onu kopyalayıp kendi statik dosyalarınıza koyun. ?v= parametresi yalnızca önbellek içindir; dosya her değiştiğinde yeni bir değer verin (Go SDK'da appsdk.AppBridgeVersion, içerikten türetilir).

var app = BiticaretAppBridge.createApp({ hostOrigin: document.body.dataset.host })

app
  .fetch('/api/hello')
  .then(function (res) {
    if (!res.ok) throw new Error('HTTP ' + res.status)
    return res.json()
  })
Çağrı Ne yapar
app.idToken() Bir oturum jetonu verir.
app.fetch(…) fetch gibi çalışır, oturum jetonunu Authorization: Bearer olarak ekler ve 401 gelirse bir kez yeniden dener.
app.titleBar.set(…) Çerçevenin üstündeki başlığı, ana düğmeyi, en çok üç ikincil düğmeyi (secondaryActions, her biri {label, disabled, onAction}) ve geri düğmesini (backAction) ayarlar.
app.toast.show(…) Kısa bir bildirim gösterir.
app.modal.open(…) Bir onay penceresi açar.
app.resourcePicker(…) Yönetim panelinin ürün veya koleksiyon seçicisini açar; seçilen kimlikleri verir.
app.navigate(…) Yönetim panelini mağazanın bir sayfasına götürür (/orders gibi).

Oturum jetonu. Tarayıcıdaki sayfanız kendi sunucunuzu oturum jetonuyla çağırır; sunucunuz jetonu doğrular ve hangi mağaza ile hangi personel adına çalıştığını ondan öğrenir. Jeton 60 saniyelik bir JWT'dir (HS256, uygulamanın gizli anahtarıyla):

Alan Değer
iss Yönetim panelinin kökeni.
dest Mağazanın adresi.
store_id Mağazanın sayısal kimliği. Kaydınızı bununla bulun, dest ile değil.
aud Uygulamanın client_id değeri.
sub Personelin sayısal kimliği, metin olarak.
exp, nbf, iat, jti Süre ve tekillik.

Jetonu yalnızca yönetim panelinde uygulamalar yetkisi olan personel alır. Go'da doğrulama: Go SDK.

Sayfayı kurmak. Yönetim paneli sayfası Biticaret Design System'in bt-* öğeleriyle çizilir; kendi görünümünüzü değil, panelin görünümünü taşır. Go SDK sayfanın kabuğunu hazır verir: appsdk.EmbeddedPage (Title, AdminOrigin, Static) tasarım sisteminin bağlantılarını, app-bridge.js, app-page.js ve static/admin.js betiklerini, yükleniyor durumunu ve içerik güvenliği kuralını (appsdk.EmbeddedPageCSP) içeren sayfayı sunar; Routes(mux, "/admin", …) sayfayı ve yüklediği dosyaları bağlar. Sayfanızın betiği <main id="app"> öğesini doldurur.

app-page.js her uygulamanın aynı çizdiği parçaları BiticaretAppPage olarak verir: h (öğe kurar), show (sayfayı çizer), stack, row, grid, card (başlıklı kart), table (kartta tablo), empty (boş durum), list, tabs, region, loading, text, muted ve strong.

var P = BiticaretAppPage
var app = BiticaretAppBridge.createApp({ hostOrigin: document.body.dataset.host })
var main = document.getElementById('app')

app.fetch('/admin/api/reviews').then(function (res) { return res.json() }).then(function (data) {
  P.show(main, 'Değerlendirmeler',
    data.reviews.length
      ? P.card({ title: 'Son değerlendirmeler' }, P.list(data.reviews.map(function (r) { return r.title })))
      : P.empty({ heading: 'Henüz değerlendirme yok' }))
})

Tasarım sistemi cdn.biticaret.com.tr üzerinden, SDK'nın sabitlediği sürümle (appsdk.DesignSystemVersion) ve bütünlük karmalarıyla yüklenir; SDK'yı güncellemek sürümü de günceller. Sunucuda çizilen, çerçeve dışındaki bir sayfa (kurulum formu, bir ileti) appsdk.ServerPageCSP kuralını kullanır.

Tema. Yönetim panelinin açık veya koyu teması sayfaya kendiliğinden ulaşır: app-bridge.js onu <html data-theme> özniteliğine yazar. Kitaplığı defer olmadan yükleyin ki sayfa yanlış temayla boyanmasın.

Arayüz uzantıları

Bir arayüz uzantısı, platformun kendi sayfasındaki bir yuvada çizilen küçük bir JavaScript modülüdür. Hedefler: Arayüz uzantısı hedefleri.

biticaret app generate extension --type ui_extension --name order-card
type = "ui_extension"
handle = "order_card"
name = "Sipariş kartı"
target = "admin.order.details.sidebar"
module = "order-card.js"

[capabilities]
network_access = true

[[settings.fields]]
key = "backend_url"
type = "single_line_text_field"
name = "Uygulama sunucusu"
default = "http://hello-ui.localhost:8093"

Modül hedefine bir işlev kaydeder:

biticaret.extension('admin.order.details.sidebar', function (root, api) {
  var orderId = api.data.selected[0].id
  var badge = root.createComponent('Badge', { tone: 'neutral' }, 'Not yok')
  root.appendChild(badge)
})

Kurallar:

Web pikselleri

Bir web pikseli, vitrinin ziyaretçi olaylarını dinleyen küçük bir JavaScript modülüdür (type = "web_pixel", bir uygulamada en çok 10). Vitrin onu gizli, yalıtılmış bir çerçevede çalıştırır: çerezlere, depolamaya ve sayfanın kendisine erişemez.

type = "web_pixel"
handle = "events"
name = "Olaylar"
module = "events.js"
consent = "analytics"

[[settings.fields]]
key = "measurement_id"
type = "string"
required = true
analytics.subscribe('product_viewed', function (event) {
  browser.sendBeacon('https://app.example.com/events?id=' + init.data.settings.measurement_id, JSON.stringify(event))
})