Sürüm politikası

Yükleyici sürümleri

Adres	İçerik	Önbellek
`https://api.mirac-ozdemir.com/widget.js`	Güncel yükleyici (şu an v1, 1.1.0).	`max-age=3600`
`https://api.mirac-ozdemir.com/widget/v1.js`	v1’e sabitlenmiş takma ad; `/widget.js` ile aynı dosya.	`max-age=3600`
`https://api.mirac-ozdemir.com/widget/v1.1.0.js`	Bu sürümün değişmez kopyası (aynı baytlar).	`max-age=31536000, immutable`
`https://api.mirac-ozdemir.com/widget/manifest.json`	Sürüm listesi, adresler ve bütünlük özetleri.	`max-age=300`

/widget.js ve /widget/v1.js aynı v1 yükleyicisini sunar; bir değişiklik ziyaretçilere en geç bir saat içinde ulaşır. İkisi de v1 ile uyumlu kalır: kırıcı değişiklikler ayrı bir adreste (/widget/v2.js) yayınlanır, yani /widget.js kullanan bir sayfa kendiliğinden v2’ye geçmez. Sürümü kodunuzda açıkça görmek ve ileride bilinçli geçiş yapmak istiyorsanız /widget/v1.js adresini, tam sabitleme için aşağıdaki değişmez adresi kullanın.

Yükleyicinin sürümünü çalışma anında window.MiracOzdemirWidget.version ("1"), .build ("1.1.0") ve .features ile okuyabilirsiniz.

Yükleyici 1.1.0’da yenilikler

Hepsi geriye dönük uyumludur; 1.0 ile yazılmış entegrasyonlar değişmeden çalışır:

update, setInputs, calculate, reset, get, getResult, unmountAll ve build/features: JavaScript API.
data-input-*, data-inputs, data-autorun, data-view: Kurulum.
data-accent, data-radius, data-density, data-theme="inherit", data-title, data-lazy.
Arama ve kategori widget’ları (data-mo-search, data-mo-category) ve <mo-calculator>, <mo-search>, <mo-category> özel öğeleri: Widget türleri, Özel öğeler ve SDK.
Yeni olaylar mo:input, mo:select; mo:ready, mo:result, mo:error için genişletilmiş detail: Olaylar.
Yer tutucu iskelet, öğrenilen yükseklik ve preconnect ile yerleşim kayması düzeltmesi.
iframe title’ı yerelleştirildi; konsol uyarıları artık İngilizce.
Sürümlü değişmez adres ve manifest (SRI).

Değişmez sürüm adresi ve SRI

Sürümlü adres (/widget/v1.1.0.js) hiç değişmez ve bir yıl boyunca önbelleklenir; bu yüzden tarayıcıya Subresource Integrity (SRI) özetiyle doğrulatabilirsiniz: dosya bir bayt bile değişirse tarayıcı betiği çalıştırmaz. Özet, manifest.json içinde yayınlanır:

{
  "latest": "1.1.0",
  "protocol": 1,
  "versions": [
    {
      "version": "1.1.0",
      "url": "https://api.mirac-ozdemir.com/widget/v1.1.0.js",
      "integrity": "sha384-…",
      "features": ["update", "inputs", "calculate", "reset", "inherit-theme", "kinds", "custom-elements"]
    }
  ]
}

integrity değeri yukarıda sha384-… ile kısaltılmıştır; gerçek değeri her zaman kullandığınız ortamın manifestinden okuyun. Özet, API’nin yapılandırıldığı site origin’ine bağlıdır (yükleyicinin içine yazılan tek değerdir); bu yüzden bir ortamın özetini başka bir ortamda kullanamazsınız. Manifest origin’ler arası okunabilir.

<div data-mo-tool="kdv"></div>
<script
  src="https://api.mirac-ozdemir.com/widget/v1.1.0.js"
  integrity="sha384-…"
  crossorigin="anonymous"
  async
></script>

const base = 'https://api.mirac-ozdemir.com';
const manifest = await (await fetch(`${base}/widget/manifest.json`)).json();
if (manifest.protocol !== 1) throw new Error('Beklenmeyen protokol');
const entry = manifest.versions.find((v) => v.version === manifest.latest);

const script = document.createElement('script');
script.src = entry.url;
script.integrity = entry.integrity;
script.crossOrigin = 'anonymous';
script.async = true;
document.head.append(script);

import { loadPinnedWidget } from '@mirac-ozdemir/widget';

const widget = await loadPinnedWidget(); // manifestteki en yeni sürüm + integrity

SDK henüz npm’de yayınlanmadı; bkz. Özel öğeler ve SDK.

SRI ile sabitlemenin bedeli: sabitlenmiş yükleyici hiç değişmez, yani hata düzeltmeleri ve yeni özellikler siz özeti ve adresi güncelleyene kadar size ulaşmaz. Sürekli güncel kalmak istiyorsanız /widget.js kullanın. CSP kullanıyorsanız adres aynı API origin’inde olduğundan ek kural gerekmez (Güvenlik ve CSP).

v1 içinde izin verilen değişiklikler

v1, yalnızca geriye dönük uyumlu değişiklikler alır:

hata düzeltmeleri,
yeni isteğe bağlı data-* öznitelikleri,
yeni olay türleri veya olayların detail alanlarına yeni alanlar,
yükleyicinin bugün yok saydığı yeni mesaj türleri.

Bu nedenle olay işleyicileriniz bilmediği alanları ve olay türlerini yok saymalıdır. Yeni yükleyici ile eski embed sayfası (veya tersi) birlikte çalışır: yükleyici, ready mesajındaki features alanından neyin desteklendiğini okur ve desteklenmeyen kontrol çağrılarını reddeder ya da iframe’i yeniden yükleyerek yerine getirir.

Kırıcı değişiklikler

Aşağıdakiler kırıcıdır ve yeni bir sürümle (/widget/v2.js, protokol version: 2) yayınlanır:

öznitelik veya global API üyelerinin yeniden adlandırılması ya da kaldırılması,
olay adlarının veya detail biçimlerinin değişmesi,
yeni bir protokol sürümü,
embed sayfasının farklı bir adres şemasına taşınması.

Yeni sürüm yayınlandığında v1, kullanım sürdüğü sürece çalışmaya devam eder; embed sayfası, v1 yükleyicilerinden (version: 1 mesajları) gelen ve önbellekte tutulan ya da sabitlenmiş yükleyicilerle uyumlu kalır.

Embed adresi sözleşmenin parçasıdır

/{locale}/embed/{key} adresi ve sorgu parametreleri (theme, header, id, view, accent, radius, density, autorun, i.<alan>), ayrıca /{locale}/embed/kit/search ve /{locale}/embed/kit/category/{key} adresleri kamuya açık sözleşmenin parçasıdır; düz iframe entegrasyonları bunları doğrudan kullanır. Bu parametreler uyumsuz biçimde değiştirilmez. kit ayrılmış bir araç anahtarıdır.