Site bağlantıları rehberi: Eklenti, bağlayıcı, API ve webhook kurulumunda güvenlik

Bir SEO panelinin ürettiği düzeltme ya da yazı, sitenize ulaşmadıkça bir öneriden ibarettir. Bu yolu açan şey bağlantı kanalıdır. Kanal ne kadar işe yararsa, o kadar da yetki taşır. Bir eklenti sayfa başlığınızı değiştirebilir, bir bağlayıcı sunucunuza dosya yazabilir, bir API anahtarı form kayıtlarınızı okuyabilir.

Bu yüzden bu rehber "hangi kanal ne yapar" sorusunu kısa tutup asıl olarak kurulum ve güvenlik üzerinde durur. Kanalların düzeltme kapsamını ayrıntılı karşılaştırmak isterseniz SEO hata düzeltme rehberine, WordPress dışı sitelerde yayın yöntemleri için de içerik otomasyonu yazısına bakabilirsiniz.

Kanallara kısa bir bakış

Otopilot ile siteniz arasında iki tür bağlantı vardır.

Çekme: Siteniz paneli düzenli olarak yoklar, hazır işleri alır ve uygular. WordPress eklentisi, Next.js ve PHP bağlayıcıları ile OpenCart modülü böyle çalışır. Sitenizin dışarıdan gelen bir isteği kabul etmesi gerekmez.

İtme: Panel, platformun kendi arayüzüyle doğrudan mağazaya yazar. Shopify, Wix ve ikas kanalları böyledir ve beta olarak işaretlidir.

Bunlara ek olarak:

• Pixel tarayıcıda çalışan bir betiktir.
• Geliştirici API'si kendi yazılımınızın panelle konuşmasını sağlar.
• MCP yapay zekâ destekli geliştirme araçlarının aynı API'yi kullanmasını sağlar.
• Webhook panelde bir olay olduğunda sizin adresinize bildirim gönderir.

Hangi kanalın ne yaptığının özeti için site bağlayıcıları sayfasına bakabilirsiniz.

Kanalları yöntemlerine göre şöyle gruplayabilirsiniz:

Proje API anahtarı: Her şeyin temeli

Eklenti, bağlayıcılar, API ve MCP aynı proje API anahtarını kullanır. Anahtar sp_ ile başlar ve proje başına tektir.

Anahtar nasıl saklanır?

• Panel anahtarın yalnız özetini ve şifrelenmiş hâlini saklar.
• Panelde anahtar normalde yalnız son dört karakteriyle görünür. Tam hâlini görmek için ayrıca görüntülemeniz gerekir.
• Anahtarı yeniden görüntülemek, yenilemek ya da iptal etmek hesap aktivitesine kaydedilir. Kimin, ne zaman yaptığı izlenebilir.

Yenileme ve iptal

Anahtarı yenilediğinizde eskisi hemen geçersiz olur. Eski anahtarı kullanan kanallar bağlantıyı kaybeder ve panel bunu gösterir. Bu bilinçli bir davranıştır: Sızdığını düşündüğünüz bir anahtarı yenilemek, onu kullanan her şeyi tek hamlede keser.

İptal ettiğinizde anahtar tamamen silinir. Yeni bir anahtar oluşturana kadar anahtarlı kanallar çalışmaz.

Anahtar hijyeni

• Anahtarı e-postayla, sohbet uygulamasıyla ya da ekran görüntüsüyle paylaşmayın.
• Kod deposuna yazmayın. Ortam değişkeni ya da depo dışında duran bir yapılandırma dosyası kullanın.
• Bir ajans ya da serbest geliştiriciyle çalıştıysanız iş bitince anahtarı yenileyin.
• Anahtarın sızdığından şüphelenirseniz önce yenileyin, sonra araştırın.

WordPress eklentisi

Kurulum

1. Panelden eklentinin ZIP dosyasını indirin. Eklenti WordPress.org dizininde listelenmez.
2. WordPress yönetiminde Eklentiler > Yeni Ekle > Eklenti Yükle ile yükleyip etkinleştirin.
3. Eklenti ayarlarına panel adresini ve proje API anahtarını girin.
4. Paneldeki bağlantı testini çalıştırın. İlk sinyal geldiğinde kart bağlı görünür.

Eklenti WordPress 6.0 ve PHP 7.4 veya üzerini ister. Yeni sürümler de panelden ZIP olarak indirilip aynı yolla yüklenir.

Güvenlik nasıl sağlanır?

Eklentinin panelle konuşması imzalıdır. Her istekte anahtarın kendisi gönderilmez. Eklenti, anahtarın özetini kimlik olarak, anahtarın kendisini ise isteği HMAC-SHA256 ile imzalamak için kullanır. İmzada zaman damgası, yöntem, adres ve gövdenin özeti bulunur.

Bu yapının üç faydası vardır:

• Yolda biri isteği görse bile anahtarı ele geçiremez.
• Saati çok kaymış ya da daha önce kullanılmış bir istek reddedilir. Böylece tekrar saldırısı engellenir.
• Panelin yanıtı da aynı anahtarla imzalanır. Eklenti, yanıtın gerçekten panelden geldiğini doğrular.

Eklenti ayrıca javascript:, data: gibi tehlikeli bağlantı şemalarını reddeder. Değiştirdiği her alanın ilk değerini saklar. Panelden geri aldığınızda özgün değer geri yazılır. Yoast SEO, Rank Math veya All in One SEO kuruluysa değerler onların alanlarına yazılır.

Eklentiyi silerseniz

Eklentinin kendi ayarları ve tabloları temizlenir. Yazı ve görsellere yazılmış değerlere dokunulmaz. .htaccess içinde yalnız eklentinin işaretli bloğu kaldırılır.

Next.js ve PHP bağlayıcıları

Bu iki paket, WordPress kullanmayan siteler için hazırlanmıştır. Paketler, mağazadaki tek seferlik kurulum modülüyle açılır ve panelden ZIP olarak indirilir. Her ikisi de çekme yöntemiyle, zamanlanmış görevle çalışır.

Next.js bağlayıcısı

• Node 18.17 veya üzeri gerekir.
• Bağlantı bilgileri .env.local dosyasına yazılır: panel adresi, proje kimliği, API anahtarı ve site adresi.
• --check ile bağlantıyı yazı yayımlamadan denersiniz.
• Sunucuda zamanlanmış görevle çalıştırılır. Pakette örnek bir zamanlama satırı bulunur.
• Yazılar varsayılan olarak content/blog altına JSON veya MDX dosyası olarak yazılır. Kendi CMS'iniz varsa kendi bağdaştırıcınızı verebilirsiniz.
• SEO kuralları bir dosyaya yazılır, sayfalarınız generateMetadata içinde bu kuralları okur. Desteklenmeyen kurallar panele "uygulandı" diye bildirilmez.
• Yayında sayfayı tazelemek isterseniz örnek bir tazeleme rotası vardır. Bu rota ayrı bir gizli değerle korunur.

PHP bağlayıcısı

• PHP 7.4 veya üzeri ile ext-json ve ext-dom gerekir.
• Paket klasörü web kökünün dışına ya da erişimi kapalı bir yere yüklenir. Bu, en önemli güvenlik adımıdır.
• Anahtar config.php içine ya da ortam değişkenine yazılır.
• Düzeltmelerin sayfaya yansıması için ortak giriş dosyanızın en üstüne tek bir require_once satırı eklenir.
• Yazılar dosya olarak, PDO ile bir veritabanı tablosuna ya da kendi sınıfınızla saklanabilir.
• Gelen yazı HTML'i izinli etiket listesinden geçer. script ve iframe gibi etiketler atılır.
• Düzeltmeleri başka bir kanaldan alıyorsanız bağlayıcıyı yalnız içerik kanalı olarak çalıştırabilirsiniz.

Bağlayıcılar için ortak öneriler

• Yapılandırma dosyalarını ve günlük kayıtlarını web'den erişilemez tutun.
• Zamanlanmış görevi, dosyaları yazabilecek ama gereğinden fazla yetkisi olmayan bir kullanıcıyla çalıştırın.
• İlk kurulumda mutlaka deneme komutunu çalıştırın.
• Günlük kaydına arada bir bakın. Geçici hatalar bir sonraki çalışmada yeniden denenir.

Pixel: Anahtarı gizli değildir, yetkisi de sınırlıdır

Pixel, px_ ile başlayan ayrı bir anahtar kullanır. Bu anahtar sayfanızın kaynak kodunda görünür. Bu bir güvenlik açığı değildir. Pixel anahtarı o projenin yayındaki kurallarını okur ve etkileşim ya da bot sayımı gibi sinyaller gönderir. Düzeltme yazamaz, form kaydı ya da yazı okuyamaz, API'deki hiçbir izni kullanamaz.

Pixel kuralları uygularken de dikkatli davranır. Gelen HTML'den script, iframe, form gibi etiketler ve on ile başlayan olay öznitelikleri temizlenir.

Pixel tarayıcıda çalıştığı için değişiklik ham HTML'de görünmez. Google'ın JavaScript SEO belgesinde anlatıldığı gibi Google sayfayı işlediğinde değişikliği görebilir, ama JavaScript çalıştırmayan botlar göremez. Kalıcı çözüm için sunucu tarafı bir kanal tercih edin.

Geliştirici API'si ve izinler

Kendi yazılımınız için geliştirici API'si kullanılır. İstekler X-SP-Auth başlığında proje anahtarıyla yapılır.

İzinler modül başınadır

API'de dört izin grubu vardır: sohbetler, formlar, randevular ve yorumlar. Her grupta okuma, bazılarında yazma izni bulunur. Bir izni yalnız ilgili modül projede açıksa verebilirsiniz.

İyi bir kural şudur: Yalnız ihtiyaç duyduğunuz izni açın. Form kayıtlarını CRM'inize aktaran bir entegrasyonun randevu yazma iznine ihtiyacı yoktur.

IP kısıtlaması

API isteklerini belirli IP adresleriyle sınırlayabilirsiniz. Listede en fazla 20 adres tutulabilir. Kısıtlama açıkken listedeki son adresi silmenize izin verilmez, çünkü bu tüm erişimi kapatır. Panel, kısıtlamayı açmadan önce son 30 günde listede olmayan kaç adresten istek geldiğini, yani kısıtlama açılsaydı nelerin engelleneceğini gösterir.

Sabit IP adresi olan bir sunucudan çalışıyorsanız bu kısıtlamayı açın. Sızan bir anahtar başka bir yerden kullanılamaz.

MCP

MCP, yapay zekâ destekli geliştirme araçlarının panelle konuşmasını sağlar. Araç düzeltmeleri ve yazıları çeker, uyguladıklarını bildirir. Proje API anahtarıyla çalışır, yani yukarıdaki anahtar kuralları burada da geçerlidir.

Bir yapay zekâ aracına anahtar verdiğinizde, o aracın kodunuzda yaptığı değişiklikleri gözden geçirmeye devam edin. Anahtar yalnız erişimi sağlar. Doğru uygulamayı sağlamaz.

Webhook

Webhook, panelde bir olay olduğunda sizin belirlediğiniz adrese bir istek gönderir. Örnekler: yeni bir düzeltme hazır, form gönderildi, randevu oluştu, yorum geldi, yazı yayımlandı.

Kurulum kuralları

• Proje başına en fazla 5 uç nokta tanımlanabilir.
• Adres HTTPS olmalıdır. Özel ağ adreslerine gönderim yapılmaz.
• Yönlendirmeler izlenmez. Uç noktanız doğrudan 2xx yanıt vermelidir.
• Bir modüle bağlı olaylara yalnız o modül açıksa abone olunabilir.

İmzayı mutlaka doğrulayın

Her istek X-SP-Signature başlığıyla gelir. Başlıkta bir zaman damgası ve HMAC-SHA256 imzası bulunur. İmza, whsec_ ile başlayan gizli değer ile hesaplanır.

Uç noktanızda şunları yapın:

1. Gövdeyi ham hâliyle okuyun, ayrıştırmadan önce imzayı doğrulayın.
2. Zaman damgası beş dakikadan eskiyse isteği reddedin.
3. İmzayı sabit sürede karşılaştıran bir fonksiyonla kontrol edin.
4. X-SP-Event-Id değerini saklayın. Aynı olay ikinci kez gelirse yeniden işlemeyin.

İmza doğrulamayan bir uç nokta, adresini bilen herkesin sahte olay göndermesine açıktır.

Teslim ve yeniden deneme

Başarısız teslimler belirli aralıklarla yeniden denenir. Teslim kayıtları 30 gün saklanır. Panelden bir deneme olayı gönderebilir ve tek bir teslimi elle yeniden gönderebilirsiniz.

Uç noktanız isteği hızlı yanıtlamalıdır. Ağır işi kuyruğa alıp hemen 2xx dönmek, zaman aşımı yüzünden gereksiz yeniden denemeleri önler. Art arda çok sayıda başarısız teslim olursa uç nokta kapatılır ve size bildirim gelir.

Bağlantıyı izlemek

Kurulum bir kez yapılır, ama bağlantı zamanla bozulabilir. Bir sunucu taşınır, bir zamanlanmış görev silinir, bir eklenti devre dışı kalır. Bu yüzden izleme de kurulumun parçasıdır.

• Son sinyal: Panel her kanalın son sinyal zamanını tutar. Belirli bir süre sinyal gelmeyen kanal bayat olarak işaretlenir.
• API kullanımı: Seçtiğiniz dönemde hangi IP adreslerinden kaç istek geldiğini ve kaçının başarısız olduğunu görebilirsiniz. Tanımadığınız bir adres görürseniz anahtarı yenileyin.
• Webhook teslimleri: Her uç nokta için son teslimlerin durumu ve yanıt kodu listelenir.
• Hesap aktivitesi: Anahtar görüntüleme, yenileme ve iptal kayıtları buradadır.

Bu kontrolleri ayda bir kez gözden geçirmek, sorunları müşteriniz fark etmeden yakalamanızı sağlar.

Neler yapmaz?

• Sunucunuzu yönetmez. Bağlayıcıların zamanlanmış görevini siz ya da geliştiriciniz kurarsınız.
• Her kanal her alanı değiştiremez. Kapsam kanala göre değişir. Desteklenmeyen kural uygulandı diye bildirilmez.
• Anahtarı sizin yerinize korumaz. Anahtar sızarsa yenilemek sizin işinizdir.
• Webhook'u sizin yerinize doğrulamaz. İmza kontrolü alıcı tarafın görevidir.
• Otomatik düzeltme her pakette yoktur. Bağlantı kurulsa da düzeltme uygulanması paketinize bağlıdır. Ayrıntı için fiyatlar sayfasına bakın.

Sık sorulan sorular

Birden fazla kanal kullanabilir miyim?

Evet. Ancak pixel ile WordPress eklentisi aynı projede birlikte açıksa panel çakışma uyarısı verir ve çift uygulamayı önler.

Anahtarı yenilersem ne olur?

Eski anahtar hemen geçersiz olur. Eski anahtarı kullanan eklenti ve bağlayıcılara yeni anahtarı girmeniz gerekir.

Pixel anahtarının görünmesi tehlikeli mi?

Hayır. Pixel anahtarı yayındaki kuralları okur ve sayım sinyali gönderir. Düzeltme yazamaz, kayıt okuyamaz.

Kurulumu sizin yapmanız mümkün mü?

Evet, mağazada tek seferlik uzaktan kurulum hizmetleri bulunur.

MCP için ayrı bir anahtar gerekir mi?

Hayır. MCP de proje API anahtarıyla çalışır. Anahtarı yenilerseniz MCP yapılandırmanızı da güncellemeniz gerekir.

Webhook gizli değerimi kaybettim, ne yapmalıyım?

Gizli değer yalnız oluşturulduğunda gösterilir, sonra şifreli saklanır. Uç noktanın gizli değerini panelden yenileyin ve yeni değeri alıcı sisteminize girin. Eski değerle imzalanmış istekler artık doğrulanmaz.

Kaynaklar

• MDN: HMAC
• MDN: SubtleCrypto.sign() ile imza üretme
• Google: JavaScript SEO temelleri
• web.dev: HTTPS neden önemli?