🚀 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
2.0	4.3	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, 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!")

Pusher.connection_established.connect(connected_handler);
Pusher.connection_error.connect(error_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(event_data):
  print(event_data)

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

Triggering client events

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

var channel = Pusher.subscribe("channel-name")
channel.bind(PusherEvent.SUBSCRIPTION_SUCCEEDED, handle_subscription);

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 nothing will be log to the debug console. If you want to debug your application and see what’s going on within Channels then you can set the debug value to true:

Pusher.debug = true

Connection

A connection to Pusher Channels can be established by invoking the connect_app method, the 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

To listen for connection state changes use the connection_state_changed signal:

$Pusher.connection_state_changed.connect(callback)

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

// PusherState.CONNECTED == "connected"

See full list: Available connection states

Channels

Subscribing to channels

The default method for subscribing to a channel involves invoking the subscribe method:

Pusher.subscribe("my-channel");

Unsubscribing from channels

To unsubscribe from a channel, invoke the unsubscribe method:

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

Accessing channels

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

var channel = Pusher.get_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	Callable	Called whenever the event is triggered.

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	Callable	Callable used when binding to the event.