well-known ucp Dosyası Nasıl Oluşturulur?

UCP profili nedir ve nereye konur

UCP profili, alan adınızın kökündeki /.well-known/ucp yolunda duran, uzantısız ve tek bir JSON nesnesinden oluşan bir keşif belgesidir. Tam adres şu biçimdedir: https://alanadiniz.com/.well-known/ucp. Dosyanın adı ucp'dir, ucp.json değildir.

Universal Commerce Protocol, Google'ın Shopify, Etsy, Wayfair, Target ve Walmart gibi perakendecilerle birlikte geliştirdiği açık bir ticaret protokolüdür. Çözmeye çalıştığı problem tekil bir arama problemi değil, entegrasyon çarpanıdır. Her satış yüzeyi için ayrı bir entegrasyon yazmak yerine, işletme desteklediği yetenekleri tek bir makine okunur belgede ilan eder. Bir alışveriş aracısı bu belgeyi çeker, hangi protokol sürümünün konuşulduğunu, hangi uç noktalara istek gönderileceğini, hangi ödeme yöntemlerinin desteklendiğini ve imzalı isteklerin hangi açık anahtarla doğrulanacağını oradan öğrenir.

Burada kritik bir ayrım var. Profil dosyası bir dizin, bir vitrin değildir. İçinde ilan edilen her uç noktanın gerçekten çalışıyor olması gerekir. Dosyayı koymak entegrasyonu tamamlamaz, yalnızca entegrasyonun keşfedilebilir olmasını sağlar.

Neden .well-known dizini kullanılıyor?

RFC 8615, bir sitenin tamamı için geçerli meta verilerin toplanacağı /.well-known/ yol önekini ayırır ve daha eski olan RFC 5785'in yerini alır. Amaç çakışmayı önlemektir. Site sahibinin kendi içerik yollarıyla protokol dosyalarının aynı isim alanında yarışmaması için bu önek rezerve edilmiştir.

Standardın iki kuralı uygulamada doğrudan sonuç doğurur. Birincisi, bu yollar yalnızca yol hiyerarşisinin tepesinde geçerlidir. /.well-known/ucp geçerlidir, /magaza/.well-known/ucp geçerli bir well-known adresi değildir. İkincisi, önekten sonra gelen isim tek bir yol parçası olmak zorundadır, içinde eğik çizgi bulunamaz.

Önek sabittir, ondan sonraki isimler ise IANA'nın Well-Known URIs kayıt defterinde tutulur ve kayıt süreci uzman incelemesine tabidir. Burada dürüst olmak gerekiyor: ucp ismi şu an bu kayıt defterinde görünmüyor. Buna karşılık aynı ekosistemdeki Agent2Agent protokolünün agent-card.json girdisi kalıcı statüyle kayıtlı. Pratik sonucu sınırlı, çünkü kendi alan adınızın kökündeki yolu yayınlama yetkisi zaten sizdedir ve dosya kayıt olmadan da çalışır. Yine de bu ayrıntı, standardın hangi olgunluk aşamasında olduğunu doğru okumaya yarar.

Kök dizindeki her makine dosyası bu dizine girmez. Tarayıcı davranışını yöneten robots.txt standardın öncesinden geldiği için doğrudan kökte durur ve kendi kurallarıyla yönetilir, bu dosyanın bütçe tarafındaki etkisini tarama bütçesi ve robots.txt optimizasyonu yazısında ayrıca ele aldık. Dil modellerine içerik haritası sunan llms.txt de benzer biçimde kökte yaşar ve dosyayı hızlıca hazırlamak için llms.txt oluşturucu aracını kullanabilirsiniz. UCP profili ise bilinçli olarak .well-known altına yerleştirilmiştir, çünkü bir insan belgesi değil, protokol düzeyinde bir keşif uç noktasıdır.

UCP profilinin içinde ne var?

Zorunlu alanlar

Belgenin kökünde zorunlu tek üye ucp nesnesidir. Onun yanında isteğe bağlı keys dizisi bulunur. ucp nesnesinin içinde version, services ve payment_handlers zorunludur. services ve payment_handlers boş olsalar bile belgede yer almak zorundadır, tamamen çıkarılamazlar. capabilities isteğe bağlıdır, ancak yetenek ilan etmeyen bir ticaret profilinin pratik bir işlevi olmaz.

{
  "ucp": {
    "version": "YYYY-MM-DD",
    "services": {
      "dev.ucp.shopping": [
        {
          "version": "YYYY-MM-DD",
          "spec": "https://ucp.dev/YYYY-MM-DD/specification/overview/",
          "transport": "rest",
          "endpoint": "https://isletme.example.com/ucp/v1",
          "schema": "https://ucp.dev/YYYY-MM-DD/services/shopping/rest.openapi.json"
        }
      ]
    },
    "capabilities": {
      "dev.ucp.shopping.checkout": [
        {
          "version": "YYYY-MM-DD",
          "spec": "https://ucp.dev/YYYY-MM-DD/specification/shopping/checkout",
          "schema": "https://ucp.dev/YYYY-MM-DD/schemas/shopping/checkout.json"
        }
      ]
    },
    "payment_handlers": {}
  },
  "keys": []
}

Yukarıdaki YYYY-MM-DD yer tutucusu bilinçli. Protokol sürüm kimliği tarih biçimindedir ve uyguladığınız yayının kimliği neyse birebir o yazılır. Sürüm alanı katı bir tarih kalıbıyla doğrulanır, dolayısıyla draft gibi tarih olmayan bir değer geçerli değildir. Spesifikasyon, kararlı olmayan ön sürümlerin herkese açık keşif üzerinden duyurulmasını da ayrıca yasaklar.

Servis ve yetenek kayıtları nasıl yazılır?

services, capabilities ve payment_handlers birer kayıt defteridir. Anahtarları ters alan adı biçimindedir, örneğin dev.ucp.shopping ya da dev.ucp.shopping.checkout. Her anahtarın değeri bir dizidir ve dizideki her öğe o kaydın belirli bir sürümünü tanımlar.

Sürüm tutarlılığı burada sessiz bir tuzak. Profilde ilan ettiğiniz ucp.version hangi tarihse, dev.ucp. ile başlayan her servis ve yetenek kaydının version değeri de aynı tarih olmak zorundadır. Farklı bir tarih taşıyan kayıt, karşı taraf tarafından hiç yokmuş gibi işlenir ve devre dışı bırakılır.

İkinci tuzak isim alanı bağıdır. Bir yeteneğin schema adresinin kaynağı, yeteneğin isim alanı otoritesiyle eşleşmek zorundadır. dev.ucp. ile başlayan bir yeteneğin şemasını kendi sunucunuza koyup adresini oraya vermeniz kabul edilmez. Kendi uzantınızı yazacaksanız kendi ters alan adı isim alanınızı kullanırsınız.

keys dizisi ise RFC 7517 biçiminde geçerli bir JWK kümesidir. İmzalı isteklerin ve imzalı webhook'ların doğrulanmasında kullanılır. Anahtar eklemek, döndürmek ve iptal etmek bu tek dizi üzerinden yapılır. İptal tarafı güvenlik açısından kritik: sızmış bir anahtar, keys dizisinden fiilen silinene kadar iptal edilmiş sayılmaz.

Dosyayı yayına alma adımları

1. Uygulanacak protokol yayınını seçin ve tarihli sürüm kimliğini not edin. Profilin tamamı bu tek karara bağlanır.
2. İlan edeceğiniz uç noktaları önce ayağa kaldırın. Profili, çalışan bir API'nin üzerine yazın, tersini değil.
3. İmza anahtar çiftini üretin. Açık anahtarı JWK biçimine çevirip keys dizisine koyun, özel anahtarı sunucu tarafında tutun.
4. JSON belgesini oluşturun. ucp.version, ucp.services ve ucp.payment_handlers alanlarının boş olsalar dahi var olduğundan emin olun.
5. Belgeyi protokolün yayımladığı profil JSON Schema dosyasına karşı doğrulayın. Bu adım, elle yazılmış profillerdeki alan hatalarının çoğunu daha yayına çıkmadan yakalar.
6. Dosyayı sunucuda /.well-known/ucp yoluna, uzantısız biçimde yerleştirin. Framework kullanıyorsanız statik dosya dizinine koyun ve yönlendiricinin bu yolu yutmadığını doğrulayın.
7. Sunucuda medya türünü ve önbellek başlıklarını elle ayarlayın. Uzantı olmadığı için otomatik MIME eşlemesi devreye girmez.
8. Yolun HTTPS üzerinden ve yönlendirmesiz yanıt verdiğini doğrulayın. www ile www olmayan biçim arasındaki normalleştirme kuralınız bu yolu da etkiler.
9. WAF, bot koruması ve nokta ile başlayan dizinleri engelleyen sunucu kurallarını gözden geçirin. Bu dosyayı çeken taraf bir tarayıcı değil, otomatik bir istemcidir.
10. Erişilebilirliği dışarıdan test edin, sonra profili tüketecek tarafa bildirin. Google tarafında bu bildirim, Merchant Center içindeki UCP entegrasyon ekranına profil adresinin girilmesi ve keşfin tetiklenmesiyle yapılır.

Sunucunun dosyayı nasıl sunması gerekir?

Spesifikasyonun barındırma kuralları nettir. Yayımlanan belgeler HTTPS üzerinden sunulmak zorundadır. Profil uç noktaları 3xx yönlendirme kullanamaz. Yanıt, public içeren ve max-age değeri en az 60 saniye olan bir Cache-Control başlığı taşımak zorundadır; private, no-store ve no-cache yönergeleriyle sunulamaz. Ayrıca ETag veya Last-Modified gibi bir doğrulayıcı eklenmesi tavsiye edilir.

Tüketici tarafındaki kurallar da aynı yöne bakar. Profili çeken taraf HTTPS olmayan adresleri reddeder, yönlendirmeleri izlemez ve özel kullanım IP aralıklarına çözülen adresleri reddeder. Ayrıca kaynağın gönderdiği başlıktan bağımsız olarak en az 60 saniyelik bir önbellek tabanı uygulaması beklenir. Bu son ayrıntı operasyonel olarak önemlidir: profili değiştirdiğinizde değişikliğin karşı tarafa yansıması anlık olmaz.

Medya türü için barındırma bölümünde ayrı bir zorunluluk cümlesi yok, ancak belge bir JSON nesnesidir ve protokolün istek ile yanıtlarında application/json zorunlu tutulur. Doğru davranış profili de aynı türle sunmaktır. Sorun şu ki sunucular medya türünü çoğunlukla dosya uzantısından çözer ve bu dosyanın uzantısı yoktur. Sonuçta nginx varsayılanı olan application/octet-stream ya da yapılandırmaya göre text/plain gönderilir.

# nginx
location = /.well-known/ucp {
    default_type application/json;
    add_header Cache-Control "public, max-age=300";
}

# Apache, .well-known dizinindeki .htaccess içinde
<Files "ucp">
    ForceType application/json
    Header set Cache-Control "public, max-age=300"
</Files>

Bir de klasik güvenlik sertleştirmesi tuzağı var. Birçok hazır yapılandırma, nokta ile başlayan yolları topluca engeller. nginx tarafında location ~ /\. { deny all; }, Apache tarafında benzer bir RedirectMatch kuralı bu dizini tamamen kapatır. Aynı kural yıllardır sertifika doğrulama dosyalarını da kırar. Çözüm, .well-known dizini için açık bir istisna tanımlamaktır.

Erişilebilirlik nasıl test edilir?

1. Yanıt başlıklarını çekin: curl -sI https://alanadiniz.com/.well-known/ucp. Beklenen sonuç 200 durum kodu, application/json medya türü, public ve yeterli max-age içeren bir Cache-Control başlığıdır. Yanıtta Location başlığı görüyorsanız yönlendirme vardır ve kural ihlali oluşmuştur.
2. Gövdeyi ayrıştırın: curl -s https://alanadiniz.com/.well-known/ucp | python3 -m json.tool. Sunucu HTML hata sayfası döndürüyorsa bu adım hemen hata verir.
3. Testi kendi ağınızın dışından tekrarlayın. CDN ve WAF kuralları çoğu zaman ofis IP'sine ayrıcalık tanır, dışarıdan gelen otomatik istemciye tanımaz.
4. Tarayıcı taklidi yapmayan bir istemciyle, çerezsiz olarak deneyin. Bot koruması genellikle tam burada devreye girer.
5. İlan ettiğiniz ana bilgisayar adını birebir test edin. www ile www olmayan biçimden hangisini duyurduysanız o adres 301 vermeden 200 dönmelidir.
6. Profilin içindeki her adresi ayrı ayrı test edin. endpoint, spec ve schema adreslerinin hepsi HTTPS üzerinden ve yönlendirmesiz yanıt vermelidir.
7. Sürüm eşitliğini kontrol edin. dev.ucp. ile başlayan her kaydın version değeri ucp.version ile aynı olmalıdır.
8. Bir düzenlemeden sonra CDN önbelleğini temizleyin ve testi tekrarlayın. Eski kopyanın yayında kalması bu dosyada en sık görülen sessiz hatadır.

Kök dizin dosyalarının erişilebilirliği, yönlendirme zincirleri ve sunucu yanıt kodları site genelinde birbirini etkileyen konulardır. Bu tarafı bütün olarak görmek için site içi SEO analizi aracıyla genel bir teknik tarama almak, tekil dosya testinin kaçırdığı yapılandırma sorunlarını ortaya çıkarır.

Sık yapılan hatalar ve nedenleri

Bu dosyayı bugün kimin koyması mantıklı

Bu dosya bir görünürlük dosyası değildir. Sıralama sinyali değildir ve organik trafik üretmez. Bir ticaret entegrasyonunun makine tarafındaki giriş kapısıdır. Karar da buradan verilir.

Bugün koyması mantıklı olanlar, kendi ödeme ve sipariş API'sine sahip, imzalı HTTP istekleri işleyebilen ve bu uç noktaları kesintisiz ayakta tutacak mühendislik kapasitesi olan çevrimiçi satıcılardır.

Beklemesi gerekenler daha kalabalık bir grup. Hazır bir e-ticaret platformu üzerinde çalışıyorsanız, profili elle yazmak platformun kendi yayılım planıyla çakışır. Bu durumda doğru hamle platformun UCP desteğini beklemek ve etkinleştirmektir. Sepeti olmayan içerik siteleri, hizmet siteleri ve teklif formuyla ilerleyen B2B siteleri için bu dosyanın karşılığı yoktur. Boş services ve boş payment_handlers ile yayımlanmış bir profil teknik olarak geçerlidir ama hiçbir şey ilan etmez, karşılığında bakımı gereken bir yüzey bırakır.

Uç noktalarını ayakta tutamayacak olanların ise bu dosyayı hiç yayımlamaması gerekir. Ölü adresler gösteren bir profil, bir makinenin üzerine işlem kurduğu bozuk bir taahhüttür ve sessizce başarısız olmaz.

Zamanlama tarafında bir gerçeklik payı daha var. Google'ın kendi yüzeyindeki aracılı ödeme akışı şu anda ilgi formu üzerinden seçilen satıcılara açık ve yayılım ABD, Kanada ile Avustralya odaklı ilerliyor. Bu programın dışında olmak profili yayımlamayı yanlış yapmaz, çünkü UCP açık bir protokoldür ve tek tüketicisi Google değildir. Ama kısa vadede somut bir hacim beklentisiyle işe girişmek gerçekçi olmaz.

Sıkça Sorulan Sorular

Dosyanın adı ucp.json olabilir mi?

Hayır. Keşif yolu /.well-known/ucp olarak tanımlıdır. Uzantılı bir dosya adı kullanıp o yoldan yönlendirme vermek de çözüm değildir, çünkü profil uç noktaları 3xx yönlendirme kullanamaz ve tüketici taraf yönlendirmeleri izlemez.

Profil dosyası olmadan UCP kullanılabilir mi?

Herkese açık keşif bu dosyadan başlar, dolayısıyla açık ekosistemde çalışmak isteyen bir işletme profili yayımlar. İki taraf birbirini zaten tanıyorsa ön sürüm uygulamaları üzerinde keşif dışında anlaşabilir, ancak bu durumun kararlılık ya da uyumluluk garantisi yoktur ve ön sürüm kimlikleri herkese açık profilde ilan edilemez.

robots.txt bu dosyayı engeller mi?

robots.txt, kendisine bakan tarayıcıların davranışını yönetir. UCP profilini çeken taraf ise bir tarayıcı değil, protokol istemcisidir. Erişimi fiilen kesen katmanlar WAF, bot koruması ve sunucu erişim kurallarıdır. Yine de .well-known dizinini kapsayan bir engelleme kuralı tutmanın hiçbir faydası yoktur, gereksiz risk üretir.

Tek dosya birden fazla protokol sürümünü destekleyebilir mi?

Doğrudan hayır. Kökteki profil tek bir güncel sürümü tanımlar. Eski sürümler supported_versions nesnesiyle ilan edilir ve her biri kendi ayrı profil adresine eşlenir. O adreslerdeki profiller yaprak belgelerdir, kendi içlerinde tek bir sürüm tanımlarlar ve kendileri supported_versions taşıyamazlar.

İmza anahtarı sızarsa ne yapılır?

Anahtar keys dizisinden çıkarılır. Diziden silinmediği sürece iptal edilmiş sayılmaz. Silme işleminden sonra bile yansımanın anlık olmayacağını hesaba katmak gerekir, çünkü tüketici taraflar profili en az bir dakikalık bir önbellek tabanıyla saklar.