API Pusher

Pusher

Pusher, WebSocket protokolüne dayalı güzel özelliklere sahip kolay ve güvenilir bir platformdur: esnek pub/sub mesajlaşma, canlı kullanıcı listeleri (presence), kimlik doğrulama...

Pusher WebSocket API'si 7'dir.

Veri, bir WebSocket üzerinden UTF8 kodlu JSON içeren metin verisi olarak çift yönlü gönderilir (İkili WebSocket çerçeveleri desteklenmez).

Sunucuya bağlantıyı test etmek için Ping yöntemini çağırabilirsiniz. Esasen, karşı taraftan alınan herhangi bir mesaj bağlantının canlı olduğu anlamına gelir. Herhangi bir mesajın yokluğunda, her iki taraf da karşı tarafın yanıt verip vermediğini bir ping mesajı göndererek kontrol edebilir, buna karşı tarafın bir pong ile yanıt vermesi gerekir.

Bağlanmadan önce aşağıdaki alanları doldurmanız gerekir:


Pusher.Cluster := 'eu'; // cluster where your pusher account is located
Pusher.Key := '9c3b7ef25qe97a00116c'; // your pusher api key
Pusher.Name := 'js'; // optional, name of your application
Pusher.Version := '4.1';  // optional, version of your application
Pusher.TLS := True; // if encrypted, set to True
Pusher.Secret := '2dc792e1916ac49e6b3f'; // pusher secret string (needed for private and presence channels)

Önemli

Pusher, websocket istemcisinin önceki alanları (key, cluster...) kullanarak bir URL'ye bağlanmasını gerektirir; bu alanlar URL'yi oluşturmak için kullanılır ve bu, istemciyi pusher bileşenine atadığınızda yapılır. Bu nedenle, URL'nin doğru oluşturulduğundan emin olmak için, pusher yapılandırma alanlarını doldurduktan sonra istemciyi ayarlayın. Aşağıdaki sözde kodu bulun:

// configure pusher fields

pusher.cluster = ...

pusher.key = ...

// set client

pusher.client = websocket client

// start connection

websocket client.Active = true;

Başarılı bir bağlantıdan sonra, OnPusherConnect olayı tetiklenir ve aşağıdaki alanları alırsınız:

Socket ID: Bağlı istemci için benzersiz bir tanımlayıcı.
Timeout: İstemcinin bir ping mesajı başlatması gereken, sonrasında geçen sunucu hareketsizliği saniye sayısı (bu, bileşen tarafından otomatik olarak işlenir).

Hata durumunda, OnPusherError tetiklenir ve hata hakkında bilgi sağlanır. Geçersiz kimlik doğrulamasına, geçersiz bir komuta vb. yanıt olarak Pusher'dan bir hata gönderilebilir.

4000-4099

Bağlantının Pusher tarafından kapatılmasına neden olan bir hatayı ve aynı parametreler kullanılarak yeniden bağlanmaya çalışmanın başarılı olmayacağını gösterir.

4000: Uygulama yalnızca SSL bağlantılarını kabul eder, wss:// kullanarak yeniden bağlanın

4001: Uygulama mevcut değil

4003: Uygulama devre dışı

4004: Uygulama bağlantı kotasını aştı

4005: Yol bulunamadı

4006: Geçersiz sürüm dizesi biçimi

4007: Desteklenmeyen protokol sürümü

4008: Hiçbir protokol sürümü sağlanmadı

4100-4199

Pusher tarafından bağlantının kapatılmasıyla sonuçlanan bir hatayı ve istemcinin 1 saniye veya daha fazla sonra yeniden bağlanabileceğini gösterir.

4100: Kapasite aşıldı

4200-4299

Bağlantının Pusher tarafından kapatılmasıyla sonuçlanan bir hatayı ve istemcinin hemen yeniden bağlanabileceğini gösterir.

4200: Genel hemen yeniden bağlanma

4201: Pong yanıtı alınmadı: istemciye ping gönderildi, ancak yanıt alınmadı - ping ve pong mesajlarına bakın

4202: Hareketsizlik sonrası kapatıldı: İstemci uzun süredir hareketsizdir (şu anda 24 saat) ve istemci ping'i desteklemiyor. Lütfen daha yeni bir WebSocket taslağına yükseltin veya bu protokolün 5 veya üzeri sürümünü uygulayın.

4300-4399

Başka herhangi bir hata türü.

4301: İstemci olayı rate limit nedeniyle reddedildi

Kanallar

Kanallar, Pusher'da temel bir kavramdır. Her uygulamanın bir dizi kanalı vardır ve her istemci hangi kanallara abone olacağını seçebilir.

Kanallar şunları sağlar:

Verileri filtrelemenin bir yolu. Örneğin, bir sohbet uygulamasında 'köpekleri' tartışmak isteyen kişiler için bir kanal olabilir
Farklı bilgi akışlarına erişimi kontrol etmenin bir yolu. Örneğin, bir proje yönetimi uygulaması, kişileri 'projectX' hakkında güncellemeler almaya yetkilendirmek isteyebilir.

Verilerinizi filtrelemek için kanalların kullanılması ve bunun olaylar kullanılarak elde edilmemesi şiddetle önerilir. Bunun nedeni, bir kanala yayınlanan tüm olayların, olay bağlamalarına bakılmaksızın tüm abonelere gönderilmesidir.

Kanalların açıkça oluşturulması gerekmez ve istemci talebi üzerine örneklenir. Bu, bir kanal oluşturmanın kolay olduğu anlamına gelir. Yalnızca bir istemciye ona abone olmasını söyleyin.

Aşağıdaki kanal türleri desteklenir:

Genel kanallar, adlarını bilen herkes tarafından abone olunabilir
Private channels, yayınladığınız verilere erişimi sunucunuzun kontrol etmesine olanak tanıyan bir mekanizma sunar
Presence kanalları, özel kanalların bir uzantısıdır. Abonelik sırasında kullanıcı bilgilerini kaydetmenize olanak tanır ve kanalın diğer üyelerinin kimin çevrimiçi olduğunu bilmesini sağlar
Cache kanalları son tetiklenen olayı hatırlar ve onu yeni abonelere ilk olay olarak gönderir (public, private ve presence varyantları)
Private-Encrypted kanalları, NaCl secretbox kullanarak uçtan uca şifreleme sağlar ve Pusher'ın bile mesaj verisini okuyamamasını güvence altına alır

Genel Kanallar

Genel kanallar, abone olmak için herhangi bir yetkilendirme biçimi gerektirmedikleri için herkese açık olarak erişilebilen veriler için kullanılmalıdır.

Kanallara istediğiniz zaman abone olabilir ve aboneliği kaldırabilirsiniz. Önce Pusher'ın bağlanmayı bitirmesini beklemenize gerek yoktur.

Örnek: "my-channel" kanalına abone olun.


Delphi
APIPusher.Subscribe('my-channel');

Başarıyla abone olduysanız OnPusherSubscribe olayı tetiklenir, bir hata varsa OnPusherError olayında bir mesaj alırsınız.

Abone olunan kanaldan gelen tüm mesajlar OnPusherEvent olayı aracılığıyla alınır.

Publish yöntemi çağrıldığında ve kanal Public olduğunda, bileşen WebSocket protokolü kullanmak yerine HTTP protokolü kullanır ve TriggerEvent yöntemini çağırır (websocket protokolü kullanılarak publish'e izin verilmez).

Private Channels

Indy 10.5.7 veya üzerini gerektirir

Bir kanala erişimin bir şekilde kısıtlanması gerektiğinde özel kanallar kullanılmalıdır. Bir kullanıcının özel bir kanala abone olabilmesi için iznin yetkilendirilmesi gerekir.

Örnek: "my-private-channel" kanalına abone olun.


Delphi
APIPusher.Subscribe('my-private-channel', pscPrivateChannel);

Başarıyla abone olduysanız OnPusherSubscribe olayı tetiklenir, bir hata varsa OnPusherError olayında bir mesaj alırsınız.

Abone olunan kanaldan gelen tüm mesajlar OnPusherEvent olayı aracılığıyla alınır.

Presence Kanalları

Indy 10.5.7 veya üzerini gerektirir

Presence kanalları, Private kanalların güvenliği üzerine kurulur ve o kanala kimin abone olduğunun farkındalığı gibi ek bir özellik sunar. Bu, uygulamanıza sohbet odası ve "çevrimiçi kim var" türünde işlevsellik oluşturmayı son derece kolaylaştırır. Sohbet odalarını, bir belge üzerinde işbirliği yapanları, aynı web sayfasını görüntüleyen kişileri, bir oyundaki rakipleri vb. düşünün.

Presence kanalları, istemci API'sinden özel kanallarla aynı şekilde abone olunur, ancak kanal adının önüne presence- eklenmelidir. Özel kanallarda olduğu gibi, geçerli kullanıcının kanala erişim izni olup olmadığını belirlemek için yapılandırılabilir bir kimlik doğrulama URL'sine bir HTTP İsteği yapılır.

Bir kanala abone olan ve abonelikten çıkan kullanıcılar hakkındaki bilgilere, presence kanalındaki olaylara bağlanarak erişilebilir; kanala abone olan kullanıcıların güncel durumu ise channel.members özelliği aracılığıyla kullanılabilir.

Örnek: "my-presence-channel" kanalına abone olun.


APIPusher.Subscribe('my-presence-channel', pscPresenceChannel,
  '{"user_id":"John_Smith","user_info":{"name":"John Smith"}}')

Başarıyla abone olduysanız OnPusherSubscribe olayı tetiklenir, bir hata varsa OnPusherError olayında bir mesaj alırsınız.

Abone olunan kanaldan gelen tüm mesajlar OnPusherEvent olayı aracılığıyla alınır.

Önbellek Kanalları

Bir önbellek kanalı, son tetiklenen olayı hatırlar ve bunu yeni abonelere ilk olay olarak gönderir.

Bir önbellek kanalında bir olay tetiklendiğinde, Pusher Channels bu olayı önbelleğe alır ve bir istemci bir önbellek kanalına abone olduğunda, önbelleğe alınmış bir değer varsa, bu değer o kanaldaki ilk olay olarak istemciye gönderilir. Bu davranış, geliştiricilerin başka bir yerden getirmek için ek mantık eklemeden başlangıç durumunu sağlamasına yardımcı olur.

Aşağıdaki Cache Kanalları desteklenir:

Public Cache Channel
Private Cache Channel
Presence Cache Channel

Örnek: "my-cache-channel" genel önbellek kanalına abone olun.


APIPusher.Subscribe('my-cache-channel', pscCacheChannel);

Başarıyla abone olduysanız OnPusherSubscribe olayı tetiklenir, bir hata varsa OnPusherError olayında bir mesaj alırsınız.

Abone olunan kanaldan gelen tüm mesajlar OnPusherEvent olayı aracılığıyla alınır.

Bir önbellek kanalına abone olurken önbelleğe alınmış bir olay yoksa, kanal adını sağlayan OnPusherCacheMiss olayı tetiklenir. Bu, uygulamanızın önbelleğe alınmış veri bulunmaması durumunu işlemesine olanak tanır.

Private-Encrypted Channels

Private-Encrypted kanallar, mesajlar için uçtan uca şifreleme sağlar. Private kanallar gibi kimlik doğrulama gerektirirler, ancak ek olarak tüm veri yükleri NaCl secretbox kullanılarak şifrelenir, böylece yalnızca yetkili aboneler içeriği okuyabilir. Pusher'ın kendisi bile mesajların şifresini çözemez.

Özel-şifrelenmiş kanalları kullanmak için, kimlik doğrulama sırasında bir SharedSecret sağlamalısınız. Paylaşılan gizli anahtar, mesaj verilerini şifrelemek ve şifresini çözmek için kullanılır.

Örnek: "my-encrypted-channel" adlı bir private-encrypted kanala abone olun.


APIPusher.Subscribe('my-encrypted-channel', pscPrivateEncryptedChannel);

Şifrelemeyi önbellek kanalı davranışıyla birleştiren özel-şifreli-önbellek varyantı da mevcuttur:


APIPusher.Subscribe('my-encrypted-cache-channel', pscPrivateEncryptedCacheChannel);

Private-encrypted kanallarla OnPusherAuthentication olayını kullanırken, şifreleme anahtarını sağlamak için yanıt nesnesinde SharedSecret özelliğini ayarlayabilirsiniz:


procedure OnPusherAuthenticationEvent(Sender: TObject;
  AuthRequest: TsgcWSPusherRequestAuthentication;
  AuthResponse: TsgcWSPusherResponseAuthentication);
begin
  AuthResponse.SharedSecret := 'your-shared-secret-key';
end;

Presence Events

Presence kanalları, kullanıcılar bir kanala katıldığında veya ayrıldığında uygulamanızı bilgilendiren ek olaylar sağlar ve abonelik sayılarını izlemenize olanak tanır.

OnPusherMemberAdded

Bir presence kanalına yeni bir üye abone olduğunda tetiklenir. Katılan üyenin kanal adını, kullanıcı kimliğini ve kullanıcı bilgilerini sağlar.


procedure PUSHERPusherMemberAdded(Sender: TObject;
  Channel, UserId, UserInfo: string);
begin
  Log('Member joined: ' + UserId + ' on ' + Channel);
end;

OnPusherMemberRemoved

Bir üye bir presence kanalından abonelikten çıktığında tetiklenir. Ayrılan üyenin kanal adını, kullanıcı kimliğini ve kullanıcı bilgisini sağlar.


procedure PUSHERPusherMemberRemoved(Sender: TObject;
  Channel, UserId, UserInfo: string);
begin
  Log('Member left: ' + UserId + ' on ' + Channel);
end;

OnPusherSubscriptionCount

Bir kanaldaki abonelik sayısı değiştiğinde tetiklenir. Kanal adını ve mevcut abone sayısını sağlar. Bu olay Pusher panonuzda etkinleştirilmelidir.


procedure PUSHERPusherSubscriptionCount(Sender: TObject;
  Channel: string; SubscriptionCount: Integer);
begin
  Log(Channel + ' has ' + IntToStr(SubscriptionCount) + ' subscribers');
end;

OnPusherCacheMiss

Önbelleğe alınmış olayı olmayan bir önbellek kanalına abone olunduğunda tetiklenir. Kanal adını sağlar. Bu, uygulamanızın önbelleğe alınmış veri kullanılamadığında durumu işlemesine olanak tanır, örneğin veriyi başka bir kaynaktan alarak.


procedure PUSHERPusherCacheMiss(Sender: TObject; Channel: string);
begin
  Log('Cache miss on: ' + Channel);
end;

Publish Messages

Yalnızca abone olunan kanallardan mesaj almakla kalmaz, aynı zamanda diğer abone olunan kullanıcılara da mesaj gönderebilirsiniz.

Kanalın abone olunan tüm kullanıcılarına bir mesaj göndermek için Publish yöntemini çağırın.

Örnek: "my-channel"in tüm abone olmuş kullanıcılarına bir olay gönderme


APIPusher.Publish('my-event', 'my-channel');

İstemci (bağlantı) başına saniyede 10'dan fazla mesaj yayınlamayın. Bu hız sınırının üzerinde tetiklenen tüm olaylar Pusher API tarafından reddedilir. Bu bir sistem sorunu değil, bir istemci sorunudur. Bir kanaldaki 100 istemci bu hızda mesaj gönderirse, her biri ayrıca saniyede 1.000 mesaj işlemek zorunda kalır! Bazı modern tarayıcılar bunu işleyebilse de, büyük olasılıkla iyi bir fikir değildir.

REST API

API, http://api-CLUSTER.pusher.com adresinde barındırılır, burada CLUSTER kendi uygulamalarınızın cluster'ı ile değiştirilir (örneğin eu).

HTTP durum kodları, isteklerin başarılı olup olmadığını göstermek için kullanılır. Aşağıdaki durumlar yaygındır:

200 Başarılı istek. Gövde, yanıt verilerinin bir JSON hash'ini içerecektir

400 Hata: ayrıntılar yanıt gövdesinde

401 Kimlik doğrulama hatası: yanıt gövdesi bir açıklama içerecektir

403 Forbidden: uygulama devre dışı veya mesaj kotası aşıldı

Aşağıdaki REST API işlevleri uygulanmıştır.

Function	Açıklama
TriggerEvent	Belirtilen kanalda yeni bir olay tetikler. İsteğe bağlı SocketId (bir istemciyi hariç tutmak için) ve Info parametrelerini destekler.
TriggerBatchEvents	Tek bir HTTP isteğinde birden çok olayı tetikler. Bir JSON olay nesneleri dizisi kabul eder.
GetChannels	Tüm etkin kanalların bir listesini sağlar. İsteğe bağlı FilterByPrefix ve Info parametrelerini destekler.
GetChannel	Belirli bir kanal hakkında bilgi sağlar. İsteğe bağlı bir Info parametresini destekler.
GetUsers	Bir kanala bağlı tüm kullanıcıların bir listesini sağlar.
TerminateUserConnections	Belirli bir kullanıcının tüm bağlantılarını kullanıcı ID'sine göre sonlandırır.

TriggerEvent

Bir veya daha fazla kanalda bir olay tetikler. Olay adını, kanal adını ve veri yükünü gerektirir.

Parameter	Açıklama
aEventName	Tetiklenecek olayın adı.
aChannel	Olayın tetikleneceği kanal adı.
aData	Olay verisi (JSON dizesi).
aSocketId (isteğe bağlı)	Olayı almaktan hariç tutulacak bir soket ID'si. Göndericinin kendi mesajını almasını önlemek için yararlıdır.
aInfo (isteğe bağlı)	Yanıta dahil edilecek özniteliklerin virgülle ayrılmış bir listesi (örneğin "subscription_count").


// trigger event on a channel
APIPusher.TriggerEvent('my-event', 'my-channel', 'Hello World');

// trigger event excluding the sender
APIPusher.TriggerEvent('my-event', 'my-channel', 'Hello World', '123.456');

// trigger event requesting subscription_count in the response
APIPusher.TriggerEvent('my-event', 'my-channel', 'Hello World', '', 'subscription_count');

TriggerBatchEvents

Tek bir API çağrısında birden çok olayı tetikler, bu her olay için ayrı istekler yapmaktan daha verimlidir. batch parametresi, her nesnenin "channel", "name" ve "data" alanlarına sahip olduğu bir olay nesneleri dizisini içeren bir JSON dizesi olmalıdır.


APIPusher.TriggerBatchEvents(
  '[{"channel":"my-channel","name":"my-event","data":"hello"},' +
  '{"channel":"my-channel-2","name":"my-event","data":"world"}]');

GetChannels

Etkin kanalların bir listesini döndürür. Sonuçları filtrelemek ve ek bilgi istemek için isteğe bağlı parametreleri destekler.

Parameter	Açıklama
aFilterByPrefix (isteğe bağlı)	Kanalları bir ad önekine göre filtreleyin (örneğin yalnızca presence kanallarını listelemek için "presence-").
aInfo (isteğe bağlı)	Yanıta dahil edilecek özniteliklerin virgülle ayrılmış listesi (örn. "user_count").


// get all channels
APIPusher.GetChannels;

// get only presence channels with user count
APIPusher.GetChannels('presence-', 'user_count');

GetChannel

Belirli bir kanal hakkında bilgi döndürür.

Parameter	Açıklama
aChannel	Hakkında bilgi alınacak kanalın adı.
aInfo (isteğe bağlı)	Dahil edilecek özniteliklerin virgülle ayrılmış listesi (örneğin "user_count,subscription_count").


// get channel info
APIPusher.GetChannel('presence-my-channel');

// get channel info with user count
APIPusher.GetChannel('presence-my-channel', 'user_count,subscription_count');

GetUsers

Bir presence kanalına bağlı kullanıcıların listesini döndürür. Kanal adı tam ön eki içermelidir (örneğin "presence-my-channel").


APIPusher.GetUsers('presence-my-channel');

TerminateUserConnections

Belirli bir kullanıcı tarafından kurulan tüm bağlantıları sonlandırır. Bu, belirli bir kullanıcıyı tüm kanallardan bağlantısını kesmeye zorlamak için kullanılabilir. Kullanıcı ID'si, kullanıcı bir presence kanalına abone olduğunda kullanılan "user_id" ile eşleşmelidir.


APIPusher.TerminateUserConnections('1234');

Özel Kimlik Doğrulama

Pusher yalnızca özel veya presence kanallarına abone olmaya izin verir, bağlantı bir kimlik doğrulama token'ı sağlarsa, bu erişimi kısıtlamanıza olanak tanır.

OnPusherAuthentication olayını kullanarak kendi Kimlik Doğrulama akışınızı oluşturabilirsiniz; bu olay, abonelik mesajı Pusher tarafından sağlanan secret key ile imzalanmadan önce çağrılır. Bu olay, kendi kimlik doğrulama sunucunuz tarafından isteğin kimliğini doğrulamak veya doğrulamamak için kullanılabilecek SocketId, kanal adı gibi alanlara sahip bir request authentication olmak üzere 2 parametreye sahiptir. Aşağıda pusher kimlik doğrulama akışını gösteren bir ekran görüntüsü bulun

Bir istemci pusher sunucusuna bağlandığında, pusher tarafından sağlanan Key'i gönderir ve sunucu bir tanımlama kimliği (socket_id) döndürür.

Bir istemci özel (veya presence) bir kanala abone olduğunda, sgcWebSockets istemcisi, abonelik mesajına dahil edilen bir imza oluşturmak için pusher tarafından sağlanan Secret Key'i kullanır. OnPusherAutentication olayını kullanarak, mesajı imzalamak için gereken alanları yakalayabilir, kendi kimlik doğrulama yöntemlerinizi uygulayabilir ve başarılı olursa imzayı döndürürsünüz; bu imza abonelik mesajına dahil edilir ve sunucuya gönderilir.

Örnek:


oClient := TsgcWebSocketClient.Create(nil);
oPusher := TsgcWSAPI_Pusher.Create(nil);
oPusher.Client := oClient;
oPusher.Cluster := 'eu';
Pusher.Name := 'js';
Pusher.Version := '4.1';
Pusher.TLS := True;
Pusher.Key := '9c3b7ef25qe97a00116c';
Pusher.Secret := ''; // the secret key is not known by the client, only by the authentication module

oPusher.OnPusherAuthentication := OnPusherAuthenticationEvent;

procedure OnPusherAuthenticationEvent(Sender: TObject; AuthRequest: TsgcWSPusherRequestAuthentication;
  AuthResponse: TsgcWSPusherResponseAuthentication);
begin
  // if the authentication request is successful return the signature
  if CustomAuthentication(AuthRequest.Channel, AuthRequest.SocketID) then
    AuthResponse.Signature := GetCustomAuthenticationSignature;
end;

İmzanın biçimi şöyledir:

Özel kanallar: key:HMAC256(SocketID, ChannelName)

Presence kanalları: anahtar: HMAC256(SocketID, ChannelName, Data)

TsgcWSPusherResponseAuthentication nesnesi aşağıdaki özellikleri sağlar:

Özellik	Açıklama
Secret	HMAC imzasını hesaplamak için kullanılan Pusher secret key. Yapılandırılmışsa Pusher.Secret ile önceden doldurulur.
Signature	Hesaplanan kimlik doğrulama imzası. Boş bırakılırsa, bileşen onu Secret'ı kullanarak otomatik olarak hesaplar.
SharedSecret	Özel şifrelenmiş kanallar için paylaşılan gizli anahtar. pscPrivateEncryptedChannel veya pscPrivateEncryptedCacheChannel aboneliğinde gereklidir. Mesaj verilerinin uçtan uca şifrelenmesi için kullanılır.