A WebSocket client written in Swift, using the Network framework from Apple.
- Supported platforms
- Installation
- Usage
- Documentation
- Reporting bugs and requesting features
- Credits
- License
- Swift 5.1 and above
- Xcode 11.0 and above
- iOS 13.0 and above
- macOS 10.15 and above
- tvOS 13.0 and above
CocoaPods is a dependency manager for Cocoa projects.
If you don't already have the Cocoapods gem installed, run the following command:
$ gem install cocoapodsTo 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.4'Then, run the following command:
$ pod installIf 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 installAlso 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.
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.gitAlternatively, 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.4")),
],
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.
This section describes how to configure and use NWWebSocket to manage a WebSocket connection.
Connection and disconnection is straightforward. Connecting to a WebSocket is manual by default, setting connectAutomatically to true makes connection automatic.
let socketURL = URL(string: "wss://somewebsockethost.com")
let socket = NWWebSocket(url: socketURL)
socket.delegate = self
socket.connect()
// Use the WebSocket…
socket.disconnect()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,
selfmust conform toWebSocketConnectionDelegate(see Receiving messages and connection updates)
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)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
}
}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)Full documentation of the library can be found in the API docs.
- 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 🙂 )
NWWebSocket is owned and maintained by Pusher. It was originally created by Daniel Browne.
It uses code from the following repositories:
NWWebSocket is released under the MIT license. See LICENSE for details.