Download the PHP package pariette/signalbird without Composer

Signalbird SDK

Tek paket, dört yüzey, on iki giriş noktası. Panelde tıklayarak yapabildiğiniz her şey kodla da yapılabilir.

Bir seçenek daha var ve kod yazmaz: hazır sohbet widget'ı (signalbird.js), siteye tek <script> ile gömülür.

Dil matrisi

Metot adları diller arasında birebir aynıdır; her dil kendi yazım geleneğini korur (createRadioProject / create_radio_project / CreateRadioProject). node scripts/check-parity.mjs bunu her derlemede denetler.

Uygulama yüzeyi mobil ve tarayıcı içindir: gizli anahtar oraya gömülmez. Gönderim ve Yönetim yüzeyleri yalnız sunucudadır.

Telsiz

Telsiz'in tek işi vardır: projenizden bir kanala mesaj yazmak.

Bildirimin kime gideceği, hangi kanaldan (push/e-posta), sessiz saatlerde ne olacağı ve aynı mesajın kaç kez uyarı üreteceği sunucuda, kanal ayarlarında durur. Kod tarafında bunlar yoktur ve olmamalıdır: bildirim kuralını değiştirmek için uygulamanızı yeniden yayınlamanız gerekmesin.

Tek anahtar

.env dosyanıza bir satır yazarsınız:

Takım anahtarı (sb_…) her şeyi kapsar: e-posta, SMS, push, kişi ve kampanya, sohbet, uygulama, domain, Telsiz log yazımı. Ne yapabileceğini anahtarın kapsamları belirler; panelde üretilirken seçersiniz. Adres yazmanız gerekmez - üretim kökü paketin içindedir.

Ayrı anahtar isteğe bağlıdır: bir sunucunun yalnız log yazıp gönderim yapamamasını istiyorsanız o sunucuya dar kapsamlı ikinci bir anahtar verirsiniz.

Bir de açık anahtarlar vardır; onlar .env'e değil, sayfanın içine gömülür ve gizli olmadıkları için ayrı durmak zorundadırlar:

Gizli anahtar tarayıcıya gömülemez: sunucu, Origin başlığı taşıyan bir istekte gizli anahtarı reddeder (SECRET_KEY_IN_BROWSER). Bu bir kolaylık değil, kasıtlı bir duvardır - anahtar bir kez istemciye indiğinde herkesindir.

Kurulum

Hepsi bu repodan çıkar ve aynı sürümü taşır - ayrı SDK reposu ya da dil başına sürüm yoktur.

Node.js / TypeScript

Kendi istemcinizi kurmak isterseniz:

Yakalanmamış hatalar:

Toplu gönderim (kısmi başarı normaldir, satır satır sonuç döner):

Next.js

Sunucu tarafında (route handler, server action, app/api/**) doğrudan signalbird kullanılır. İstemci bileşenlerinde kullanmayın - anahtar paketle birlikte tarayıcıya iner.

Tarayıcı (React, Vue, Angular, düz JS)

Çatıya özel sarmalayıcı yoktur; gereken tek şey bir fonksiyon çağrısıdır.

Kayıtlar tek tek değil, toplu gider (varsayılan 3 saniyede bir) ve sekme kapanırken sendBeacon ile boşaltılır.

React - app/providers.tsx ya da main.tsx:

Vue - main.ts:

Angular - ErrorHandler sağlayıcısı:

Panelde bu projenin izinli kökenlerini ve izinli kanallarını açmayı unutmayın; ikisi de boşken tarayıcı anahtarı hiçbir şey yapamaz. Kritik kanalları tarayıcıya açmayın: istemci kodu herkesin elindedir.

PHP / Laravel

.env:

Laravel'in kendi loglarını Telsiz'e bağlamak - config/logging.php:

Sonra LOG_STACK=single,signalbird. Mevcut Log::error() satırlarınız olduğu gibi çalışır; tek satır kod yazmadan Telsiz'e düşerler.

Laravel dışı PHP:

Davranış kuralları

• Sessiz hata varsayılandır. Telsiz erişilemezse çağrı ok: false döner ve uygulamanız çalışmaya devam eder. Log göndermek, ödeme akışını çökertmek için geçerli bir sebep değildir. Geliştirme sırasında throwOnError: true.
• Tanımsız kanal düşürülmez. İlk log('odeme-hatasi', …) çağrısında kanal kendiliğinden açılır ve panelde "otomatik açıldı" işaretiyle görünür. Yeni kanal sessizdir - kuralı ekip koyar.
• Seviye kanalın varsayılanını ezer. level göndermezseniz kanalın kendi seviyesi geçerlidir.
• Kritik seviye sessiz saatleri deler. Gece üçte ölen servis sabahı bekleyemez.
• Tekrar bastırma kaydı değil bildirimi susturur. Aynı mesaj kanalın dedupe süresi içinde tekrar gelirse ikinci bildirim gitmez ama kayıt tutulur.
• SDK sürümünü bildirir (2.6.0). Her istek `X-Signalbird-Sdk: /` taşır. Yeni sürüm çıktığında SDK süreç başına **bir kez** uyarı yazar; eski sürümdeki anahtarların sahiplerine panel bildirimi gider. Uyarı hata değildir, istek sonucu değişmez (CONTRACT §14).

Gönderim (Messaging)

Takım API anahtarı (sb_…, panelde Konsol → API anahtarları, scope'lu) ile çalışır. Telsiz anahtarı burada geçmez - istemci kurulurken WRONG_KEY_TYPE ile reddeder. Yalnız sunucuda kullanılır.

Node:

PHP / Laravel:

.env: SIGNALBIRD_DOMAIN_KEY=sb_secret_live_… (isteğe bağlı SIGNALBIRD_MESSAGING_URL, SIGNALBIRD_MESSAGING_TIMEOUT). Laravel dışı PHP: Signalbird::configureMessaging('sb_…') ya da new MessagingClient('sb_…').

Metot kümesi iki dilde aynıdır: sendEmail sendSms previewSms sendPush · listContacts createContact updateContact deleteContact bulkContacts · listContactLists createContactList deleteContactList · listCampaigns createCampaign getCampaign cancelCampaign listCampaignMessages iterateCampaignMessages · listMessages getMessage. Hepsi {ok, status, data?, code?, message?} döner; throwOnError: true ile istisna (SignalbirdError / SignalbirdException, code + status + body taşır).

Webhook imzası (message.*, campaign.* olayları):

Doğrulama ham gövde üzerinde yapılır; JSON'u ayrıştırıp yeniden serileştirmek imzayı bozar.

Yönetim (Management)

Panelde tıklayarak yaptığınız her şeyi kodla yapar. Ortam kurulumunuz, CI akışınız ya da kendi ajan arayüzünüz artık panel oturumu taklit etmek zorunda değil.

Bu bir admin yüzeyi değildir: anahtar tek bir takıma bağlıdır ve yalnız o takımın kayıtlarına dokunur. Kullanıcı, faturalama ve abonelik işlemleri SDK'da yoktur.

Panelden radio:*, chat:*, apps:* scope'larıyla bir sb_… anahtarı açın.

Sohbet gelen kutusunu kendi botunuzla işleyin:

Signalbird ekranını kendi panelinizde göstermek isterseniz gömme jetonu:

Anahtar embed:issue kapsamı ister - jeton 60 dakikalık bir panel oturumuna çevrildiği için bu kapsam bilerek ayrıdır.

Aynısı PHP, Python, Go ve .NET'te birebir aynı metot adlarıyla:

Tam liste (40 metot): docs/CONTRACT.md § 10.

Partner - müşteri sağlama

Signalbird'ü kendi ürününüzün içinde satıyorsanız (sözleşmeli platform) bu yüzey sizindir: müşteri hesabı açar, domain ekleyip izlemeye alır, uptime okur, ödeme alındığında modül açar ve panel ekranını kendi sayfanıza gömersiniz.

PHP'de Signalbird::partner()->createCompany([...]).

İki kural: anahtar tarayıcıya inmez ve TXT'siz domain kampanya gönderemez (izleme, sohbet ve push açıktır). Ayrıntı: docs/CONTRACT.md § 12.

Mesaj uçları salt okurdur: alıcı maskeli döner, gövde hiç dönmez - gövde zaten saklanmıyor.

Gönderim - müşterinin kendi sisteminden

Bir platformun (SubmitCMS, veribenim…) müşterisiyseniz kendi sunucunuzdan da gönderim yapabilirsiniz. Gereken tek şey kendi takım anahtarınızdır (sb_…); panelinizdeki entegrasyon kartında durur.

İkisinin farkı gövdenin nerede durduğudur: taşıyıcıda uygulamada (Blade), mail()'de Signalbird panelinde. Metni değiştirmek için dağıtım beklemek istemiyorsanız ikincisi.

Üç şey bilinmeli:

1. Sınıfı siz seçmezsiniz, sistem belirler. Kampanya arayüzünden çıkan her şey zorunlu commercialtır. Ticari iletiyi transactional işaretleyip İYS'yi atlamak, sistemin izin verebileceği en pahalı hatadır.
2. Gönderen kimliği panelde kurulur. Hazır adresiniz (bildirim@<takım>.sendsignalbird.com) hesapla birlikte gelir; kendi alan adınızı bağlamak için DKIM/SPF/MX kayıtlarını yayınlamanız gerekir.
3. Anahtar sunucuda kalır. Tarayıcıya ya da mobil uygulamaya konmaz; oralar için açık uygulama anahtarı (sb_public_live_…) vardır.

Uygulama (App) - kendi sohbet arayüzünüz

Hazır widget yerine kendi arayüzünüzü yazmak, ya da sohbeti mobil uygulamanıza koymak istiyorsanız bu yüzey içindir. Açık uygulama anahtarı (sb_public_live_…) kullanır ve yalnız ziyaretçinin kendi verisine dokunur.

React / Next.js

Vue 3

Angular

React Native / Expo

Swift (iOS)

Kotlin (Android)

Tam liste (17 metot) ve yoklama merdiveni: docs/CONTRACT.md § 11.

Widget (canlı sohbet)

Panelde Gelen Kutusu → Ayarlar → Uygulamalar'dan bir uygulama açın; verilen sb_public_live_… anahtarını sitenize gömün:

Bu kadar. Sohbet modülü açıksa balon görünür; renk, konum, karşılama, ön-form, çalışma saatleri panelden yönetilir. Programatik kullanım:

data-key/data-channel yerine Signalbird.init({ publicKey, chatKey, baseUrl?, locale? }) da çağrılabilir. Widget ev sahibi sayfaya asla hata fırlatmaz; Shadow DOM içinde çalışır, sayfanızın CSS'iyle çakışmaz; < 20 KB gzip. Ayrıntı: docs/CONTRACT.md § 9 ve https://signalbird.io/sdk/widget.

Gömme (embed) - Signalbird ekranını kendi panelinizde çalıştırın

Partner (veribenim, submitcms, yeni ortaklar) Signalbird modülünü kendi panelinin içinde gösterir. Ekran kopyalanmaz - çalışan ekranın kendisi gelir; Signalbird'de güncellenen her şey partner panelinde de anında günceldir.

npm ile:

Sunucu tarafı tek çağrıdır (Signalbird::partner()->createEmbedToken(...), §12.5): 120 saniyelik, tek kullanımlık jeton. Ayrıntı: docs/CONTRACT.md § 13.

Hata kodları

Gönderim ve Yönetim istemcilerine özgü: WRONG_KEY_TYPE (kurulumda), API_KEY_INVALID, API_KEY_SCOPE (anahtarda gereken scope yok), VALIDATION_ERROR (422), NO_CONSENT, SUPPRESSED, NO_SENDING_DOMAIN, LIST_NOT_FOUND, MODULE_DISABLED, NETWORK_ERROR, TIMEOUT, HTTP_<durum>.

Uygulama yüzeyi ve widget: VISITOR_INVALID (yerel kimlik silinir, yeni oturum açılır), CHAT_UNAVAILABLE (kota - "sohbet kullanılamıyor" bandı), NOT_INITIALIZED.