API Pusher
Klik hier om deze pagina in volledige context te bekijken

API Pusher

Pusher

Pusher is een eenvoudig en betrouwbaar platform met mooie functies gebaseerd op het WebSocket-protocol: flexibel pub/sub-berichten, live gebruikerslijsten (aanwezigheid), authenticatie...

De Pusher WebSocket API-versie is 7.

Gegevens worden bidirectioneel over een WebSocket verzonden als tekstgegevens met UTF8-gecodeerde JSON (binaire WebSocket-frames worden niet ondersteund).

U kunt de methode Ping aanroepen om de verbinding met de server te testen. Alle berichten die van de andere partij worden ontvangen, worden beschouwd als bewijs dat de verbinding actief is. Als er geen berichten zijn, kan een van beide partijen controleren of de andere kant reageert door een ping-bericht te sturen, waarop de andere partij met een pong moet antwoorden.

Voordat u verbinding maakt, moet u de volgende velden invullen:


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)

Belangrijk

Pusher vereist dat de websocket-client verbinding maakt met een URL met behulp van de vorige velden (sleutel, cluster...), deze velden worden gebruikt om de URL op te bouwen en dit wordt gedaan wanneer u de client in de Pusher-component toewijst. Zorg er dus voor dat de URL correct is opgebouwd door de client in te stellen nadat u de Pusher-configuratievelden hebt ingevuld. Hieronder vindt u pseudocode:

// configure pusher fields

pusher.cluster = ...

pusher.key = ...

// stel client in

pusher.client = websocket client

// start connection

websocket client.Active = true;

Na een succesvolle verbinding wordt het evenement OnPusherConnect geactiveerd en ontvangt u de volgende velden:

In geval van een fout wordt OnPusherError gegenereerd met informatie over de fout. Een fout kan worden verzonden door Pusher als reactie op ongeldige authenticatie, een ongeldig commando, enz.

4000-4099

Indicates een fout resulting in the verbinding being closed by Pusher, and that attempting to reconnect using the dezelfde parameters will not succeed.

4000: Applicatie accepteert alleen SSL-verbindingen, maak opnieuw verbinding via wss://

4001: Applicatie bestaat niet

4003: Applicatie uitgeschakeld

4004: Applicatie heeft verbindingsquotum overschreden

4005: Pad niet gevonden

4006: Ongeldige opmaak van versietekenreeks

4007: Niet-ondersteunde protocolversie

4008: Geen protocolversie opgegeven

4100-4199

Geeft een fout aan die resulteert in het sluiten van de verbinding door Pusher, en de client kan na 1 seconde of meer opnieuw verbinding maken.

4100: Capaciteit overschreden

4200-4299

Geeft een fout aan die resulteert in het sluiten van de verbinding door Pusher, en dat de client onmiddellijk opnieuw verbinding kan maken.

4200: Generic reconnect immediately

4201: Pong-reactie niet ontvangen: ping is naar de client verzonden, maar er is geen reactie ontvangen — zie ping- en pong-berichten.

4202: Gesloten na inactiviteit: De client is gedurende een lange tijd inactief geweest (momenteel 24 uur) en de client ondersteunt ping niet. Upgrade naar een nieuwere WebSocket-versie of implementeer versie 5 of hoger van dit protocol.

4300-4399

Any other type of error.

4301: Clientgebeurtenis geweigerd vanwege snelheidslimiet

Kanalen

Kanalen zijn een fundamenteel concept in Pusher. Elke applicatie heeft een aantal kanalen en elke client kan kiezen op welke kanalen hij zich abonneert.

Kanalen bieden:

Het wordt sterk aanbevolen om kanalen te gebruiken om uw gegevens te filteren en dit niet te bereiken via gebeurtenissen. Dit komt doordat alle gebeurtenissen die op een kanaal worden gepubliceerd, naar alle abonnees worden verzonden, ongeacht hun gebeurtenisbinding.

Kanalen hoeven niet expliciet te worden aangemaakt en worden op verzoek van de client geïnstantieerd. Dit betekent dat het aanmaken van een kanaal eenvoudig is. Vertel een client gewoon om erop te abonneren.

De volgende typen kanalen worden ondersteund:

Openbare kanalen

Publieke kanalen moeten worden gebruikt voor openbaar toegankelijke gegevens omdat ze geen enkele vorm van autorisatie vereisen om op te abonneren.

U kunt op elk moment abonneren en afmelden van kanalen. Het is niet nodig te wachten tot Pusher klaar is met verbinden.

Voorbeeld: abonneer u op kanaal "my-channel".


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

Als u met succes bent geabonneerd, wordt de gebeurtenis OnPusherSubscribe geactiveerd; als er een fout is, ontvangt u een bericht in de gebeurtenis OnPusherError.

Alle berichten van het geabonneerde kanaal worden ontvangen via de OnPusherEvent-gebeurtenis.

Wanneer de Publish-methode wordt aangeroepen en het kanaal Openbaar is, gebruikt het component in plaats van het WebSocket-protocol het HTTP-protocol en roept de methode TriggerEvent aan (publiceren is niet toegestaan via het WebSocket-protocol).

Privékanalen

Vereist Indy 10.5.7 of hoger

Privékanalen moeten worden gebruikt wanneer de toegang tot het kanaal op een bepaalde manier beperkt moet zijn. Om een gebruiker in staat te stellen zich op een privékanaal te abonneren, moet toestemming worden geautoriseerd.

Voorbeeld: abonneer op kanaal "my-private-channel".


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

Als u met succes bent geabonneerd, wordt de gebeurtenis OnPusherSubscribe geactiveerd; als er een fout is, ontvangt u een bericht in de gebeurtenis OnPusherError.

Alle berichten van het geabonneerde kanaal worden ontvangen via de OnPusherEvent-gebeurtenis.

Presence-kanalen

Vereist Indy 10.5.7 of hoger

Presence-kanalen bouwen voort op de beveiliging van privékanalen en bieden de extra functie van bewustzijn van wie is geabonneerd op dat kanaal. Dit maakt het bijzonder eenvoudig om chatroom- en "wie is online"-functionaliteit aan uw applicatie toe te voegen. Denk aan chatrooms, medewerkers op een document, mensen die dezelfde webpagina bekijken, concurrenten in een spel, dat soort dingen.

Presence-kanalen worden vanaf de client-API op dezelfde manier geabonneerd als privékanalen, maar de kanaalnaam moet worden voorafgegaan door presence-. Net als bij privékanalen wordt een HTTP-verzoek gedaan naar een configureerbare authenticatie-URL om te bepalen of de huidige gebruiker machtigingen heeft om toegang te krijgen tot het kanaal.

Informatie over gebruikers die zich abonneren op en afmelden van een kanaal kan worden benaderd door te binden aan evenementen op het presence-kanaal en de huidige staat van gebruikers die geabonneerd zijn op het kanaal is beschikbaar via de eigenschap channel.members.

Voorbeeld: abonneer u op kanaal "my-presence-channel".


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

Als u met succes bent geabonneerd, wordt de gebeurtenis OnPusherSubscribe geactiveerd; als er een fout is, ontvangt u een bericht in de gebeurtenis OnPusherError.

Alle berichten van het geabonneerde kanaal worden ontvangen via de OnPusherEvent-gebeurtenis.

Cachekanalen

Een cachekanaal onthoudt het laatste geactiveerde evenement en stuurt dit als eerste evenement naar nieuwe abonnees.

Wanneer een gebeurtenis wordt geactiveerd op een cachekanaal, slaat Pusher Channels deze gebeurtenis op, en wanneer een client zich abonneert op een cachekanaal, wordt als er een gecachede waarde bestaat, deze als eerste gebeurtenis op dat kanaal naar de client verzonden. Dit gedrag helpt ontwikkelaars de beginstatus aan te bieden zonder extra logica toe te voegen om deze elders op te halen.

De volgende cachekanalen worden ondersteund:

Voorbeeld: abonneer u op het openbare cachekanaal "my-cache-channel".


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

Als u met succes bent geabonneerd, wordt de gebeurtenis OnPusherSubscribe geactiveerd; als er een fout is, ontvangt u een bericht in de gebeurtenis OnPusherError.

Alle berichten van het geabonneerde kanaal worden ontvangen via de OnPusherEvent-gebeurtenis.

Als er geen gecached evenement is bij het abonneren op een cachekanaal, wordt de gebeurtenis OnPusherCacheMiss gegenereerd, die de kanaalnaam biedt. Hierdoor kan uw toepassing omgaan met het geval waarbij er geen gecachede gegevens beschikbaar zijn.

Privé-versleutelde kanalen

Privé-versleutelde kanalen bieden end-to-end-versleuteling voor berichten. Net als privékanalen vereisen ze authenticatie, maar bovendien worden alle gegevenspayloads versleuteld met NaCl secretbox, zodat alleen geautoriseerde abonnees de inhoud kunnen lezen. Zelfs Pusher zelf kan de berichten niet ontsleutelen.

Om privé-versleutelde kanalen te gebruiken, moet u een SharedSecret opgeven tijdens authenticatie. Het gedeelde geheim wordt gebruikt voor het versleutelen en ontsleutelen van berichtgegevens.

Voorbeeld: abonneer u op een privé-versleuteld kanaal "my-encrypted-channel".


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

Er is ook een privé-versleuteld-cache-variant beschikbaar, die versleuteling combineert met cachekanaalgedrag:


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

Bij gebruik van de gebeurtenis OnPusherAuthentication met privé-gecodeerde kanalen kunt u de eigenschap SharedSecret instellen op het antwoordobject om de coderingssleutel op te geven:


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

Aanwezigheidsgebeurtenissen

Presence-kanalen bieden aanvullende gebeurtenissen die uw applicatie informeren wanneer gebruikers een kanaal betreden of verlaten, en bieden de mogelijkheid om het aantal abonnees bij te houden.

OnPusherMemberAdded

Wordt geactiveerd wanneer een nieuw lid zich abonneert op een presence-kanaal. Geeft de kanaalnaam, gebruikers-ID en gebruikersinformatie van het lid dat zich heeft aangemeld.


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

OnPusherMemberRemoved

Geactiveerd wanneer een lid zich afmeldt voor een aanwezigheidskanaal. Biedt de kanaalnaam, het gebruikers-ID en de gebruikersinformatie van het lid dat het kanaal heeft verlaten.


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

OnPusherSubscriptionCount

Wordt geactiveerd wanneer het abonnementenaantal op een kanaal verandert. Biedt de kanaalnaam en het huidige aantal abonnees. Deze gebeurtenis moet zijn ingeschakeld op uw Pusher-dashboard.


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

OnPusherCacheMiss

Wordt geactiveerd bij het abonneren op een cachekanaal dat geen gecached evenement heeft. Geeft de kanaalnaam. Hierdoor kan uw applicatie de situatie afhandelen waarbij geen gecachte gegevens beschikbaar zijn, bijvoorbeeld door de gegevens uit een andere bron op te halen.


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

Berichten publiceren

U kunt niet alleen berichten ontvangen van geabonneerde kanalen, maar ook berichten sturen naar andere geabonneerde gebruikers.

Roep de methode Publish aan om een bericht te sturen naar alle geabonneerde gebruikers van het kanaal.

Voorbeeld: stuur een gebeurtenis naar alle geabonneerde gebruikers van "my-channel"


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

Publiceer niet meer dan 10 berichten per seconde per client (verbinding). Alle gebeurtenissen die boven deze snelheidslimiet worden geactiveerd, worden geweigerd door de Pusher API. Dit is geen systeemprobleem, maar een clientprobleem. 100 clients in een kanaal die berichten verzenden met deze snelheid, zouden elk ook 1.000 berichten per seconde moeten verwerken! Hoewel sommige moderne browsers dit misschien aankunnen, is het hoogstwaarschijnlijk geen goed idee.

REST API

De API wordt gehost op http://api-CLUSTER.pusher.com, waarbij CLUSTER wordt vervangen door uw eigen apps-cluster (bijvoorbeeld eu).

HTTP-statuscodes worden gebruikt om het succes of anderszins van verzoeken aan te geven. De volgende statussen zijn gebruikelijk:

200 Geslaagd verzoek. De body bevat een JSON-hash met responsgegevens

400 Fout: details in de responsbody

401 Authenticatiefout: de antwoordtekst bevat een toelichting

403 Verboden: app uitgeschakeld of berichtquotum overschreden

De volgende REST API-functies zijn geïmplementeerd.

Functie Beschrijving
TriggerEvent Activeert een nieuwe gebeurtenis op het opgegeven kanaal. Ondersteunt optionele parameters SocketId (om een client uit te sluiten) en Info.
TriggerBatchEvents Activeert meerdere evenementen in één HTTP-verzoek. Accepteert een JSON-array van evenementobjecten.
GetChannels Biedt een lijst van alle actieve kanalen. Ondersteunt optionele FilterByPrefix- en Info-parameters.
GetChannel Geeft informatie over een specifiek kanaal. Ondersteunt een optionele Info-parameter.
GetUsers Geeft een lijst van alle gebruikers die zijn verbonden met een kanaal.
TerminateUserConnections Terminates all connections for a given user by their user ID.

TriggerEvent

Activeert een gebeurtenis op een of meer kanalen. Vereist de gebeurtenisnaam, kanaalnaam en datapayload.

Parameter Beschrijving
aEventName De naam van de te activeren gebeurtenis.
aChannel De kanaalnaam waarop de gebeurtenis moet worden geactiveerd.
aData De gebeurtenisgegevens (JSON-tekenreeks).
aSocketId (optioneel) Een socket-ID om uit te sluiten van het ontvangen van de gebeurtenis. Nuttig om te voorkomen dat de afzender zijn eigen bericht ontvangt.
aInfo (optioneel) Een door komma's gescheiden lijst met attributen die in het antwoord moeten worden opgenomen (bijv. "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

Activeert meerdere gebeurtenissen in één API-aanroep, wat efficiënter is dan afzonderlijke verzoeken voor elke gebeurtenis. De batchparameter moet een JSON-string zijn met een array van gebeurtenisobjecten, waarbij elk object "channel"-, "name"- en "data"-velden heeft.


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

GetChannels

Retourneert een lijst van actieve kanalen. Ondersteunt optionele parameters om de resultaten te filteren en aanvullende informatie op te vragen.

Parameter Beschrijving
aFilterByPrefix (optioneel) Filter kanalen op naam-prefix (bijv. "presence-" om alleen aanwezigheidskanalen te weergeven).
aInfo (optioneel) Een komma-gescheiden lijst van kenmerken die in de respons moeten worden opgenomen (bijv. "user_count"). 


// get all channels
APIPusher.GetChannels;

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

GetChannel

Retourneert informatie over een specifiek kanaal.

Parameter Beschrijving
aChannel De kanaalnaam waarover informatie wordt opgevraagd.
aInfo (optioneel) Een door komma's gescheiden lijst van te bevatten attributen (bijv. "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

Retourneert een lijst van gebruikers die zijn verbonden met een presence-kanaal. De kanaalnaam moet het volledige voorvoegsel bevatten (bijv. "presence-my-channel").


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

TerminateUserConnections

Beëindigt alle verbindingen die door een bepaalde gebruiker zijn tot stand gebracht. Dit kan worden gebruikt om een specifieke gebruiker te dwingen de verbinding met alle kanalen te verbreken. De gebruikers-ID moet overeenkomen met de "user_id" die is gebruikt toen de gebruiker zich abonneerde op een aanwezigheidskanaal.


APIPusher.TerminateUserConnections('1234');

Aangepaste authenticatie

Pusher staat alleen abonneren op privé- of aanwezigheidskanalen toe; als de verbinding een authenticatietoken verstrekt, kunt u hiermee de toegang beperken.

U kunt uw eigen authenticatiestroom bouwen met de OnPusherAuthentication-gebeurtenis. Deze gebeurtenis wordt aangeroepen voordat het abonnementsbericht wordt ondertekend met de geheime sleutel van Pusher. Deze gebeurtenis heeft 2 parameters: een authenticatieverzoek met velden zoals SocketId, kanaalnaam... die door uw eigen authenticatieserver kunnen worden gebruikt om het verzoek al dan niet te authenticeren. Hieronder vindt u een schermafbeelding van de Pusher-authenticatiestroom

Wanneer een client verbinding maakt met de Pusher-server, verzendt het de sleutel verstrekt door Pusher en de server retourneert een identificatie-ID (socket_id).

Wanneer een client zich abonneert op een privé- (of aanwezigheids)kanaal, gebruikt de sgcWebSockets-client de geheime sleutel van Pusher om een handtekening te maken die wordt opgenomen in het abonnementsbericht. Met de OnPusherAutentication-gebeurtenis kunt u de velden vastleggen die nodig zijn om het bericht te ondertekenen, uw eigen authenticatiemethoden implementeren en, indien succesvol, de handtekening retourneren. Deze handtekening wordt opgenomen in het abonnementsbericht en naar de server verzonden.

Voorbeeld:


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;

Het formaat van de handtekening is:

Privékanalen: key:HMAC256(SocketID, ChannelName)

Presence-kanalen: sleutel: HMAC256(SocketID, ChannelName, Data)

Het TsgcWSPusherResponseAuthentication-object biedt de volgende eigenschappen:

Eigenschap Beschrijving
Geheim De geheime Pusher-sleutel die wordt gebruikt om de HMAC-handtekening te berekenen. Vooraf ingevuld met Pusher.Secret indien geconfigureerd.
Handtekening De berekende authenticatiehandtekening. Indien leeg gelaten, berekent het component deze automatisch met behulp van de Secret.
SharedSecret De gedeelde geheime sleutel voor privé-versleutelde kanalen. Vereist bij het abonneren op pscPrivateEncryptedChannel of pscPrivateEncryptedCacheChannel. Gebruikt voor end-to-end-versleuteling van berichtgegevens.