Starscream Documentation

Add Starscream to your Cartfile using the following line:

github "daltoniam/Starscream" >= 4.0.6

Ensure you have Carthage installed via Homebrew if needed: brew install carthage.

Before using fastlane, ensure that the latest version of the Xcode command line tools is installed on your system.

xcode-select --install

To establish a connection, create a URLRequest, initialize a WebSocket instance, assign a delegate (or use the onEvent closure), and call connect(). It is recommended to store the WebSocket instance as a property to prevent it from being deallocated immediately.

import Starscream

var request = URLRequest(url: URL(string: "http://localhost:8080")!)
request.timeoutInterval = 5
socket = WebSocket(request: request)
socket.delegate = self
socket.connect()

To add Starscream as a dependency in your Swift package, add it to the dependencies array in your Package.swift file.

dependencies: [
    .package(url: "https://github.com/daltoniam/Starscream.git", from: "4.0.6")
]

Add the following to your Podfile and run pod install to integrate Starscream into your project.

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '12.0'
use_frameworks!

pod 'Starscream', '~> 4.0.6'

To allow self-signed certificates, use FoundationSecurity with allowSelfSigned: true and pass it to the WebSocket initializer via the certPinner parameter.

var request = URLRequest(url: URL(string: "ws://localhost:8080/")!)
let pinner = FoundationSecurity(allowSelfSigned: true)
let socket = WebSocket(request: request, certPinner: pinner)

Alternatively, you can use the onEvent closure on the WebSocket instance to process events instead of using a delegate.

socket.onEvent = { event in
	switch event {
		// handle events just like in didReceive...
	}
}

You can customize the connection by modifying the URLRequest before passing it to the WebSocket initializer. This allows you to set timeouts and custom HTTP headers (e.g., Sec-WebSocket-Protocol).

var request = URLRequest(url: URL(string: "ws://localhost:8080/")!)
request.timeoutInterval = 5
request.setValue("chat,superchat", forHTTPHeaderField: "Sec-WebSocket-Protocol")
request.setValue("Everything is Awesome!", forHTTPHeaderField: "My-Awesome-Header")
let socket = WebSocket(request: request)

By default, Starscream automatically responds to incoming ping control frames with a pong. You can disable this behavior by setting respondToPingWithPong to false.

socket.respondToPingWithPong = false

Use the disconnect() method to close the connection. You can optionally provide a custom close code using CloseCode.

socket.disconnect()
// Or with a specific close code
socket.disconnect(closeCode: CloseCode.normal.rawValue)

Starscream provides specific methods for writing different types of frames to the server:

• Binary data: Use write(data:).
• String/Text: Use write(string:).
• Ping control frame: Use write(ping:).
• Pong control frame: Use write(pong:).

Compression (RFC 7692) is enabled by default if supported by the server. To explicitly provide a compression handler, pass a WSCompression instance to the WebSocket initializer.

var request = URLRequest(url: URL(string: "ws://localhost:8080/")!)
let compression = WSCompression()
let socket = WebSocket(request: request, compressionHandler: compression)