Kampanyalar
Kampanya yaşam döngüsü — türler (tek seferlik, zamanlanmış, tekrarlı), durum makinesi, kitle ve içerik, teslimat ayarları, onay akışı, A/B varyantları, istatistikler ve public API.
Kampanya, kayıtlı bir kitleye (segmentler/filtre) planlı ya da tekrarlı gönderilen mesajdır; tek seferlik API mesajlarından (bildirim gönderme) farkı yaşam döngüsü, onay akışı, A/B testi ve zengin istatistiktir. Dashboard Mesajlar → Kampanyalar 5 adımlı oluşturucu (kitle → içerik → kanallar → teslimat → özet) sunar.
Türler ve durumlar
type | Açıklama |
|---|---|
one_time | Hemen gönderilir (send) |
scheduled | scheduled_at anında gönderilir (schedule) |
recurring | recurrence.cron (5 alan) + timezone + isteğe bağlı until; her tetiklemede yeni mesaj |
automated, transactional | Journey ve API tarafından oluşturulan sistem kampanyaları (salt okunur) |
Durum makinesi: draft → scheduled → running → completed; ara durumlar paused (duraklat/sürdür), cancelled, failed, onay bekleyen pending_approval. Durum geçişleri campaign.scheduled, campaign.started, campaign.completed webhook'larını üretir.
Tanım
{
"name": "Bahar kampanyası",
"type": "scheduled",
"audience": { "included_segments": ["seg_…"], "excluded_segments": [], "channels": ["ios_push", "android_push", "email"] },
"content": { "headings": { "tr": "Bahar indirimi" }, "contents": { "tr": "Seçili ürünlerde %20" }, "email_subject": "Bahar indirimi başladı", "template_id": "tpl_…" },
"delivery": {
"timezone_mode": "per_user_timezone",
"delivery_time_of_day": "10:00",
"throttle_per_minute": 5000,
"ttl": 86400,
"priority": 10,
"frequency_cap_exempt": false,
"quiet_hours_exempt": false,
"one_per_user": true
},
"send_at": "2026-10-20T07:00:00Z",
"variants": [
{ "name": "A", "weight_percent": 45, "content": null },
{ "name": "B", "weight_percent": 45, "content": { "headings": { "tr": "Bugüne özel %20" } } },
{ "name": "Holdout", "weight_percent": 10, "is_control": true }
],
"ab_test": { "enabled": true, "test_percentage": 20, "winner": { "mode": "auto", "metric": "click_rate", "evaluate_after_minutes": 120 } }
}- Kitle: segmentler, filtre AST'si ve kanallar; kanal verilmezse içerikten çıkarılır.
- İçerik: satır içi
contentya datemplate_id(+template_version);labelsvecategory(tercihler). - Teslimat:
timezone_mode(immediate,per_user_timezone,optimized), saat, hız sınırı, TTL, öncelik,collapse_id, frekans/sessiz saat muafiyeti,one_per_user. - A/B:
variants(içeriknull→ kampanya içeriği;is_controlholdout) veab_test(test yüzdesi, elle/otomatik kazanan, metrik, değerlendirme süresi); deterministik atama ve z-testi anlamlılığı (A/B testi).
Onay akışı
App ayarı campaignApprovalRequired açıkken marketer rolü gönderemez; send/schedule isteği pending_approval durumuna düşer ve approval.pending_action ile kimin onaylayacağı görünür. POST …/campaigns/{id}/approve (admin/owner) onaylar; onay ekranı kota önizlemesi (mesaj/abone kotası etkisi) gösterir. Kampanya düzenlenirse onay korunur, içerik değişirse yeniden onay gerekir.
Public API
| İşlem | Uç |
|---|---|
| Liste / oluştur | GET, POST /v1/apps/{app_id}/campaigns |
| Oku / güncelle / sil | GET, PATCH, DELETE …/campaigns/{id} (PATCH yalnızca gönderilen alanları değiştirir) |
| Yaşam döngüsü | POST …/{id}/send, /schedule { scheduled_at?, recurrence? }, /pause, /resume, /cancel, /approve, /duplicate, /resend-failed |
| İstatistik | GET …/{id}/stats (sayaçlar, oranlar, hata kodları), GET …/{id}/variants/stats, GET …/{id}/messages, GET …/{id}/deliveries |
| A/B kazanan | POST …/{id}/winner { variant_id } |
Okuma analytics:read, yazma admin. Tüm alanlar ve örnekler: API → Kampanyalar. Sunucu SDK'larında hs.campaigns.*.
İstatistik ve izleme
stats şunları döner: targeted, suppressed, sent, delivered, failed, opened, clicked, converted, bounced, complained, unsubscribed; oranlar (delivery_rate, open_rate, click_rate, conversion_rate); kanal ve gün kırılımı; hata kodu dağılımı. Saatlik delivery_event_rollups işi rapor tablolarını günceller; dönüşümler olay tanımındaki is_conversion ve atribüsyon penceresine göre sayılır (analitik).
Tekrarlı kampanyalarda her tetikleme ayrı bir mesaj (msg_…) oluşturur; GET …/{id}/messages listeler. Duraklatılan kampanyanın bekleyen teslimatları ertelenir, sürdürülünce devam eder; iptal bekleyenleri düşürür.
Bildirim gönderme
POST /v1/notifications — hedefleme (target), çok dilli içerik, kanal bazlı alanlar, zamanlama ve saat dilimi, teslimat politikaları (TTL, öncelik, frekans, sessiz saat), idempotency, durum ve teslimat sorgulama.
Şablonlar ve Liquid
Sürümlü mesaj şablonları — oluşturma, sürümler ve geri alma, render önizlemesi, başka app'e kopyalama, şablon galerisi, istatistikler ve Liquid kişiselleştirme sözdizimi.