Tek API. Üç kanal.

PushLuyo ve eski entegrasyonlar

Platform adresi https://pushluyo.com oldu. Yeni kodlarda window.PushLuyo kullanın; window.PushDesk aynı SDK için geriye uyumlu kalır. Mevcut pushdesk:* olay adları, API anahtarı/oturum kimlikleri ve DNS kanıtı _pushdesk / pushdesk-verification değişmez. WordPress eklentisinin görünen adı PushLuyo olur; teknik klasörü/slug'ı pushdesk ve mevcut seçenek/meta anahtarları korunur. Müşteri sitelerinin proje origin'leri ve kaydedilmiş ayarlar marka değişimi nedeniyle sıfırlanmaz.

1. Web entegrasyonu

SDK kodunu kendi sitenize ekleyin. Panelden indirdiğiniz push-sw.js dosyasını o sitenin kök dizinine yerleştirin. HTTPS kullanın. İzin penceresi abone ol düğmesine basıldığında açılır. Yerel testte localhost kullanılabilir.

<script src="https://pushluyo.com/sdk.js"
  data-site="PROJE_KIMLIGI" defer></script>
<button type="button" id="push-subscribe">Bildirimlere abone ol</button>
<button type="button" id="push-unsubscribe">Aboneliği kapat</button>

Siteye özel izin kartı

Panelde İzin kartı ekranından marka adını, HTTPS logo adresini, başlığı, açıklamayı, düğme metinlerini, rengi, köşeleri ve konumu düzenleyin. Görünme gecikmesi ve erteleme süresi de proje bazında kaydedilir. Yeni projelerde kart açık oluşturulur; mevcut projenizin kaydedilmiş açık/kapalı seçimi korunur. Gerekirse etkinleştirip kaydedin. SDK en geç yaklaşık 60 saniyelik önbellek süresinden sonra yeni sayfa yüklemelerinde ayarları alır. Siteye kodu yeniden eklemek gerekmez.

İzin kartı otomatik gösterilse de tarayıcının bildirim izni yalnız ziyaretçinin onay düğmesine basmasıyla istenir. Abone olanlara ve tarayıcıda izni reddedenlere kart gösterilmez. Erteleme kaydı ilgili site ve tarayıcıda tutulur; tarayıcı depolaması kapalıysa sayfalar arasında hatırlanamaz. Kendi düğmenizi kullanmak için SDK etiketine data-prompt="off" ekleyebilirsiniz.

Sitenizde Content-Security-Policy kullanıyorsanız platform adresini script-src, style-src ve connect-src kurallarına; logo adresini img-src kuralına ekleyin. Logo dosyanız dışarıdan erişilebilen HTTPS adresinde olmalıdır; sunucu logoyu indirmez. Önizleme ve ziyaretçi kartı aynı oluşturucuyu kullanır. Bu tasarım sistem bildirimlerini veya tarayıcının yerleşik izin penceresini değiştirmez.

Mevcut service worker varsa

Mevcut dosyanın üzerine yazmayın. push-sw.js içindeki push ve notificationclick dinleyicilerini mevcut service worker dosyanıza ekleyin. SDK etiketine data-worker="/mevcut-sw.js" ekleyin. Bu sürüm kök scope kullanır; worker dosyası kökte olmalıdır. Çakışan mevcut push dinleyicilerini uygulamanıza göre birleştirin.

Hata ve sonuç olayları

window.addEventListener('pushdesk:subscribed', event => {
  console.log('Abonelik kimliği:', event.detail.id);
});
window.addEventListener('pushdesk:error', event => {
  // Kendi arayüzünüzde ziyaretçiye gösterin.
  console.error(event.detail.message);
});

Abonelik anahtarları, endpoint ve mobil token değerleri gizli kabul edilmelidir. Web SDK'da API anahtarı bulunmaz. Her alt alan adı ayrı proje olarak kaydedilir. Safari/iOS Web Push, cihaz ve tarayıcı koşullarına bağlıdır; iOS ana ekran web uygulaması şartlarını resmi belgelerden kontrol edin.

2. Sunucu API'si

API anahtarı yalnızca ait olduğu projeye erişir. Anahtarı Proje ayarları ekranında oluşturun. Tüm sunucu isteklerinde bu başlıkları kullanın:

Authorization: Bearer pd_SUNUCU_ANAHTARI
Content-Type: application/json

Bildirim oluşturma

POST /v1/notifications
Idempotency-Key: siparis-123-hazir

{
  "title": "Siparişiniz hazır",
  "body": "Paketiniz yola çıkmaya hazır.",
  "url": "https://magazam.com/siparisler/123",
  "channels": ["web", "android", "ios"],
  "ttl_seconds": 86400
}

Aynı iş olayı için aynı Idempotency-Key kullanın (8–128 karakter). Aynı anahtar ve içerik aynı kampanyayı döndürür; değişen içerik 409 döndürür. Yanıt 202'dir ve id, total, accepted, failed, pending, cancelled, duplicate alanlarını içerir. HTTP 202, kuyruğa alındığını gösterir. Hedef cihaz listesi oluşturma anında sabitlenir. Sonradan abone olanlara önceki planlı kampanya gönderilmez.

İsteğe bağlı scheduled_at ISO 8601 zamanıdır; en çok 30 gün sonrası kabul edilir. ttl_seconds 60–604800 arasındadır ve planlanan andan başlar. external_ids: ["kullanici-123"] yalnızca eşleşen mobil cihazları seçer. Alanı göndermemek seçili kanalların tüm aktif abonelerini hedefler. Bildirim bağlantısı projenizin alan adında olmalıdır.

Mobil cihaz kaydı

POST /v1/devices
{
  "channel": "android",
  "token": "FIREBASE_FCM_TOKEN",
  "external_id": "kullanici-123"
}

iOS için channel: "ios" kullanın; APNs cihaz token'ı yerine Firebase FCM token gönderin. Token yenilendiğinde yeniden kaydedin ve eski cihaz kaydını pasife alın. Çıkışta DELETE /v1/devices/{id} çağrısı yapın. Uygulamanızdaki kullanıcı oturumunu kendi sunucunuz doğrulamalı; external_id değerini doğrulanmış kullanıcıdan türetmelidir. Uygulamanın içine PushLuyo API anahtarı gömmeyin.

Hatalar ve limitler

400 doğrulama; 401 oturum/anahtar; 403 yetki/kaynak; 404 kayıt bulunamadı; 409 çakışma/eksik yapılandırma; 413 gövde boyutu; 429 istek limiti. Hatalar error ve request_id içerir. Hesap başına 300 istek/dakika; proje başına 30 kampanya/dakika; web kayıt IP/proje başına 120 istek/dakika. Kayıt/giriş IP başına 12 istek/15 dakika. Gövdeler en fazla 64 KB.

3. Android ve iOS kurulumu

Firebase projenize uygulamalarınızı kaydedin. Android için google-services.json, iOS için GoogleService-Info.plist ve Firebase Messaging SDK'sını ekleyin. iOS uygulamanızın Push Notifications capability ve ilgili Background Modes ayarlarını yapın; Firebase konsoluna APNs .p8 anahtarını bağlayın. Android 13+ bildirim iznini isteyin. iOS'ta izin isteyin ve APNs kaydının tamamlanmasını bekleyin.

Firebase Cloud Messaging HTTP v1 API etkin olmalıdır. Sunucu service account dosyasının gönderim yetkisi olmalıdır. Bir PushLuyo projesi bir Firebase projesine bağlanır. Farklı Firebase projeleri için ayrı PushLuyo projesi açın. Ön planda mesaj gösterimi ve bildirim tıklamasıyla uygulama yönlendirmesi mobil uygulamanızda uygulanır. Kaynak paketinde Flutter ve sunucu bağlantı örnekleri vardır.

Mesaj şablonları

Panelde yeni bir mesaj hazırlayıp Şablon olarak kaydet formuyla saklayabilirsiniz. Şablonlar menüsünden Kullan veya Düzenle ile açın. Mesaj, bağlantı, kanallar, kategori seçimi ve geçerlilik süresi saklanır; planlanan tarih saklanmaz. Kaydetmek veya uygulamak bildirim göndermez. Kampanya göndermek için gönderim düğmesine ayrıca basmanız gerekir. Şablonlar proje bazında özel tutulur, arşivden geri alınabilir ve arşiv dahil 100 kayıtla sınırlıdır. Sunucu API anahtarları bu panel kayıtlarına erişemez.

Kategori bazlı abonelik ve alıcı kontrolü

İzin kartı ekranında kategori adı ve sabit API kodu tanımlayın (örneğin Son dakika / son-dakika). Kod değişirse önceki aboneliklerle eşleşmez; yalnız görünen adı değiştirebilirsiniz. Kartta ziyaretçi konularını seçer. Sonradan tercihlerini değiştirmesi için sitenize şu düğmeyi ekleyin:

<button type="button" id="push-preferences">Bildirim tercihleri</button>

Özel arayüzde PushLuyo.subscribe({topics: ["spor"]}) veya PushLuyo.preferences() kullanın. Gerçek tarayıcı izin isteği ziyaretçinin tıklamasından başlatılmalıdır. Sayfa yenilenmesi mevcut kategori tercihlerini silmez. Mobil cihaz kayıt API’si de topics kabul eder. Alanın gönderilmemesi mevcut tercihleri korur, boş dizi kategori tercihlerini temizler.

POST /v1/notifications/estimate
Authorization: Bearer SUNUCU_API_ANAHTARI
Content-Type: application/json

{"channels":["web"],"topics":["spor","son-dakika"]}

Bu istek gönderim yapmaz. Sonuç toplam ve kanal bazında alıcı sayısıdır; gönderim anına kadar değişebilir. Kategori kodlarını GET /v1/topics ile okuyabilirsiniz. Aynı konular POST /v1/notifications isteğine eklenir. Birden fazla kategori VEYA, kanal ve external_ids filtreleri VE ilişkisiyle uygulanır. Birden fazla kategoriye abone olan cihaz tek kez sayılır. API anahtarı yalnız kendi projesini hedefleyebilir.

Kategori filtresi yoksa genel duyuru tüm seçili kanallardaki aktif abonelere gider; ziyaretçi kartında bu bilgi gösterilir. Belirli kategoriye hedeflenen bir gönderim kuyruğa alındıktan sonra ziyaretçi o kategoriden çıkarsa, worker göndermeden önce tercihi yeniden kontrol edip kaydı TOPIC_OPT_OUT olarak iptal eder. Başlamış sağlayıcı isteği geri alınamaz.

4. Güvenilirlik ve sınırlar

PostgreSQL tabanlı kalıcı kuyruk, atomik kampanya oluşturma, işçi kilidi, 2 dakikalık lease, 30 saniyelik lease yenileme, artan bekleme ve en fazla 8 deneme uygulanır. 429/5xx/ağ hataları yeniden denenir. Geçersiz Web Push abonelikleri ve FCM UNREGISTERED cihazları pasife alınır. Sağlayıcı Retry-After süresi dikkate alınır.

accepted, push sağlayıcısının isteği kabul etmesidir. Cihazda görülme veya okunma ölçümü yoktur. Worker sağlayıcıya gönderip veritabanına yazamadan kapanırsa tekrar gönderim olabilir; sistem en az bir kez deneme semantiğindedir. Web bildirim tag ve mobil collapse değerleri yinelenen görünümü azaltır, tam tekillik garantisi vermez. İşleme girmiş bir isteği iptal etmek her zaman mümkün değildir.

Bu sürüm pilot kurulum içindir. Alan adı doğrulaması, kullanım sınırları ve hesap güvenliği akışları aşağıda açıklanır; canlı SMTP henüz etkin değildir. Ücretli abonelik paketleri, ekip rolleri, kullanıcı arayüzünden toplu veri silme, cihaz teslimi/okunma analitiği ve yüksek erişilebilirlik kurulumu kapsam dışındadır. Gerçek cihaz kabulü ve temsilî yük testleri ayrıca yapılmalıdır.

WordPress eklentisi

Kurulabilir WordPress ZIP dosyasını indir

WordPress 6.4+ ve PHP 7.4+ gerektirir. Eklentiler → Yeni eklenti ekle → Eklenti yükle ile ZIP dosyasını yükleyin. Ayarlar → PushLuyo bölümüne bu sitenin proje kimliğini ve sunucu API anahtarını girin. Anahtar ziyaretçiye gönderilmez; WordPress veritabanında saklanır. Bağlantıyı kontrol et düğmesi proje kimliğini ve site adresini doğrular, bildirim göndermez.

Site bağlantısını açtıktan sonra izin kartını PushLuyo panelinde özelleştirin ve etkinleştirin. Yazı editöründe Push bildirimi → Bu haberi push bildirimi olarak gönder seçeneğini işaretleyin. İlk yayımlama, web aboneleri için bir kampanya oluşturur. Blok editörü ve klasik editör desteklenir. Varsayılan seçim ayarlardan değiştirilebilir; başlangıçta kapalıdır. Düzenleme veya yeniden yayımlama mevcut işi tekrar oluşturmaz. Yazı ilk yayımlandığında seçilmediyse sonradan bu seçenekle gönderim yapılmaz; panelden ayrı bir bildirim oluşturabilirsiniz.

WordPress zamanlayıcısı site trafiğine bağlıdır; düzenli sunucu zamanlayıcısı önerilir. İstek içeriği ilk yayımlamada sabitlenir ve tekrar denemelerde aynı Idempotency-Key kullanılır. Geçici hatalar 10, 20, 40, 80, 160 dakika aralıklarla en fazla 5 kez yeniden denenir. Mevcut PWA/service worker varsa geliştiricinizle birleştirin. HTTPS, doğru proje adresi ve tarayıcı izni gerekir. Eklenti müşteri sitesine kendiliğinden kurulmaz.

Hedef takibi ve analiz

Hedefler ve analiz ekranından bu proje için analizi açıp hedef adı ve sabit API kodunu tanımlayın. En fazla 30 hedef vardır. Analiz başlangıçta kapalıdır ve yalnız sonradan oluşturulan kampanyalar izlenir. Eski bildirimlere geriye dönük izleme eklenmez.

window.PushLuyo.track('haber_okundu').catch(console.warn);

Çağrıyı gerçek hedef gerçekleştiğinde yapın; örneğin okuma tamamlandığında veya üyelik başarıyla oluştuğunda. Sıradan ziyaretçileri değil, bildirimle ilişkilendirilmiş ziyaretleri sayar. Web açma URL’sindeki pd_click parametresi SDK tarafından temizlenir, ilişkilendirme sekmenin sessionStorage alanında en fazla 24 saat tutulur. İzlemeyi kapatmak yeni olayların kabulünü durdurur. Olay kayıtları 90 gün sonra temizlenir. Hesaplar arasında olay aktarılmaz. Bildirimdeki kod, kampanyanın geçerlilik süresinden 7 gün sonra sona erer. Kodu kimlik doğrulama veya ödeme kanıtı olarak kullanmayın. Site bilgilendirme ve izin mekanizmanıza analizi dahil edin.

GET /v1/project
GET /v1/goals
GET /v1/analytics
POST /v1/events
Authorization: Bearer SUNUCU_API_ANAHTARI
Content-Type: application/json

{"type":"conversion","goal":"haber_okundu","token":"BILDIRIMDEKI_TRACKING_TOKEN"}

Mobil bildirim verisindeki tracking_token değerini uygulamanız tıklama veya hedef gerçekleştiğinde kendi sunucunuza iletir. Sunucunuz doğrulanmış işlemden sonra /v1/events çağırır. Anahtarı mobil uygulamaya gömmeyin. Aynı bildirim/olay/hedef tekrarları tek kayıt sayılır. Bildirim başına bir hedef bir kez ölçülür; sipariş cirosu veya ayrı satın alma sayısı ölçülmez. Browser olayları kullanıcı tarafından üretilebilir; finansal veya güvenlik kaydı değildir.

Tıklama, güncel worker tarafından gözlenen bildirim açma eylemidir. Ziyaret, sayfada SDK çalıştığında kaydedilir. Hedef, kodunuzun bildirdiği eylemdir. Dönüşüm yüzdesi, ziyaret kaydı bulunan bildirimlerden en az bir hedefe ulaşanların payıdır. Engel yazılımları ve ağ sorunları eksik ölçüme yol açabilir. Sağlayıcı kabulü cihazda teslim veya okunma garantisi değildir. Kampanya raporu son 30 günde oluşturulan en yeni 200 kampanyayı; hedef toplamları bu 30 günde oluşturulan tüm kampanyaları kapsar. Güncel SDK ve worker gerekir; mevcut kurulumlardaki worker dosyasını güncelleyin.

İzin kartının görünmesini kontrol etme

Yeni projelerde izin kartı başlangıçta açıktır; mevcut projelerde kaydettiğiniz tercih korunur. Entegrasyon ekranında açık/kapalı durumunu görün. SDK ve service worker müşteri sitesinde bulunmalıdır. Paneldeki önizleme, müşteri sitesine kurulum yapılmış olduğu anlamına gelmez.

Kart; desteklenen HTTPS tarayıcıda, yeni ziyaretçiye, ayarladığınız gecikmeden sonra çıkar. Önceden abone olanlara, tarayıcıda bildirimi engellemiş olanlara, “Şimdi değil” süresi dolmayanlara veya özel arayüz için data-prompt="off" kullanılan sayfalara otomatik çıkmaz. Ziyaretçi tercihler düğmesiyle kartı tekrar açabilir; engellenmiş tarayıcı iznini önce kendisi değiştirmelidir. iPhone/iPad için desteklenen sürümde Ana Ekrana eklenen web uygulaması gerekebilir.

await window.PushLuyo.ready;
console.log(window.PushLuyo.status());
// prompt: shown / scheduled / disabled / snoozed / already_subscribed
// permission_denied / unsupported / custom_ui / renderer_error
// worker: idle / loading / ready / failed

window.addEventListener('pushdesk:error', e => console.warn(e.detail));
// Ziyaretçinin düğmesine bağlayın:
window.PushLuyo.showPrompt();

Aynı tarayıcıdaki aboneliğin VAPID anahtarı başka projeye aitse otomatik olarak içeri alınmaz. Mevcut PWA worker dosyası sessizce değiştirilmez. Kartın görünmesi bağlantının tüm parçalarının sağlıklı olduğunu kanıtlamaz; status worker ve subscription alanlarını da kontrol edin. Gerçek cihazda tarayıcı/işletim sistemi bildiriminin görünmesi ayrıca test edilmelidir. WordPress bağlantı kontrolü API anahtarı, proje adresi ve son kontrol anındaki kart tercihini doğrular; tema, CSP ve tarayıcı izinleri için siteyi açıp kontrol edin.

Şehir, ülke ve IP analizi

Analiz açıkken bildirimden gelen yeni web ziyaretlerinin IP’si ve yaklaşık şehri kaydedilir. Sadece yetkili proje hesabı ve sunucu API anahtarı raporu okuyabilir. IP alanı veritabanında şifrelidir, olaylarla birlikte en fazla 90 gün saklanır. Eski kayıtlara geriye dönük IP eklenmez. Tekrar eden aynı ziyaret kaydı ilk IP/konum bilgisini değiştirmez. Tarayıcının gövdeye yazdığı IP/şehir alanları kullanılmaz.

Konum sorgusu sunucuda tutulan DB-IP City Lite veritabanıyla yapılır. Ziyaretçi IP’si konum sorgusu için dış servise gönderilmez. VPN, mobil operatör ve veri kapsamı nedeniyle konum yaklaşık veya bilinmiyor olabilir. Bu alanları ziyaretçi bilgilendirme/izin akışınıza dahil edin. Mobil sunucu olaylarında cihazın IP’si kendiliğinden çıkarılamaz; mevcut sunucu olayları IP’siz kalır.

GET /v1/analytics/locations
Authorization: Bearer SUNUCU_API_ANAHTARI

Yanıt cities içinde son 30 günün şehir/ülke bazlı ziyaret kayıt sayılarını; recent içinde en yeni 100 ziyaretin kampanya başlığı, IP, şehir/ülke, kaynak ve zamanını içerir. Bu rakamlar tekil kişi sayısı değildir. IP’siz kayıtlar da sayılır.

IP Geolocation by DB-IP · CC BY 4.0

Grafikler ve canlı takip

Hedefler ve analiz ekranında 7, 30 veya 90 günlük dönem seçebilirsiniz. Günlük grafikler UTC tarihleriyle hesaplanır. Aktif abone ve tarayıcı/kanal dağılımı güncel kitlenizi; kabul, tıklama, ziyaret ve hedef sayaçları seçilen dönemdeki gerçek olayları gösterir. Kampanya tablosu, seçilen dönemde oluşturulan son 50 kampanyayı ve sonuçlarını gösterir.

Canlı mod açıkken görünür analiz ekranı yaklaşık 5 saniyede bir güncellenir. Sekme gizlenince veya başka ekrana geçilince canlı sorgular durur. Modu kapatıp elle de yenileyebilirsiniz. Bağlantı hatasında son kayıtlı görünüm korunur ve son güncelleme durumu gösterilir. Hedef ayarları formundaki kaydedilmemiş değişiklikler canlı yenilemeyle ezilmez.

GET /v1/analytics/dashboard?days=30
Authorization: Bearer SUNUCU_API_ANAHTARI

Tarayıcı sınıfı yeni/yenilenen web aboneliği isteğinin User-Agent başlığından yalnız Chrome, Safari, Firefox, Edge, Opera, Other veya Unknown olarak türetilir. Ham User-Agent saklanmaz; geçmiş kayıtlarda bilinmiyor görünür. Kanal dağılımı web/Android/iOS bağlantılarını gösterir; web abonelerinin masaüstü veya telefon türü ayrıca ölçülmez. Gerçek cihaz teslimi veya okunma sayacı yoktur.

İzin kartı biçimleri ve gösterim kuralları

İzin kartı ekranında klasik, oval, baloncuk, kıvrımlı veya kapsül biçim seçebilirsiniz. Açık/koyu/otomatik tema, rahat/kompakt görünüm, dolu/çerçeveli düğme ve metin hizalaması da proje bazında kaydedilir. Klasik biçimde köşe değeri elle ayarlanabilir. Biçim değiştirmek logo, renk ve metinlerinizi silmez. İçerik uzadığında kart yüksekliği büyür; metni kesen sabit yuvarlak bir çerçeve kullanılmaz.

Gösterilecek ve hariç tutulacak yolları her satıra bir yol olacak şekilde yazın. /haber, /haber ve /haber/... alt yollarını kapsar; /haberler ile eşleşmez. / bütün yolları kapsar. Hariç tutma önceliklidir. Boş dahil listesi tüm yolları kapsar. Her listede en fazla 20 yol bulunabilir. Sorgu parametresi, düzenli ifade veya joker karakter kullanılmaz. Mobil/masaüstü seçimi tarayıcı genişliğine göre yapılır (767 piksel ve altı mobil).

Yüzen bildirim düğmesini açarsanız ziyaretçi ertelediği veya zaten abone olduğu kartı kendi isteğiyle yeniden açabilir. Düğme daire veya kapsül olabilir, metni ve alt köşe konumu değiştirilebilir. Tarayıcıda izin engelliyse düğme açıklama gösterir; engeli kendiliğinden kaldıramaz. Otomatik kart ve yüzen düğme, sayfa/cihaz kurallarına ve kapalı kart/özel arayüz tercihlerine uyar. Ziyaretçinin özel tercihler düğmesine tıklamasıyla açılan kart sayfa ve erteleme kurallarını geçebilir; tarayıcı izni kısıtları devam eder.

// Kendi SPA yönlendirmelerinizden veya ayar değişikliğinden sonra:
await window.PushLuyo.refresh();
console.log(window.PushLuyo.status());

Raporları dışa aktarma

Analiz ekranındaki CSV seçimiyle seçili dönemin en son 50 kampanyasının sonuçlarını, sabit son 30 günün şehir dağılımını veya son 100 ziyaret kaydını indirebilirsiniz. Ziyaret raporu IP içerir; kendi veri paylaşım kurallarınız doğrultusunda saklayın. Dışa aktarma yalnız o anda yetkili olduğunuz projenin son başarılı raporunu kullanır; proje değiştirince önceki rapor temizlenir. Türkçe karakterler için UTF-8 ve Excel uyumlu noktalı virgül ayıracı kullanılır. Kullanıcı metinleri elektronik tablo formülü olarak çalıştırılmaz.

API anahtarı yetkileri ve süreleri

Proje ayarlarında anahtara en fazla 80 karakterlik bir ad, işlem yetkileri ve isteğe bağlı son kullanma tarihi verebilirsiniz. Tarih gelecekte ve en fazla 365 gün sonra olmalıdır; boş bırakılırsa süresizdir. Bir projede en fazla 50 etkin anahtar bulunur; listede en yeni 100 geçmiş kayıt gösterilir. Anahtar yalnız oluşturulurken tam görünür, sonrasında yalnız öneki ve ayarları listelenir. Eski anahtarların mevcut tüm yetkileri korunur. Yeni anahtarda yetkileri özellikle seçmezseniz yedi yetkinin tamamı tanımlanır.

Eksik, iptal edilmiş veya süresi dolmuş anahtar HTTP 401; geçerli anahtarın yetkisi yetersizse HTTP 403 döndürür. OpenAPI içindeki x-required-scope her işlemin gereken yetkisini belirtir. WordPress'te yayın bildirimi için en az project:read ve notifications:write gerekir. API anahtarını tarayıcıya veya mobil uygulamaya koymayın.

Abone listesi ve yönetim engeli

GET /v1/devices?status=active&channel=all&query=okur&limit=25
Authorization: Bearer SUNUCU_API_ANAHTARI

Durum filtresi active, inactive, blocked veya all; kanal all, web, android veya ios olabilir. Varsayılan durum active, kanal all ve sayfa boyutu 25'tir. Sayfa boyutu 1–100 arasında olmalıdır. query en fazla 100 karakterdir; dış kullanıcı kimliğinde büyük/küçük harf duyarsız düz metin araması yapar. Tam UUID yazılırsa abonelik kimliğiyle de eşleşir. % ve _ joker olarak çalışmaz. Yanıt items, next_cursor, proje geneli totals ve uygulanan filters alanlarını içerir. Inactive, engellenmiş kayıtları da kapsar; blocked bunun yönetim engeli bulunan alt kümesidir.

Sonraki sayfa için next_cursor değerini değiştirmeden cursor parametresine verin. Kod aynı proje, durum, kanal ve arama metni içindir; filtre değiştiğinde kodu sıfırlayın. Yanlış veya başka filtreye ait kod HTTP 400 döndürür. Liste yeni kayıttan eskiye sıralanır. Token, endpoint, IP, özel anahtar ve şifreli ham cihaz içeriği listelenmez.

POST /v1/devices/ABONELIK_UUID/block
POST /v1/devices/ABONELIK_UUID/unblock
Authorization: Bearer SUNUCU_API_ANAHTARI

Engelleme kaydı pasife alır ve SDK/mobil kayıt yenilense de engeli korur. Engel kaldırma daha önce engellenmiş kaydı kendiliğinden aktif yapmaz; yeniden istemci kaydı gerekir. Bu işlem tarayıcı iznini değiştirmez. DELETE /v1/devices/{id} ise olağan pasife alma işlemidir; engellenmemiş kayıt sonraki istemci kaydıyla yeniden aktif olabilir. Başka projeye ait veya bulunamayan abonelik için HTTP 404 alınır. İşlem gerçek bildirim göndermez.

Servis durumu ve gönderim detayı

GET /v1/health
GET /v1/notifications/KAMPANYA_UUID/detail
Authorization: Bearer SUNUCU_API_ANAHTARI

Servis ekranı görünürken yaklaşık 10 saniyede bir proje durumunu yeniler. worker.active son 45 saniyelik genel işçi yaşam sinyalidir. queue.pending gelecekte planlanan işleri de içerir; processing sağlayıcı işlemi süren kayıtlardır; retrying, daha önce denenmiş pending kayıtlarının alt kümesidir. accepted_24h ve failed_24h son 24 saatte güncellenen ilgili durumları, eski kampanyalar dahil sayar. overdue_count yalnız gönderim zamanı gelmiş pending işlerdir; oldest_pending_at bu grubun en eski zamanıdır. Kanal dağılımı ve yapılandırma hazırlığı ayrıca gösterilir. Hazır anahtar veya Firebase kaydı sağlayıcı bağlantı testi değildir.

Detay, mesajı, oluşturulma/planlanma/geçerlilik zamanlarını, hedef seçimlerini, ayrı durum ve kanal toplamlarını, gözlenen tıklama/ziyaret/hedef kayıtlarını ve en yeni 100 temizlenmiş hata kaydını döndürür. Hatalarda beklenmeyen ham metin PROVIDER_ERROR olarak gösterilir. Cihaz adresi, token, ziyaretçi IP'si veya özel hesap bilgisi içermez. Kabul edilen kayıt sayısı cihaz teslimi veya okunma sayısı değildir.

Yeni kampanyalarda targeting_recorded=true ile özgün kanallar ve dış kullanıcı filtresi saklanır. Eski kayıtlarda targeting_recorded=false olur; kanal listesi mevcut alıcılardan çıkarılabilir ve tam hedef seçimi bilinmeyebilir. Taslak olarak kopyala yalnız düzenleme formunu doldurur, gönderim oluşturmaz; eski kaydı kopyalarken hedef kitleyi yeniden seçin. Panelde gönderimden önce mesajı, güncel alıcı tahminini ve zamanı ayrı inceleyip son gönderim adımını onaylayın. API'de POST /v1/notifications doğrudan gönderim/zamanlama işlemidir; GET detay veya POST tahmin kampanya oluşturmaz.

Kuyruktaki alıcı kaydı, cihazın kayıt nesliyle eşleştirilir. Kimlik değiştiğinde veya yeni bir abonelik döngüsü başladığında eski iş RECIPIENT_CHANGED ile iptal edilir; önceki kimliğe ait kuyruk yeni kimliğe taşınmaz. Tercih ve iptal kontrolü gönderimden hemen önce yapılır. Sağlayıcı isteği başlamışsa geri çağırmak mümkün değildir.

İzin kartında üst alan renkleri

Logo ve marka başlığının bulunduğu üst alanın arka planı, marka/düğme renginden bağımsız ayarlanabilir. header_background ve header_text_color boş ya da altı haneli HEX renk olmalıdır. Arka plan seçili, yazı rengi otomatikken okunabilir siyah/beyaz renk hesaplanır. Yazı rengini ayrıca seçerseniz bu seçim kullanılır. İki alan da otomatik olduğunda temanın önceki görünümü korunur. Değişiklik yalnız üst alanı etkiler; logo, içerik ve onay düğmesi rengi değiştirilmez.

Hesap güvenliği ve iki aşamalı giriş

Hesap güvenliği panel oturumuyla yönetilir; aşağıdaki /api/account ve proje koruması uçları bearer API anahtarı kabul etmez. POST isteklerinin Origin değeri platformun APP_URL adresiyle eşleşmelidir. Normal giriş HTTP 200 ile hesap bilgisi ve HttpOnly pd_session çerezi döndürür; JSON içinde oturum token'ı verilmez.

POST /auth/login
{"email":"[email protected]","password":"MEVCUT_PAROLANIZ"}

// TOTP açıkken: HTTP 202; henüz oturum çerezi oluşturulmaz.
{"requires_2fa":true,"challenge":"GECICI_GIRIS_KODU","expires_in":300}

POST /auth/totp-login
{"challenge":"GECICI_GIRIS_KODU","code":"UYGULAMADAKI_6_HANELI_KOD"}
// Başarı: HTTP 200 + pd_session çerezi.

İkinci adımda tek kullanımlık kurtarma kodu da kullanılabilir. Giriş challenge'ı 5 dakika geçerlidir ve en fazla 5 hatalı faktör denemesi kabul eder; yeniden giriş önceki challenge'ı değiştirir. E-posta doğrulaması bekleyen hesapta giriş/kayıt 202 ile verification_required:true dönebilir. Bu yanıtlar giriş başarısı olarak işlenmemelidir.

Onay, kapatma ve kurtarma kodlarını yenileme diğer oturumları iptal eder. TOTP sırrını/URI'yi ve bir kez dönen kurtarma kodlarını loglamayın, analiz sistemine veya sohbete göndermeyin. Parola yenilemek TOTP'yi kapatmaz.

Otomatik e-posta durumu

Canlı SMTP şu anda etkin değildir. Otomatik e-posta doğrulaması ve parola yenileme e-postası gönderilmez. mail.configured yalnız sunucu yapılandırmasını gösterir; posta teslim kanıtı değildir. SMTP kapalıyken mevcut giriş çalışır, yeni hesaplar e-posta doğrulaması nedeniyle kilitlenmez.

POST /auth/forgot-password       {"email":"[email protected]"}
POST /auth/resend-verification   {"email":"[email protected]"}
// SMTP kapalıyken HTTP 200: ok:false, available:false, configured:false

POST /auth/verify-email          {"token":"EPOSTA_DOGRULAMA_KODU"}
POST /auth/reset-password       {"token":"PAROLA_YENILEME_KODU","password":"YENI_PAROLANIZ"}

SMTP yapılandırıldığında uygun hesaba e-posta işlemi başlatılır; genel yanıt hesabın varlığını veya posta teslimini doğrulamaz. Yeni hesapların doğrulama bağlantısı 24 saat, parola yenileme bağlantısı 15 dakika ve tek kullanımlıktır. Parola 12–128 karakterdir. Parola değişikliği eski oturumları ve diğer parola yenileme bağlantılarını iptal eder. SMTP yokken sunucu yöneticisinin ürettiği kurtarma bağlantısı kullanılabilir.

Alan adı doğrulaması ve ücretsiz kullanım sınırları

Varsayılanlar hesap başına 25 proje, proje başına 50.000 aktif abone ve UTC günü için 100.000 planlanan alıcı gönderimidir. İşletmeci sınırları değiştirebilir; panelde geçerli değerler gösterilir. Bu sınırlar test edilmiş kapasite veya cihaz teslim garantisi değildir. Ücretli paket veya ödeme işlemi yoktur.

Yeni canlı projede Proje ayarları → Alan adı ve kullanım bölümünden TXT adını ve rastgele değeri alın. Kaydı projenin tam alan adına ekleyip DNS yayılımını bekleyin. Kayıt adı _pushdesk.<proje hostname>, değeri pushdesk-verification=<kod> biçimindedir. Kurulum sırasında izin kartı ve abonelik kaydı kullanılabilir; yeni kampanya için doğrulama gerekir. Eski projeler Eski proje · korunuyor olarak gösterilir; doğrulanmış sayılmaz ve bu geçiş nedeniyle durdurulmaz.

// Yalnız proje sahibinin panel oturumu; bearer anahtarı kabul edilmez.
GET  /api/sites/PROJE_UUID/guard
POST /api/sites/PROJE_UUID/guard/check   {}
POST /api/sites/PROJE_UUID/guard/reset   {}

Yanıt verification, geçerli limits ve usage içerir. can_send alanı yalnız sahiplik koşuludur; kalan kota, worker veya cihaz teslim testi değildir. Kontrol en sık 30 saniyede, yeni TXT kodu en sık 60 saniyede yapılır. Yeni kod önceki doğrulamayı iptal eder; zorunlu projede yeni gönderimler tekrar doğrulanana kadar durur. Mevcut kuyruk topluca değiştirilmez.

Proje ve aktif abone sınırları eşzamanlı kayıtlarda korunur. Kota, gerçek alıcı kuyruğuna atomik olarak ayrılır; sınır aşılırsa kampanya ve kuyruk birlikte geri alınır (429). Eksik sahiplik doğrulaması 409 döndürür. Zamanlanmış gönderim, planlandığı UTC gününün kotasından düşer. İdempotent tekrar ek kota tüketmez; otomatik yeniden denemeler sayaca eklenmez ve iptal kotayı iade etmez. Bu nedenle recipients_reserved gerçek sağlayıcı çağrısı sayısı değildir. Kota doluyken mevcut aktif abonelik yenilenebilir.

GET /v1/project yanıtı değişmedi: id, name, origin, prompt_enabled. Bu yanıta DNS/kota alanları eklenmez. WordPress bağlantı kontrolü anahtar/proje eşleşmesini gösterir; sahiplik veya teslim testinin yerine geçmez.

Gerçek cihazda kabul testi

Otomatik testler gerçek cihaza teslimi doğrulamaz. Her testte ayrı test projesi/kitlesi kullanın; işletim sistemi sürümünü, proje/kampanya kimliğini ve ön plan, arka plan, kilitli ekran sonuçlarını kaydedin. Sağlayıcı kabulünü, cihazdaki görünümü ve tıklamayı ayrı kontrol edin. İzin reddi, abonelikten çıkma, yönetim engeli ve token yenilemesi de denenmelidir. Gerçek test bildirimi oluşturmak gönderim yapar.

iPhone/iPad web için iOS/iPadOS 16.4+ üzerinde siteyi ana ekrana web uygulaması olarak ekleyin ve simgesinden açın; manifest display değeri standalone veya fullscreen olmalıdır. İzin kullanıcı dokunuşuyla istenir. Bu standart Web Push yoludur ve kendi Firebase/APNs anahtarınız gerekmez. WebKit resmi açıklaması.

Yerel Android uygulamasında Firebase istemcisi ve Android 13+ çalışma zamanı POST_NOTIFICATIONS izni gerekir. Token kaydı bildirim gösterme iznini kanıtlamaz. Yerel iOS uygulamasında Firebase Apple uygulaması, APNs anahtarı ve uygulama bildirim izni ayrıca yapılandırılır. /v1/devices iOS kaydına APNs token'ı yerine FCM kayıt token'ı gönderilir. API anahtarı yalnız kendi backend'inizde tutulur. Firebase Android, Firebase Apple.

Ön plandaki görünüm ve bildirime tıklayınca uygulama ekranının açılması uygulama işleyicilerinde uygulanmalıdır. Panelde kabul görüldüğü için bu adımlar tamamlanmış sayılmaz. Kaynak pakette docs/device-acceptance.md ayrıntılı adımlar ve henüz çalıştırılmamış sonuç formu içerir.

Resmi kaynaklar

MDN · Push API

Firebase · HTTP v1 API

Firebase · Flutter istemci kurulumu

Apple · Web Push

← Panele dön