Important Information

Events

All events accept basic parameters:

parameter	required?	type	notes
http_sync	optional	boolean	Default false. Method will be executed asynchronously and will return future, to get it's value you can use `#value` method. If set to true, method will return array of envelopes (even if there's only one envelope).
callback	optional	lambda accepting one parameter	Callback that will be called for each envelope.

Returned values

For sync methods Envelope object will be returned (#subscribe and #presence are exceptions - they will return array of envelopes - envelope for each message). For async methods future will be returned, to retrieve value Envelope object you have to call #value method (thread will be locked until the value is returned).

Add Channels To Channel Group

DESCRIPTION

This method adds a channel to a channel group.

METHOD

To Add Channels to Channel Group you can use the following method in the Ruby SDK

#channel_registration(action: :add, channel: channel, channel_group: channel_group)

parameter	required?	type	notes
action	required	symbol	Action that you want to preform, to add, it's `:add`.
channel	required	string/symbol	The `channel` to add to channel group.
channel_group	required	string/symbol	The `channel_group` to add channel to.

BASIC USAGE

# Async without callback
future = pubnub.channel_registration(action: :add, channel: :my_channel, channel_group: :somegroup)

# Sync without callback
envelopes = pubnub.channel_registration(action: :add, channel: :my_channel, channel_group: :somegroup, http_sync: true)

# Async with callback (callback can be specified also as :callback key)
future = pubnub.channel_registration(action: :add, channel: :my_channel, channel_group: :somegroup){ |envelope| puts envelope.status }

Audit

DESCRIPTION

This function provides a mechanism to reveal existing PubNub Access Manager attributes for any combination of subscribe_key, channel, auth_key.

METHOD

To run Audit you can use the following method in the Ruby SDK #audit(channel: channel, auth_key: auth_key)

parameter	required?	type	notes
auth_key	Optional	string/symbol	Specifies the `auth_key` to return PAM attributes for. If only a single `channel` is specified, it is possible to return results for a comma separated list of `auth_keys`.
channel	Optional	string/symbol	Specifies `channel` name to return PAM attributes optionally in combination with `auth_key`. If `channel` or `channel_group` is not specified, results for all channels associated with `subscribe_key` are returned. If `auth_key` is not specified, it is possible to return results for a comma separated list of channels.
channel_group	Optional	string/symbol	Specifies `channel_group` name to return PAM attributes optionally in combination with `auth_key`.

EXAMPLE USAGE

# Reveal PAM permissions for `channel` and all associated `auth_key` entries:
pubnub.audit(channel: :my_channel, auth_key: :my_authkey) do |envelope|
  puts envelope.result[:data]
end

Get Authentication Key

DESCRIPTION

This method provides the capability to get a user's auth_key.

METHODS

#auth_key()

BASIC USAGE

pubnub.auth_key

RETURNS

Te current authentication key.

Get State

DESCRIPTION

The state API is used to get key/value pairs specific to a subscriber uuid. State information is supplied as a JSON object of key/value pairs.

METHOD

To get_state you can use the following method in Ruby SDK #get_state(channel: channel, uuid: uuid)

parameter	required?	type	notes
channel	Required	string/symbol	Specifies `channel` name to get state from.
uuid	Optional	string	Specifies `uuid`.

BASIC USAGE

Returning state information.

pubnbu.state(channel: :my_channel, uuid: 'some-uuid') do |envelope|
  puts envelope.result[:data][:state]
end

Global Here Now

DESCRIPTION

Return occupancy for add channels.

METHOD

To do global here_now you can use the following method in the Ruby SDK.

#here_now

This method doesn't take any other options than basic (like http_sync, callback).

Grant

DESCRIPTION

CURRENT DESCRIPTION IS OK

METHOD

To grant permission on a channel or group you can use following method in Ruby SDK.

#grant(channel: channel, channel_group: :group, auth_key: auth_key, read: read, write: write, manage: manage, ttl: ttl)

parameter	required?	type	notes
channel	optional	string / symbol	Specifies `channel` name to grant permissions to. If `channel` is not specified, the grant applies to all channels associated with the `subscribe_key`. If `auth_key` is not specified, it is possible to grant permissions to multiple channels simultaneously by specifying the channels as a comma separated list.
channel_group	optional	string / symbol	Specifies `channel_group` name to grant permissions to.
auth_key	optional	string / symbol	Specifies `auth_key` to grant permissions to.
read	optional	boolean	Read permissions. (default: true)
write	optional	boolean	Write permissions. (default: true)
manage	optional	boolean	Manage permissions. (default: true)
ttl	optional	integer	Time in minutes for which granted permissions are valid. Default is `1440` (24hrs), Max is `525600` , Min is `1`. Setting `ttl` to `0` will apply the grant indefinitely.

Here Now

DESCRIPTION

You can obtain information about the current state of a channel including a list of unique user-ids currently subscribed to the channel and the total occupancy count of the channel by calling the #here_now method in your application.

METHOD

#here_now(channel: channel)

parameter	required?	type	notes
channel	optional	string / symbol	Specifies the `channel` name to return occupancy results. If channel is not provided, `here_now` will return data for all channels (global `here_now`).
channel_group	optional	string / symbol	Specifies the `channel_group` name to return occupancy results.

History

DESCRIPTION

CURRENT DESCRIPTION IS OK

METHOD

To run history you can use the following method in Ruby SDK.

#history(channel: channel, count: count, start: start, end: end, reverse: reverse)

parameter	required?	type	notes
channel	required	string / symbol	Specifies channel to return history messages from.
count	optional	integer	Specifies the number of historical messages to return. Default/maximum is 100.
start	optional	integer	Time token delimiting the start of time slice (exclusive) to pull messages from.
end	optional	integer	Time token delimiting the end of time slice (inclusive) to pull messages from.
reverse	optional	boolean	Setting to true will traverse the time line in reverse starting with the oldest message first. Default is false. If both start and end arguments are provided, reverse is ignored and messages are returned starting with the newest message.

Initialize

DESCRIPTION

Installing

In order to use pubnub ruby gem you need to install it. You can do it via rubygems command:

gem install pubnub

Or add it to your Gemfile.

gem 'pubnub', '~> 4.0'

Usage

To use pubnub you need to require it in your files.

require 'pubnub'

That's it, you can use pubnub ruby client right away.

METHODS

To initialize pubnub client you need to use #new method and specify at least required parameters in hash of parameters.

pubnub = Pubnub.new(
  subscribe_key: :demo,
  publish_key:   :demo
)

There are more parameters that could be passed while initializing client:

parameter	required?	type	notes
subscribe_key	required	string / symbol	Your subscribe key
publish_key	optional	string / symbol	Your publish key. Required to publish messages.
secret_key	optional	string / symbol	Your secret key. Required for PAM.
auth_key	optional	string / symbol	Your auth key.
cipher_key	optional	string	Your cipher key, it's used to encrypt and decrypt messagages if set.
ssl	optional	boolean	If set to `true` ssl connection will be used.
uuid	optional	string	If not set, it will be generated by pubnub client. Has to be unique.
connect_callback	optional	lambda	`connect_callback` will be called on successful connection to pubnub cloud.
heartbeat	optional	integer	Setting value of heartbeat enables heartbeat with given value. Heartbeat starts with first async subscribe. Disabled by default.
callback	optional	lambda	That callback will be automatically passed to all method calls fired from this client (like publish, history, subscribe). Will be overwrote by callback passed to called event.
ttl	optional	integer	Default ttl for grant and revoke.
open_timeout	optional	integer	Timeout for opening connection for non-subscribe events.
read_timeout	optional	integer	Timeout for reading for non-subscribe events.
idle_timeout	optional	integer	Timeout for idle for non-subscribe events.
s_open_timeout	optional	integer	Timeout for opening connection for subscribe.
s_read_timeout	optional	integer	Timeout for read for subscribe.
s_idle_timeout	optional	integer	Timeout for idle for subscribe.
origins_pool	optional	array of strings	Custom origins pool.

List all Channels from a Channel Group

DESCRIPTION

This function lists all the channels of the channel group.

METHOD

To list all channels in a channel group you can use the following method in the Ruby SDK.

#channel_registration(action: :get, channel_group: group)

parameter	required?	type	notes
action	required	symbol	To get all channels from a channel group you need to specify action as :get.
channel_group	required	symbol / string	Channel group to fetch the channels of.

Presence to a Channel Group

DESCRIPTION

This functions subscribes to the presence channel of a channel group.

METHOD

To do Presence to a Channel Group you can use the following method(s) in Ruby SDK: Go to subscribe

BASIC USAGE

Subscribe to presence channel of a channel group

pubnub.presence(channel_group: 'my_group') do |envelope|
  puts envelope.parsed_response
end

Listener

Listeners are used to handle messages from subscriptions.

Adding listener

callbacks = Pubnub::SubscribeCallback.new(
  message:  ->(envelope) { puts #{envelope.result[:data][:message]}" },
  presence: ->(envelope) { puts #{envelope.result[:data][:message]}" },
  status:   ->(envelope) { puts #{envelope.status}" }
)

pubnub.add_listener(name: 'my_listener', callback: callbacks)

Removing listener

pubnub.remove_listener(name: 'my_listener')
# or
pubnub.remove_listener(callbacks)

Example

# Init pubnub client
pubnub_client = Pubnub.new(subscribe_key: 'demo', publish_key: 'demo')

# First callbacks object
callbacks0 = Pubnub::SubscribeCallback.new(
  message:  ->(envelope) { puts "C0 MESSAGE: #{envelope.result[:data][:message]}" },
  presence: ->(envelope) { puts "C0 PRESENCE: #{envelope.result[:data][:message]}" },
  status:   ->(envelope) { puts "C0 STATUS: #{envelope.result[:data][:message]}" }
)

# Second callbacks object
callbacks1 = Pubnub::SubscribeCallback.new(
  message:  ->(envelope) { puts "C1 MESSAGE: #{envelope.result[:data][:message]}" },
  presence: ->(envelope) { puts "C1 PRESENCE: #{envelope.result[:data][:message]}" },
  status:   ->(envelope) { puts "C1 STATUS: #{envelope.result[:data][:message]}" }
)

# Adding listener allows you to specify name, it's not required to specify a name
pubnub_client.add_listener(name: 'c0', callback: callbacks0)

# Let's subscribe somewhere
pubnub_client.subscribe(channel: :demo, presence: :demo)

# SOME OUTPUT:
# C0 PRESENCE: {"action"=>"join", "timestamp"=>1461683357, "uuid"=>"fc0c0460-44b4-4338-b7e9-1b534b85072e", "occupancy"=>2}
# C0 MESSAGE: {"text"=>"hey"}
# C0 PRESENCE: {"action"=>"join", "timestamp"=>1461683374, "uuid"=>"3efb92f6-bf02-4373-aafa-996527718ecc", "occupancy"=>3}
# C0 MESSAGE: {"text"=>"hey"}

# Adding another subscriber
pubnub_client.add_listener(name: 'c1', callback: callbacks1)

# SOME OUTPUT WITH TWO LISTENERS ACTIVE:
# C0 MESSAGE: {"text"=>"hey"}
# C1 MESSAGE: {"text"=>"hey"}
# C0 PRESENCE: {"action"=>"leave", "timestamp"=>1461683435, "uuid"=>"3efb92f6-bf02-4373-aafa-996527718ecc", "occupancy"=>2}
# C1 PRESENCE: {"action"=>"leave", "timestamp"=>1461683435, "uuid"=>"3efb92f6-bf02-4373-aafa-996527718ecc", "occupancy"=>2}

# We're removing subscriber by giving it's name
pubnub_client.remove_listener(name: 'c1')

# SOME OUTPUT AFTER REMOVING C1 LISTENER
# C0 MESSAGE: {"text"=>"hey"}
# C0 MESSAGE: {"text"=>"hey"}
# C0 PRESENCE: {"action"=>"join", "timestamp"=>1461683698, "uuid"=>"3efb92f6-bf02-4373-aafa-996527718ecc", "occupancy"=>2}

# We're removing subsciber by giving it's object, now we don't have any listeners active
pubnub_client.remove_listener(callback: callbacks0)

Publish

CURRENT DESCRIPTION IS OK

METHOD

To publish a message you can use the following method in the Ruby SDK.

#publish(channel: channel, message: message, store: store, compressed: compressed, publish_key: publish_key)

parameter	required?	type	notes
channel	required	symbol / string	Specifies `channel` name to `publish` messages to.
message	required	Object (see notes)	Serializable object that has definied `#to_json` method.
store	optional	boolean	Specifies if message should be stored for `history`. Default true.
compressed	optional	boolean	Specifies if message should be compressed. Default false.

BASIC USAGE

Publish a message to a channel:

pubnub.publish(
  channel: 'my_channel',
  message: { text: 'Hi!' }
) do |envelope|
  puts envelope.status
end

Remove Channels from a Channel Group

DESCRIPTION

This method removes the channels from the channel group.

METHOD

To remove channels from a channel group you can use the following method in the Ruby SDK.

#channel_registration(action: :remove, channel: channel, channel_group: group).

parameter	required?	type	notes
action	required	symbol	Use `:remove` to remove channel.
channel	required	symbol / string	Specifies `channel` name to remove from channel group.
channel_group	required	symbol / string	Specifies `channel_group` name to remove channel from.

Set Authentication Key !!! REMOVE

Set State

DESCRIPTION

The state API is used to set key/value pairs specific to a subscriber uuid. State information is supplied as a JSON object of key/value pairs.

METHOD

To set_state you can use following method in the Ruby SDK #set_state(channel: channel, state: state)

parameter	required?	type	notes
channel	required	symbol / string	Specifies `channel` name to set state for.
state	required	Hash	The state to set.

BASIC USAGE

pubnub.set_state(channel: 'my_channel', state: { key: 'value' }) do |envelope|
  puts envelope.state
end

Subscribe

DESCRIPTION

...

METHOD

To subscribe to a channel you can use the following method in the Ruby SDK

#subscribe(channel: channel, channel_group: group, presence: presence, callback: callback, presence_callback: presence_callback)

parameter	required?	type	notes
channel	optional	symbol / string / array	Specifies the channel to subscribe to. It is possible to specify multiple channels as an array. It is possible to subscribe to wildcard channels. See Examples for more info.
channel_group	optional	symbol / string / array	Specifies the group to subscribe to. It is possible to specify multiple groups as an array. See Examples for more info.
presence	optional	symbol / string / array	Specifies the channel to presence subscribe to. It is possible to specify multiple channels as an array. See Examples for more info.
callback	optional	lambda accepting one argument	Callback that is called for each retreived message. Works only with http_sync set to true.
presence_callback	optional	lambda accepting one argument	Callback that is called for each presence event from wildcard subscribe. *Works only with http_sync set to true.

LISTENERS

The response of the subscription is handled by Listener. Please see the Listener section for more details.

USAGE

# Subscribe to channel 'my_channel'.
pubnub.subscribe(
  channel: :my_channel
)

# Subscribe to wildcard channel 'ruby.*' (make sure you have wildcard subscribe enabled in your pubnub admin console!)
# specify two different callbacks for messages from channels and presence events in channels.
pubnub.subscribe(
  channel: 'ruby.*'
)

# Subscribe to channel ruby and ruby-pnpres (presence).
pubnub.subscribe(
  channel: 'ruby',
  presence: 'ruby'
)

# And channel 'ruby' presence (ruby-pnpres).
pubnub.subscribe(
  presence: 'ruby'
)

# Subscribe to group
pubnub.subscribe(
  channel_group: 'ruby_group'

# Subscribe to channels (with presence) and groups
pubnub.subscribe(
  channel: ['debug', 'info', 'warn'],
  channel_group: ['ruby_group', 'jruby_group', 'rbx_group'],
  presence: ['debug', 'info', 'warn']
)
# You will be subscribed to channels: debug, info, warn, debug-pnpres, info-pnpres and warn-pnpres
# and to groups: ruby_group, jruby_group, rbx_group.

Subscribe to a Channel Group

See #subscribe

Time

DESCRIPTION

...

METHOD

To fetch time form server you can use the following method in the Ruby SDK.

#time

Time doesn't accept any other keys than basic ones.

Unset Authentication Key !!! REMOVE !!!

Unsubscribe

DESCRIPTION

When subscribed to a single channel or group, this function causes the client to issue a leave from the channel or group and close any open socket to the PubNub Network. For multiplexed channels, the specified channel(s) or group(s) will be removed and the socket remains open until there are no more channels remaining in the list.

METHOD

#unsubscribe(channel: channel, channel_group: group) aliased to leave

parameter	required?	type	notes
channel	optional	symbol / string	Specifies the `channel` to unsubscribe from. (Required if `channel_group` is not specified)
channel_group	optional	symbol / string	Specifies the `channel_group` to unsubscribe from. (Required if `channel` is not specified)

BASIC USAGE

pubnub.unsubscribe(
  channel: 'my_channel'
) do |envelope|
  puts envelope.status
end

pubnub.unsubscribe(
  channel: ['chan1','chan2','chan3']
) do |envelope|
  puts envelope.status
end

pubnub.leave(channel_group: :cg1) do |envelope| 
  puts envelope.status
end

UUID !!! REMOVE !!!!

Where Now

DESCRIPTION

You can obtain information about the current list of a channels to which a uuid is subscribed to by calling the #where_now method in your application.

METHOD

To do where_now you can use the following method in the Ruby SDK. #where_now(uuid: uuid)

parameter	required?	type	notes
uuid	required	string	`UUID` we are looking for.

BASIC USAGE

pubnub.where_now(
  uuid: "my_uuid"
) do |envelope|
  puts envelope.result[:data]
end

Files

docs.md

Latest commit

History

docs.md

File metadata and controls

Important Information

Events

Returned values

Add Channels To Channel Group

DESCRIPTION

METHOD

BASIC USAGE

Audit

DESCRIPTION

METHOD

EXAMPLE USAGE

Get Authentication Key

DESCRIPTION

METHODS

BASIC USAGE

RETURNS

Get State

DESCRIPTION

METHOD

BASIC USAGE

Global Here Now

DESCRIPTION

METHOD

Grant

DESCRIPTION

METHOD

Here Now

DESCRIPTION

METHOD

History

DESCRIPTION

METHOD

Initialize

DESCRIPTION

Installing

Usage

METHODS

List all Channels from a Channel Group

DESCRIPTION

METHOD

Presence to a Channel Group

DESCRIPTION

METHOD

BASIC USAGE

Listener

Adding listener

Removing listener

Example

Publish

METHOD

BASIC USAGE

Remove Channels from a Channel Group

DESCRIPTION

METHOD

Set Authentication Key !!! REMOVE

Set State

DESCRIPTION

METHOD

BASIC USAGE

Subscribe

DESCRIPTION

METHOD

LISTENERS

USAGE

Subscribe to a Channel Group

Time

DESCRIPTION

METHOD

Unset Authentication Key !!! REMOVE !!!

Unsubscribe

DESCRIPTION

METHOD

BASIC USAGE

UUID !!! REMOVE !!!!