SwiftNetwork Lifecycle for Swift Native

 
These docs are for the new PubNub Swift SDK written purely in Swift. To view the docs for the older version (the PubNub Objective-C SDK wrapper for Swift), have a look here.
It is the user's responsibility to prepare the client's configuration instance and pass it during PubNub client instantiation. As long as there is a reference to the client instance, it will be alive. The initialized client doesn't perform any activities until activated by user commands.

The client doesn't check for an active connection on its own, and instead relies on the network API response.

On a user command, the client prepares a REST request to the PubNub API and passes it to the networking API for processing. If there were no issues and the response arrived in time (the timeout is configurable), the results are parsed and wrapped into objects which are returned using callbacks.

If there was an issue during request processing, the networking API returns information about the error, which is then parsed and wrapped into objects and returned to the caller.

In case of network issues, realtime APIs return a status object with its category set to PNNetworkIssuesCategory.

There are also a set of other error categories:

PNNetworkIssuesCategory - no network connection when the client tried to send the request.

PNTLSConnectionFailedCategory - TLS handshake issues, generally due to poor connection quality and packet loss/delays.

PNTimeoutCategory - no response received before the specified timeout.

PNUnknownCategory - non-200 HTTP response code received from the server.

The Heartbeat API can be used as way to detect when network issues appear. Heartbeats send a request at a set interval (configured during client instance configuration) and use the observer's callback to report successful and failed attempts. If the network quality degrades between calls to this API, a socket with an active long-poll (subscribe API for realtime messages) may not notice those issues and end up listening for events on a broken pipe.

These status events may indicate network issues: PNTimeoutCategory, PNUnexpectedDisconnectCategory and PNNetworkIssuesCategory. Swift has exclusive statuses that can reveal deeper information about the network from the browser APIs.

This status may arrive if a non-subscribe request doesn't receive a response from the server in time. This may happen only if:

  • There are issues on the service itself
  • There is a proxy between the client and the PubNub service, and the proxy doesn't send the request or return a response in time
  • There are issues with poor network signal quality (or there is a lot of noise on the band)

No connection at the moment the request is sent. This status is returned immediately to the calling API through a callback.

  • During subscription API usage, the client stumbled on a network issue or received an unexpected response.
  • There were network issues and the networking API reported back to the SDK to generate an error.
  • The service itself (if the data provided to the client is malformed and breaks the composed URI) or a proxy server returns a response that the subscribe parser can't parse.

This status is exclusive to Swift and indicates that the browser reported network stability and the SDK was instructed to reconnect. This status is the first status fired after a connectivity disruption.

This status is exclusive to Swift and indicates that the browser reported network instability and the SDK has lost its connection to the host. This status is fired, but there are no guarantees on the chain of events (for example, the subscribe may time out first); in this situation, everything is dependent on the browser.

A PNUnexpectedDisconnectCategory may be generated in the middle of the client lifecycle while it subscribed to real-time data channels.

If this status arrives, the client starts pinging PubNub services every 10 seconds using the Time API. As soon as a request is processed successfully, the client attempts to restore its subscriptions on the channels to which it was previously subscribed. If it's configured to keep a timetoken on subscription restore, the client attempts to catch up on missed messages.

When the client completes its subscription restore after PNUnexpectedDisconnectCategory, it generates a PNReconnectedCategory to notify observers that the client is reconnected to real-time data channels.

If more than 100 messages arrive from the PubNub in-memory messages cache, it's better to use the History API to fetch the missed messages. To be notified of this situation, set requestMessageCountThreshold to 100. This tells the client to send a PNRequestMessageCountExceededCategory status.

PubNub client allow user to describe behavior in case of network issue. For this purpose there is two parameters in PNConfiguration: restoreSubscription and catchUpOnSubscriptionRestore. Both values by default set to YES which configure client to restore subscription after it has been in unexpected disconnect state (because of network issues) and use last received time token to try catch up on missed messages.

  1. restoreSubscription: instruct on whether client should restore subscription to channels after network issues or not. If set to NO after network failure client will clean up list of channels on which it subscribed and after network will go up again won't do anything.
  2. catchUpOnSubscriptionRestore: instruct client whether after subscription restore (if restoreSubscription is set to YES) should use time token from previous subscribe loop (time token which has been received with last message/event while client has been connected). If property set to YES client will request and use new time token and all messages which has been sent while client was offline will be lost (sure they can be received with history calls).
  3. keepTimeTokenOnListChange: this property not related to reconnection logic, but also may confuse users. If set to YES client will reuse previous time token when user subscribe to new channels. If set to NO client will use time token which will be received with subscription using new channels. If client has been subscribed to some channels with tt1 and subscribe to new channels, it will ignore tt2 (received in response for subscribe with new channels from PubNub service) and use tt1 to complete subscribe loop if set to YES. This also mean, what if since tt1 in new channels was some messages - they will be received as well (this is what some users reported what old messages has been received). If property set to NO client will use tt2 to complete subscribe loop.

The Apple ecosystem will begin pinging the time endpoint at regular intervals until the connection is restored or application goes into the background.

On some platforms, application owners have more visibility into networking conditions than the SDK. You can subscribe on same set of channels or empty list and client will terminate currently active long-poll request and start new one.

For the Apple SDKs, you can just subscribe to the same set of channels or an empty array to force a manual reconnect.

403 response on a subscribe event occurs when Access Manager is enabled and the user doesn't have access to the channel or the grant TTL has expired. In this case you need to create a new auth key, grant access to the user (from your server) and subscribe again.

For more info please check: http://www.pubnub.com/docs/swift-native/pam-security#handling-permission-denied-errors