Genel bakış
Web Push Webhook’ları, kullanıcılar push bildirimlerinizle etkileşime girdiğinde gerçek zamanlı HTTP POST bildirimleri almanızı sağlar. Bir bildirim görüntülendiğinde, tıklandığında veya kapatıldığında, OneSignal otomatik olarak bildirim verilerini ve özel parametreleri belirttiğiniz webhook URL’sine gönderir.
Temel Faydalar:
- Bildirim etkileşimini gerçek zamanlı olarak izleyin
- Kullanıcı etkileşimlerine dayalı otomatik iş akışlarını tetikleyin
- Bildirim verilerini analitik platformunuzla senkronize edin
- Bildirim olayları için özel iş mantığı uygulayın
Tarayıcı desteği
| Tarayıcı | Platform Desteği | Kullanılabilir Webhook Olayları |
|---|
| Chrome | macOS, Windows, Android | Tüm olaylar (görüntüleme, tıklama, kapatma) |
| Firefox | macOS, Windows, Android | Görüntüleme ve tıklama olayları |
| Safari | Desteklenmiyor | Yok |
Kullanılabilir webhook olayları
notification.willDisplay
Bir bildirim kullanıcının ekranında göründükten hemen sonra tetiklenir.
Kullanım senaryoları: Teslimat oranlarını izleyin, gösterim verilerini kaydedin, takip kampanyalarını tetikleyin
notification.clicked
Bir kullanıcı bildirim gövdesine veya herhangi bir eylem düğmesine tıkladığında tetiklenir.
Kullanım senaryoları: Etkileşim oranlarını izleyin, dönüşüm olaylarını tetikleyin, kullanıcıları belirli içeriğe yönlendirin
notification.dismissed
Bir kullanıcı bir bildirimi aktif olarak kapattığında veya otomatik olarak sona erdiğinde tetiklenir.
Tarayıcı desteği: Yalnızca Chrome
Kullanım senaryoları: Kapatma oranlarını izleyin, bildirim zamanlamasını optimize edin, bildirim içeriğini A/B test edin
Önemli: Bildirim gövdesine veya eylem düğmelerine tıklamak kapatma webhook’unu tetiklemez.
Kurulum yöntemleri
OneSignal kontrol panelinizde Ayarlar > Web’e gidin
“Webhook’ları etkinleştir” anahtarını etkinleştirin
İzlemek istediğiniz her olay için webhook URL’lerinizi girin
Mevcut OneSignal.init() yönteminize webhook yapılandırması ekleyin:// Mevcut OneSignal başlatmanıza ekleyin - init'i iki kez çağırmayın
OneSignal.init({
// Diğer mevcut ayarlarınız buraya
webhooks: {
cors: false, // Önerilir: özel başlıklara ihtiyacınız olmadıkça false olarak bırakın
'notification.willDisplay': 'https://yoursite.com/webhook/display',
'notification.clicked': 'https://yoursite.com/webhook/click',
'notification.dismissed': 'https://yoursite.com/webhook/dismiss' // Yalnızca Chrome
}
});
Webhook URL’lerinizin HTTPS olduğundan emin olun (Chrome’un güvenlik politikaları tarafından gereklidir).
CORS yapılandırması
cors ayarı, webhook endpoint’inizin hangi başlıkları ve verileri alacağını belirler:
cors: false (Önerilir): Daha basit kurulum, sunucunuzda CORS yapılandırması gerekmezcors: true: Ek başlıklar sağlar ancak sunucunuzda CORS desteği gerektirir
cors: true ne zaman kullanılır:
Content-Type: application/json başlığına ihtiyacınız var- Daha kolay olay tanımlama için
X-OneSignal-Event başlığını istiyorsunuz
- Sunucunuz zaten basit olmayan istekler için CORS’u destekliyor
Standart istek (cors: false)
Webhook endpoint’iniz bu yük yapısına sahip bir POST isteği alır:
{
"event": "notification.clicked",
"notificationId": "ed46884e-0e3f-4373-9e11-e28f27746d3d",
"heading": "Your notification title",
"content": "Your notification message",
"additionalData": {
"userId": "12345",
"campaignId": "summer-sale",
"customField": "customValue"
},
"actionId": "buy-now-button",
"url": "https://yoursite.com/product/123"
}
Gelişmiş istek (cors: true)
Yukarıdaki yükle aynı, artı şu ek başlıklar:
Content-Type: application/json
X-OneSignal-Event: notification.clicked
Yük alanı referansı
| Alan | Tür | Açıklama | Her Zaman Mevcut |
|---|
event | string | Webhook’u tetikleyen olay türü | ✅ |
notificationId | string | Benzersiz OneSignal bildirim tanımlayıcısı | ✅ |
heading | string | Bildirim başlığı | Yalnızca sağlanmışsa |
content | string | Bildirim mesaj gövdesi | Yalnızca sağlanmışsa |
additionalData | object | Bildirimle gönderilen özel veriler | Yalnızca sağlanmışsa |
actionId | string | Tıklanan eylem düğmesinin ID’si (boş dize = bildirim gövdesi tıklandı) | Yalnızca tıklama olayları |
url | string | Bildirim için başlatma URL’si | Yalnızca sağlanmışsa |
subscriptionId | string | OneSignal kullanıcı/abonelik ID’si | Yalnızca CORS etkin |
İmplementasyon en iyi uygulamaları
Webhook endpoint gereksinimleri
Güvenlik:
- Yalnızca HTTPS URL’leri kullanın (HTTP URL’leri Chrome tarafından engellenecektir)
- Webhook endpoint’leriniz için uygun kimlik doğrulama/doğrulama uygulayın
- Yüksek hacimli bildirimleri yönetmek için hız sınırlamasını göz önünde bulundurun
Yanıt gereksinimleri:
- Başarılı işleme için HTTP 200 durumu döndürün
- Zaman aşımlarını önlemek için 10 saniye içinde yanıt verin
- Yinelenen webhook çağrılarını zarif bir şekilde yönetin (idempotency uygulayın)
Hata yönetimi
// Örnek webhook endpoint (Node.js/Express)
app.post('/webhook/notification', (req, res) => {
try {
const { event, notificationId, additionalData } = req.body;
// Gerekli alanları doğrula
if (!event || !notificationId) {
return res.status(400).json({ error: 'Missing required fields' });
}
// Webhook verilerini işle
processNotificationEvent(req.body);
// Her zaman 200 OK ile yanıt ver
res.status(200).json({ success: true });
} catch (error) {
console.error('Webhook processing error:', error);
res.status(500).json({ error: 'Internal server error' });
}
});
Yaygın sorunlar ve çözümler
Webhook’lar tetiklenmiyor
Olası nedenler:
- Webhook kodu, OneSignal başlatması olan tüm sayfalarda mevcut değil
- Kullanıcı, eklendikten sonra webhook kodu olan bir sayfayı ziyaret etmedi
- HTTPS gereksinimi karşılanmadı
- Sunucu 200 olmayan durum kodları döndürüyor
Çözüm: Webhook yapılandırmasının, bildirimlerin aktif olduğu tüm sayfalarda OneSignal init kodunuza dahil edildiğinden emin olun.
Webhook’larda eksik veri
Neden: Webhook’lar yalnızca webhook yapılandırması aktif olan sayfaları ziyaret eden kullanıcılar için olayları izler.
Çözüm: Webhook kodunu yalnızca belirli açılış sayfalarına değil, OneSignal olan tüm sayfalara dağıtın.
Yinelenen webhook çağrıları
Neden: Ağ sorunları veya tarayıcı davranışı yinelenen isteklere neden olabilir.
Çözüm: Olayları tekilleştirmek için notificationId alanını kullanarak idempotency uygulayın.
Webhook sınırlamaları
- Olay başına bir webhook URL’si: Aynı olay türü için birden fazla webhook URL’si ayarlayamazsınız
- Yalnızca HTTPS: HTTP URL’leri tarayıcı güvenlik kısıtlamaları nedeniyle çalışmaz
- Yalnızca Chrome kapatma izleme:
notification.dismissed olayı yalnızca Chrome’da çalışır
- Sayfa bağımlılığı: İzlemenin çalışması için kullanıcıların webhook kodu aktif olan sayfaları ziyaret etmesi gerekir
Webhook’larınızı test etme
- OneSignal kontrol paneliniz aracılığıyla bir test bildirimi gönderin
- Gelen istekler için webhook endpoint’inizi izleyin
- Yük yapısının beklentilerinizle eşleştiğini doğrulayın
- Farklı senaryoları test edin:
- Bildirim görüntüleme
- Bildirim gövdesine tıklama
- Eylem düğmelerine tıklama (yapılandırılmışsa)
- Bildirimleri kapatma (yalnızca Chrome)
Sonraki adımlar
Webhook’ları kurduktan sonra, şunları göz önünde bulundurun:
- Analitik Entegrasyonu: Webhook verilerini analitik platformunuza iletin
- Kullanıcı Segmentasyonu: Etkileşime dayalı kullanıcı segmentleri oluşturmak için webhook olaylarını kullanın
- Otomatik İş Akışları: Push bildirim etkileşimlerine dayalı e-posta kampanyalarını veya uygulama bildirimlerini tetikleyin
- A/B Testi: Farklı bildirim stratejilerinin etkinliğini ölçmek için webhook verilerini kullanın
