API Pusher
Klicken Sie hier, um diese Seite im vollständigen Kontext anzuzeigen

API Pusher

Pusher

Pusher ist eine einfache und zuverlässige Plattform mit netten Funktionen, die auf dem WebSocket-Protokoll basieren: flexibles Pub/Sub-Messaging, Live-Benutzerlisten (Präsenz), Authentifizierung ...

Die Pusher-WebSocket-API ist 7.

Daten werden bidirektional über einen WebSocket als Textdaten gesendet, die UTF8-kodiertes JSON enthalten (binäre WebSocket-Frames werden nicht unterstützt).

Sie können die Methode Ping aufrufen, um die Verbindung zum Server zu testen. Im Wesentlichen werden alle von der Gegenseite empfangenen Nachrichten als Hinweis darauf gewertet, dass die Verbindung aktiv ist. Bei Abwesenheit jeglicher Nachrichten kann jede Seite prüfen, ob die andere Seite antwortet, indem sie eine Ping-Nachricht sendet, auf die die andere Seite mit einem Pong antworten sollte.

Bevor Sie eine Verbindung herstellen, müssen Sie die folgenden Felder ausfüllen:


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)

Wichtig

Pusher erfordert, dass der WebSocket-Client sich mit einer URL verbindet, die die vorherigen Felder (key, cluster...) verwendet; diese Felder werden zum Erstellen der URL verwendet, und dies geschieht, wenn Sie den Client in der Pusher-Komponente zuweisen. Um sicherzustellen, dass die URL korrekt erstellt wird, setzen Sie den Client also, nachdem Sie die Pusher-Konfigurationsfelder ausgefüllt haben. Unten finden Sie Pseudo-Code:

// Pusher-Felder konfigurieren

pusher.cluster = ...

pusher.key = ...

// Client festlegen

pusher.client = websocket client

// Verbindung starten

websocket client.Active = true;

Nach einer erfolgreichen Verbindung wird das Ereignis OnPusherConnect ausgelöst, und Sie erhalten die folgenden Felder:

Im Fehlerfall wird OnPusherError ausgelöst und Informationen über den Fehler bereitgestellt. Ein Fehler kann von Pusher als Antwort auf eine ungültige Authentifizierung, einen ungültigen Befehl usw. gesendet werden.

4000-4099

Zeigt einen Fehler an, der dazu führt, dass die Verbindung von Pusher geschlossen wird, und dass ein erneuter Verbindungsversuch mit denselben Parametern nicht erfolgreich sein wird.

4000: Die Anwendung akzeptiert nur SSL-Verbindungen, stellen Sie die Verbindung über wss:// wieder her

4001: Anwendung existiert nicht

4003: Application disabled

4004: Application is over connection quota

4005: Pfad nicht gefunden

4006: Invalid version string format

4007: Nicht unterstützte Protokollversion

4008: Keine Protokollversion angegeben

4100-4199

Gibt einen Fehler an, der dazu führt, dass die Verbindung von Pusher geschlossen wird, und dass der Client sich nach 1 s oder mehr erneut verbinden kann.

4100: Over capacity

4200-4299

Zeigt einen Fehler an, der dazu führt, dass die Verbindung von Pusher geschlossen wird, und dass der Client sofort erneut verbinden darf.

4200: Generisch sofort erneut verbinden

4201: Pong-Antwort nicht empfangen: Ein Ping wurde an den Client gesendet, aber es wurde keine Antwort empfangen - siehe Ping- und Pong-Nachrichten

4202: Nach Inaktivität geschlossen: Der Client war lange Zeit inaktiv (derzeit 24 Stunden) und der Client unterstützt kein Ping. Bitte aktualisieren Sie auf einen neueren WebSocket-Draft oder implementieren Sie Version 5 oder höher dieses Protokolls.

4300-4399

Jede andere Art von Fehler.

4301: Client-Ereignis aufgrund von Ratenbegrenzung abgelehnt

Kanäle

Channels sind ein grundlegendes Konzept in Pusher. Jede Anwendung hat eine Reihe von Kanälen, und jeder Client kann auswählen, welche Kanäle er abonniert.

Channels bieten:

Es wird dringend empfohlen, dass Channels verwendet werden, um Ihre Daten zu filtern, und dass dies nicht über Events erreicht wird. Das liegt daran, dass alle auf einem Channel veröffentlichten Events an alle Subscriber gesendet werden, unabhängig von ihrer Event-Bindung.

Channels müssen nicht explizit erstellt werden und werden bei Bedarf des Clients instanziiert. Das bedeutet, dass das Erstellen eines Channels einfach ist. Weisen Sie einen Client einfach an, ihn zu abonnieren.

Die folgenden Arten von Kanälen werden unterstützt:

Public Channels

Öffentliche Kanäle sollten für öffentlich zugängliche Daten verwendet werden, da sie keinerlei Autorisierung erfordern, um abonniert werden zu können.

Sie können Kanäle jederzeit abonnieren und abbestellen. Es ist nicht erforderlich, zuerst zu warten, bis Pusher die Verbindung hergestellt hat.

Beispiel: Abonnieren des Kanals "my-channel".


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

Wenn Sie erfolgreich abonniert sind, wird das Ereignis OnPusherSubscribe ausgelöst; wenn ein Fehler auftritt, erhalten Sie eine Nachricht im Ereignis OnPusherError.

Alle Nachrichten vom abonnierten Kanal werden im Ereignis OnPusherEvent empfangen.

Wenn die Methode Publish aufgerufen wird und der Kanal öffentlich ist, verwendet die Komponente anstelle des WebSocket-Protokolls das HTTP-Protokoll und ruft die Methode TriggerEvent auf (Publish ist über das WebSocket-Protokoll nicht erlaubt).

Private Kanäle

Erfordert Indy 10.5.7 oder neuer

Private Kanäle sollten verwendet werden, wenn der Zugriff auf den Kanal in irgendeiner Weise eingeschränkt werden muss. Damit ein Benutzer einen privaten Kanal abonnieren kann, muss die Berechtigung autorisiert werden.

Beispiel: Abonnieren des Kanals "my-private-channel".


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

Wenn Sie erfolgreich abonniert sind, wird das Ereignis OnPusherSubscribe ausgelöst; wenn ein Fehler auftritt, erhalten Sie eine Nachricht im Ereignis OnPusherError.

Alle Nachrichten vom abonnierten Kanal werden im Ereignis OnPusherEvent empfangen.

Presence-Kanäle

Erfordert Indy 10.5.7 oder neuer

Presence-Kanäle bauen auf der Sicherheit von privaten Kanälen auf und stellen die zusätzliche Funktion einer Kenntnis darüber bereit, wer diesen Kanal abonniert hat. Dies macht es extrem einfach, Chatroom- und "Wer ist online"-Funktionalität für Ihre Anwendung zu erstellen. Denken Sie an Chatrooms, Mitarbeiter an einem Dokument, Personen, die dieselbe Webseite betrachten, Konkurrenten in einem Spiel, solche Dinge.

Presence-Kanäle werden von der Client-API auf dieselbe Weise abonniert wie private Kanäle, aber dem Kanalnamen muss presence- vorangestellt werden. Wie bei privaten Kanälen wird eine HTTP-Anfrage an eine konfigurierbare Authentifizierungs-URL gestellt, um zu bestimmen, ob der aktuelle Benutzer die Berechtigung hat, auf den Kanal zuzugreifen.

Informationen über Benutzer, die einen Kanal abonnieren und sich von ihm abmelden, können dann durch Binden an Ereignisse auf dem Presence-Kanal abgerufen werden, und der aktuelle Zustand der für den Kanal abonnierten Benutzer ist über die Eigenschaft channel.members verfügbar.

Beispiel: Abonnieren Sie den Kanal "my-presence-channel".


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

Wenn Sie erfolgreich abonniert sind, wird das Ereignis OnPusherSubscribe ausgelöst; wenn ein Fehler auftritt, erhalten Sie eine Nachricht im Ereignis OnPusherError.

Alle Nachrichten vom abonnierten Kanal werden im Ereignis OnPusherEvent empfangen.

Cache Channels

Ein Cache-Kanal merkt sich das zuletzt ausgelöste Ereignis und sendet dies als erstes Ereignis an neue Abonnenten.

Wenn ein Ereignis auf einem Cache-Kanal ausgelöst wird, speichert Pusher Channels dieses Ereignis zwischen, und wenn ein Client einen Cache-Kanal abonniert und ein zwischengespeicherter Wert existiert, wird dieser als erstes Ereignis auf diesem Kanal an den Client gesendet. Dieses Verhalten hilft Entwicklern, den Anfangszustand bereitzustellen, ohne zusätzliche Logik hinzuzufügen, um ihn von woanders abzurufen.

Die folgenden Cache-Kanäle werden unterstützt:

Beispiel: Abonnieren des öffentlichen Cache-Kanals "my-cache-channel".


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

Wenn Sie erfolgreich abonniert sind, wird das Ereignis OnPusherSubscribe ausgelöst; wenn ein Fehler auftritt, erhalten Sie eine Nachricht im Ereignis OnPusherError.

Alle Nachrichten vom abonnierten Kanal werden im Ereignis OnPusherEvent empfangen.

Wenn beim Abonnieren eines Cache-Channels kein zwischengespeichertes Ereignis vorhanden ist, wird das Ereignis OnPusherCacheMiss ausgelöst und der Channel-Name bereitgestellt. Dies ermöglicht Ihrer Anwendung, den Fall zu behandeln, in dem keine zwischengespeicherten Daten verfügbar sind.

Private-Encrypted-Kanäle

Private-Encrypted-Kanäle bieten Ende-zu-Ende-Verschlüsselung für Nachrichten. Wie private Kanäle erfordern sie eine Authentifizierung, aber zusätzlich werden alle Daten-Nutzlasten mit NaCl secretbox verschlüsselt, sodass nur autorisierte Abonnenten den Inhalt lesen können. Selbst Pusher selbst kann die Nachrichten nicht entschlüsseln.

Um private verschlüsselte Channels zu verwenden, müssen Sie bei der Authentifizierung ein SharedSecret angeben. Das Shared Secret wird zum Ver- und Entschlüsseln von Nachrichtendaten verwendet.

Beispiel: Abonnieren eines private-encrypted-Kanals "my-encrypted-channel".


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

Eine Variante mit privatem verschlüsseltem Cache ist ebenfalls verfügbar, die Verschlüsselung mit Cache-Channel-Verhalten kombiniert:


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

Wenn Sie das Ereignis OnPusherAuthentication mit verschlüsselten privaten Kanälen verwenden, können Sie die Eigenschaft SharedSecret auf dem Antwortobjekt setzen, um den Verschlüsselungsschlüssel bereitzustellen:


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

Presence-Ereignisse

Presence-Channels bieten zusätzliche Ereignisse, die Ihre Anwendung benachrichtigen, wenn Benutzer einem Channel beitreten oder ihn verlassen, und ermöglichen es Ihnen, Abonnementzahlen zu verfolgen.

OnPusherMemberAdded

Wird ausgelöst, wenn ein neues Mitglied einen Presence-Kanal abonniert. Stellt den Kanalnamen, die Benutzer-ID und die Benutzerinformationen des beigetretenen Mitglieds bereit.


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

OnPusherMemberRemoved

Wird ausgelöst, wenn sich ein Mitglied von einem Presence-Kanal abmeldet. Stellt den Kanalnamen, die Benutzer-ID und die Benutzerinformationen des Mitglieds bereit, das ihn verlassen hat.


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

OnPusherSubscriptionCount

Wird ausgelöst, wenn sich die Abonnentenanzahl auf einem Kanal ändert. Stellt den Kanalnamen und die aktuelle Anzahl der Abonnenten bereit. Dieses Ereignis muss in Ihrem Pusher-Dashboard aktiviert werden.


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

OnPusherCacheMiss

Wird ausgelöst, wenn ein Cache-Kanal abonniert wird, der kein zwischengespeichertes Ereignis hat. Stellt den Kanalnamen bereit. Dies ermöglicht es Ihrer Anwendung, den Fall zu behandeln, in dem keine zwischengespeicherten Daten verfügbar sind, zum Beispiel indem die Daten aus einer anderen Quelle abgerufen werden.


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

Nachrichten veröffentlichen

Sie können nicht nur Nachrichten von abonnierten Kanälen empfangen, sondern auch Nachrichten an andere abonnierte Benutzer senden.

Rufen Sie die Methode Publish auf, um eine Nachricht an alle abonnierten Benutzer des Kanals zu senden.

Beispiel: ein Ereignis an alle abonnierten Benutzer von "my-channel" senden


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

Veröffentlichen Sie nicht mehr als 10 Nachrichten pro Sekunde pro Client (Verbindung). Alle Ereignisse, die über dieser Ratenbegrenzung ausgelöst werden, werden von der Pusher-API abgelehnt. Dies ist kein Systemproblem, es ist ein Client-Problem. 100 Clients in einem Kanal, die mit dieser Rate Nachrichten senden, müssten jeweils auch 1.000 Nachrichten pro Sekunde verarbeiten! Während einige moderne Browser dies bewältigen könnten, ist es höchstwahrscheinlich keine gute Idee.

REST API

Die API wird unter http://api-CLUSTER.pusher.com gehostet, wobei CLUSTER durch den Cluster Ihrer eigenen Apps ersetzt wird (zum Beispiel eu).

HTTP-Statuscodes werden verwendet, um den Erfolg oder Misserfolg von Anforderungen anzuzeigen. Die folgenden Status sind häufig:

200 Erfolgreiche Anfrage. Der Body enthält einen JSON-Hash von Antwortdaten

400 Fehler: Details im Antworttext

401 Authentifizierungsfehler: Der Antwort-Body enthält eine Erklärung

403 Forbidden: App deaktiviert oder Nachrichtenkontingent überschritten

Die folgenden REST-API-Funktionen wurden implementiert.

Function Beschreibung
TriggerEvent Löst ein neues Event auf dem angegebenen Channel aus. Unterstützt optionale SocketId- (um einen Client auszuschließen) und Info-Parameter.
TriggerBatchEvents Löst mehrere Ereignisse in einer einzigen HTTP-Anfrage aus. Akzeptiert ein JSON-Array von Ereignisobjekten.
GetChannels Stellt eine Liste aller aktiven Kanäle bereit. Unterstützt optionale FilterByPrefix- und Info-Parameter.
GetChannel Stellt Informationen über einen bestimmten Kanal bereit. Unterstützt einen optionalen Info-Parameter.
GetUsers Stellt eine Liste aller mit einem Kanal verbundenen Benutzer bereit.
TerminateUserConnections Beendet alle Verbindungen eines bestimmten Benutzers anhand seiner Benutzer-ID.

TriggerEvent

Löst ein Ereignis auf einem oder mehreren Kanälen aus. Erfordert den Ereignisnamen, den Kanalnamen und die Datennutzlast.

Parameter Beschreibung
aEventName Der Name des auszulösenden Ereignisses.
aChannel Der Name des Kanals, auf dem das Ereignis ausgelöst werden soll.
aData Die Ereignisdaten (JSON-Zeichenkette).
aSocketId (optional) Eine Socket-ID, die vom Empfang des Events ausgeschlossen werden soll. Nützlich, um zu verhindern, dass der Sender seine eigene Nachricht empfängt.
aInfo (optional) Eine durch Kommas getrennte Liste von Attributen, die in die Antwort aufgenommen werden sollen (z. B. "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

Löst mehrere Ereignisse in einem einzigen API-Aufruf aus, was effizienter ist, als für jedes Ereignis separate Anfragen zu stellen. Der Parameter batch muss eine JSON-Zeichenfolge sein, die ein Array von Ereignisobjekten enthält, wobei jedes Objekt die Felder "channel", "name" und "data" hat.


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

GetChannels

Gibt eine Liste der aktiven Kanäle zurück. Unterstützt optionale Parameter, um die Ergebnisse zu filtern und zusätzliche Informationen anzufordern.

Parameter Beschreibung
aFilterByPrefix (optional) Filtert Kanäle nach einem Namenspräfix (z. B. "presence-", um nur Presence-Kanäle aufzulisten).
aInfo (optional) Eine durch Kommata getrennte Liste von Attributen, die in die Antwort aufgenommen werden sollen (z. B. "user_count"). 


// get all channels
APIPusher.GetChannels;

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

GetChannel

Gibt Informationen über einen bestimmten Channel zurück.

Parameter Beschreibung
aChannel Der Kanalname, über den Informationen abgerufen werden sollen.
aInfo (optional) Eine durch Kommas getrennte Liste von Attributen, die einbezogen werden sollen (z. B. "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

Gibt eine Liste der mit einem Presence-Kanal verbundenen Benutzer zurück. Der Kanalname muss das vollständige Präfix enthalten (z. B. "presence-my-channel").


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

TerminateUserConnections

Beendet alle von einem bestimmten Benutzer hergestellten Verbindungen. Dies kann verwendet werden, um einen bestimmten Benutzer zur Trennung von allen Kanälen zu zwingen. Die Benutzer-ID muss mit der beim Abonnieren eines Presence-Kanals verwendeten "user_id" übereinstimmen.


APIPusher.TerminateUserConnections('1234');

Benutzerdefinierte Authentifizierung

Pusher erlaubt nur das Abonnieren von privaten oder Presence-Kanälen; wenn die Verbindung ein Authentifizierungstoken bereitstellt, ermöglicht Ihnen dies, den Zugriff einzuschränken.

Sie können Ihren eigenen Authentifizierungs-Ablauf mit dem Ereignis OnPusherAuthentication erstellen. Dieses Ereignis wird aufgerufen, bevor die Subscription-Nachricht mit dem von Pusher bereitgestellten geheimen Schlüssel signiert wird. Dieses Ereignis hat 2 Parameter: eine Request-Authentifizierung mit Feldern wie SocketId, Channel-Name usw., die von Ihrem eigenen Authentifizierungsserver verwendet werden können, um die Anfrage zu authentifizieren oder nicht. Nachfolgend finden Sie einen Screenshot, der den Pusher-Authentifizierungsablauf zeigt

Wenn sich ein Client mit dem Pusher-Server verbindet, sendet er den von Pusher bereitgestellten Key, und der Server gibt eine Identifikations-ID (socket_id) zurück.

Wenn ein Client einen privaten (oder Presence-) Channel abonniert, verwendet der sgcWebSockets-Client den von Pusher bereitgestellten Secret Key, um eine Signatur zu erstellen, die in die Abonnementnachricht aufgenommen wird. Über das Ereignis OnPusherAutentication können Sie die zum Signieren der Nachricht erforderlichen Felder erfassen, eigene Authentifizierungsmethoden implementieren und bei Erfolg die Signatur zurückgeben; diese Signatur wird dann in die Abonnementnachricht aufgenommen und an den Server gesendet.

Beispiel:


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;

Das Format der Signatur lautet:

Private channels: key:HMAC256(SocketID, ChannelName)

Presence-Kanäle: Schlüssel: HMAC256(SocketID, ChannelName, Data)

Das Objekt TsgcWSPusherResponseAuthentication stellt die folgenden Eigenschaften bereit:

Eigenschaft Beschreibung
Secret Der Pusher-Secret-Key, der zur Berechnung der HMAC-Signatur verwendet wird. Vorausgefüllt mit Pusher.Secret, falls konfiguriert.
Signatur Die berechnete Authentifizierungssignatur. Wenn leer gelassen, berechnet die Komponente sie automatisch unter Verwendung des Secrets.
SharedSecret Der gemeinsame geheime Schlüssel für privat verschlüsselte Kanäle. Erforderlich beim Abonnieren von pscPrivateEncryptedChannel oder pscPrivateEncryptedCacheChannel. Wird für die End-to-End-Verschlüsselung von Nachrichtendaten verwendet.