Entegrasyonlar: Segment, Amplitude, Mixpanel, Zapier, Slack, WordPress, GTM

Pushizo'yu veri ve otomasyon yığınınıza kod yazmadan bağlamak için hazır entegrasyonlar (docs/adr/0031-entegrasyonlar-ve-mcp-sunucusu.md). Dashboard'da Geliştirici → Entegrasyonlar bölümünden yönetilir (webhooks.manage izni: geliştirici ve yönetici rolleri). Her entegrasyon app başına bir kez bağlanır.

Ortak davranışBağlantıyı kopyala

• Kimlik bilgileri zarf şifreli saklanır; yanıtlarda ve ekranda yalnızca maskeli görünür (•••• + son 4 karakter). Güncellemede boş bıraktığınız kimlik alanı korunur; alanı silmek için boş değer gönderin.
• Bağlantı testi düğmesi kimlik bilgisini sağlayıcıda doğrular. Sağlayıcı 401/403 dönerse entegrasyon Hata durumuna alınır ve istek atılmaz; kimlik bilgisini güncelleyince yeniden etkin olur.
• Son çalışmalar: olay gönderimi, cohort senkronu, gelen istekler ve testler (30 gün saklanır).
• Giden olaylar (Segment/Amplitude/Mixpanel hedefi, Zapier, Slack) bir outbox'a yazılır ve worker tarafından 5 sn'de bir toplu gönderilir. Geçici hatalarda (429, 5xx, ağ) 30 sn → 2 dk → 10 dk → 30 dk → 2 sa → 6 sa beklenir (Retry-After daha uzunsa o); yedinci başarısızlıkta veya kalıcı hatada (400/413/422) olay bırakılır.
• Bağlantıyı kesmek kimlik bilgilerini, Zapier aboneliklerini ve bekleyen olayları siler.

Analitik hedefleri: gönderilen olaylarBağlantıyı kopyala

Segment, Amplitude ve Mixpanel'e şu Pushizo olayları gönderilebilir: event.received, subscription.created, subscription.unsubscribed, delivery.sent|delivered|failed|opened|clicked|bounced|unsubscribed, in_app.impression|clicked|dismissed, conversion.created, journey.entered|completed. event.received için isteğe bağlı olay adı filtresi (en fazla 50 ad) verilebilir.

• Sistem olayları Segment Spec "Nesne Eylem" adlarıyla gider (Notification Opened, Subscription Created …); özel olaylar kendi adlarıyla.
• Kullanıcı external_id ile tanınır; yoksa Pushizo kullanıcı kimliği anonim kimlik olur (Segment anonymousId, Amplitude device_id, Mixpanel distinct_id). Abonelik belirteci (push token) gönderilmez.
• Tekilleştirme anahtarı olay kimliğidir (Segment messageId, Amplitude insert_id, Mixpanel $insert_id); yeniden denemeler hedefte çift kayıt oluşturmaz.

SegmentBağlantıyı kopyala

Pushizo hem Segment hedefi (Pushizo → Segment) hem kaynağı (Segment → Pushizo) olabilir.

Hedef (olay gönderimi)

1. Segment'te bir HTTP API kaynağı oluşturun ve Write Key'i kopyalayın.
2. Pushizo'da Segment kartında Write Key'i girin, bölgeyi (US/EU) seçin ve gönderilecek olayları işaretleyin.
3. Olaylar Segment HTTP Tracking API /v1/batch ucuna gider (istek ≤ 450 KB; 32 KB'ı aşan tek mesaj gönderilmez).

Kaynak (Segment'ten gelen veri)

1. Pushizo'da Gelen uçu açın ve bir shared secret belirleyin. Kartta gelen uç adresi gösterilir: {API_URL}/hooks/integrations/segment/{integrationId}.
2. Segment'te kaynağınıza Webhooks (Actions) / Webhooks hedefini ekleyin; URL olarak bu adresi, imza için aynı shared secret'ı girin.
3. Her istek X-Signature başlığıyla imzalanmalıdır: gövdenin shared secret ile HMAC-SHA1 özeti (hex). İmzasız veya hatalı imzalı istek reddedilir; gelen uç kapalıysa veya entegrasyon etkin değilse 404 döner.

Gövde tek mesaj, mesaj dizisi veya { "batch": [...] } olabilir; toplu istekte en fazla 1000 mesaj. Bu uçta gövde sınırı 500 KB'tır (Segment'in belgelenmiş en büyük toplu gönderim boyutu); diğer /hooks/* uçlarında 256 KB. Sınırı aşan istek 400 HS_BAD_REQUEST ile reddedilir (genel gövde sınırıyla aynı yanıt).

Segment'ten gelen olaylar Segment hedefine geri gönderilmez (döngü önleme). Bir identify/group reddedilirse aynı toplu istekteki diğer mesajlar işlenmeye devam eder.

AmplitudeBağlantıyı kopyala

1. Amplitude Settings → Projects bölümünden API Key ve Secret Key'i alın (cohort senkronu için Secret Key zorunlu).
2. Pushizo'da Amplitude kartında anahtarları girin, bölgeyi (US/EU) seçin.
3. Olay gönderimi: gönderilecek olayları seçin (HTTP V2 API, istek başına 500 olay).
4. Cohort senkronu: cohort kimliklerini ekleyin (en fazla 20) ve senkron aralığını seçin (15 dk – 7 gün, varsayılan 60 dk). Cohort Behavioral Cohorts API ile indirilir.

MixpanelBağlantıyı kopyala

1. Mixpanel Organization Settings → Service Accounts bölümünden bir servis hesabı oluşturun (projeye erişimli) ve Project ID'yi not edin.
2. Pushizo'da Mixpanel kartında servis hesabı kullanıcı adı/gizli anahtarı, Project ID ve bölgeyi (US/EU/IN) girin.
3. Olay gönderimi: Import API (strict=1, istek başına 1000 olay; Mixpanel'in reddettiği kayıtlar tek tek bırakılır).
4. Cohort senkronu: cohort kimliklerini ekleyin (en fazla 20); üyeler Engage Query API ile sayfalı okunur.

Cohort senkronu (Amplitude ve Mixpanel)Bağlantıyı kopyala

• Cohort üyeliği tag ile taşınır: cohort'taki external_id'lere cohort_amp_<id> (Amplitude) veya cohort_mxp_<id> (Mixpanel) tag'i "1" değeriyle eklenir; cohort'tan çıkanlardan kaldırılır. Senkron tek transaction'dır, yarım sonuç görünmez.
• İlk senkronda tags.<tag_key> exists koşullu bir dinamik segment oluşturulur (silinirse sonraki senkronda yeniden oluşturulur). Bu segmenti kampanya, journey ve in-app hedeflemede doğrudan kullanabilirsiniz.
• Pushizo'da karşılığı olmayan üyeler için kullanıcı oluşturulmaz; sayıları çalıştırma kaydında unmatched olarak görünür.
• Bir cohort'un hatası diğerlerini durdurmaz (partial). Şimdi senkronla düğmesi senkronu öne çeker; worker en geç 1 dakika içinde çalıştırır.

Önemli: Entegrasyonun bağlantısını kesmek cohort tag'lerini (cohort_amp_<id> / cohort_mxp_<id>) ve senkronun oluşturduğu dinamik segmenti silmez; bunlar kullanıcılarda ve segment listesinde kalır. Artık kullanılmayacaksa segmenti Kitle → Segmentlerden, tag'leri API ile elle kaldırın (PATCH /v1/apps/{app_id}/users/by/external_id/{id} gövdesinde {"tags": {"cohort_amp_<id>": null}}). Bu segmenti kullanan kampanya veya journey varsa önce onları güncelleyin.

ZapierBağlantıyı kopyala

Pushizo Zapier uygulaması (integrations/zapier) REST Hook tetikleri kullanır; olaylar Zap'e 1 dakikadan kısa sürede ulaşır.

1. Dashboard'da Geliştirici → API anahtarları bölümünden bir anahtar oluşturun. Tetikler için users:read; kullanacağınız eylemlere göre users:write, events:write, notifications:write.
2. Zapier'de Pushizo bağlantısı eklerken API anahtarını ve App ID'yi girin (kendi barındırdığınız kurulumda API URL alanına API kök adresinizi https ile girin).
3. Zap açıldığında Zapier abone olur; kapatıldığında abonelik silinir. Abonelikler Entegrasyonlar → Zapier kartında listelenir.

Hook adresi herkese açık HTTPS olmalıdır; app başına en fazla 200 abonelik. Abonelik şu durumlarda kendiliğinden kaldırılır: Zapier 410 Gone döner, art arda 50 kalıcı hata olur veya aboneliği açan API anahtarı iptal edilir, süresi dolar ya da silinir. Public uçlar: GET /v1/apps/{app_id}/integrations/zapier/me, POST …/hooks, DELETE …/hooks/{hookId}, GET …/samples (kapsam users:read).

SlackBağlantıyı kopyala

Kampanya başladı/tamamlandı, mesaj hatası, kampanya onay isteği ve kota eşiği bildirimleri bir Slack kanalına gider. İletiler Block Kit biçiminde, Türkçe veya İngilizcedir.

Bot modunda gerekli bot kapsamları: chat:write, users:read, users:read.email. Botu kanala davet edin (/invite @Pushizo).

Slack'ten kampanya onayı

1. Bot modunu seçin, Signing Secret'ı (Slack app → Basic Information) girin ve Slack'ten onayı açın.
2. Slack app → Interactivity & Shortcuts'ı açın; Request URL olarak kartta gösterilen adresi girin: {API_URL}/hooks/integrations/slack/{integrationId}/interactions.
3. Onay isteği iletisinde Onayla/Reddet düğmeleri görünür. Düğmeye basan Slack kullanıcısı e-posta adresiyle Pushizo üyesine eşlenir; üyenin aktif, campaigns.approve izinli ve app'e erişimli olması gerekir. Ret durumunda kampanya taslak olarak kalır.

İstekler Slack imzasıyla (v0= HMAC-SHA256, 5 dk zaman penceresi) doğrulanır.

WordPress eklentisiBağlantıyı kopyala

integrations/wordpress/pushizo (WordPress ≥ 6.2, PHP ≥ 8.1).

1. pushizo klasörünü /wp-content/plugins/ altına yükleyip eklentiyi etkinleştirin.
2. Ayarlar → Pushizo'de App ID'yi girin (Entegrasyonlar → WordPress kartında kopyalanabilir). Kendi barındırdığınız kurulumda API URL alanını değiştirin.
3. Eklenti her sayfada Web SDK'yı yükler ve service worker'ı site kökünden (/PushizoSDKWorker.js) sunar. İsteğe bağlı slidedown veya zil açılabilir. Worker 404 dönerse Ayarlar → Kalıcı bağlantılar'ı bir kez kaydedin.
4. Abonelik formu için [pushizo_subscribe] kısa kodunu veya Pushizo subscribe form bloğunu kullanın (isteğe bağlı e-posta alanı).
5. Yayında bildirim: açtığınızda seçili yazı türlerinde yazı yayınlanınca bildirim gider (segment seçimi ve yazı başına meta kutusu). Bunun için notifications:write kapsamlı bir REST API anahtarı girin; anahtar sayfalara yazılmaz.

Google Tag Manager şablonuBağlantıyı kopyala

integrations/gtm/template.tpl (web Custom Template).

1. GTM'de Şablonlar → Etiket şablonları → Yeni → İçe aktar ile template.tpl'yi yükleyip kaydedin.
2. Pushizo Web Push türünde bir etiket oluşturun; App ID'yi girin (gerekirse API URL).
3. Eylemler: Initialize (Initialization – All Pages tetikleyicisiyle), Send event (ad, isteğe bağlı sayısal değer, özellikler), Add tags (anahtar/değer), Log in (external ID). Her eylem önce SDK'yı yükleyip idempotent olarak başlatır.
4. Service worker dosyası (PushizoSDKWorker.js) sitenizin kökünden sunulmalıdır; farklı bir yol kullanıyorsanız şablonun Service worker path alanına girin.

Şablonun izinleri inject_script, access_globals ve logging ile sınırlıdır.