Bir web sitesine “şu kartı biraz açalım” demek kolay, hangi kartı ve hangi tasarım değişkenini kastettiğinizi araca doğru aktarmak zor. Browser Annotation API, DevDay 2026'da bu boşluk için duyuruldu. Site, seçilebilir nesneleri, geri bildirime eşlik eden bağlamı ve değişikliği önizleten özel kontrolleri tanımlayabiliyor.
Resmî kılavuz özelliği ChatGPT masaüstü uygulamasının desteklenen tarayıcılarıyla sınırlandırıyor. API document.oai.annotation altında sunuluyor. Her tarayıcıda çalışan standart web API'si gibi düşünmek yanlış olur. Bu yazı özellikle tasarım ve web geliştirme ekibinin doğru geri bildirim alması açısından değerini açıklıyor.
Bu yazının duyuru ve erişim bilgileri OpenAI’nın resmî özellik belgesi ile DevDay 2026 toplu duyurusu üzerinden doğrulandı. Örnek proje ve deneme önerileri editoryal yorumdur.
Seçilebilir nesneyi site belirleyebilir
Varsayılan Annotation modu metin, görsel ve kontroller gibi DOM öğelerini seçiyor. Daha büyük bir bölgeyi tek nesne yapmak için oai-annotation-container ve seçilebilir hedef işaretleri kullanılabiliyor. Böylece kullanıcı bütün ürün kartına veya fiyat tablosundaki bir satıra yorum verebilir. Metin sürükleyerek seçilecekse ayrı oai-annotation-container-text niteliği var. Tasarım açısından hedef, kullanıcının tıkladığı nokta ile geri bildirimde anlatılan bileşenin aynı olması. Aşırı büyük seçilebilir alanlar ise ayrıntılı yorumun kaybolmasına yol açabilir.
Görünmeyen bağlamı eklemek
oai-annotation-metadata ile seçili öğeye ek bilgi bağlanabiliyor. Örneğin ekranda görünen bir kartın iç sistemdeki bileşen kimliği, varyantı veya onay durumu iletilebilir. Bu, “mavi kartı değiştir” gibi belirsiz bir isteği doğru kayıtla eşleştirmeye yardım eder. Fakat metadata hassas bilgi taşıyorsa dikkat gerekir; yalnız geri bildirim için gerçekten gereken alanlar seçilmeli. Bir site, kullanıcıya görünmeyen her veriyi otomatik olarak annotation bağlamına dökmemeli. Veri minimizasyonu burada doğrudan ürün tasarımı kararıdır.
Site içinden annotation başlatma
Kılavuz, document.oai.annotation.request(target, options) ile kullanıcı etkileşiminden bir annotation açmayı anlatıyor. Hedef görünür belge içindeki bağlı öğe veya bir metin aralığı olabilir. Örneğin bir “Geri bildirim ver” düğmesi, doğru ürün kartını önceden seçerek kullanıcının işini kolaylaştırabilir. Bunu sayfa yüklenir yüklenmez beklenmedik modal açmak için kullanmazdım. Kullanıcı hangi eylemi başlattığını bilmeli; seçimin neye bağlandığı arayüzde anlaşılır olmalı.
Özel kontrollerle önizleme
registerControls() seçilen öğeye özel kontrol ekleyebiliyor. Resmî örnekte boşluk değişkeni önizleniyor; başka bir örnekte önizlemesiz seçim toplanıyor. controlsMode ile yerleşik kontrollere ekleme veya onların yerine kendi kontrollerini gösterme seçeneği var. Tasarım sisteminde bu, “24 piksel boşluk dene” isteğinin görsel sonucunu kullanıcı göndermeden önce görmesini sağlayabilir. Ancak önizleme ile kalıcı değişiklik ayrı aşamalar. Kullanıcı iptal ettiğinde başlangıç değerine dönme davranışı test edilmeli.
Canvas nesneleri için ayrı yol
Canvas üzerinde çizilen nesneler DOM öğesi gibi tek tek seçilemez. Kılavuz registerSurface() ve hitTest fonksiyonuyla sanal nesnelere kararlı kimlik vermeyi anlatıyor. Bir diyagram editörü, görsel moodboard veya plan çizimi için bu önemli: kullanıcı tüm canvas yerine belirli etikete, şekle ya da karta yorum verebilir. Sanal nesnede özel kontroller çalışıyor; yerleşik CSS ve metin kontrollerinin aynı şekilde uygulanacağını varsaymamak gerekir. Her nesnenin kararlı ID'si, yorumun doğru öğeye dönmesi için temel.
Örnek: marka sitesi tasarım incelemesi
Bir landing page'de üç farklı ürün kartı olduğunu düşünelim. Müşteri ikinci kartı seçiyor; annotation bağlamı bileşen anahtarını ve kullanılan spacing tokenını ekliyor. Kontrol panelinde yatay boşluğu deneyip sonucu görüyor, sonra “metin bir satır kısalsın” notunu gönderiyor. Bu editoryal örnek API'nin mümkün kıldığı akışın tasarımı; ChatGPT'nin her isteği otomatik doğru koda çevireceği iddiası değil. Geliştirici hâlâ responsive görünümü, erişilebilirliği ve diğer kartlara etkisini kontrol etmeli.
Destek ve geriye dönüş
Browser Annotation API desteklenen ChatGPT masaüstü tarayıcılarında. Sıradan ziyaretçinin kullandığı Chrome veya Safari'de aynı nesne seçimini beklemek doğru değil. Uygulama, document.oai.annotation varlığını kontrol edip yoksa normal geri bildirim kanalı sunmalı. Bu sayede özellik ürünün geri bildirim deneyimini geliştirse de tek giriş kapısı olmaz. Entegrasyonun kılavuzdaki DevDay sürümü ve sonraki sürümler için tarif edildiği de test matrisine yazılmalı.
Geri bildirim kalitesini ölçmek
Annotation sayısı tek başına iyi metrik değil. Kullanıcının kastettiği öğeyi doğru yakalama oranı, yanlış bileşene giden yorum sayısı, açıklığa kavuşturma turu ve revizyon süresi daha yararlı. Kontrol önizlemesi varsa kabul edilen ve geri alınan değişiklikleri de izlerdim. Geri bildirimin fazla ayrıntılı olması her zaman iyi değil; özel kontrol yalnız gerçekten karar verilen özellikleri göstermeli. Basit bir blog sayfasında on farklı panel ayarı, doğrudan metin notundan daha yorucu olabilir.
Bileşen kimliği için tasarım sistemi
Annotation metadata'sına bileşen anahtarı eklemek istiyorsanız önce tasarım sistemindeki kimliklerin kararlı olması gerekir. “Kart 3” gibi sıraya bağlı ad, responsive düzen değişince başka nesneyi işaret edebilir. Bunun yerine ürün kartı ID'si, varyant ve kullanılan token gibi alanlar daha güvenilir. Canvas içindeki sanal nesneler için de kararlı ID şartı var. Bu bilgiyi seçili nesneyle bağlamak, yorumu geliştiricinin kodda bulmasını hızlandırabilir. Yalnız kişisel veya gizli metadata eklememek gerekir. Hedef, AI'ya daha çok veri dökmek değil, doğru değişikliğe yetecek bağlamı vermek.
Önizleme ile nihai değişiklik arasında
Bir spacing tokenı kontrol panelinde değiştirince iki kartın birlikte hareket etmesi, paylaşılan tasarım değişkenini gösterebilir. Fakat kullanıcının gördüğü önizleme kalıcı sürüm değil. Gönderme, iptal ve geri alma anları ayrı test edilmeli. Resmî kılavuz değişiklik olayındaki action değerini ve değeri her eylemde uygulamayı anlatıyor. Uygulama bunu yanlış yorumlarsa panel kapanınca sayfa değişmiş kalabilir. Ben testte kontrolü artırma, azaltma, iptal etme ve yeniden açma adımlarını sırayla denerdim. Böylece geri bildirim aracı site durumunu beklenmedik biçimde bozmaz.
Erişilebilir seçim deneyimi
Görsel olarak tıklanabilen nesne klavye veya ekran okuyucu ile de anlaşılmalı. Annotation hedeflerinin DOM semantiği ve odak davranışı tasarım kontrolünden geçmeli. Canvas yüzeyinde sanal nesnenin adı ve seçili durumu ayrıca temsil edilebilir. Bu, resmî API'nin tek başına çözdüğünü varsayamayacağımız bir ürün sorumluluğu. Bir kullanıcı yanlış öğeyi seçiyorsa en iyi metadata bile problemi çözmez. Pilot testte küçük ekran, zoom, klavye kullanımı ve yoğun sayfa düzeniyle seçim doğruluğunu görürdüm. İyi geri bildirim önce doğru hedefe ulaşmaktan başlar.
Özel kontrol sayısını sınırlamak
API kontrol eklemeyi mümkün kılıyor diye her CSS değişkenini kullanıcıya açmak iyi fikir değil. Bir müşteri “daha ferah olsun” derken padding, gap, line-height ve kart yüksekliğini ayrı sliderlarla görmek zorunda kalırsa karar vermek zorlaşır. Ben bileşene özgü iki veya üç anlamlı kontrol seçerdim. Diğer ayrıntılar açıklayıcı metin olarak kalabilir. controlsMode replace kullanılırsa yerleşik kontrollerin gizlenmesi sonuç yaratır; extend ise paneli kalabalıklaştırabilir. Tasarım incelemesinde bu seçimi gerçek kullanıcının vereceği kararın karmaşıklığına göre yapmak gerekir.
Desteklenmeyen tarayıcı için geriye dönüş
document.oai.annotation bulunmadığında site bozuk görünmemeli. Normal yorum formu veya ekran görüntüsüyle geri bildirim yolu sunmak gerekir. Desteklenen masaüstü uygulamasında özel seçim açılır; diğer tarayıcıda aynı düğme anlaşılır alternatif gösterir. Böyle bir geriye dönüş, pazarlama sitesini yalnız ChatGPT içinden görülebilir hale getirmez. Özelliğin sürüm hedefi de belgelendiği için test planında eski uygulama sürümüne yer vermek mantıklı. Teknolojiye duyarlı zengin deneyim sunarken temel iletişim kanalını korumak, gerçek kullanıcıların farklı cihazlarda yaşayacağı sürprizleri azaltır.
Responsive görünümü birlikte test etmek
Bir bileşende masaüstü önizlemede güzel görünen boşluk değişikliği mobilde taşma yaratabilir. Annotation kontrolü seçili öğenin yakınında etkiyi gösterse de başka kırılımları otomatik onaylamaz. Ben değişiklik önerisini göndermeden önce en az dar ve geniş ekranı görürdüm; uygulama bu önizlemeyi sağlamıyorsa revizyon sonrası normal QA süreci devam eder. Özellikle ortak tasarım tokenı iki veya daha çok bileşeni etkileyebilir. Seçili kartın iyi görünmesi diğer kartların da iyi olduğu anlamına gelmez. Bağlamlı geri bildirim, kapsamlı tasarım kontrolünün yerine değil önüne gelir.
İyi yorumun yapısı
Seçilebilir nesne ve metadata sorunu hedeflemeyi kolaylaştırır; yine de geri bildirimin amaç kısmı insan tarafından yazılmalı. “Bu butonu büyüt” yerine “mobilde ödeme eylemi yeterince görünmüyor; bu butonun önceliğini artır” daha kullanışlı. Kontrol önizlemesi çözüm önerisi sunabilir, ancak asıl kullanıcı problemi kayda geçmeli. Böylece geliştirici önerilen ölçüye bağlı kalmadan daha iyi çözüm bulabilir. Annotation'ın gücü tıklanan pikseli tarif etmek değil, doğru bileşen ile tasarım niyetini aynı bağlamda toplamak. Pilot yorumları bu açıdan değerlendirilirse aracın gerçek katkısı anlaşılır.
Sonuç
Website annotations, web içeriği ile AI destekli geri bildirim arasına daha doğru hedef ve bağlam koyuyor. Özellikle bileşen temelli tasarım sisteminde seçme, metadata ve önizleme üçlüsü güçlü. Entegrasyon desteklenen masaüstü uygulamasıyla sınırlı olduğu için genel web özelliği gibi sunulmamalı. Pilotun başarısı, daha fazla kontrol açmak değil, “hangi nesne, hangi değişiklik?” sorusuna daha az turda doğru cevap vermek.
Sık sorulan sorular
Browser Annotation API her tarayıcıda var mı?
Hayır. Resmî doküman desteklenen ChatGPT masaüstü uygulama tarayıcılarını hedefliyor.
Canvas içindeki şekiller seçilebilir mi?
Evet, uygun registerSurface ve hitTest entegrasyonuyla sanal nesneler seçilebilir.
Önizleme değişikliği otomatik kaydeder mi?
Önizleme ve kalıcı uygulama ayrı süreçlerdir; entegrasyon geri alma ve onay davranışını tasarlamalı.
İlgili yazılar
- DevDay 2026: bütün duyurular
- Sign in with ChatGPT: Giriş ve Plan Kullanımı Nasıl İşliyor?
- ChatGPT Sites'ta Bağlı Veri: Her Ziyaretçinin Kendi Hesabı
- ChatGPT Plugin Extensions: Eklentiler İçin Yeni Arayüzler