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×tamp=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.
- Uygulamaya yalnızca şu başlıklar gider:
Accept,Accept-Language,Content-Type,If-Modified-Since,If-None-Match,Origin,User-Agent,X-Requested-With. Platform ayrıcaX-Biticaret-Store-Id,X-Biticaret-Store-Domain,X-Biticaret-Customer-Id(yalnızca giriş yapılmışsa),X-Biticaret-SignatureveX-Forwarded-Forekler; bunlar kolaylıktır, kanıt imzalı sorgudur. - Uygulamadan yalnızca şu başlıklar döner:
Cache-Control,Content-Disposition,Content-Language,Content-Type,ETag,Expires,Last-Modified,Location,Vary. - Çerezler ve
Authorizationhiçbir yönde geçmez. - Yanıt uygulamanın durum koduyla döner; yönlendirmeler izlenmez, olduğu gibi iletilir. Giriş yapmış müşteriye verilen yanıt her zaman
private, no-storeolur. - Sınırlar: çağrının tamamı için 10 saniye (aşılırsa
504), yanıt için 5 MB (daha büyük birContent-Lengthiçin502), istek gövdesi için 1 MiB (aşılırsa413). Dosya sunan bir uygulamaapp_proxy.large_responsesileGETveHEADiçin 120 saniye ve 256 MiB isteyebilir; bu sınırlar platform izin verdiğinde geçerli olur (Yapılandırma).
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:
- Uzantı ham HTML yazamaz; yalnızca platformun bileşenlerini kullanır:
Card,Stack,Text,Badge,Banner,Button,TextField,Select,Checkbox,Divider. - Kod, sayfadan yalıtılmış bir Web Worker'da çalışır: çerezlere, depolamaya ve sayfanın kendisine erişemez.
- Ağa yalnızca
capabilities.network_access = trueise çıkar. Kendi sunucusunuapi.sessionToken()ile aldığı jetonla çağırır. - Bir modül en çok 64 KB'tır; bir uygulama en çok 25 arayüz uzantısı taşır; bir uzantı en çok 20 ayar alanı tanımlar (
single_line_text_field,multi_line_text_field,boolean,number_integer,number_decimal).choiceslistesi olan birsingle_line_text_fieldtek seçimli bir ayardır. - Mağaza, yönetim panelinin Ayarlar → Uzantılar sayfasında her uzantıyı açıp kapatır, aynı hedefteki uzantıların sırasını seçer ve ayarlarını doldurur; uzantı bunları
api.settings.currentolarak okur, doldurulmayan alanlar varsayılanlarıyla gelir.targetslistesi olan bir uzantıyı mağaza bu hedefler arasında taşıyabilir; modül her hedef içinbiticaret.extensionile bir işlev kaydeder. - Bir uzantı yalnızca kurulu sürümü onaylanmış uygulamalar için çizilir.
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))
})
- Olaylar:
page_viewed,product_viewed,collection_viewed,search_submitted,product_added_to_cart,cart_viewed,checkout_started,checkout_completed. - Piksel olayları yalnızca ziyaretçi
consentkategorisini (analyticsveyamarketing) onayladıysa alır. init.datamağazayı, giriş yapmış ziyaretçide müşteriyi vesettingsaltında kurulumun ayar değerlerini taşır.browsersendBeaconvefetchverir.- Ayarlar. Piksel en çok 20 ayar alanı tanımlar (
string, en çok 500 karakter, veyastring_list; toplam 4 KB). Değerleri satıcı değil uygulama yazar:GET,PUT /api/v1/pixels/{pixelID}/settings(write_pixels). Zorunlu bir ayar boşken piksel çalışmaz; yönetim panelinin Müşteri olayları sayfası onu ayarları yapılmamış olarak gösterir.