Uygulamanızın arayüzünü gömme

Bir uygulama kendi sayfasını Stoneity'nin içinde gösterebilir. Sayfa sizin web uygulamanızdır, iframe içinde yüklenir ve kimin neye baktığını söyleyen kısa ömürlü imzalı bir jeton taşır.

Yüzey tanımlama

Manifest'e surfaces ekleyin. Her girdi bir sayfayı bir konuma yerleştirir:

{
  "key": "acme-crm",
  "egress": ["app.acme.com"],
  "surfaces": [
    { "location": "ticket_sidebar", "url": "https://app.acme.com/stoneity/ticket", "title": { "en": "Acme CRM", "tr": "Acme CRM" }, "height": 460 },
    { "location": "admin_page", "url": "https://app.acme.com/stoneity/admin", "title": { "tr": "Acme ayarları" } }
  ]
}

Konum	Nerede görünür
ticket_sidebar	Kayıt detayında, Geçmiş ve Bağlantılar sekmelerinin yanında
ticket_toolbar	Kayıt detayında sayfayı bir pencerede açan düğme
admin_page	Ayarlar → Uygulamalar altında kurulum satırındaki Uygulamayı aç

Kurulum sırasında uygulanan kurallar:

• Adres https olmalıdır.
• Adresin host'u uygulamanın egress listesinde bulunmalıdır. O liste yöneticiye "bu uygulama verinizi şuraya gönderir" diye gösterilir; çerçeve de onun dışına çıkamaz.
• height başlangıç yüksekliğidir, 120 ile 1200 arasında. Sayfanız çalışırken değiştirebilir.
• Bir konum uygulama başına yalnız bir kez tanımlanabilir.

Jeton

Stoneity adresinizin sonuna ?token= ekler. Jeton, kurulumunuzun paylaşılan sırrından türetilen bir anahtarla HS256 imzalanmış bir JWT'dir:

anahtar = HMAC-SHA256(paylasilanSir, "stoneity-surface-token-v1")

Paylaşılan sır, kurulumun gelen istek adresinde görünen sırdır. Anahtar kurulum başına olduğundan bir çalışma alanının jetonu başka bir yerde asla doğrulanmaz.

{
  "iss": "stoneity",
  "aud": "acme-crm",
  "sub": "42",
  "exp": 1789000000,
  "installation": 7,
  "surface": "ticket_sidebar",
  "workspace": "https://acme.stoneity.com",
  "user": { "id": 42, "name": "Ada Lovelace", "email": "ada@acme.com", "language": "tr" },
  "ticket": { "id": "651f…", "boardId": "b1" }
}

İçeriğine güvenmeden önce her zaman imzayı ve exp alanını doğrulayın. Jeton beş dakika yaşar; Stoneity süresi dolmadan çerçeveyi yenisiyle yeniler. Onu bu tek görüntülemenin kanıtı sayın, oturum yerine geçmez.

Çalışma alanının verisinde işlem yapmak için API anahtarıyla Public API kullanılır. Yüzey jetonu bakan kişiyi tanımlar, bir API kimlik bilgisi değildir.

Stoneity ile konuşma

Sayfanız postMessage ile küçük bir komut kümesini çağırabilir. Komutlar window.parent'a, workspace alanındaki origin hedeflenerek gönderilir.

parent.postMessage({ type: 'stoneity:ready' }, workspaceOrigin);

window.addEventListener('message', (event) => {
  if (event.data?.type === 'stoneity:context') {
    // { user, ticket, installationId, location }
  }
});

parent.postMessage({ type: 'stoneity:resize', height: document.body.scrollHeight }, workspaceOrigin);
parent.postMessage({ type: 'stoneity:showToast', level: 'success', message: 'Kaydedildi' }, workspaceOrigin);
parent.postMessage({ type: 'stoneity:close' }, workspaceOrigin);

Komut	Etkisi
stoneity:ready / stoneity:getContext	Stoneity stoneity:context ile yanıt verir
stoneity:resize	Çerçeve yüksekliğini 120–1200 arasına sıkıştırarak ayarlar
stoneity:showToast	Bildirim gösterir; ilk 300 karakter, düz metin olarak
stoneity:navigate	Çalışma alanını /agent/home gibi göreli bir yola götürür
stoneity:close	Yüzey bir pencerede gösteriliyorsa pencereyi kapatır

Bunların dışındaki mesajlar yok sayılır. Stoneity hem gönderenin origin'ini hem hangi çerçeveden geldiğini doğrular; yalnız sizin sayfanız bu komutları çalıştırabilir.

Kum havuzu

Çerçeve allow-scripts allow-forms allow-popups allow-same-origin ile çalışır. Listede allow-top-navigation bilerek yoktur: sayfanız çalışma alanını başka bir adrese götüremez. Uygulama içi gezinme için stoneity:navigate kullanın.