# 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.

```toml
[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](go-sdk.md#uygulama-vekilini-dogrulamak).

**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ıca `X-Biticaret-Store-Id`, `X-Biticaret-Store-Domain`, `X-Biticaret-Customer-Id` (yalnızca giriş yapılmışsa), `X-Biticaret-Signature` ve `X-Forwarded-For` ekler; 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 `Authorization` hiç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-store` olur.
- 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 bir `Content-Length` için `502`), istek gövdesi için 1 MiB (aşılırsa `413`). Dosya sunan bir uygulama `app_proxy.large_responses` ile `GET` ve `HEAD` için 120 saniye ve 256 MiB isteyebilir; bu sınırlar platform izin verdiğinde geçerli olur ([Yapılandırma](configuration.md#biticaret-app-toml)).

**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.

```toml
[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](api.md#kurulum) 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`):

```html
<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).

```js
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](go-sdk.md#oturum-jetonunu-dogrulamak).

**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`.

```js
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](../reference/ui-extension-targets.md).

```bash
biticaret app generate extension --type ui_extension --name order-card
```

```toml
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:

```js
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 = true` ise çıkar. Kendi sunucusunu `api.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`). `choices` listesi olan bir `single_line_text_field` tek 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.current` olarak okur, doldurulmayan alanlar varsayılanlarıyla gelir. `targets` listesi olan bir uzantıyı mağaza bu hedefler arasında taşıyabilir; modül her hedef için `biticaret.extension` ile 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.

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

[[settings.fields]]
key = "measurement_id"
type = "string"
required = true
```

```js
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 `consent` kategorisini (`analytics` veya `marketing`) onayladıysa alır.
- `init.data` mağazayı, giriş yapmış ziyaretçide müşteriyi ve `settings` altında kurulumun ayar değerlerini taşır. `browser` `sendBeacon` ve `fetch` verir.
- **Ayarlar.** Piksel en çok 20 ayar alanı tanımlar (`string`, en çok 500 karakter, veya `string_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.
