Django / Jinja

Bu sayfa Django ya da Jinja şablonlarıyla kurulmuş mağazalar içindir. Sayproof ekibinin sağladığı Django kiti sunucudan Sayproof’a gönderilen isteği, önbelleği, hata durumunu ve şablon yardımcılarını hazır getirir. Kit mağaza projesine kopyalanır; paket kurulumu gerektirmez, yalnızca Django ve Python’un standart kütüphanesini kullanır. Python 3.9 ve Django 2.2 ile daha yeni sürümlerde çalışır.

SSR ya da script

Aynı şablon iki yöntemle de çalışır; fark yalnızca sunucu anahtarıdır:

• SSR (önerilen): Sunucu anahtarı tanımlıysa yorumlar sunucuda hazır HTML olarak alınır ve sayfanın ilk yanıtında yer alır. Arama motorları yorum metnini ve puanı script’i beklemeden görür; script yüklendiğinde bölümü devralır. Ayrıntılar: Server-side rendering.
• Script: Sunucu anahtarı tanımlı değilse boş bir container basılır ve yorumları script tarayıcıda getirir. Sunucudan Sayproof’a hiçbir istek gönderilmez. Daha sonra SSR’a geçmek için yalnızca sunucu anahtarı eklenir.

Kurulum

1. Kitin sayproof klasörünü projenizin uygulamasına kopyalayın (örneğin proje_app/sayproof/). Altyapının kendi klasörleri değiştirilmez; kit yalnızca sizin uygulamanıza eklenir.

2. Ayarları tanımlayın:

   SAYPROOF_BASE = os.environ.get("SAYPROOF_BASE", "")
   SAYPROOF_SITE_KEY = os.environ.get("SAYPROOF_SITE_KEY", "")
   SAYPROOF_SSR_KEY = os.environ.get("SAYPROOF_SSR_KEY", "")
   SAYPROOF_CHANNEL = os.environ.get("SAYPROOF_CHANNEL", "web")

   Sayproof adresi, Site anahtarı ve Kanal kodu panelde Entegrasyon › Sitede gösterim sekmesinde Kurulum yolu olarak Django / Jinja (sunucuda) seçildiğinde Kurulumda kullanılacak değerler listesinde kopyalanabilir olarak gösterilir. Sunucu anahtarı orada gösterilmez; Kanallar › Anahtarlar sekmesinde oluşturulur ve yalnızca oluşturulduğu anda bir kez görünür. Sunucu anahtarı yalnızca sunucunun ortam değişkeninde tutulur; şablona ya da tarayıcıya yazılmaz.

3. Şablon yardımcılarını Jinja ortamının global değişkenlerine kaydedin. Ayar dosyanızda global değişkenler bir sözlükle güncelleniyorsa (örneğin GLOBAL_OPTIONS.update({...})) şu satırları ekleyin:

   GLOBAL_OPTIONS.update({
       "sayproof_ssr": "proje_app.sayproof.markup.sayproof_ssr",
       "sayproof_reviews": "proje_app.sayproof.markup.sayproof_reviews",
       "sayproof_script": "proje_app.sayproof.markup.sayproof_script",
       "sayproof_rating": "proje_app.sayproof.markup.sayproof_rating",
       "sayproof_json_ld": "proje_app.sayproof.markup.sayproof_json_ld",
       "sayproof_order_reviews": "proje_app.sayproof.markup.sayproof_order_reviews",
   })

   Kendi Jinja ortamını kuran projeler JINJA_GLOBALS sözlüğünü ortamın globals alanına ekler. Django şablon dilinde aynı adlar {% load sayproof_tags %} ile kullanılır.

İsteğe bağlı ayarlar:

Ayar	Varsayılan	Kullanımı
SAYPROOF_SERVER_BASE	SAYPROOF_BASE	Sunucu Sayproof’a tarayıcıdan farklı bir adresten ulaşıyorsa
SAYPROOF_SCRIPT	SAYPROOF_BASE + /storefront/sayproof.js	Script bir CDN’den sunuluyorsa
SAYPROOF_TIMEOUT	1.5	SSR isteğinin zaman aşımı (saniye)
SAYPROOF_VIEWER_TIMEOUT	3	Oturum açmış müşteri ve sipariş detayı isteklerinin zaman aşımı (saniye)
SAYPROOF_CACHE_SECONDS	60	SSR yanıtının önbellekte kalma süresi
SAYPROOF_FAILURE_SECONDS	10	Sayproof’a ulaşılamadığında yeniden denemeden önce beklenen süre
SAYPROOF_VIEWER_URL	/sayproof/viewer/	Oturum açmış müşteri endpoint’inin adresi
SAYPROOF_CUSTOMER_EMAIL	request.user.email	Oturumdaki e-posta adresini okuyan fonksiyonun yolu
SAYPROOF_CUSTOMER_NAME	(yok)	Soru-cevapta sorunun yanında görünecek adı okuyan fonksiyonun yolu; verilmezse soru adsız görünür (Oturum açmış müşteri › Soru-cevap)

Ürün sayfası

{% set reviews = sayproof_ssr(product.sku, product.name) %}
{{ sayproof_reviews(product.sku, product.name, ssr=reviews) }}
{{ sayproof_script() }}

• sayproof_ssr yanıtı bir kez alınır; hem bölüm hem yapılandırılmış veri için kullanılır. Aynı ürünün yanıtı 60 saniye önbellekten gelir.
• Ürün kodu, ürün kaynağınızdaki anahtar ve siparişteki satır koduyla aynı olmalıdır.
• Bir ürünün bütün renk ve bedenlerinin yorumlarını birlikte göstermek için grup kodunu scope="group" ile verin.
• sayproof_script() sayfada bir kez yer alır.
• Yorum bölümünü kendi bileşenlerinizle çiziyorsanız headless=True verin; container’a HTML yerine yalnızca durum etiketi yazılır. Bkz. Headless.

Yapılandırılmış veri

Sayfada ürünün Product JSON-LD’si varsa ikinci bir Product eklenmez; puan mevcut nesneye eklenir:

{{ sayproof_json_ld(sayproof_rating(product_json_ld, reviews)) }}

Sayfada Product JSON-LD’si yoksa:

{% if reviews %}{{ sayproof_json_ld(reviews.json_ld) }}{% endif %}

sayproof_json_ld, müşteri metinleri </script> içerse bile etiketin dışına taşmayacak biçimde escape eder.

Oturum açmış müşteri

1. Kitin endpoint’ini bağlayın: path("", include("proje_app.sayproof.urls")).
2. Ürün sayfasında viewer=True verin: sayproof_reviews(product.sku, product.name, ssr=reviews, viewer=True).

Müşterinin durumu sayfaya yazılmaz; tarayıcı /sayproof/viewer/ adresine sorar, mağaza sunucusu soruyu sunucu anahtarıyla Sayproof’a iletir. Sayfa önbelleğe alınabilir kalır. E-posta adresi varsayılan olarak request.user.email alanından okunur; oturum bilgisi başka bir yerdeyse SAYPROOF_CUSTOMER_EMAIL ile kendi fonksiyonunuzu tanımlayın. Fonksiyon boş metin döndürürse müşteri anonim sayılır ve Sayproof’a istek gönderilmez. Ayrıntılar: Oturum açmış müşteri.

Sipariş detayı sayfası

{{ sayproof_order_reviews(order.number, customer_email) }}
{{ sayproof_script() }}

Sipariş Sayproof’ta bulunamazsa ya da başka bir müşteriye aitse hiçbir şey basılmaz. Bu isteğin yanıtı önbelleğe alınmaz.

Content Security Policy

Sayfa CSP nonce kullanıyorsa sayproof_script, sayproof_reviews (viewer=True ile) ve sayproof_json_ld yardımcılarına nonce parametresini verin. script-src ve connect-src Sayproof adresini içermelidir.

Hata durumunda

• SSR isteği 1,5 saniyede yanıt almazsa ya da 200 dışında bir yanıt alınırsa container boş basılır ve script yorumları tarayıcıda getirir.
• Hata 10 saniye önbellekte tutulur; Sayproof’a ulaşılamadığı sürece her sayfa açılışı yeniden beklemez.
• Önbellek çalışmasa da sayfa bozulmaz.
• Log kayıtlarına yalnızca istek gönderilen yol ve hatanın türü yazılır; müşteri e-postası ve anahtarlar yazılmaz.