Configuration API for PubNub Ruby SDK

Ruby V4 complete API reference for building real-time applications on PubNub, including basic usage and sample code.

Initialization

Installing

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', '~> 5.2.2'

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.

Description

This function is used for initializing the PubNub Client API context. This function must be called before attempting to utilize any API functionality in order 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 V4 SDK:

Pubnub(
    subscribe_key,
    publish_key,
    secret_key,
    auth_key,
    cipher_key,
    ssl,
    uuid,
    heartbeat,
    callback,
    ttl,
    open_timeout,
    read_timeout,
    idle_timeout,
    s_open_timeout,

show all 21 lines

Parameter	Type	Required	Default	Description
subscribe_key	String, Symbol	Yes		Your subscribe key.
publish_key	String, Symbol	Optional		Your publish key, required to publish messages.
secret_key	String, Symbol	Optional		Your secret key, required for Access Manager.
auth_key	String, Symbol	Optional		Your auth key.
cipher_key	String	Optional		Your cipher key, it's used to encrypt and decrypt messages, if set.
ssl	Boolean	Optional	false	If set to true ssl connection will be used.
user_id	String	Yes		user_id to use. You should set a unique user_id to identify the user or the device that connects to PubNub. <br/ It's a UTF-8 encoded string of up to 64 alphanumeric characters. If you don't set the user_id, you won't be able to connect to PubNub.
heartbeat	Integer	Optional		Setting value of heartbeat enables heartbeat with given value. Heartbeat starts with first async subscribe. Disabled by default.
callback	Lambda	Optional		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	Integer	Optional		Default ttl for grant and revoke.
open_timeout	Integer	Optional	10	Timeout for opening connection for non-subscribe events.The value is in seconds.
read_timeout	Integer	Optional	10	Timeout for reading for non-subscribe events.The value is in seconds.
idle_timeout	Integer	Optional	10	Timeout for idle for non-subscribe events.The value is in seconds.
s_open_timeout	Integer	Optional	310	Timeout for opening connection for subscribe.The value is in seconds.
s_read_timeout	Integer	Optional	310	Timeout for read for subscribe.The value is in seconds.
s_idle_timeout	Integer	Optional	310	Timeout for idle for subscribe.The value is in seconds.
logger	Object	Optional	Logger instance that outputs logs to 'pubnub.log'	Custom logger instance.
origin	String	Optional	ps.pndsn.com	Custom origin. Add method that allows changing the origin.#origin=(origin)
http_sync	Boolean	Optional	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.
random_iv	Boolean	Optional	true	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	String	Yes		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.

Basic Usage

Initialize the PubNub client API

Required UserId

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.

pubnub = Pubnub.new(
    subscribe_key: :demo,
    publish_key:   :demo,
    ssl: true,
    user_id: 'myUniqueUserId'
)

Returns

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

Other Examples

Initialize the client

Required UserId

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.

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

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 UserId

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.

# Initialize for Read Only Client
pubnub = Pubnub.new(
    subscribe_key : 'demo'
)

Use a custom UUID

Set a custom UUID to identify your users.

Required UserId

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.

# initialize
pubnub = Pubnub.new(
    publish_key: 'myPublishKey',
    subscribe_key: 'mySubscribeKey',
    user_id: 'myUniqueUserId'
)

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 UserId

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.

pubnub = Pubnub.new(
    subscribe_key: :demo,
    publish_key:   :demo,
    ssl: true,
    user_id: 'myUniqueUserId'
)

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 UserId

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.

pubnub = 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

callback = 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

show all 25 lines

Remove Listeners

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

Listeners 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]}" }

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 V4 SDK:

Go to Subscribe Method

Basic Usage

Subscribe to the presence channel of a channel group

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

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

show all 18 lines

Authentication Key

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

Method(s)

auth_key

This method doesn't take any arguments.

Basic Usage

pubnub.auth_key

Returns

The current authentication key.