Skip to content

Update README.md #180

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jguz-pubnub merged 3 commits into from
Oct 21, 2026
Merged

Update README.md #180

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0e1c5be
Update README.md
jguz-pubnub Oct 19, 2026
483f33a
Merge branch 'master' into ruby-readme
jguz-pubnub Oct 21, 2026
1a38dff
Update README.md
jguz-pubnub Oct 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
230 changes: 157 additions & 73 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,73 +1,157 @@
<img width="1920" height="600" alt="ruby-header" src="https://github.com/user-attachments/assets/ddf7134b-804c-48d6-aa74-cc67ee5aab94" />

# PubNub Ruby SDK

![Tests Status](https://github.com/pubnub/ruby/actions/workflows/run-tests.yml/badge.svg)

This is the official PubNub Ruby SDK repository.

PubNub takes care of the infrastructure and APIs needed for the realtime communication layer of your application. Work on your app's logic and let PubNub handle sending and receiving data across the world in less than 100ms.

## Get keys

You will need the publish and subscribe keys to authenticate your app. Get your keys from the [Admin Portal](https://dashboard.pubnub.com/).

## Configure PubNub

1. Integrate PubNub into your project using RubyGems:

```bash
gem install pubnub
```

1. Create a new `App.rb` file and add the following code.

```ruby
require 'pubnub'

pubnub = Pubnub.new(
subscribe_key: :mySubscribeKey,
publish_key: :myPublishKey,
uuid: :myUniqueUUID
)
```

This is the minimum configuration you need to send and receive messages with PubNub.

## Add event listeners

```ruby
callback = Pubnub::SubscribeCallback.new(
message: ->(envelope) {
puts "MESSAGE: #{puts envelope.result[:data][:message]['msg']}"
},
presence: ->(envelope) {
puts "PRESENCE: #{envelope.result[:data]}"
}
)
pubnub.add_listener(callback: callback)
```

## Publish and subscribe

```ruby
pubnub.subscribe(
channels: ['my_channel'],
with_presence: true
)

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

## Documentation

[API reference for Ruby](https://www.pubnub.com/docs/ruby/pubnub-ruby-sdk)

## Support

If you **need help** or have a **general question**, contact <support@pubnub.com>.
<img width="1920" height="600" alt="ruby-header" src="https://github.com/user-attachments/assets/ddf7134b-804c-48d6-aa74-cc67ee5aab94" />

# PubNub Ruby SDK

[![Gem Version](https://img.shields.io/gem/v/pubnub.svg)](https://rubygems.org/gems/pubnub)

PubNub provides global infrastructure for real-time, interactive applications.

Publish and receive messages in Ruby. Use this SDK for Ruby server, command-line, and backend applications.

[Documentation](https://www.pubnub.com/docs/sdks/ruby) · [API reference](https://www.pubnub.com/docs/sdks/ruby/api-reference/publish-and-subscribe) · [Changelog](https://www.pubnub.com/docs/sdks/ruby/changelog) · [Support](https://support.pubnub.com/)

## Requirements

| Requirement | Supported version or setup |
| --- | --- |
| Ruby | [Ruby 3.0.0 or later](https://github.com/pubnub/ruby/blob/master/pubnub.gemspec) |
| Dependency manager | RubyGems or Bundler. Install the `pubnub` gem directly or declare it in the application's Gemfile. |

## Installation

From the Ruby environment:

```sh
gem install pubnub
```

For other installation methods, see [environment setup](https://www.pubnub.com/docs/sdks/ruby).

## Quickstart

This example runs in a Ruby CLI application. It subscribes to `hello_world`, publishes one message, and prints the received text.

### Get your keys

1. Open the [PubNub Admin Portal](https://admin.pubnub.com/).
2. Create an app and a keyset for development, or select an existing development keyset.
3. Copy its publish key and subscribe key.

If Access Manager is enabled, obtain a token from your trusted backend and call `pubnub.set_token(token)`. Keep the secret key on the backend.

### Send and receive a message

Create `app.rb` in the project root and add:

Replace the key placeholders. Use a User ID that identifies the user or device in your app.

```ruby
require 'pubnub'

pubnub = Pubnub.new(
subscribe_key: 'YOUR_SUBSCRIBE_KEY',
publish_key: 'YOUR_PUBLISH_KEY',
user_id: 'hello-world-user'
)

received = Queue.new
published = false

callback = Pubnub::SubscribeCallback.new(
message: ->(envelope) do
puts envelope.result[:data][:message]
received << true
end,

status: ->(envelope) do
if !published && !envelope.error?
published = true

pubnub.publish(
channel: 'hello_world',
message: 'Hello world'
)
end
end
)
Comment thread
jguz-pubnub marked this conversation as resolved.
Resolved

pubnub.add_listener(callback: callback)

pubnub.subscribe(
channels: ['hello_world']
)

received.pop

pubnub.unsubscribe(
channels: ['hello_world']
)
```

### Run the example

```sh
ruby app.rb
```

The terminal should show:

```
Hello world
```

The example unsubscribes from `hello_world` after receiving the message, and the script then exits.

For a complete application, see the [getting started guide](https://www.pubnub.com/docs/sdks/ruby).

## Next steps

| Task | Documentation |
| --- | --- |
| Configure the client | [Configuration](https://www.pubnub.com/docs/sdks/ruby/api-reference/configuration) |
| Work with subscriptions and messages | [Publish & Subscribe](https://www.pubnub.com/docs/sdks/ruby/api-reference/publish-and-subscribe) |
| Check channel occupancy | [Presence](https://www.pubnub.com/docs/sdks/ruby/api-reference/presence) |
| Read message history | [Message Persistence](https://www.pubnub.com/docs/sdks/ruby/api-reference/storage-and-playback) |

## Build with an AI coding assistant

The [PubNub MCP server](https://www.pubnub.com/docs/ai/pubnub-mcp-server) gives an AI coding assistant access to PubNub SDK documentation and PubNub APIs. Connect the assistant to the hosted server at `https://mcp.pubnub.com`, or run `npx @pubnub/mcp@latest` locally.

The [server repository](https://github.com/pubnub/pubnub-mcp-server) has setup steps for VS Code, Cursor, Claude Code, Claude Desktop, Codex, Gemini CLI, and OpenCode.

## Before production

Use [Access Manager](https://www.pubnub.com/docs/sdks/ruby/api-reference/access-manager) to grant each client the permissions it needs. Keep the secret key on your backend. Never include it in a distributed client.

Reuse the PubNub client for the owning service/application lifetime. Call `pubnub.unsubscribe(channels: [...])` for channel subscriptions that are no longer needed.

Live delivery through PubNub SDKs is at-most-once. A subscriber can miss messages while disconnected or if its buffer overflows. For longer-gap recovery, see [Message Persistence](https://www.pubnub.com/docs/sdks/ruby/api-reference/storage-and-playback).

## Troubleshooting

| Symptom | Check |
| --- | --- |
| Ruby loads a different PubNub gem version than the application expects | When using Bundler, declare `gem 'pubnub'` in the Gemfile and run the application with `bundle exec ruby app.rb`. See the [Ruby SDK guide](https://www.pubnub.com/docs/sdks/ruby). |
| A publish succeeds but no message appears | Check the message handler, subscription readiness, keyset, and channel name. |
| The process continues running after the owning workflow ends | Unsubscribe channels that are no longer needed with `pubnub.unsubscribe(channels: [...])`. See [Ruby troubleshooting](https://www.pubnub.com/docs/sdks/ruby/troubleshoot). |
| Extra clients or duplicate messages during development | For long-running Ruby servers/workers, create the PubNub client at application/service scope rather than on each request or code reload. |

For setup help, see [troubleshooting](https://www.pubnub.com/docs/sdks/ruby/troubleshoot). Check [network status](https://status.pubnub.com/) for service incidents.

## Releases

Read the [changelog](https://www.pubnub.com/docs/sdks/ruby/changelog) before upgrading.

For a major version change, review the [Ruby SDK changelog](https://www.pubnub.com/docs/sdks/ruby/changelog) for breaking changes before upgrading.

## Support and contributions

For setup or account help, contact [PubNub Support](https://support.pubnub.com/).

For a reproducible SDK bug, use [GitHub Issues](https://github.com/pubnub/ruby/issues). Include the SDK version, runtime, and a small reproduction with credentials removed.

Install the repository development dependencies, run the test suite, and include tests for behavioral changes before opening a pull request.

## License

See the [PubNub Software Development Kit License](https://github.com/pubnub/ruby/blob/master/LICENSE.txt).
Loading