Client Libraries

Using Pusher client libraries with Sockudo

Sockudo is a drop-in replacement for Pusher, which means you can use any Pusher-compatible client library without modifications. This guide shows you how to configure popular client libraries to connect to Sockudo.

JavaScript (pusher-js)

The official Pusher JavaScript library works seamlessly with Sockudo.

Installation

npm install pusher-js

Configuration

Configure pusher-js to point to your Sockudo server:

import Pusher from 'pusher-js';

const pusher = new Pusher('app-key', {
    wsHost: 'localhost',
    wsPort: 6001,
    cluster: '',
    forceTLS: false
});

const channel = pusher.subscribe('my-channel');
channel.bind('my-event', (data) => {
    console.log('Received:', data);
});

Production Configuration

For production with SSL/TLS:

const pusher = new Pusher('your-app-key', {
    wsHost: 'sockudo.yourdomain.com',
    wsPort: 443,
    cluster: '',
    forceTLS: true,
    enabledTransports: ['ws', 'wss']
});

PHP (pusher-php-server)

Use the official Pusher PHP library for server-side event triggering.

Installation

composer require pusher/pusher-php-server

Configuration

require __DIR__ . '/vendor/autoload.php';

$pusher = new Pusher\Pusher(
    'app-key',
    'app-secret',
    'app-id',
    [
        'host' => 'localhost',
        'port' => 6001,
        'scheme' => 'http'
    ]
);

// Trigger an event
$pusher->trigger('my-channel', 'my-event', [
    'message' => 'Hello from PHP'
]);

Production Configuration

$pusher = new Pusher\Pusher(
    getenv('SOCKUDO_APP_KEY'),
    getenv('SOCKUDO_APP_SECRET'),
    getenv('SOCKUDO_APP_ID'),
    [
        'host' => 'sockudo.yourdomain.com',
        'port' => 443,
        'scheme' => 'https',
        'useTLS' => true
    ]
);

Python (pusher)

The Pusher Python library works with Sockudo for server-side operations.

Installation

pip install pusher

Configuration

import pusher

pusher_client = pusher.Pusher(
    app_id='app-id',
    key='app-key',
    secret='app-secret',
    host='localhost',
    port=6001,
    ssl=False
)

# Trigger an event
pusher_client.trigger('my-channel', 'my-event', {
    'message': 'Hello from Python'
})

Ruby (pusher-gem)

Installation

gem install pusher

Configuration

require 'pusher'

pusher = Pusher::Client.new(
  app_id: 'app-id',
  key: 'app-key',
  secret: 'app-secret',
  host: 'localhost',
  port: 6001,
  encrypted: false
)

# Trigger an event
pusher.trigger('my-channel', 'my-event', {
  message: 'Hello from Ruby'
})

Node.js (pusher)

For server-side Node.js applications.

Installation

npm install pusher

Configuration

const Pusher = require('pusher');

const pusher = new Pusher({
    appId: 'app-id',
    key: 'app-key',
    secret: 'app-secret',
    host: 'localhost',
    port: 6001,
    useTLS: false
});

// Trigger an event
pusher.trigger('my-channel', 'my-event', {
    message: 'Hello from Node.js'
});

React Native

Use pusher-js with React Native.

Installation

npm install pusher-js @react-native-community/netinfo

Configuration

import Pusher from 'pusher-js/react-native';

const pusher = new Pusher('app-key', {
    wsHost: 'sockudo.yourdomain.com',
    wsPort: 443,
    cluster: '',
    forceTLS: true
});

const channel = pusher.subscribe('mobile-channel');
channel.bind('notification', (data) => {
    console.log('Push notification:', data);
});

Common Configuration Options

Connection Options

Option	Description	Default
wsHost	Sockudo server hostname	-
wsPort	WebSocket port	6001
forceTLS	Use secure WebSocket (wss)	false
cluster	Leave empty for Sockudo	''
enabledTransports	Transport protocols	['ws', 'wss']
activityTimeout	Connection activity timeout (ms)	120000
pongTimeout	Pong response timeout (ms)	30000

Authentication

For private and presence channels:

const pusher = new Pusher('app-key', {
    wsHost: 'localhost',
    wsPort: 6001,
    cluster: '',
    forceTLS: false,
    authEndpoint: '/pusher/auth',
    auth: {
        headers: {
            'X-CSRF-Token': 'your-csrf-token'
        }
    }
});

const privateChannel = pusher.subscribe('private-channel');
const presenceChannel = pusher.subscribe('presence-channel');

Troubleshooting

Connection Refused

Problem: Client cannot connect to Sockudo.

Solution:

• Verify wsHost and wsPort match your Sockudo configuration
• Check firewall rules allow connections to port 6001
• Ensure Sockudo is running: curl http://localhost:6001/up/app-id

Authentication Failures

Problem: Private/presence channel subscriptions fail.

Solution:

• Verify app credentials (key, secret, id) match Sockudo configuration
• Check authentication endpoint returns proper signature format
• Ensure HMAC signature uses correct app secret

SSL/TLS Errors

Problem: Connection fails with SSL errors in production.

Solution:

• Set forceTLS: true when using wss://
• Verify SSL certificates are properly configured on your reverse proxy
• Check that WebSocket upgrade headers are preserved through proxy

Messages Not Received

Problem: Client connects but doesn’t receive events.

Solution:

• Verify channel name matches exactly (case-sensitive)
• Check event binding uses correct event name
• Ensure server is triggering events to the correct channel
• Check browser console for error messages

CORS Issues

Problem: Browser blocks WebSocket connection due to CORS.

Solution:

• Configure allowed_origins in Sockudo app configuration:
  {
    "allowed_origins": [
      "https://yourdomain.com",
      "https://*.staging.yourdomain.com",
      "http://localhost:3000"
    ]
  }
  
• Use environment variable: SOCKUDO_DEFAULT_APP_ALLOWED_ORIGINS=https://yourdomain.com,http://localhost:3000

Next Steps

• Migrate from Pusher - Complete migration guide
• Using with Nginx - Production deployment with reverse proxy
• Redis Setup - Configure Redis for horizontal scaling