Müşteri Paneli Sepet

Entegrasyon örnekleri

Sürüm 1.0.0 · Bu sayfa whmcs-musteri-yorumlari-1.0.0.zip paketindeki examples/README.md dosyasının HTML görünümüdür.

WHMCS'teki "Müşteri Yorumları" modülünün (musteriyorumlari) herkese açık okuma API'sini WHMCS dışındaki sitelerde kullanmak için örnekler. Bütün örnekler modülün kendi çıktısıyla aynı myr-* sınıflı HTML'i üretir; bu yüzden stil için yalnızca modülün widget.css dosyasına bağlantı verilir (CSS kopyalanmaz):

https://my.ornek.com/modules/addons/musteriyorumlari/assets/widget.css

my.ornek.com = WHMCS adresiniz, www.ornek.com = yorumları göstereceğiniz site (yer tutucular).

Hangi örnek ne zaman?

Örnek Ne zaman Çizim CORS kökeni gerekir mi?
html/embed.html Düz HTML ya da kod yazamadığınız bir site oluşturucu; bir sayfaya blok/özet eklemek Tarayıcıda (JS widget) Evet
html/musteri-yorumlari.html Harici sitede ayrı bir /musteri-yorumlari sayfası (filtreler, sayfalama) Tarayıcıda (JS widget, data-gorunum="sayfa") Evet
php/musteri-yorumlari-adaptor.php Framework'süz PHP sitesi; içerik HTML'de gelsin (SEO, JS'siz ziyaretçi) Sunucuda Hayır
wordpress/musteri-yorumlari/ WordPress; [musteri_yorumlari] kısa kodu Sunucuda Hayır
laravel/ Laravel; <x-musteri-yorumlari /> Blade bileşeni Sunucuda Hayır
routing/ WHMCS'in kendi yorum sayfasını /musteri-yorumlari dostu adresiyle açmak — —

Sunucu tarafı örnekler (PHP, WordPress, Laravel) içerik arama motorlarına doğrudan görünsün istiyorsanız ve JSON-LD basacaksanız tercih edilir. JS widget en kolay kurulumdur; içerik sayfa yüklendikten sonra eklenir.

JS widget

Sayfaya tek bir betik eklenir; sayfadaki bütün data-musteri-yorumlari öğelerini o doldurur. Widget, API'yi yüklendiği WHMCS adresinden (aynı modules/addons/musteriyorumlari/ klasörü) çağırır. Gerekirse öğeye ya da script etiketine data-api="https://my.ornek.com/modules/addons/musteriyorumlari/api.php" yazılarak adres açıkça verilebilir (öğedeki değer önceliklidir).

<link rel="stylesheet" href="https://my.ornek.com/modules/addons/musteriyorumlari/assets/widget.css?v=SURUM">
<div data-musteri-yorumlari data-kategori="vds" data-adet="6" data-gorunum="kart"></div>
<script src="https://my.ornek.com/modules/addons/musteriyorumlari/assets/widget.js?v=SURUM" defer></script>
Öznitelik Değerler Not
data-musteri-yorumlari (değersiz) Widget'ın dolduracağı öğe
data-kategori kategori anahtarı (^[a-z][a-z0-9_]{1,39}$) Yoksa bütün aktif kategoriler
data-adet 1–50 Yoksa yönetici/kategori ayarı
data-gorunum kart | liste | ozet | sayfa ozet: yalnızca puan özeti; sayfa: filtreli tam sayfa
data-tema acik | koyu | otomatik otomatik: ziyaretçinin sistem ayarı
data-sirala yeni | eski | puan_yuksek | puan_dusuk
data-sema 1 JSON-LD. Yalnızca kategorinin kendi tek ürün sayfasında
  • ?v=SURUM yerine modül sürümünü (ya da dosya değiştiğinde değişen herhangi bir değeri) yazın; modül güncellendiğinde değiştirin ki ziyaretçiler eski CSS/JS'yi önbellekten kullanmasın.
  • data-sema="1": modül şemayı yalnızca yönetim panelinde "Product" modu açılmış, tek ürünlü kategoride üretir. Ana sayfa, genel yorum sayfası, birden çok ürünü listeleyen sayfa ya da aynı kategoriyi gösteren ikinci bir sayfada kullanmayın. Aynı sayfada aynı kategori için yalnızca bir öğede kullanın.
  • html/musteri-yorumlari.html: sayfanın <title>, meta description, sorgusuz canonical ve tek H1'i sayfanın kendisindedir; widget yalnızca içerik ekler. Bu sayfayı kullanıyorsanız modül ayarlarındaki "Genel yorum sayfası adresi"ni https://www.ornek.com/musteri-yorumlari yapın ki "Daha Fazla Göster" bağlantıları buraya gelsin.

Kökeni izin listesine ekleyin (yalnızca JS widget)

Tarayıcı, başka bir kökenden gelen API yanıtını ancak API o kökene izin verirse sayfaya verir. WHMCS yönetim panelinde Eklentiler → Müşteri Yorumları → Alan Adları listesine sitenizin kökenini ekleyin:

https://www.ornek.com
  • Yalnızca köken: şema + alan adı (+ standart dışı port). Yol yok (https://www.ornek.com/sayfa değil), sonda / yok, joker yok.
  • Eşleşme birebirdir: https://ornek.com ile https://www.ornek.com ayrı kökenlerdir; ikisini de kullanıyorsanız ikisini de ekleyin. http:// kökenler kabul edilmez (geliştirme için yalnızca ayarla açılan http://localhost istisnası vardır).
  • WHMCS'in kendi adresi ve "Genel yorum sayfası adresi"nin kökeni kendiliğinden izinlidir.
  • Sunucu tarafı örnekler (PHP, WordPress, Laravel) için bu listeye ekleme gerekmez.

Sitenizde Content-Security-Policy varsa script-src, style-src ve connect-src yönergelerine https://my.ornek.com eklenmelidir.

Güvenlik kuralları

Örnekler bu kurallara göre yazıldı; kendi entegrasyonunuzu yazıyorsanız aynılarını uygulayın.

  1. Sabit kaynak. API adresi yapılandırmada sabittir; yalnızca https, kullanıcı adı/şifre ve sorgu içermeyen, /api.php ile biten adres kabul edilir. İstek adresi asla kullanıcıdan gelen değerden (sorgu, form, çerez, başlık) kurulmaz. Yönlendirmeler izlenmez.
  2. İzin listesi. API'ye yalnızca r, kategori, adet (1–50), sayfa (1–500), sirala, puan (1–5), donem (30|90|365) gönderilir; her biri kendi kuralıyla doğrulanır, geçersiz değer gönderilmez.
  3. Zaman aşımı ve boyut. Bağlantı 3 sn, toplam 5 sn; TLS doğrulaması açık; yanıt 1 MB ile sınırlı. API yavaşladığında sayfanız en çok bu kadar bekler; başarısızlıktan sonra kısa bir süre (varsayılan 30 sn, 429'da Retry-After) yeniden denenmez.
  4. Yanıt doğrulama. Yalnızca HTTP 200 + Content-Type: application/json; surum ve bütün kullanılan alanların türleri denetlenir. Bir alan bile beklenen türde değilse veri kullanılmaz (boş blok). Renkler yalnızca #rgb/#rrggbb/#rrggbbaa, bağlantılar yalnızca https olabilir; değilse varsayılan renk kullanılır / bağlantı basılmaz.
  5. Kaçış. Bütün metin HTML'e kaçışlanarak yazılır (htmlspecialchars(ENT_QUOTES|ENT_SUBSTITUTE|ENT_HTML5), WordPress'te esc_html/esc_attr/esc_url, Blade'de {{ }}). Satır sonları için metin önce kaçışlanır, sonra yalnızca <p> ve <br> eklenir; yorum metninden bağlantı ya da HTML üretilmez.
  6. JSON-LD yalnızca açıkça istenirse ve JSON_HEX_TAG|JSON_HEX_AMP|JSON_HEX_APOS|JSON_HEX_QUOT ile basılır (</script> kırılması mümkün değildir); istek başına kategori başına bir kez.
  7. Hata durumunda sayfa bozulmaz. Önce son başarılı önbellek (en çok 1 gün), o da yoksa boş çıktı döner. API "kategori yok / modül kapalı" derse eski veri gösterilmez.
  8. Önbellek web kökü dışında tutulur (PHP adaptörü web kökü içindeki klasörü reddeder); dosyalar 0600, yazma atomiktir (tempnam + rename).

CORS hakkında

  • CORS bir kimlik doğrulama yöntemi değildir. Yalnızca tarayıcıların, başka bir kökenden gelen yanıtı sayfanın JavaScript'ine verip vermeyeceğini belirler. API zaten yalnızca herkese açık veriyi (yayındaki yorumlar, puan özeti) döndürür; gizli bir şey CORS'a güvenilerek korunmaz.
  • Tarayıcı dışı istemciler (sunucu tarafı PHP/WordPress/Laravel, curl, botlar) CORS'tan etkilenmez; bu yüzden sunucu tarafı örnekler için köken eklemek gerekmez ve CORS listesi kötüye kullanımı engellemez. API'deki IP başına istek sınırı (varsayılan dakikada 120) bunun içindir; sunucu tarafı entegrasyonlar bütün ziyaretçiler için tek IP'den istek attığından önbellek zorunludur.
  • API Access-Control-Allow-Origin başlığında yalnızca izinli kökeni yansıtır (asla *), Allow-Credentials göndermez. Widget çerez göndermez (credentials: 'omit'); API oturum, çerez ya da API anahtarı kullanmaz.

Önbellek ve gecikme

  • API yanıtları Cache-Control: public, no-cache + ETag ile döner; tarayıcı ve vekiller her istekte yeniden doğrular. JS widget bu yüzden yönetim panelindeki değişikliği bir sonraki sayfa açılışında görür.
  • Sunucu tarafı örnekler kendi önbelleklerini tutar (varsayılan 120 sn). Yeni onaylanan bir yorum bu süre kadar geç görünür; yayından kaldırılan bir yorum da bu süre boyunca görünmeye devam edebilir. API'ye ulaşılamadığı anlarda "son başarılı veri" en çok 1 gün gösterilir.
  • Kısa TTL önerilir (60–300 sn). Bir yorumu hemen kaldırmanız gerekiyorsa: PHP adaptöründe önbellek klasöründeki myr_*.json dosyalarını silin, WordPress'te Ayarlar → Müşteri Yorumları → "Önbelleği temizle", Laravel'de ilgili önbellek deposunu temizleyin.

Doğrulama durumu

  • php/musteri-yorumlari-adaptor.php: PHP 8.2 ve 8.5 ile sahte bir API'ye karşı CLI testinden geçti (XSS yükleri, geçersiz JSON, yanlış içerik türü, 500/404/429, 2 MB yanıt, 302, 10 sn yavaş yanıt, önbellek, bayat yedek, parametre izin listesi, sayfa görünümü).
  • wordpress/ ve laravel/: bu sunucuda WordPress/Laravel ortamı olmadığı için gerçek ortamda çalıştırılmadı; php -l, elle inceleme ve çerçeve işlevlerinin basit taklitleriyle sahte API'ye karşı duman testi yapıldı (Blade bileşeni derlenmedi). Kurulumdan sonra bir hazırlık ortamında deneyin.
  • routing/: Apache ve nginx kuralları bu sunucuda ayrı, geçici test örneklerinde (yüksek port) denendi.
  • html/: widget betiğinin öznitelik sözleşmesine göre yazıldı; gerçek WHMCS kurulumunda tarayıcıda deneyin.
İnternet bağlantınız kesildi