NWWebSocket
A WebSocket client written in Swift, using the Network framework from Apple.
- Supported platforms
- Installation
- Usage
- Documentation
- Reporting bugs and requesting features
- Credits
- License
Supported platforms
- Swift 5.1 and above
- Xcode 11.0 and above
Deployment targets
- iOS 13.0 and above
- macOS 10.15 and above
- tvOS 13.0 and above
Installation
CocoaPods
CocoaPods is a dependency manager for Cocoa projects.
If you don't already have the Cocoapods gem installed, run the following command:
$ gem install cocoapods
To integrate NWWebSocket into your Xcode project using CocoaPods, specify it in your Podfile
:
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '14.0'
use_frameworks!
pod 'NWWebSocket', '~> 0.5.3'
Then, run the following command:
$ pod install
If you find that you're not having the most recent version installed when you run pod install
then try running:
$ pod cache clean
$ pod repo update NWWebSocket
$ pod install
Also you'll need to make sure that you've not got the version of NWWebSocket locked to an old version in your Podfile.lock
file.
Swift Package Manager
To integrate the library into your project using Swift Package Manager, you can add the library as a dependency in Xcode – see the docs. The package repository URL is:
https://github.com/pusher/NWWebSocket.git
Alternatively, you can add the library as a dependency in your Package.swift
file. For example:
// swift-tools-version:5.1
import PackageDescription
let package = Package(
name: "YourPackage",
products: [
.library(
name: "YourPackage",
targets: ["YourPackage"]),
],
dependencies: [
.package(url: "https://github.com/pusher/NWWebSocket.git",
.upToNextMajor(from: "0.5.3")),
],
targets: [
.target(
name: "YourPackage",
dependencies: ["NWWebSocket"]),
]
)
You will then need to include both import Network
and import NWWebSocket
statements in any source files where you wish to use the library.
Usage
This section describes how to configure and use NWWebSocket to manage a WebSocket connection.
Connection and disconnection
Connection and disconnection is straightforward. Connecting to a WebSocket is manual by default, setting connectAutomatically
to true
makes connection automatic.
Manual connection
let socketURL = URL(string: "wss://somewebsockethost.com")
let socket = NWWebSocket(url: socketURL)
socket.delegate = self
socket.connect()
// Use the WebSocket…
socket.disconnect()
Automatic connection
let socketURL = URL(string: "wss://somewebsockethost.com")
let socket = NWWebSocket(url: socketURL, connectAutomatically: true)
socket.delegate = self
// Use the WebSocket…
socket.disconnect()
NOTES:
- In the above code examples,
self
must conform toWebSocketConnectionDelegate
(see Receiving messages and connection updates)
Sending data
UTF-8 encoded strings or binary data can be sent over the WebSocket connection.
// Sending a `String`
let message = "Hello, world!"
socket.send(string: message)
// Sending some binary data
let data: [UInt8] = [123, 234]
let messageData = Data(data)
socket.send(data: messageData)
Receiving messages and connection updates
String or data messages (as well as connection state updates) can be received by making a type you define conform to WebSocketConnectionDelegate
. You can then respond to received messages or connection events accordingly.
extension MyWebSocketConnectionManager: WebSocketConnectionDelegate {
func webSocketDidConnect(connection: WebSocketConnection) {
// Respond to a WebSocket connection event
}
func webSocketDidDisconnect(connection: WebSocketConnection,
closeCode: NWProtocolWebSocket.CloseCode, reason: Data?) {
// Respond to a WebSocket disconnection event
}
func webSocketViabilityDidChange(connection: WebSocketConnection, isViable: Bool) {
// Respond to a WebSocket connection viability change event
}
func webSocketDidAttemptBetterPathMigration(result: Result<WebSocketConnection, NWError>) {
// Respond to when a WebSocket connection migrates to a better network path
// (e.g. A device moves from a cellular connection to a Wi-Fi connection)
}
func webSocketDidReceiveError(connection: WebSocketConnection, error: NWError) {
// Respond to a WebSocket error event
}
func webSocketDidReceivePong(connection: WebSocketConnection) {
// Respond to a WebSocket connection receiving a Pong from the peer
}
func webSocketDidReceiveMessage(connection: WebSocketConnection, string: String) {
// Respond to a WebSocket connection receiving a `String` message
}
func webSocketDidReceiveMessage(connection: WebSocketConnection, data: Data) {
// Respond to a WebSocket connection receiving a binary `Data` message
}
}
Ping and pong
Triggering a Ping on an active WebSocket connection is a best practice method of telling the connected peer that the connection should be maintained. Pings can be triggered on-demand or periodically.
// Trigger a Ping on demand
socket.ping()
// Trigger a Ping periodically
// (This is useful when messages are infrequently sent across the connection to prevent a connection closure)
socket.ping(interval: 30.0)
Documentation
Full documentation of the library can be found in the API docs.
Reporting bugs and requesting features
- If you have found a bug or have a feature request, please open an issue
- If you want to contribute, please submit a pull request (preferably with some tests 🙂 )
Credits
NWWebSocket is owned and maintained by Pusher. It was originally created by Daniel Browne.
It uses code from the following repositories:
License
NWWebSocket is released under the MIT license. See LICENSE for details.