API Pusher
Cliquez ici pour afficher cette page dans son contexte complet

API Pusher

Pusher

Pusher est une plateforme fiable et facile d'utilisation avec de bonnes fonctionnalités basées sur le protocole WebSocket : messagerie pub/sub flexible, listes d'utilisateurs en direct (présence), authentification...

L'API WebSocket Pusher est 7.

Les données sont envoyées de manière bidirectionnelle sur un WebSocket sous forme de données texte contenant du JSON encodé en UTF8 (les trames WebSocket binaires ne sont pas prises en charge).

Vous pouvez appeler la méthode Ping pour tester la connexion au serveur. Essentiellement, tout message reçu de l'autre partie est considéré comme indiquant que la connexion est active. En l'absence de messages, l'une ou l'autre partie peut vérifier que l'autre répond en envoyant un message ping, auquel l'autre partie doit répondre par un pong.

Avant de vous connecter, vous devez renseigner les champs suivants :


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)

Important

Pusher exige que le client WebSocket se connecte à une URL en utilisant les champs précédents (clé, cluster...), ces champs sont utilisés pour construire l'URL et cela se fait lorsque vous assignez le client dans le composant Pusher. Donc, pour s'assurer que l'URL est construite correctement, définissez le client après avoir rempli les champs de configuration Pusher. Voici un pseudo-code :

// configure pusher fields

pusher.cluster = ...

pusher.key = ...

// set client

pusher.client = websocket client

// start connection

websocket client.Active = true;

Après une connexion réussie, l'événement OnPusherConnect est déclenché et vous obtenez les champs suivants :

En cas d'erreur, OnPusherError sera déclenché, et les informations sur l'erreur seront fournies. Une erreur peut être envoyée par Pusher en réponse à une authentification invalide, une commande invalide, etc.

4000-4099

Indique une erreur entraînant la fermeture de la connexion par Pusher, et qu'une tentative de reconnexion avec les mêmes paramètres ne réussira pas.

4000 : L'application n'accepte que les connexions SSL, reconnectez-vous en utilisant wss://

4001 : L'application n'existe pas

4003 : Application désactivée

4004 : L'application a dépassé le quota de connexions

4005 : Chemin introuvable

4006: Format de chaîne de version invalide

4007 : Version de protocole non prise en charge

4008 : Aucune version de protocole fournie

4100-4199

Indique une erreur entraînant la fermeture de la connexion par Pusher, et que le client peut se reconnecter après 1 seconde ou plus.

4100 : Capacité dépassée

4200-4299

Indique une erreur entraînant la fermeture de la connexion par Pusher, et que le client peut se reconnecter immédiatement.

4200 : Reconnexion immédiate générique

4201 : Réponse Pong non reçue : un ping a été envoyé au client, mais aucune réponse n'a été reçue - voir les messages ping et pong

4202 : Fermé après inactivité : le client a été inactif pendant une longue période (actuellement 24 heures) et le client ne prend pas en charge le ping. Veuillez passer à un brouillon WebSocket plus récent ou implémenter la version 5 ou supérieure de ce protocole.

4300-4399

Tout autre type d'erreur.

4301 : Événement client rejeté en raison de la limitation de débit

Canaux

Les canaux sont un concept fondamental dans Pusher. Chaque application possède un certain nombre de canaux, et chaque client peut choisir les canaux auxquels il s'abonne.

Les canaux fournissent :

Il est fortement recommandé d'utiliser des canaux pour filtrer vos données plutôt que d'y parvenir via des événements. En effet, tous les événements publiés sur un canal sont envoyés à tous les abonnés, quelles que soient leurs liaisons d'événements.

Les canaux n'ont pas besoin d'être créés explicitement ; ils sont instanciés à la demande du client. Cela signifie que la création d'un canal est simple. Il suffit d'indiquer à un client de s'y abonner.

Les types de canaux suivants sont pris en charge :

Canaux publics

Les canaux publics doivent être utilisés pour les données accessibles publiquement car ils ne nécessitent aucune forme d'autorisation pour y être abonnés.

Vous pouvez vous abonner et vous désabonner des canaux à tout moment. Il n'est pas nécessaire d'attendre que Pusher ait terminé sa connexion au préalable.

Exemple : s'abonner au canal « my-channel ». 


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

Si vous êtes abonné avec succès, l'événement OnPusherSubscribe sera déclenché ; en cas d'erreur, vous recevrez un message dans l'événement OnPusherError.

Tous les messages du canal abonné seront reçus dans l'événement OnPusherEvent.

Lorsque la méthode Publish est appelée et que le canal est Public, le composant, au lieu d'utiliser le protocole WebSocket, utilise le protocole HTTP et appelle la méthode TriggerEvent (la publication n'est pas autorisée via le protocole WebSocket).

Canaux privés

Nécessite Indy 10.5.7 ou version ultérieure

Les canaux privés doivent être utilisés lorsque l'accès au canal doit être restreint d'une certaine façon. Pour qu'un utilisateur puisse s'abonner à un canal privé, l'autorisation doit être accordée.

Exemple : s'abonner au canal « my-private-channel ».


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

Si vous êtes abonné avec succès, l'événement OnPusherSubscribe sera déclenché ; en cas d'erreur, vous recevrez un message dans l'événement OnPusherError.

Tous les messages du canal abonné seront reçus dans l'événement OnPusherEvent.

Canaux de présence

Nécessite Indy 10.5.7 ou version ultérieure

Les canaux de présence s'appuient sur la sécurité des canaux privés et exposent la fonctionnalité supplémentaire de connaissance des abonnés au canal. Cela facilite grandement la création de fonctionnalités de chat et de « qui est en ligne » dans votre application. Pensez aux salles de chat, aux collaborateurs sur un document, aux personnes consultant la même page web, aux concurrents dans un jeu, etc.

Les canaux de présence sont souscrits depuis l'API client de la même manière que les canaux privés, mais le nom du canal doit être préfixé par presence-. Comme pour les canaux privés, une requête HTTP est effectuée vers une URL d'authentification configurable pour déterminer si l'utilisateur actuel dispose des autorisations d'accès au canal.

Les informations sur les utilisateurs qui s'abonnent et se désabonnent d'un canal peuvent ensuite être consultées en se liant aux événements sur le canal de présence, et l'état actuel des utilisateurs abonnés au canal est disponible via la propriété channel.members.

Exemple : s'abonner au canal "my-presence-channel". 


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

Si vous êtes abonné avec succès, l'événement OnPusherSubscribe sera déclenché ; en cas d'erreur, vous recevrez un message dans l'événement OnPusherError.

Tous les messages du canal abonné seront reçus dans l'événement OnPusherEvent.

Canaux de cache

Un canal cache mémorise le dernier événement déclenché et l'envoie comme premier événement aux nouveaux abonnés.

Lorsqu'un événement est déclenché sur un canal de cache, Pusher Channels met cet événement en cache. Lorsqu'un client s'abonne à un canal de cache, si une valeur en cache existe, elle est envoyée au client comme premier événement sur ce canal. Ce comportement aide les développeurs à fournir l'état initial sans ajouter de logique supplémentaire pour le récupérer ailleurs.

Les canaux de cache suivants sont pris en charge :

Exemple : s'abonner au canal cache public « my-cache-channel ». 


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

Si vous êtes abonné avec succès, l'événement OnPusherSubscribe sera déclenché ; en cas d'erreur, vous recevrez un message dans l'événement OnPusherError.

Tous les messages du canal abonné seront reçus dans l'événement OnPusherEvent.

S'il n'y a pas d'événement en cache lors de l'abonnement à un canal de cache, l'événement OnPusherCacheMiss sera déclenché, fournissant le nom du canal. Cela permet à votre application de gérer le cas où aucune donnée en cache n'est disponible.

Canaux privés chiffrés

Les canaux privés chiffrés fournissent un chiffrement de bout en bout pour les messages. Comme les canaux privés, ils nécessitent une authentification, mais en plus toutes les charges utiles de données sont chiffrées à l'aide de NaCl secretbox afin que seuls les abonnés autorisés puissent lire le contenu. Même Pusher lui-même ne peut pas déchiffrer les messages.

Pour utiliser des canaux privés chiffrés, vous devez fournir un SharedSecret lors de l'authentification. Le secret partagé est utilisé pour chiffrer et déchiffrer les données des messages.

Exemple : s'abonner à un canal privé chiffré "my-encrypted-channel". 


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

Une variante de cache privé chiffré est également disponible, combinant le chiffrement avec le comportement du canal de cache : 


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

Lors de l'utilisation de l'événement OnPusherAuthentication avec des canaux chiffrés privés, vous pouvez définir la propriété SharedSecret sur l'objet de réponse pour fournir la clé de chiffrement :


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

Événements de présence

Les canaux de présence fournissent des événements supplémentaires qui notifient votre application lorsque des utilisateurs rejoignent ou quittent un canal, et vous permettent de suivre le nombre d'abonnements.

OnPusherMemberAdded

Déclenché lorsqu'un nouveau membre s'abonne à un canal de présence. Fournit le nom du canal, l'identifiant de l'utilisateur et les informations sur le membre qui a rejoint.


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

OnPusherMemberRemoved

Déclenché lorsqu'un membre se désabonne d'un canal de présence. Fournit le nom du canal, l'identifiant utilisateur et les informations utilisateur du membre qui est parti.


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

OnPusherSubscriptionCount

Déclenché lorsque le nombre d'abonnements change sur un canal. Fournit le nom du canal et le nombre actuel d'abonnés. Cet événement doit être activé sur votre tableau de bord Pusher.


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

OnPusherCacheMiss

Déclenché lors de l'abonnement à un canal cache qui n'a pas d'événement mis en cache. Fournit le nom du canal. Cela permet à votre application de gérer le cas où aucune donnée mise en cache n'est disponible, par exemple en récupérant les données depuis une autre source. 


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

Publier des messages

Non seulement vous pouvez recevoir des messages des canaux auxquels vous êtes abonné, mais vous pouvez également envoyer des messages à d'autres utilisateurs abonnés.

Appelez la méthode Publish pour envoyer un message à tous les utilisateurs abonnés au canal.

Exemple : envoyer un événement à tous les utilisateurs abonnés à « my-channel »


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

Ne publiez pas plus de 10 messages par seconde par client (connexion). Tout événement déclenché au-delà de cette limite de débit sera rejeté par l'API Pusher. Ce n'est pas un problème système, c'est un problème côté client. 100 clients dans un canal envoyant des messages à ce rythme devraient chacun également traiter 1 000 messages par seconde ! Même si certains navigateurs modernes pourraient le gérer, ce n'est probablement pas une bonne idée.

REST API

L'API est hébergée sur http://api-CLUSTER.pusher.com, où CLUSTER est remplacé par le cluster de votre propre application (par exemple, eu).

Les codes de statut HTTP servent à indiquer le succès ou l'échec des requêtes. Les statuts suivants sont courants :

200 Requête réussie. Le corps contiendra un hash JSON des données de réponse

400 Erreur : détails dans le corps de la réponse

401 Erreur d'authentification : le corps de la réponse contiendra une explication

403 Forbidden : application désactivée ou quota de messages dépassé

Les fonctions API REST suivantes ont été implémentées.

Fonction Description
TriggerEvent Déclenche un nouvel événement sur le canal spécifié. Prend en charge des paramètres optionnels SocketId (pour exclure un client) et Info.
TriggerBatchEvents Déclenche plusieurs événements en une seule requête HTTP. Accepte un tableau JSON d'objets événements.
GetChannels Fournit une liste de tous les canaux actifs. Prend en charge les paramètres FilterByPrefix et Info optionnels.
GetChannel Fournit des informations sur un canal spécifique. Prend en charge un paramètre Info facultatif.
GetUsers Fournit la liste de tous les utilisateurs connectés à un canal.
TerminateUserConnections Termine toutes les connexions d'un utilisateur donné par son identifiant utilisateur.

TriggerEvent

Déclenche un événement sur un ou plusieurs canaux. Nécessite le nom de l'événement, le nom du canal et la charge utile des données.

Paramètre Description
aEventName Le nom de l'événement à déclencher.
aChannel Le nom du canal sur lequel déclencher l'événement.
aData Les données de l'événement (chaîne JSON).
aSocketId (optionnel) Un identifiant de socket à exclure de la réception de l'événement. Utile pour éviter que l'expéditeur reçoive son propre message.
aInfo (facultatif) Une liste séparée par des virgules d'attributs à inclure dans la réponse (ex. "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

Déclenche plusieurs événements en un seul appel API, ce qui est plus efficace que de faire des requêtes séparées pour chaque événement. Le paramètre batch doit être une chaîne JSON contenant un tableau d'objets événement, où chaque objet a les champs « channel », « name » et « data ». 


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

GetChannels

Retourne une liste des canaux actifs. Prend en charge des paramètres optionnels pour filtrer les résultats et demander des informations supplémentaires.

Paramètre Description
aFilterByPrefix (optionnel) Filtrer les canaux par préfixe de nom (par exemple « presence- » pour lister uniquement les canaux de présence).
aInfo (facultatif) Une liste d'attributs séparés par des virgules à inclure dans la réponse (ex : "user_count"). 


// get all channels
APIPusher.GetChannels;

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

GetChannel

Retourne des informations sur un canal spécifique.

Paramètre Description
aChannel Le nom du canal dont on souhaite obtenir des informations.
aInfo (facultatif) Liste séparée par des virgules des attributs à inclure (ex. « 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

Retourne une liste des utilisateurs connectés à un canal de présence. Le nom du canal doit inclure le préfixe complet (par ex. "presence-my-channel").


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

TerminateUserConnections

Met fin à toutes les connexions établies par un utilisateur donné. Cela peut être utilisé pour forcer un utilisateur spécifique à se déconnecter de tous les canaux. L'ID utilisateur doit correspondre au "user_id" utilisé lors de l'abonnement de l'utilisateur à un canal de présence.


APIPusher.TerminateUserConnections('1234');

Authentification personnalisée

Pusher ne permet de s'abonner qu'aux canaux privés ou de présence ; si la connexion fournit un jeton d'authentification, cela vous permet de restreindre l'accès.

Vous pouvez construire votre propre flux d'authentification en utilisant l'événement OnPusherAuthentication, cet événement est appelé avant que le message d'abonnement ne soit signé avec la clé secrète fournie par Pusher. Cet événement a 2 paramètres : une demande d'authentification avec des champs tels que SocketId, nom de canal... qui peuvent être utilisés par votre propre serveur d'authentification pour authentifier ou non la demande. Retrouvez ci-dessous une capture d'écran illustrant le flux d'authentification Pusher.

Lorsqu'un client se connecte au serveur pusher, il envoie la clé fournie par pusher et le serveur renvoie un identifiant d'identification (socket_id).

Lorsqu'un client s'abonne à un canal privé (ou de présence), le client sgcWebSockets utilise la clé secrète fournie par pusher pour créer une signature qui est incluse dans le message d'abonnement. En utilisant l'événement OnPusherAutentication, vous pouvez capturer les champs requis pour signer le message, implémenter vos propres méthodes d'authentification et, en cas de succès, renvoyer la signature qui sera incluse dans le message d'abonnement et envoyée au serveur.

Exemple :


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;

Le format de la signature est :

Canaux privés : key:HMAC256(SocketID, ChannelName)

Canaux Presence : clé : HMAC256(SocketID, ChannelName, Data)

L'objet TsgcWSPusherResponseAuthentication fournit les propriétés suivantes :

Propriété Description
Secret La clé secrète Pusher utilisée pour calculer la signature HMAC. Pré-remplie avec Pusher.Secret si configurée.
Signature La signature d'authentification calculée. Si laissée vide, le composant la calculera automatiquement à l'aide du Secret.
SharedSecret La clé secrète partagée pour les canaux chiffrés privés. Requise lors de l'abonnement à pscPrivateEncryptedChannel ou pscPrivateEncryptedCacheChannel. Utilisée pour le chiffrement de bout en bout des données de message.