PubNub Client State Management Framework

The PubNub CSM framework offers a data management framework that listens to realtime events generated by the PubNub network to update the view inside your application. And of course, your data can coexist with PubNub-defined data.

Note: This is a beta version of the PubNub CSM framework

Table of Contents

• Concepts
• Setup Instructions
• Usage Examples

Concepts

The PubNub CSM framework includes the following components that you help manage your application’s state and PubNub server communications.

• Actions: Preconfigured actions that correspond to PubNub internals
• Reducers: Configured to respond to the actions dispatched by the PubNub CSM framework
• Listeners: Monitor subscription notifications and dispatch actions
• Commands: Functions that execute PubNub API calls and dispatch actions

Supported Features

• Sending and Receiving Messages
• Indicating User Presence
• Monitoring Network Status
• Managing Users
• Managing Spaces
• Managing Space Memberships

Not Yet Supported

• PubNub Access Manager
• Storage and Playback
• Signals
• Message Actions

Prerequisites

• Xcode
• PubNub Account (Free)

Requirements

• iOS 8.0+ / MacOS 10.10 / Mac Catalyst 13.0+ / tvOS 9.0+ / watchOS 2.0+
• Swift 5+

Setup Instructions

This section provides the basic integration steps to connect the PubNub CSM framework into your existing application. For an example of an application built on top of this framework, go to our reference application site at: https://www.pubnub.com/docs/chat/quickstart

• Before You Begin
• Configure the Store
• Register Listeners

Before You Begin

Before you can create an application with the PubNub CSM framework, obtain a set of chat-optimized keys from your PubNub Dashboard.

In the following instructions, replace the following references with key values from your PubNub Dashboard.

• myPublishKey
• mySubscribeKey

Configure the Store

A Redux application manages all application state in a centralized location called the store. To gain the benefits offered by the PubNub CSM framework, you must configure your store to include references to the PubNub libraries.

Configure State

struct AppState: StateType, Equatable {
  var networkStatus = NetworkStatusState()
  var user = UserState<UserObject>()
  var membership = MembershipState<UserObjectMembership>()
  var space = SpaceState<SpaceObject>()
  var member = MemberState<SpaceObjectMember>()
  var presence = PresenceState<[String: AnyJSON]>()
  var messages = MessageState<AnyJSON>()
}

Configure Reducers

func appReducer(action: Action, state: AppState?) -> AppState {
  var state = state ?? AppState()

  switch action {
  case let action as PubNubActionType:
    NetworkStatusReducer.reducer(action, state: &state.networkStatus)
    UserReducer.reducer(action, state: &state.user)
    SpaceReducer.reducer(action, state: &state.conversation)
    MembershipReducer.reducer(action, state: &state.membership)
    MemberReducer.reducer(action, state: &state.member)
    MessageReducer.reducer(action, state: &state.messages)
    PresenceReducer.reducer(action, state: &state.presence)
  default: break
  }

  return state
}

Configure Redux Thunk Middleware

The PubNub CSM framework uses Redux Thunk to manage the interaction with commands that execute PubNub API calls, process the responses, and dispatch ReSwift actions.

// Create the PubNub Instance
let pubnub = PubNub(configuration: .init(publishKey: "myPublishKey", subscribeKey: "mySubscribeKey"))

// Configure the service provider used by the Thunk
PubNubServiceProvider.shared.set(service: pubnub)

let middleware = ThunkAction.getMiddleware

Complete the Store Configuration

let myStore = Store(
  reducer: appReducer,
  state: AppState(),
  middleware: [ThunkAction.getMiddleware]
)

Register Listeners

You can register all the listeners that are included in the PubNub CSM framework.

PubNubServiceProvider.shared.add(listener: PubNubListener.createListener(dispatch: dispatch))

Usage Examples

This section contains a few examples of commands to get your started. This is not meant to be an exhaustive list. Also, you can create commands in your application that use our actions to meet your requirements.

• Sending a Message
• Creating a User
• Retrieving a User
• Creating a Space
• Joining a Space

Sending a Message

store.dispatch(
  MessageCommand.sendMessage(
    SendMessageRequest(
      content: [
        "title": "hello world",
        "body": "This is our hello world message."
      ],
      channel: "my-channel")
))

Creating a User

store.dispatch(
  UserCommand.createPubNub(
    UserRequest(user: UserObject(name: "User Name", id: "my-user-id"))
))

Retrieving a User

store.dispatch(
  UserCommand.fetchPubNubUser(
    UserIdRequest(userId: "my-user-id")
))

Creating a Space

store.dispatch(
  SpaceCommand.createPubNub(
    SpaceRequest(space: SpaceObject(name: "Space Name", id: "my-space-id"))
))

Joining a Space

store.dispatch(
  MembershipCommand.join(
    MembershipModifyRequest(
      userId: "my-user-id",
      modifiedBy: [
        UserObjectMembership(id: "my-space-id")
      ])
))