API ile Beden Önerisi Ekleme Rehberi

Çoğu beden önerisi satıcısı size bir widget satarlar, API değil. Ön cepheniz özel olarak inşa edilmişse — headless commerce ön ucu, native uygulama veya bir iFrame'i tolere etmeyen ödeme akışı — bu bir sorun. Bu yazı gerçekten işe yarayan entegrasyon şeklini açıklıyor: ne gönderileceği, ne zaman çağrılacağı, nasıl önbelleğe alınacağı ve başarısız olduğunda ne yapılacağı.

Özel Ön Cepheler İçin API-First Neden Önemlidir

Hazır bir widget, kontrol etmediğiniz bir DOM'u ve sahibi olmadığınız bir render cadencesini varsayar. Next.js, Remix veya native mobile shell üzerine inşa edilen headless ön cepheler, önerme mantığının kendi component ağaçları içinde olmasını gerektirir — bu da bir script etiketi değil, bir JSON sözleşmesi anlamına gelir.

Pratik fark üç yerde ortaya çıkar: gecikme bütçesi, durum mülkiyeti ve tasarım tutarlılığı. Kendiniz yapabileceğiniz bir API çağrısı, diğer ürün sayfası veri alımlarıyla paralelleştirilebilir, kenar sunucuda önbelleğe alınabilir ve enjekte edilen bir iFrame yerine kendi component kitaplığınız ile stillendirilir. Bu, shopify integration düzenlerine yönelen takımları gerçekleştirme kontrol yönüne itiş aynı mantıktır — gömülü çerçeveler yerine native uygulama blokları — render kontrolü, ekstra entegrasyon çalışmasının faydasının değerine layık.

İstek ve Yanıt Şekli

Bir beden önerisi API çağrısı genellikle üç öğeye ihtiyaç duyar: bir ürün tanımlayıcısı (beden tablosu veya giysi meta verileriyle), depolanan veya oturum ölçümleri, ve yerel ayar/birim tercihidir. Minimal bir istek gövdesi buna benzer:

{
  "productId": "sku_48213",
  "measurements": {
    "heightCm": 172,
    "weightKg": 64,
    "fitPreference": "regular"
  },
  "unit": "metric"
}

Yanıt, tek bir tahminden ziyade sıralanmış bir önerilişi döndürmelidir — güven puanları, ön ucun bir boyutu belirginleştirmesine veya iki seçeneği bir notla sunmasına karar vermesini sağlar. Makul bir şekil:

{
  "recommended": "M",
  "alternatives": [
    { "size": "L", "confidence": 0.31 }
  ],
  "confidence": 0.87,
  "fallback": false
}

Sözleşmeyi confidence ve fallback her zaman mevcut olacak şekilde tasarlayın — ön uç mantığı her ikisinde de dallanır ve eksik bir alan ödeme sırasında sessiz bir çökmesine neden olmamalıdır.

Ne Zaman Uç Noktasını Çağırmalı

Her sayfa yüklemesinde çağrı yapmak bir gidiş turu israf eder; sadece açık bir "boyutu bul" tıklaması yapılsa bile alıcılar almayacak şekilde sürtünme ekler. Pratikte en iyi işe yarayan orta yol: depolanan bir alıcı profili varsa ürün sayfası mount olduğunda bir kez çağırın (dönen ziyaretçi, oturum açmış hesap veya kaydedilmiş oturum) ve yalnızca alıcı ölçümleri değiştirdiğinde veya ürün değiştirdiğinde yeniden çağırın.

Ürün listeleme sayfaları için, önerilşi uç noktasını kart başına çağırmayın — toplu halde yapın. Bir productId değerleri dizisi içeren tek bir istek, tüm ızgaranın önerilerini bir gidiş turunda döndürür ve bu, mobil bağlantılarda olduğu kadar görünmek kadar önemlidir.

Önbellekleme Stratejisi

Beden önerileri önbelleğe alınabilirdir ama sonsuz değildir — alıcının ölçümleri nadir olarak oturum içinde değişir, ancak giysi meta verileri (beden tablosu düzeltme, yeni fit notu) herhangi bir zamanda sunucu tarafında değişebilir. Yapılabilir bir ilke:

Sadece productId'de edge'de önbellekleme (alıcıya özel ölçümleri hariç tutan) çalışır, eğer önerilişim modeli girdilere göre deterministikse — hesaplamayı önbelleğe alın, alıcının kimliğini değil. Uç noktanız son iade geçmişi gibi gerçek zamanlı sinyalleri karıştırırsa, TTL'leri kısa tutun ve önbelleği gecikme tampon olarak, doğruluk kaynağı olarak değil.

Gizlilik ve Veri Yönetimi

Vücut ölçümleri, bir alıcı kendileri tarafından daha iyi uyum için gönüllü olarak girilse bile, makul bir tanımla gizlidir. Gereken minimum değerleri saklayın — boy, kilo ve fit tercihi genellikle yeterlidir; ham anket cevaplarını veya cihaz sensörü verilerini ender olarak kalıcı olarak depolammanız gerekir. Alıcılara depolanan ölçümleri temizlemek için görünür bir yol verin ve varsayılan olarak bunları üçüncü taraf analitiğe veya reklam piksellerine aktarmayın.

Bu, gizlilik incelemesinden önce bağlanmış bir ek değil, birinci sınıf API tasarımı olarak değerlendirilmeye değer bir konudur. İlgili parça try-on'da vücut verileri gizliliği alıcıların vücut ölçümleri talep ettiğinde ne beklediğini kapsar, bu istek şemanızı sonuçlandırmadan önce okunmaya değerdir.

API Başarısız Olduğunda veya Veri Olmadığında Zarif Geri Dönüşler

Bir API çağrısı sıradan nedenlerle başarısız olabilir — bir zaman aşımı, soğuk önbellek veya ölçüm geçmişi olmayan bir alıcı. Yukarıdaki yanıt sözleşmesi tam da bu durum için bir fallback: true işareti içerir; ön ucunuz bunu "güvenli önerilişi yok" olarak, bir hata durumu olarak değil.

Makul geri dönüş davranışı, tercih sırasına göre:

• Ürün için statik bir beden tablosu varsa, boş bir önerilişi yuvası yerine onu render edin.
• Alıcının hiç ölçümü yoksa, uzun bir form yerine hızlı 2 alanına (boy ve bir fit tercihi) giriş isteyin.
• API zaman aşımına uğrarsa, sepete ekle düğmesini engellemeyin — sessizce beden tablosuna degraded olun ve arızayı izleme için günlüğe yazın.

Başarısız bir önerilişi çağrısının başarısız bir sayfa yüküne dönüşmesine asla izin vermeyin. Bu, beden tablosunu doğru nasıl okuyacağınız bir beden tablosunun başarısız olmadığı, her önerilişim sisteminin geri dönebileceği temel yapı olduğunu söyleyen genel SEO bitişik prensibini yansıtır.

Çok Marka ve Çok Boyut Sistemi Karmaşıklığını Yapılandırma

Ön cepheniz birden fazla markayı veya satıcıyı kapsarsa, bir beden tablosu şeması tüm uyumunu varsayarak koşmayın. Markalar rutin olarak aynı giysi farklı etiketlerle etiketlerler — bir etiket tarafından ABD 8'i başka bir etiket tarafından ABD 6'ya uyan şekilde uyabilir, bu endüstride iyi belgelenmiş ve özel yapılar için daha zor entegrasyon sorunlarından biridir. API katmanınız productId ile birlikte bir brandId veya vendorId taşımalı, böylece önerilişim motoru global bir eğri yerine markaya özel uyum modellerini uygulayabilir.

Bu karmaşıklık, beden tabloları tek başlarına ölçekte hesaplanmış öneriler için zayıf bir yedek olmasının nedenidir — bir tablo, bir alıcıya bir markanın iddia ettiğini söyler, giysi bir vücuda göre gerçekte nasıl uyduğunu değil. Bu ayrım hakkında daha fazlası için bkz. beden tablosu vs beden önerisi.

YourSizer Nerede Uyuyor

YourSizer'ın önerilişim motoru, sadece paketlenmiş bir widget olarak değil, doğrudan bir API olarak mevcuttur, özel ön cepheler veya native uygulamalar inşa eden takımlar için. İstek/yanıt sözleşmesi yukarıda açıklanan şekli takip eder: ürün ve alıcı profilinde, bir güven puanı ile sıralanmış boyut dışında, açık bir geri dönüş işareti, böylece ön ucunuz yanıtın yetkili olup olmadığını tahmin etmek zorunda değildir.

Ölçüm verileri saklama sınırları ve açık silme yollarıyla işlenir ve API, listeleme sayfaları için toplu istekleri destekler, böylece ürün kartı başına bir gidiş turu yapılmaz. Entegrasyon takımları genellikle bunu mevcut ürün verileri getirme katmanına yükler — Next.js sunucu bileşenleri, GraphQL çözümleyicisi veya native uygulamanın ürün hizmeti — ayrı bir istemci tarafı betiği eklenmek yerine, gecikmeyi ve tasarım kontrolünü ellerinizde tutar.

Sıkça Sorulan Sorular

Beden önerisi API'si gerçek zamanlı ölçümlere mi ihtiyaç duyar yoksa depolanan profil verilerini kullanabilir mi?

Her ikisi de işe yarar ve çoğu entegrasyon her ikisini de kullanır. Dönen alıcının depolanan profili (boy, kilo, fit tercihi) birincil giriş iken, ilk ziyaretçi tipik olarak oturumlarına önbelleğe alınan hızlı iki alan tahmini girer. API, her iki yolu aynı measurements nesnesi aracılığıyla kabul etmelidir, böylece ön ucunuz yeni ve dönen alıcılar için ayrı kod dalları yaratmak zorunda değildir.

Bu sadece bir beden önerişi widget gömmeye nasıl farklıdır?

Bir widget kendi render, stilendirme ve genellikle kendi iFrame sınırını sahip olur, bu entegre etmesi hızlıdır ancak tasarım ve sayfa performansı kontrolü sınırlandırır. Bir API-first entegrasyon, takımınız tamamen UI'ya sahip olduğu ve yalnızca önerilişim mantığını veri olarak tükettiği anlamına gelir, bu headless ön cepheler, native uygulamalar veya yerleştirilmiş bir frame uygun olmadığı strict tasarım sistemlerine sahip markalar için doğru takasıdır.

API düşük güvenli bir önerilişim döndürürse ne olmalı?

Düşük güven puanını alternatifler göstermek yerine bir boyuta taahhüt etmeye bir sinyal olarak ele alın. Makul bir ön uç düzeni, güven kabaca 0.7-0.8'in üzerinde olduğunda üst önerilişimi belirgin bir şekilde göstermek ve altına düştüğünde kısa bir notla yanında iki boyutu yan yana göstermektir. Bu alıcıyı UI'a yanlış kesinlik hissi zorlamadan bilgilendirmiş tutar, bu beden önerişi çözümü seçme alanlarından biridir.

API, bir ön cephede farklı boyut sistemlerine sahip birden fazla markayı destekleyebilir mi?

Evet, istek ürün kimliği ile birlikte bir marka veya satıcı tanımlayıcısı içerdiği sürece, uyum modelleri global yerine markaya duyarlı olması gerektiğinden. Pazaryerleri ve çok marka perakendecileri, en yaygın durumlardır — tek bir "beden M" etiketi satıcılar arasında farklı şeyler ifade eder ve iyi tasarlanmış bir API, ortalamada gitmek yerine bunun hesabı vardır.

Sonuç

Özel bir ön cepheye beden önerileri inşa etmek çoğu zaman makine öğrenmesi değil, entegrasyon tasarımı sorunudur — zor kısımlar sözleşme şekli, önbellekleme sınırları ve çağrı başarısız olduğunda ne olacağıdır. Bunları doğru yapın ve önerilişim katmanı, ön ucunuzun envanteri veya fiyatlandırma API'lerini zaten işlediği şekilde zarif olarak işlenebileceği başka bir veri bağımlılığı olur. Daha fazla ticaret headless ve native mimarilere doğru hareket ettikçe, API-first uyum aletleri muhtemelen istisnai olarak değil varsayılan beklenti haline gelecektir.