Codakey
Play
← Back to facebook/SocketRocket

How to Deploy & Use facebook/SocketRocket

SocketRocket Deployment & Usage Guide

A comprehensive guide for integrating and deploying the SocketRocket WebSocket client library in iOS, macOS, tvOS, and visionOS applications.

Prerequisites

  • Xcode 12.0 or later (latest stable recommended)
  • Deployment Targets: iOS 9.0+, macOS 10.10+, tvOS 9.0+, or visionOS 1.0+
  • Dependency Manager: CocoaPods 1.10+ or Carthage 0.38+ (optional but recommended)
  • Python 2.7 or 3.6+ (required only for running test suite)
  • Git for cloning the repository

Installation

Option 1: CocoaPods (Recommended)

Add to your Podfile:

platform :ios, '9.0'
use_frameworks!

target 'YourApp' do
  pod 'SocketRocket'
end

Install dependencies:

pod install

Option 2: Carthage

Add to your Cartfile:

github "facebookincubator/SocketRocket"

Build the framework:

carthage update --platform iOS

Drag the built SocketRocket.framework from Carthage/Build/iOS/ into your project's "Frameworks, Libraries, and Embedded Content" section. Ensure "Embed & Sign" is selected.

Option 3: Git Submodule (Manual Integration)

git submodule add https://github.com/facebookincubator/SocketRocket.git
git submodule update --init --recursive

Drag SocketRocket.xcodeproj into your workspace. Add SocketRocket.framework to your target's "Frameworks, Libraries, and Embedded Content" and add it to your target dependencies.

Configuration

Basic Setup

SocketRocket requires no external configuration files. Configure your WebSocket connection via NSURLRequest:

NSURLRequest *request = [NSURLRequest requestWithURL:[NSURL URLWithString:@"wss://echo.websocket.org"]];
SRWebSocket *webSocket = [[SRWebSocket alloc] initWithURLRequest:request];
webSocket.delegate = self;
[webSocket open];

SSL Certificate Pinning (Optional)

For enhanced security, implement certificate pinning by configuring the NSURLRequest with appropriate security policies before initializing SRWebSocket.

HTTP Proxy Support

SocketRocket automatically detects system proxy settings. No additional configuration required for standard proxy environments.

Build & Run

Building the Library

  1. Open SocketRocket.xcworkspace (if using CocoaPods) or SocketRocket.xcodeproj
  2. Select target scheme (SocketRocket-iOS, SocketRocket-macOS, etc.)
  3. Build: ⌘+B or xcodebuild -scheme SocketRocket-iOS

Running Tests

Command Line:

# Setup Python environment (first time only)
make test

# Run short test suite
make test

# Run full test suite including performance tests
make test_all

Xcode:

  1. Select SocketRocketTests target
  2. Set destination to macOS or any iOS Simulator
  3. Run tests: ⌘+U

Running the TestChat Demo

Start the Server:

# Activate Python virtualenv (created during make test)
source .env/bin/activate

# Install Tornado (if not already installed)
pip install git+https://github.com/tornadoweb/tornado.git

# Start chat server
python TestChatServer/py/chatroom.py

Alternative Go implementation:

cd TestChatServer/go
go run chatroom.go

Run the Client:

  1. In Xcode, select TestChat target
  2. Build and run on Simulator or device
  3. Click refresh button to connect (should display "Connected!")
  4. Open browser to http://localhost:9000 to chat between web and app clients

Deployment

App Store Distribution

When deploying apps using SocketRocket to the App Store:

  1. Framework Embedding:

    • CocoaPods: Automatically handles embedding
    • Carthage: Ensure "Embed & Sign" is selected for SocketRocket.framework in Build Phases
    • Manual: Verify framework is copied to Frameworks directory in Build Phases

  2. Bitcode: SocketRocket supports Bitcode. Ensure ENABLE_BITCODE = YES in Build Settings.

  3. App Transport Security (ATS): SocketRocket supports TLS 1.2+ for secure WebSocket connections (wss://). For insecure ws:// connections, add appropriate ATS exceptions to Info.plist.

Version Management

Pin to specific versions in production:

CocoaPods:

pod 'SocketRocket', '~> 0.6'

Carthage:

github "facebookincubator/SocketRocket" ~> 0.6.0

Server Compatibility

SocketRocket is tested and compatible with:

  • Tornado (Python)
  • Gorilla WebSocket (Go)
  • Autobahn test suite (RFC 6455 compliance)

Ensure your WebSocket server implements RFC 6455 standard for full compatibility.

Troubleshooting

Build Issues

"SocketRocket/SocketRocket.h file not found"

  • Verify framework is properly linked in "Frameworks, Libraries, and Embedded Content"
  • For CocoaPods: Ensure using .xcworkspace not .xcodeproj
  • Check "Header Search Paths" includes $(inherited) for CocoaPods

Carthage build failures

  • Update Carthage: brew upgrade carthage
  • Use --no-use-binaries flag if pre-built binary is incompatible with your Xcode version
  • Check carthage update --platform iOS for specific platform

Connection Issues

"WebSocket connection failed" / Timeout errors

  • Verify URL scheme: Use wss:// for TLS, ws:// for plain text
  • Check server supports WebSocket protocol (RFC 6455)
  • Verify no proxy/firewall blocking WebSocket port (typically 80/443)
  • For self-signed certificates: Ensure server certificate is trusted or implement custom trust evaluation

SSL/TLS handshake failures

  • Verify server supports TLS 1.2 or higher
  • Check certificate validity and expiration
  • For certificate pinning: Ensure pinned certificate matches server certificate exactly

Runtime Issues

Memory leaks / Retain cycles

  • Ensure delegate is set to weak (not strong)
  • SocketRocket retains itself between open and close/error events
  • Manually call close when done to release self-retain

Message delivery failures

  • Verify socket is in webSocketDidOpen: state before sending
  • Check error parameter in sendString:error: or sendData:error:
  • For binary data: Ensure proper NSData encoding

Test Suite Issues

Python virtualenv errors

  • Ensure Python 2.7 or 3.6+ is installed: python --version
  • If .env directory is corrupted: rm -rf .env and rerun make test
  • For pip install failures: pip install --upgrade pip setuptools

Autobahn test failures

  • Tests 6.4.2 and 6.4.4 are expected to fail (non-strict UTF-8 handling is by design)
  • Ensure test server is not running other WebSocket services on port 9001

Getting Help

  • Review Autobahn test results for protocol compliance
  • Check GitHub Issues for similar problems
  • Verify compatibility with your WebSocket server implementation (Tornado, Gorilla, etc.)
← Project overviewView alternatives to facebook/SocketRocket →