Dokümantasyon

Magicgate, her ziyaretçiyi yapılandırılabilir bir dizi filtreye göre değerlendirerek bot trafiğini gerçek kullanıcılardan ayırır. Platform, 10 milisaniyeden kısa bir sürede "beyaz" (bot/crawler/unwanted) veya "teklif" (gerçek kullanıcı) şeklinde bir karar verir.

İki entegrasyon modu vardır. API Mode, ziyaretçi özelliklerini bir REST uç noktası aracılığıyla göndermenize ve uygulamanızın harekete geçeceği bir JSON kararı almanıza olanak tanır. Direct Mode her şeyi otomatik olarak yönetir: alanınızı Magicgate'ye yönlendirin; ziyaretçiler sizin tarafınızdan herhangi bir kod değişikliği yapılmadan filtrelenir ve yönlendirilir.

Bu hızlı başlangıç API Mode'e odaklanır çünkü geliştirme sırasında size en fazla kontrolü ve en hızlı geri bildirim döngüsünü sağlar. Kendinizi rahat hissettiğinizde, sıfır kod entegrasyonunun tercih edildiği üretim dağıtımları için Direct Mode'a geçebilirsiniz.

Magicgate, gelen her ziyaretçiyi çok katmanlı bir algılama hattına göre değerlendirir. Her filtre bağımsız olarak çalışır ve nihai karara katkıda bulunur. Değerlendirmenin tamamı 10 milisaniyeden kısa sürede tamamlanarak gerçek kullanıcılar için sıfır algılanabilir gecikme süresi sağlanır.

Tespit hattı birkaç kategoriye ayrılmıştır: ağ düzeyindeki kontroller (IP itibarı, GeoIP, VPN/proxy/Tor algılama, veri merkezi tanımlama), tarayıcı düzeyindeki kontroller (kullanıcı aracısı analizi, JavaScript parmak izi alma, başlık tutarlılığı), davranışsal kontroller (tıklama modelleri, oturum hızı, yönlendiren doğrulaması) ve liste tabanlı kontroller (engelleme listeleri, izin verilenler listeleri, ISP filtreleme).

Her filtre akış başına ayrı ayrı etkinleştirilebilir veya devre dışı bırakılabilir. Bu ayrıntılı kontrol, farklı trafik kaynakları için algılamaya ince ayar yapmanıza olanak tanır. Örneğin, ABD'deki mobil kullanıcıları hedefleyen bir kampanya, GeoIP (yalnızca ABD), VPN/proxy algılamayı ve mobil cihaz doğrulamayı etkinleştirirken ISP filtrelemeyi devre dışı bırakabilir.

GeoIP filtreleme, sıfır gecikmeli aramalar için haftalık olarak güncellenen, yerel olarak barındırılan MaxMind veritabanlarını kullanır. Trafiği ülkeye, bölgeye veya şehre göre hedefleyebilir veya hariç tutabilirsiniz. Veritabanı, ülke düzeyinde %99,8 doğrulukla IPv4 ve IPv6 adreslerini kapsamaktadır.

VPN, proxy ve Tor algılama, birden fazla ticari ve açık kaynaklı veritabanını birleştirir. Magicgate, bilinen VPN çıkış düğümlerinin, genel ve özel proxy sunucularının, Tor çıkış rölelerinin ve yerleşik proxy ağlarının sürekli güncellenen bir listesini tutar. Algılama hem IPv4 hem de IPv6 aralıklarını kapsar.

Veri merkezi tespiti, bulut sağlayıcılarından (AWS, GCP, Azure, DigitalOcean, OVH, Hetzner ve 200'den fazla kişi) kaynaklanan trafiği tanımlar. Bu, özellikle sanal makinelerde çalışan otomatik komut dosyalarının ve başsız tarayıcıların yakalanmasında etkilidir.

Kullanıcı aracısı analizi, ziyaretçinin kullanıcı aracısı dizesini bilinen tarayıcılardan, botlardan ve otomatik araçlardan oluşan bir veritabanına göre ayrıştırır. Ayrıca tutarsızlıkları da tespit eder; örneğin, bir kullanıcı aracısının Windows'ta Chrome olduğunu iddia etmesi ancak Linux'a özgü başlıklar göndermesi.

Engellenenler listesi filtresi, her zaman bot olarak sınıflandırılması gereken IP adresleri, IP aralıkları (CIDR gösterimi) ve kullanıcı aracısı modellerinden oluşan özel listeler tutmanıza olanak tanır. Buna karşılık, izin verilenler listesi filtresi, her zaman geçmesi gereken güvenilir IP'leri (kendi test altyapınız gibi) beyaz listeye almanıza olanak tanır.

Referer doğrulama, HTTP Referer başlığını beklenen kalıplara göre kontrol eder. Trafiğin belirli alanlardan (ör. Google, Facebook) gelmesini zorunlu kılabilir veya trafiği boş, eksik veya şüpheli yönlendirenlerle engelleyebilirsiniz.

Magicgate özünde bir trafik yönlendiricisidir. Her ziyaretçi, yapılandırılmış filtrelerinize göre değerlendirilir ve bir karara varılır: 'teklif' (meşru kullanıcı) veya 'beyaz' (bot, tarayıcı veya istenmeyen trafik). Karar, ziyaretçinin nereye yönlendirileceğini belirler.

Teklif Sayfası, gerçek açılış sayfanız, teklif sayfanız veya dönüşüm huninizdir; gerçek insan ziyaretçilerin görmesini istediğiniz sayfadır. Beyaz Sayfa, botlara, tarayıcılara ve reklam ağı incelemecilerine gösterilen sahte veya zararsız bir sayfadır. Yaygın beyaz sayfalar arasında basit blog gönderileri, haber makaleleri veya genel bilgi içeriği bulunur.

Bu ayırma kampanyanın korunması için gereklidir. Reklam ağı uyumluluğunu inceleyenler, tıklama sahtekarlığı botları ve rakipler beyaz sayfayı görürken, hedef kitlenizdeki gerçek kullanıcılar da teklif sayfasına ulaşır. Yönlendirme şeffaf bir şekilde ve kablo hızında gerçekleşir.

Direct Mode'da yönlendirme tamamen otomatiktir. Alan adınızın DNS'sini Magicgate'ye yönlendirirsiniz ve platform tüm istek yaşam döngüsünü yönetir: ziyaretçiyi alır, filtreleri değerlendirir ve uygun hedefe bir HTTP yönlendirmesi (varsayılan olarak 302) düzenler. Ziyaretçi asla bir ara sayfa görmez.

API Mode'de uygulamanız, ziyaretçi öznitelikleriyle /api/v1/check uç noktasını çağırır ve kararı ve önerilen yönlendirme URL'sini içeren bir JSON yanıtı alır. Uygulamanız daha sonra yönlendirmeyi kendisi yönetir. Bu size kullanıcı deneyimi üzerinde tam kontrol sağlar; yönlendirmeden önce özel mantık, günlük kaydı veya A/B testi ekleyebilirsiniz.

Magicgate, ziyaretçileri yönlendirmek için üç ekran modunu destekler. 'Yönlendirme' (varsayılan), hedef URL'ye bir HTTP yönlendirmesi düzenler. 'Proxy', tarayıcının adres çubuğunu değiştirmeden hedef sayfa içeriğini orijinal URL'de sunar. 'Iframe', hedef sayfayı orijinal URL'deki bir iframe içine yükler. Görüntüleme modu akışa göre yapılandırılabilir.

Kararlar eşzamanlı olarak işlenir ve aynı ziyaretçiden gelen hızlı ardışık istekleri (örneğin, ilk yönlendirmeden sonra yüklenen sayfa kaynakları) işlemek için kısa süreliğine önbelleğe alınır. Önbellek TTL'si, varsayılan olarak 30 saniye olacak şekilde akış başına yapılandırılabilir.

Magicgate, her biri farklı kullanım durumları ve teknik gereksinimler için tasarlanmış iki farklı entegrasyon modu sunar. Doğru modun seçilmesi, dağıtım karmaşıklığınızı, kullanıcı deneyimi üzerindeki kontrolünüzü ve operasyonel ek yükünüzü etkiler.

API Mode programlı bir entegrasyondur. Uygulamanız, ziyaretçi özelliklerini (IP adresi, kullanıcı aracısı, yönlendiren vb.) içeren /api/v1/check uç noktasına bir POST isteği gönderir ve kararı içeren bir JSON yanıtı alır. Kodunuz daha sonra yönlendirmeyi yönetir; botları beyaz sayfaya yönlendirir ve gerçek kullanıcıların geçmesine izin verir. Bu mod, entegrasyon kodu yazmanızı gerektirir ancak size istek akışı üzerinde tam kontrol sağlar.

Direct Mode, DNS düzeyinde bir entegrasyondur. Alan adınızın DNS kayıtlarını (CNAME ila proxy.magicgate.io veya kök alanlar için ALIAS/ANAME) Magicgate'yi işaret edecek şekilde yapılandırırsınız. Bir ziyaretçi geldiğinde, Magicgate şeffaf bir şekilde isteği keser, ziyaretçiyi değerlendirir ve teklif sayfasına veya beyaz sayfaya bir HTTP yönlendirmesi gönderir. Uygulamanızda hiçbir kod değişikliğine gerek yoktur; filtreleme ve yönlendirme katmanının tamamı, kaynak sunucunuzun önünde bulunur.

API Mode avantajları: Yönlendirme mantığı üzerinde tam kontrol. Kararın alınması ile kullanıcıyı yeniden yönlendirme arasında özel işlemler (günlüğe kaydetme, A/B testi ataması, çerez ayarı, analiz etkinlikleri veya karar meta verilerine dayalı koşullu mantık) ekleyebilirsiniz. API Mode herhangi bir arka uç yığınıyla çalışır ve DNS değişikliği gerektirmez. Ayrıca istemci tarafı JavaScript'in kontrol çağrısını yaptığı tek sayfalı uygulamalar (SPA'lar) için de idealdir.

API Mode dezavantajları: Uygulamanızda kod değişikliği gerektirir. API çağrısını, hata durumlarını (zaman aşımları, hız sınırları) ve yönlendirme mantığını ele almanız gerekir. API çağrısı, sayfa yükleme sürenize bir ağ gidiş-dönüş süresi ekler (genellikle Magicgate'nin sınırına coğrafi yakınlığa bağlı olarak 10-50 ms).

Direct Mode avantajları: Sıfır kod değişikliği. DNS'nizi yönlendirin ve akışınızı yapılandırın; ziyaretçiler otomatik olarak filtrelenir ve yönlendirilir. Direct Mode son kullanıcı için daha hızlıdır çünkü ekstra API gidiş-dönüş yoktur; filtreleme, DNS çözünürlüğünün ve ilk HTTP isteğinin bir parçası olarak kenarda gerçekleşir. Ayrıca tüm uç durumları (zaman aşımları, yeniden denemeler) şeffaf bir şekilde yönetir.

Direct Mode dezavantajları: Yönlendirme süreci üzerinde daha az kontrol. Karar ile yönlendirme arasına özel mantık ekleyemezsiniz. DNS değişiklikler yavaşça yayılır (dakikalardan saatlere kadar), bu da test etme ve geri alma işlemlerini yavaşlatır. Direct Mode beyaz sayfanıza ve teklif sayfanıza genel URL'ler aracılığıyla erişilebilmesini gerektirir.

Hibrit bir yaklaşım da mümkündür. Ana açılış sayfalarınız için (sıfır kod entegrasyonunun öncelikli olduğu yerlerde) Direct Mode ve özel karar işleme gerektiren belirli uç noktalar (ör. form gönderimleri, API uç noktaları veya ödeme akışları) için API Mode kullanın.

Her Magicgate hesabının anında kullanım için paylaşılan bir alana (go.magicgate.io) erişimi vardır. Starter ve üzeri planlar, markalı URL'ler için özel alanlar ve reklam ağlarıyla iyileştirilmiş güven sinyalleri ekleyebilir.

Özel alanlar, paylaşılan alan adı yerine kendi URL'nizi (ör. track.yourbrand.com) kullanmanıza olanak tanır. Bu, reklam uyumluluğu açısından önemlidir; birçok reklam ağı, paylaşılan izleme alanları yerine markalı alanlardan gelen trafiğe karşı daha hoşgörülüdür.

Magicgate hem alt alan adlarını (track.yourbrand.com) hem de kök alan adlarını (yourbrand.com) destekler. Alt alan adları, ana web sitenizin DNS yapılandırmasını etkilemedikleri ve yönetimleri daha kolay oldukları için önerilir.

Alan adı doğrulaması, proxy.magicgate.io işaretini gösteren CNAME kayıtlarını kullanır. Bir alan eklediğinizde, alanınızdan proxy.magicgate.io'ye bir CNAME kaydı yapılandırırsınız. CNAME kayıtlarını desteklemeyen kök alanlar için bunun yerine proxy.magicgate.io işaretini taşıyan bir ALIAS veya ANAME kaydı kullanın. Magicgate, DNS kaydının proxy uç noktasına doğru şekilde çözümlendiğini kontrol ederek sahipliği doğrular.

SSL sertifikaları, DNS yayılımı tamamlandıktan sonra Let's Encrypt aracılığıyla otomatik olarak sağlanır. Magicgate sertifika verme, yenileme ve kurulum işlemlerini gerçekleştirir. Özel etki alanınız, DNS yapılandırmasından birkaç dakika sonra geçerli bir sertifikayla HTTPS üzerinden trafiğe hizmet verecektir.

Cloudflare kullanıcıları için, Magicgate'i işaret eden CNAME kaydı için proxy'nin (turuncu bulut) devre dışı bırakıldığından emin olun. Cloudflare'in proxy'si trafiği Magicgate'e ulaşmadan önce keser ve bu da ziyaretçi değerlendirmesini etkileyebilir. Kaydı 'Yalnızca DNS' (gri bulut) moduna ayarlayın.

Alan adlarını doğrudan Magicgate'in pazar yeri üzerinden de satın alabilirsiniz. Bu alanlar önceden yapılandırılmıştır ve hemen kullanıma hazırdır; DNS kurulumu veya doğrulaması gerekmez. Pazar, trafik kampanyalarına uygun çeşitli temiz alan adları sunar.

Webhooks, Magicgate hesabınızda akış değişiklikleri, etki alanı doğrulaması veya ödeme güncellemeleri gibi önemli olaylar meydana geldiğinde gerçek zamanlı HTTP POST bildirimleri almanızı sağlar.

Magicgate birden fazla kategorideki webhook olaylarını destekler: akış olayları (flow.created, flow.updated, flow.deleted), etki alanı olayları (domain.added, domain.verified, domain.deleted, domain.registration_failed), beyaz sayfa olayları (white_page.ready, white_page.failed, white_page.deleted), kara liste etkinlikleri (blacklist.created, blacklist.updated, blacklist.deleted), API key etkinlikleri (apikey.created, apikey.deleted, apikey.activated, apikey.deactivated), cüzdan etkinlikleri (wallet.credited, wallet.debited), abonelik etkinlikleri (subscription.changed, subscription.canceled,subscribe.plan_changed ve daha fazlası), faturalandırma etkinlikleri (payment.completed, payment.failed) ve destek etkinlikleri (ticket.created, ticket.replied, ticket.resolved, ticket.closed).

Her webhook teslimatı üç güvenlik başlığı içerir: X-Webhook-Signature (HMAC-SHA256 onaltılık özet), X-Webhook-Timestamp (Unix zaman damgası) ve X-Webhook-ID (uç nokta tanımlayıcısı). İmza, zaman damgasını ve gövdeyi birlikte kapsar (HMAC-SHA256(gizli, zaman damgası + '.' + gövde) olarak hesaplanır) ve hem kurcalama hem de yeniden oynatma saldırılarını önler. İmzayı doğrulamalı ve zaman damgası 5 dakikadan eski olan istekleri reddetmelisiniz. İmzalama sırrı, webhook uç noktasını oluşturduğunuzda oluşturulur ve bir kez görüntülenir; bunu güvenli bir şekilde saklayın.

Magicgate başarısız webhook teslimatlarını yeniden dener. Uç noktanız 2xx olmayan bir durum kodu döndürürse veya 10 saniye içinde yanıt vermezse teslimat yeniden denenir. Tüm yeniden denemeler bittikten sonra olay başarısız olarak işaretlenir ve uç noktanın başarısızlık sayısı artırılır.

Webhook verileri şu yapıya sahip JSON kodludur: { id, event, timestamp, data }. 'Olay' alanı, olay türü dizesini (örneğin, 'domain.verified') içerir, 'id', zaman aşımı için benzersiz bir teslimat kimliğidir, 'zaman damgası', ISO 8601 tarih saattir ve 'veri', etkinliğe özgü ayrıntıları içerir.

Hesap başına, her biri farklı etkinlik türlerine abone olan birden fazla webhook uç noktası yapılandırabilirsiniz. Bu, örneğin etki alanı olaylarını dağıtım hattınıza ve faturalama olaylarını muhasebe sisteminize yönlendirmenize olanak tanır.

Magicgate, cüzdan tabanlı bir faturalandırma modeli kullanır. Kripto para yatırma yoluyla cüzdanınıza para eklersiniz ve aboneliğiniz her faturalandırma döngüsünde cüzdan bakiyenizden otomatik olarak yenilenir. Bu, yinelenen kart ücreti ihtiyacını ortadan kaldırır ve harcamalarınız üzerinde tam kontrol sağlar.

Üç ödeme sağlayıcısı desteklenmektedir: CCPayment, NowPayments ve TransVoucher. Her sağlayıcı Bitcoin, Ethereum, USDT, USDC ve 50'den fazla ek kripto para birimini destekler. Para yatırma işlemini başlattığınızda bir ödeme adresi ve tutarı oluşturulur. Blockchain işlemi onayladıktan sonra cüzdan bakiyeniz otomatik olarak güncellenir.

Planlar özellik sınırlarınızı belirler: aylık kontroller, akış sayısı, akış başına kurallar, API erişimi, özel alanlar ve daha fazlası. Mevcut planları kimlik doğrulaması olmadan görüntüleyebilirsiniz. Yükseltme veya düşürme hemen geçerli olur; cari döneme ait kullanılmayan bakiye eşit olarak dağıtılır ve cüzdanınıza geri yatırılır.

Abonelikler aylık veya yıllık olabilir. Yıllık aboneliklerde indirim sunulur. İstediğiniz zaman iptal edebilirsiniz; abonelik, geçerli fatura döneminin sonuna kadar etkin kalır. İptal edilen bir aboneliğin devam ettirilmesi, yeni bir aboneliğin oluşturulmasına gerek kalmadan aboneliğin geri yüklenmesini sağlar.

M-cüzdan tüm işlemleri izler: para yatırma, abonelik ücretleri, geri ödemeler ve eşit dağıtılan krediler. Her işlem, onu kaynak etkinliğe (para yatırma, abonelik yenileme, plan değişikliği vb.) bağlayan bir referans türü ve kimlik içerir.

Magicgate kontrol paneli, trafik akışlarını yönetmek, analizleri izlemek ve hesap ayarlarını yapılandırmak için merkezi kontrol panelinizdir. Giriş yaptıktan sonra hesabınızın önemli ölçümlerinin bir özetini gösteren Genel Bakış sayfasına yönlendirilirsiniz.

Genel Bakış sayfası, işlenen toplam çekleri, karar dağıtımını (teklif ve beyaz), etkin akışları ve son etkinlikleri görüntüler. Zaman serisi grafiği, son 24 saat, 7 gün veya 30 gün içindeki trafik hacmini gösterir. Bu size trafik sağlığınız ve filtreleme etkinliğiniz hakkında anında fikir verir.

Akışlar bölümü, trafik akışlarını oluşturduğunuz ve yönettiğiniz yerdir. Her akış, bir dizi filtre, bir teklif sayfası URL'si, bir beyaz sayfa URL'si ve entegrasyon ayarları (API Mode veya Direct Mode) olmak üzere farklı bir filtreleme yapılandırmasını temsil eder. Farklı kampanyalar, açılış sayfaları veya trafik kaynakları için birden fazla akışınız olabilir.

Her akışın ayrıntılı görünümünde akış başına analizleri görebilirsiniz: toplam kontroller, karar dökümü, filtre isabet oranları, coğrafi dağılım ve en çok yönlendirenler. Bu ayrıntılı veriler, her bir kampanya için filtre ayarlarını optimize etmenize yardımcı olur.

Analitik bölümü, tüm akışlara ilişkin kapsamlı bir görünüm sağlar. Grafikler, zaman içindeki karar eğilimlerini, filtre etkinliğini (hangi filtreler en sık tetiklenir), trafiğin kaynağını gösteren coğrafi ısı haritalarını, cihaz ve tarayıcı arızalarını ve saatlik trafik modellerini içerir. Tüm grafikler tarih aralığı filtrelemeyi ve akışa özel filtrelemeyi destekler.

Etki Alanları bölümünde tüm yapılandırılmış etki alanları (paylaşılan ve özel) listelenir. Her alan adı için durumunu (etkin, doğrulama bekleniyor, DNS hatası), SSL sertifikası durumunu ve ilgili akışları görebilirsiniz. Alan adı sağlık kontrolleri otomatik olarak çalıştırılır ve DNS veya SSL sorunları tespit edilirse sizi uyarır.

Ayarlar bölümü hesap çapında yapılandırmayı içerir. API Anahtarları: isteğe bağlı son kullanma tarihleriyle API key'ler oluşturun ve yönetin. Webhooks: webhook uç noktalarını yapılandırın ve dağıtım günlüklerini görüntüleyin. Sağlayıcılar: ödeme ve DNS sağlayıcılarını ekleyin ve yönetin. Faturalandırma: Cüzdan bakiyesini, yükleme geçmişini ve abonelik durumunu görüntüleyin. Ekip: Rol tabanlı erişime sahip ekip üyelerini (kullanıcı, yönetici) davet edin.

Kontrol paneli, sağ üst köşedeki tema geçişiyle hem açık hem de koyu temaları destekler. Tüm sayfalar duyarlıdır ve mobil cihazlarda çalışır; ancak masaüstü deneyimi en kapsamlı veri görünümlerini sağlar.