:rocket: Pusher Channels ( godot plugin )

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

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:

Options:

Based on Pusher channels options parameter:

UserAuthentication:

ChannelAuthorization:

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:

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: