In this article, you’ll learn what is Pusher API, its specifications, Public & Private Channel of Pusher, integrating Pusher to your IDE Software, connecting pusher network with TsgcWSAPI_Pusher component of ESEGECE, and many more.
Table of Contents
What is Pusher ?
Pusher is a set of bidirectional APIs targeted at real-time communication. The main use cases for those APIs are :
- Real time charts (cryptocurrency values)
- Network games (synchronization of players)
- In app chat (application support)
- Real time results (basketball, soccer, baseball)
- Instant geolocation (products to home delivery)
What are the main specifications of Pusher ?
Pusher is a publish-subscribe messaging system that allows to exchange messages reliably and effectively. Pusher solves by design the problems of :
- Scale of number of messages and users
- The real time constraint of messages delivery.
Pusher supports the concept of channels.
A channel of communication can have 4 different type :
- Public
- Private
- Encrypted
- Presence
What is a Public Channel in Pusher?
Public channels should be used for publicly accessible data as they do not require any form of authorisation in order to be subscribed to.
What is a Private Channel in Pusher?
Private channels should be used when access to the channel needs to be restricted in some way. In order for a user to subscribe to a private channel permission must be authorized. The authentication occurs via a HTTP Request to a configurable authentication url when the subscribe method is called with a private- channel name.
What is an Encrypted Channel in Pusher?
An encrypted channel is similar to a private channel. However the content of the message is end-to-end encrypted This encryption follows the specifications of the Secretbox encryption standard defined in NaCl and the message is encrypted before it leaves the server. Only authorized subscribers have access to the channel specific decryption key. This means that nobody except authorized subscribers can read the payload data, not even Pusher. End-to-end encrypted channels also provide end-to-end authenticity; that is your messages are protected from forgery, and that they are guaranteed to come from someone who holds the encryption master key.
What is a Pusher Presence Channel?
Presence channels build on the security of Private channels and expose the additional feature of an awareness of who is subscribed to that channel. This makes it extremely easy to build chat room and “who’s online” type functionality to your application.
How can I integrate Pusher into my Delphi app?
The first step is to create an “application” on Pusher.com
First of all users need to subscribe to the Pusher network and create an application. Pusher will generate several ids and keys needed to use the Pusher system as follows:
With all this data, the developer will be able to interact with the Pusher system.
How do I connect to the Pusher network with the TsgcWSAPI_Pusher component of ESEGECE?
The low-level communication with Pusher is based on web socket. As a result you can find a Pusher component in the websocket component suite of ESEGECE.
You can download the component suite from here. The component installation is done by the compilation the bpl for the Delphi version. There are full instructions and it’s quite easy to do, even for novices.
Now, in RAD Studio Delphi, create a new application and drop on the main form the web socket component TsgcWebSocketClient and the Pusher component TsgcWSAPI_Pusher.
In the property of the pusher component we will need to set :
|
1 2 3 4 5 6 7 |
sgcPusher.Pusher.Cluster := 'eu'; sgcPusher.Pusher.AppId := myAppid; sgcPusher.Pusher.Key := myKey; sgcPusher.Pusher.Secret := mySecret; sgcPusher.Pusher.TLS := True; sgcPusher.Pusher.Version := myVersion; sgcPusher.Pusher.Name := myName; |
for the websocket component the property we set the following :
|
1 2 |
wsClient.Port := 443; //means secure because TLS of Pusher component is on wsClient.Host := 'ws-eu.pusher.com'; |
The cluster value ‘eu‘ is used as a subdomain connection. The use of a secure connection (TLS) raises a dependency with two dlls from the OpenSSL : libeay32.dll and ssleay32.dll (for Win32). Do not forget to add these libraries in the same directory of the Delphi application or in a directory defined in the PATH system variable.
When both components are parametrized we can associate them by setting that the Pusher client is the websocket component :
|
1 |
sgcPusher.Client := wsClient; |
To connect to the Pusher network just activate the websocket component :
|
1 |
wsClient.Active := True; |
When the application connects, a OnConnect event is fired. If an error occurred an event OnError or OnPusherError is raised depending on what the error is.
How do I get my app to subscribe to a Pusher channel?
A user can subscribe to a Pusher channel by calling the Subscribe method :
|
1 2 3 |
TsgcWSAPI_Pusher.Subscribe(aChannelName : string; aChannelType : TsgcWSpusherChannels = pscPublicChannel; data:string=''); |
When the subscription is successfull an event OnPusherSubscribe is raised
We can notice that by default the subscription is done for public channel.
What are the Pusher channel naming conventions?
According to Pusher documentation, a public channel has no naming rule but a private channel must start with ‘private-‘ and presence channel ‘presence-‘. Actually this naming convention is done by setting the channel type during the call of the Subscribe method.
Here is a Delphi example of subscribing to a Pusher channel:
|
1 |
sgcPusher.Subscribe('privatename',pscPrivateChannel); |
The above code will subscribe the channel ‘private-privatename‘. The concatenation of the name used as a variable in the Subscribe call with ‘private-‘ as a suffix is done by the TsgcWSAPI_Pusher class. The same behavior is implemented for a presence channel.
What happens during a subscription to a Pusher presence channel?
When a user subscribes to a presence channel, the system waits for information regarding the user. Then the data variable of the subscribe method call will be set as follows:
|
1 2 3 4 5 6 7 |
{ "user_id":"user_id", "user_info": { "name":"John Smith" } } |
The user_id field value must be of course unique. Use an unique identifier as an email or GUID for this field for example.
The user data as json will be published immediately during subscription to all subscribers of this presence channel.
How to publish a message in a Pusher channel?
The user can use the method Publish as follows for any channel type:
|
1 2 3 4 |
TsgcWSAPI_Pusher.Publish (const anEventName : string ; const aChannelName : string; aChannelType : TsgcWSpusherChannels = pscPublicChannel; const eventData : string=''); |
Then when the user calls Publish, if another Pusher client subscribed to the same channel for the same application, it will receive an event OnPusherEvent(Sender: TObject; Event, Channel, Data: string) containing all message parameters.
For public channels, the user can use the TriggerEvent method. It’s a transcription of the Pusher API trigger event limited to public channel.
|
1 2 3 |
TsgcWSAPI_Pusher.TriggerEvent(const anEventName : string ; const aChannelName : string; const eventData : string); |
Then when the user calls TriggerEvent, if another Pusher client subscribed the same public channel for the same application, they will receive an event OnPusherEvent.
How do I make my app get a list of all available Pusher channels?
When the client is connected to the Pusher cloud application, it is possible to know all subscribed channels by calling the method GetChannels.
It returns synchronously a json string with all available channel names.
Is there a full Delphi example of using Pusher?
You can download a full example from here: https://github.com/checkdigits/Pusher_example
Two VCL projects can be found. One with the whole Pusher feature implemented and another one where the secret key was not shared and this application can only listen to messages on public channels.
Do you want to try out this example right now? Why not download a free trial of the latest version of RAD Studio Delphi and get coding something new today?
Design. Code. Compile. Deploy.
Start Free Trial Upgrade Today
Free Delphi Community Edition Free C++Builder Community Edition
This looks interesting, is there an FMX version for this too?
Although the example project is a VCL project this code will work for Firemonkey FMX apps too. The sgcWebSockets component quoted in the article can be found here: https://www.esegece.com/ and will work in VCL and cross platform Firemonkey FMX. If you just follow along the steps in your own Firemokey project it will work just fine.