🚀 Pusher Channels ( godot plugin )

A Godot plugin for creating real-time interactions with the Pusher Channels Protocol over a WebSocket connection.

Plugin version	Godot version	Pusher Channels Protocol version
1.0	3.5.1	7.0

Table of Contents

• Installation

• Quick start

  • Activation
  • Open a connection
  • Listen for connection events
  • User authentication
  • Subscribe to a channel
  • Listen for events on your channel
  • Triggering client events

• Configuration

  • Options
    • UserAuthentication
    • ChannelAuthorization
  • Loggin

• Connection

  • Disconnect
  • connection-states
    • Available states

• Channels

  • Subscribing to channels
  • Unsubscribing from channels
  • Accessing channels

• Binding to events

  • Event callback
  • Binding on the client
  • Binding on the channel
  • Unbinding from events

Installation

Move the ./addons folder into your project folder.

See full guide: Installing a plugin

Quick start

Activation

Enable the plugin and add a Pusher node to your main scene.

See full guide: Enabling a plugin

Get your Free API keys

Create an account and then create a Channels app. See full guide

Open a connection

$Pusher.connect_app( APP_KEY, { "cluster": APP_CLUSTER } )

Listen for connection events:

func connected_handler(data):
  print("Hello!")
  
 func error_handler(data):
  print("Oh No!")
  
var error_callback = funcref(self, "error_handler")  
var connected_callback = funcref(self, "connected_handler")

$Pusher.connection.bind("error", error_callback);
$Pusher.connection.bind("connected", connected_callback);

User authentication

Authentication happens when you call the signin method:

$Pusher.signin()

See full documentation

Subscribe to a channel

Before your app can receive any events from a channel, you need to subscribe to the channel. Do this with the subscribe method:

var channel = $Pusher.subscribe("channel-name")

Listen for events on your channel

Every published event has an “event name”. For your app to do something when it receives an event called "my-event", your web app must first “bind” a function to this event name. Do this using the channel’s bind method:

func event_handler(data):
  print(data)
 
var event_callback = funcref(self, "event_handler")

channel.bind("my-event", event_callback)

Triggering client events

You can only trigger a client event once a subscription has been successfully registered:

var channel = $Pusher.subscribe("channel-name")
var on_subscribed = func_ref(self, "handle_subscription")

channel.bind(PusherEvent.SUBSCRIPTION_SUCCEEDED, on_subscribed);

func handle_subscription():
	channel.trigger("client-someEventName", { "message": "hello!" })

See full documentation

Configuration

It is possible to set and update the client configuration through the configure method:

$Pusher.configure(KEY, OPTIONS)

Params of the configure method:

Param	Type	description
key	string	The application key
options	dictionary	See below

Options:

Based on Pusher channels options parameter:

Options	Type	description
cluster	string	The cluster used by your application
userAuthentication	dictionary	See below
channelAuthorization	dictionary	See below

UserAuthentication:

Based on Pusher userAuthentication object:

Option	Type	description
params	dictionary	Additional parameters
headers	dictionary	Additional HTTP headers
endpoint	string	URL endpoint of server for authentication.

ChannelAuthorization:

Based on Pusher channelAuthorization object:

Option	Type	description
params	dictionary	Additional parameters
headers	dictionary	Additional HTTP headers
endpoint	string	URL endpoint

Loggin

By default we don’t log anything. If you want to debug your application and see what’s going on within Channels then you can assign a global logging function. The _log value should be set with a function with the following signature:

$Pusher._log = funcref(self, "logger")
  
func logger(message):
	print(message)

Connection

A connection to Pusher Channels can be established by invoking the connect_app method of your pusher node:

$Pusher.connect_app()

A connection with custom configuration can be established by passing the same params from configure method:

$Pusher.connect_app(APP_KEY, { "cluster": APP_CLUSTER })

Disconnect

You may disconnect by invoking the disconnect_app method:

$Pusher.disconnect_app()

Connection States

You can monitor the state of the connection so that you can notify users about expected behaviour. See guide: connection states API

Available states

You can access the current state as:

$Pusher.connection.state

And bind to a state change using the connection bind method:

$Pusher.connection.bind("connected", callback)

All state names are available as constants trough the PusherState class:

// PusherState.CONNECTED == "connected"
$Pusher.connection.bind(PusherState.CONNECTED, callback)

See full list: Available connection states

Channels

Subscribing to channels

The default method for subscribing to a channel involves invoking the subscribe method of your pusher node:

$Pusher.subscribe("my-channel");

Unsubscribing from channels

To unsubscribe from a channel, invoke the unsubscribe method of your pusher object:

$Pusher.unsubscribe("my-channel");

Accessing channels

If a channel has been subscribed to already it is possible to access channels by name, through the channel method:

var channel = $Pusher.channel("channel-name")

Binding to events

Binding on the client:

Use the bind method of the pusher node to listen for an event on all the channels that you are currently subscribed to:

$Pusher.bind(EVENT, CALLBACK);

Params of the bind method:

Param	Type	description
event	string	The name of the event to bind to.
callback	funcRef	Called whenever the event is triggered. See below

Event callback

In GDScript, functions are not first-class objects. This means it is impossible to store them directly as variables, return them from another function, or pass them as arguments.

However, by creating a FuncRef reference to a function in a given object can be created, passed around and called:

func event_handler(data):
  print("Event received")
  
var callback = funcref(self, "event_handler")

Binding on the channel

Events can be bound to directly on a channel. This means you will only receive an event if it is sent on that specific channel:

channel.bind(eventName, callback)

Unbinding from events:

Use unbind to remove a binding of an event:

$Pusher.unbind(EVENT, CALLBACK)

Params of the unbind method:

Param	Type	description
event	string	The name of the event from which your want to remove the binding.
callback	funcRef	The function reference used when binding to the event.