On this page

Configuration API for Ruby SDK

Complete API reference for building real-time applications on PubNub with the Ruby Software Development Kit (SDK). This page covers configuration, initialization, and event handling with concise, working examples.

Initialization

Installing

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

1gem install pubnub

Or add it to your Gemfile.

1gem 'pubnub', '~> 6.0.0'

Usage

To use pubnub, require it in your files.

1require 'pubnub'

Description

This function initializes the PubNub Client API context. Call it before using any APIs to establish account-level credentials such as publish_key and subscribe_key.

Method(s)

To Initialize PubNub you can use the following method(s) in the Ruby SDK:

1Pubnub(
  subscribe_key,
  publish_key,
  secret_key,
  auth_key,
  ssl,
  user_id,
  heartbeat,
  callback,
  ttl,
  open_timeout,
  read_timeout,
  idle_timeout,
  s_open_timeout,
  s_read_timeout,
  s_idle_timeout,
  logger,
  origin,
  http_sync,
  crypto_module
21)
show all 21 lines

* required

Parameter	Description
`subscribe_key` * Type: String, Symbol Default: n/a	Your `subscribe key`.
`publish_key` Type: String, Symbol Default: n/a	Your `publish key`, required to publish messages.
`secret_key` Type: String, Symbol Default: n/a	Your `secret key`, required for Access Manager.
`auth_key` Type: String, Symbol Default: n/a	Your `auth key`.
`ssl` Type: Boolean Default: `false`	If set to `true`, `ssl` connection will be used.
`user_id` * Type: String Default: n/a	User ID to use. You should set a unique user ID to identify the user or the device that connects to PubNub. It's a UTF-8 encoded string of up to 92 alphanumeric characters. If you don't set the user ID, you won't be able to connect to PubNub.
`heartbeat` Type: Integer Default: n/a	That single value serves a two-fold purpose. First of all, it specifies how often the client will send heartbeat signals to the server to confirm its activity on a channel. Secondly, the value defines a timeout period after which the server considers the client inactive, with inactivity beyond this period triggering a "timeout" on the presence channel. Disabled by default.
`callback` Type: Lambda Default: n/a	That `callback` will be automatically passed to all method calls fired from this client (like `publish`, `history`, `subscribe`). Will be overwritten by the `callback` passed to called event.
`ttl` Type: Integer Default: n/a	Default `ttl` for grant and revoke.
`open_timeout` Type: Integer Default: `10`	Timeout for opening connection for `non-subscribe` events. The value is in seconds.
`read_timeout` Type: Integer Default: `10`	Timeout for reading for `non-subscribe` events. The value is in seconds.
`idle_timeout` Type: Integer Default: `10`	Timeout for idle for `non-subscribe` events. The value is in seconds.
`s_open_timeout` Type: Integer Default: `310`	Timeout for opening connection for `subscribe`. The value is in seconds.
`s_read_timeout` Type: Integer Default: `310`	Timeout for read for `subscribe`. The value is in seconds.
`s_idle_timeout` Type: Integer Default: `310`	Timeout for idle for `subscribe`. The value is in seconds.
`logger` Type: Object Default: `Logger instance that outputs logs to 'pubnub.log'`	Custom `logger` instance. For detailed information about logging options and customization, refer to the Logging document.
`origin` Type: String Default: `ps.pndsn.com`	Custom `origin`. Add method that allows changing the `origin`.`#origin=(origin)` To request a custom domain, contact support and follow the request process.
`http_sync` Type: 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`). For `sync` methods `Envelope` object will be returned.
`crypto_module` Type: `Crypto::CryptoModule` Default: n/a	The cryptography module used for encryption and decryption of messages. Takes the `cipher_key` and `random_iv` parameters as arguments. For detailed encryption configuration and examples, refer to the Encryption API page.
~~`cipher_key`~~ Type: ~~String~~ Default: n/a	This way of setting this parameter is deprecated, pass it to `crypto_module` instead. ~~Your `cipher key`, it's used to encrypt and decrypt messages, if set.~~
~~`random_iv`~~ Type: ~~Boolean~~ Default: ~~`true`~~	This way of setting this parameter is deprecated, pass it to `crypto_module` instead. ~~When `true` the initialization vector (IV) is random for all requests (not just for file upload). When `false` the IV is hard-coded for all requests except for file upload.~~
~~`uuid`~~ * Type: ~~String~~ Default: n/a	This parameter is deprecated, use `user_id` instead. `UUID` to use. You should set a unique `UUID` to identify the user or the device that connects to PubNub. If you don't set the `UUID`, you won't be able to connect to PubNub.

Disabling random initialization vector

Disable random initialization vector (IV) only for backward compatibility (< 4.6.0) with existing applications. Never disable random IV on new applications.

`crypto_module`

crypto_module encrypts and decrypts messages and files. From 5.2.2, you can configure the algorithms it uses.

Each SDK includes two options: legacy 128‑bit encryption and recommended 256‑bit AES‑CBC. For background, see Message Encryption.

For configuration details, implementation examples, and manual encryption methods, see Encryption.

Legacy encryption with 128-bit cipher key entropy

You don't have to change your encryption configuration if you want to keep using the legacy encryption. If you want to use the recommended 256-bit AES-CBC encryption, you must explicitly set that in the PubNub config.

Sample code

Initialize the PubNub client API with encryption

Required User ID

Always set the UserId to uniquely identify the user or device that connects to PubNub. This UserId should be persisted, and should remain unchanged for the lifetime of the user or the device. If you don't set the UserId, you won't be able to connect to PubNub.

Reference code

This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.

1require 'pubnub'
2

3

4def main
5  # Configuration for PubNub instance
6  pubnub = Pubnub.new(
7    subscribe_key: ENV.fetch('SUBSCRIBE_KEY', 'demo'),
8    publish_key: ENV.fetch('PUBLISH_KEY', 'demo'),
9    ssl: true,
10    user_id: 'myUniqueUserId',
11    crypto_module: Pubnub::Crypto::CryptoModule.new_aes_cbc("enigma", true)
12  )
13

14  # Example to demonstrate successful configuration
15  puts "PubNub client initialized successfully with user_id: #{pubnub.user_id}"
16end
17

18

19if __FILE__ == $0
20  main
21  puts 'finished'
22end
show all 22 lines

Returns

It returns the PubNub instance for invoking PubNub APIs like publish(), subscribe(), history(), here_now(), etc.

Other examples

Initialize the client

Required User ID

1pubnub = Pubnub.new(
2    publish_key: 'demo',
3    subscribe_key: 'demo',
4    user_id: 'myUniqueUserId'
5)

Initialization for a read-only client

In the case where a client will only read messages and never publish to a channel, you can simply omit the publish_key when initializing the client:

Required User ID

1# Initialize for read-only client
2# Note: The following line uses a hash argument. Ensure the key and value
3# are separated by a colon and a space (Ruby keyword argument style):
4# subscribe_key: 'demo'
5pubnub = Pubnub.new(
6    subscribe_key : 'demo'
7)

Use a custom user ID

Set a custom user_id to identify your users.

Required User ID

1# initialize
2pubnub = Pubnub.new(
3    publish_key: 'myPublishKey',
4    subscribe_key: 'mySubscribeKey',
5    user_id: 'myUniqueUserId'
6)

Initializing with SSL enabled

This examples demonstrates how to enable PubNub Transport Layer Encryption with SSL. Just initialize the client with ssl set to true. The hard work is done, now the PubNub API takes care of the rest. Just subscribe and publish as usual and you are good to go.

Required User ID

1pubnub = Pubnub.new(
2    subscribe_key: :demo,
3    publish_key:   :demo,
4    ssl: true,
5    user_id: 'myUniqueUserId'
6)

Initializing with Access Manager

Requires Access Manager add-on

This method requires that the Access Manager add-on is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.

Secure your secret_key

Anyone with the secret_key can grant and revoke permissions to your app. Never let your secret key be discovered, and to only exchange it / deliver it securely. Only use the secret_key on secure server-side platforms.

When you init with secret_key, you get root permissions for the Access Manager. With this feature you don't have to grant access to your servers to access channel data. The servers get all access on all channels.

For applications that will administer Access Manager permissions, the API is initialized with the secret_key as in the following example:

Required User ID

1pubnub = Pubnub.new(subscribe_key: 'my_subkey', secret_key: 'my_secretkey', user_id: 'myUniqueUserId')

Now that the pubnub object is instantiated the client will be able to access the Access Manager functions. The pubnub object will use the secret_key to sign all Access Manager messages to the PubNub Network.

Event listeners

You can be notified of connectivity status, message and presence notifications via the listeners.

Listeners should be added before calling the method.

Add listeners

1callback = Pubnub::SubscribeCallback.new(
  message:  ->(_envelope) {}, # this will be fired only for non-presence messages
  presence: ->(_envelope) {}, # this will be fired only for presence messages
  signal: ->(_envelope) {}, # Handle signal message
  status: ->(envelope)  do  # this will be fired for status messages and errors
  if envelope.status[:error]
      case envelope.status[:category]
          when Pubnub::Constants::STATUS_ACCESS_DENIED # :access_denied
              # Access denied. Double check Access Manager etc.
          when Pubnub::Constants::STATUS_TIMEOUT # :timeout
              # Timeout error
          when Pubnub::Constants::STATUS_NON_JSON_RESPONSE # :non_json_response
              # Non json response
          when Pubnub::Constants::STATUS_API_KEY_ERROR # :api_key_error
              # API key error
          when Pubnub::Constants::STATUS_ERROR
              # Other error
          else
              # Shouldn't happen
          end
      end
  end
23)
24

25pubnub.add_listener(name: 'my_listener', callback: callback)
show all 25 lines

Remove listeners

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

Listeners example

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

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

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

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

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

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

30# Add another subscriber
31pubnub_client.add_listener(name: 'c1', callback: callbacks1)
32

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

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

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

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

Presence to a channel group

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

Method(s)

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

Go to the subscribe() method.

Sample code

Subscribe to the presence channel of a channel group

1pubnub = Pubnub.new(
2    subscribe_key: :demo,
3    publish_key: :demo
4)
5

6callback = Pubnub::SubscribeCallback.new(
7    message:  ->(_envelope) {
8    },
9    presence: ->(envelope) {
10        puts "PRESENCE: #{envelope.result[:data]}"
11    },
12    status:   ->(_envelope) {
13    }
14)
15

16pubnub.add_listener(callback: callback)
17

18pubnub.presence(channel_groups: 'family')
show all 18 lines

Authentication key

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

Method(s)

1auth_key

This method doesn't take any arguments.

Sample code

1pubnub.auth_key

Returns

The current authentication key.

Initialization​

Installing​

Usage​

Description​

Method(s)​

Disabling random initialization vector

crypto_module​

Legacy encryption with 128-bit cipher key entropy

Sample code​

Initialize the PubNub client API with encryption​

Required User ID

Reference code

Returns​

Other examples​

Initialize the client​

Required User ID

Initialization for a read-only client​

Required User ID

Use a custom user ID​

Required User ID

Initializing with SSL enabled​

Required User ID

Initializing with Access Manager​

Requires Access Manager add-on

Secure your secret_key

Required User ID

Event listeners​

Add listeners​

Remove listeners​

Listeners example​

Presence to a channel group​

Method(s)​

Sample code​

Authentication key​

Method(s)​

Sample code​

Returns​

Initialization

Installing

Usage

Description

Method(s)

`crypto_module`

Sample code

Initialize the PubNub client API with encryption

Returns

Other examples

Initialize the client

Initialization for a read-only client

Use a custom user ID

Initializing with SSL enabled

Initializing with Access Manager

Event listeners

Add listeners

Remove listeners

Listeners example

Presence to a channel group

Method(s)

Sample code

Authentication key

Method(s)

Sample code

Returns