Setup and event listeners

All chat applications have a notion of a user. It's important to be able to uniquely identify users as they interact with the PubNub Network. Usually, a user is a human end user—a person using an app to interact with a system (via a laptop, phone, tablet, or kiosk).

You use a User ID to uniquely identify each user on the system. Users can connect from multiple devices, such as phones, tablets, desktops, etc., using the same User ID. If a user is connected from multiple devices simultaneously, they will receive the same messages on each device.

User ID / UUID

User ID is also referred to as UUID/uuid in some APIs and server responses but holds the value of the userId parameter you set during initialization.

Setup

Start by initializing a PubNub object with publishKey, subscribeKey, and userId as required fields. The userId is a string of maximum 92 characters that represents a user in your application.

Your publish and subscribe keys are available in your PubNub Account. Go to the Admin Portal to create your free account.

userId is required

Setting the userId parameter is required to establish a connection to PubNub, ensure that your billing is accurate, and for other features like presence and storage to work as expected.

JavaScript

1const pubnub = new PubNub({
2  subscribeKey: "mySubscribeKey",
3  publishKey: "myPublishKey",
4  userId: "john-doe",
5  autoNetworkDetection: true, // enable for non-browser environment automatic reconnection
6  restore: true, // enable catchup on missed messages
7});

Java

1PNConfiguration.Builder configBuilder = PNConfiguration.builder(new UserId("yourUserId"), "yourSubscribeKey");
2configBuilder.publishKey("myPublishKey");
3PubNub pubNub = PubNub.create(configBuilder.build());

Swift

1let config = PubNubConfiguration(
2  publishKey: "myPublishKey",
3  subscribeKey: "mySubscribeKey",
4  userId: "john-doe"
5)
6

7let pubnub = PubNub(configuration: config)

Objective-C

1PNConfiguration *pnconfig = [PNConfiguration configurationWithPublishKey:@"myPublishKey"
2                                             subscribeKey:@"mySubscribeKey"];
3pnconfig.uuid = "john-doe";
4self.pubnub = [PubNub clientWithConfiguration:pnconfig];

Add event listeners

Events are received in your app using listeners. These listeners allows a single point to receive messages, signals, and presence events. Each event type has its own handler to receive them where you implement your custom app logic to perform actions on events.

The following handlers are available to you:

Handler	Description
Status	Receives events when the client successfully connects (subscribes), or reconnects (in case of connection issues) to channels.
Message	Receives all messages published to all the channels subscribed by the client. The event payload will contain the published message data, publish timetoken, the User ID of the client that published the message and more.
Signal	Receives all signals that are sent to any channels subscribed by the client. The event payload will contain the signal data, signal timetoken, the User ID of the client that published the message and more.
Presence	Receives all presence events that are triggered on any channels subscribed by the client. The event payload will contain the presence event type (join, leave, timeout, state-change), timetoken of the action, the User ID of the client that caused the event, state data (if applicable) and more.
MessageAction	Receives all events when existing messages are annotated (by an action) for any channels subscribed by the client. The event payload will contain the User ID that acted on the message, message reaction type (such as an emoji reaction), timetoken of the annotated message, timetoken of the action, action value and more.
Objects	Receives all objects events that are emitted when a channel, channel membership, or user metadata is created, updated or removed.

JavaScript

1pubnub.addListener({
2    message: function(m) {
3        // handle message
4        var channelName = m.channel; // The channel to which the message was published
5        var channelGroup = m.subscription; // The channel group or wildcard subscription match (if exists)
6        var pubTT = m.timetoken; // Publish timetoken
7        var msg = m.message; // The Payload
8        var publisher = m.publisher; //The Publisher
9    },
10    presence: function(p) {
11        // handle presence
12        var action = p.action; // Can be join, leave, state-change, or timeout
13        var channelName = p.channel; // The channel to which the message was published
14        var occupancy = p.occupancy; // Number of users subscribed to the channel
15        var state = p.state; // User State
16        var channelGroup = p.subscription; //  The channel group or wildcard subscription match (if exists)
17        var publishTime = p.timestamp; // Publish timetoken
18        var timetoken = p.timetoken;  // Current timetoken
19        var uuid = p.uuid; // UUIDs of users who are subscribed to the channel
20    },
21    signal: function(s) {
22        // handle signal
23        var channelName = s.channel; // The channel to which the signal was published
24        var channelGroup = s.subscription; // The channel group or wildcard subscription match (if exists)
25        var pubTT = s.timetoken; // Publish timetoken
26        var msg = s.message; // The Payload
27        var publisher = s.publisher; //The Publisher
28    },
29    objects: (objectEvent) => {
30        var channel = objectEvent.channel; // The channel
31        var channelGroup = objectEvent.subscription; // The channel group
32        var timetoken = objectEvent.timetoken; // The event timetoken
33        var publisher = objectEvent.publisher; // The User ID that triggered this event
34        var event = objectEvent.event; // The event name that occurred
35        var type = objectEvent.type; // The event type that occurred
36        var data = objectEvent.data; // The event data that occurred
37    },
38    messageAction: function(ma) {
39        // handle message reaction
40        var channelName = ma.channel; // The channel to which the message was published
41        var publisher = ma.publisher; //The Publisher
42        var event = ma.message.event; // message reaction added or removed
43        var type = ma.message.data.type; // message reaction type
44        var value = ma.message.data.value; // message reaction value
45        var messageTimetoken = ma.message.data.messageTimetoken; // The timetoken of the original message
46        var actionTimetoken = ma.message.data.actionTimetoken; // The timetoken of the message reaction
47    },
48    file: function (event) {
49        const channelName = event.channel; // Channel to which the file belongs
50        const channelGroup = event.subscription; // Channel group or wildcard subscription match (if exists)
51        const publisher = event.publisher; // File publisher
52        const timetoken = event.timetoken; // Event timetoken
53        const message = event.message; // Optional message attached to the file
54        const fileId = event.file.id; // File unique id
55        const fileName = event.file.name;// File name
56        const fileUrl = event.file.url; // File direct URL
57    },
58    status: function(s) {
59        var affectedChannelGroups = s.affectedChannelGroups; // The channel groups affected in the operation, of type array.
60        var affectedChannels = s.affectedChannels; // The channels affected in the operation, of type array.
61        var category = s.category; //Returns PNConnectedCategory
62        var operation = s.operation; //Returns PNSubscribeOperation
63        var lastTimetoken = s.lastTimetoken; //The last timetoken used in the subscribe request, of type long.
64        var currentTimetoken = s.currentTimetoken; //The current timetoken fetched in the subscribe response, which is going to be used in the next request, of type long.
65        var subscribedChannels = s.subscribedChannels; //All the current subscribed channels, of type array.
66    },
67});

show all 67 lines

Java

1pubnub.addListener(new StatusListener() {
2    // PubNub status
3    @Override
4    public void status(PubNub pubnub, PNStatus status) {
5            switch (status.getCategory()) {
6                /* handle various statuses */
7            }
8        }
9    });
10

11pubnub.addListener(new EventListener() {
12    // Messages
13    @Override
14    public void message(PubNub pubnub, PNMessageResult message) {
15        String messagePublisher = message.getPublisher();
16        System.out.println("Message publisher: " + messagePublisher);
17        System.out.println("Message Payload: " + message.getMessage());
18        System.out.println("Message Subscription: " + message.getSubscription());
19        System.out.println("Message Channel: " + message.getChannel());
20        System.out.println("Message timetoken: " + message.getTimetoken());
21    }
22

23    // Presence
24    @Override
25    public void presence(@NotNull PubNub pubnub, @NotNull PNPresenceEventResult presence) {
26        System.out.println("Presence Event: " + presence.getEvent());
27        // Can be join, leave, state-change or timeout
28

29        System.out.println("Presence Channel: " + presence.getChannel());
30        // The channel to which the message was published
31

32        System.out.println("Presence Occupancy: " + presence.getOccupancy());
33        // Number of users subscribed to the channel
34

35        System.out.println("Presence State: " + presence.getState());
36        // User state
37

38        System.out.println("Presence UUID: " + presence.getUserId());
39        // User ID to which this event is related
40

41        presence.getJoin();
42        // List of users that have joined the channel (if event is 'interval')
43

44        presence.getLeave();
45        // List of users that have left the channel (if event is 'interval')
46

47        presence.getTimeout();
48        // List of users that have timed-out off the channel (if event is 'interval')
49

50        presence.getHereNowRefresh();
51        // Indicates to the client that it should call 'hereNow()' to get the
52        // complete list of users present in the channel.
53    }
54

55    // Signals
56    @Override
57    public void signal(PubNub pubnub, PNSignalResult pnSignalResult) {
58        System.out.println("Signal publisher: " + signal.getPublisher());
59        System.out.println("Signal payload: " + signal.getMessage());
60        System.out.println("Signal subscription: " + signal.getSubscription());
61        System.out.println("Signal channel: " + signal.getChannel());
62        System.out.println("Signal timetoken: " + signal.getTimetoken());
63    }
64

65    // Message reaction
66    @Override
67    public void messageAction(PubNub pubnub, PNMessageActionResult pnActionResult) {
68        PNMessageAction pnMessageAction = pnActionResult.getAction();
69        System.out.println("Message reaction type: " + pnMessageAction.getType());
70        System.out.println("Message reaction value: " + pnMessageAction.getValue());
71        System.out.println("Message reaction User ID: " + pnMessageAction.getUserId());
72        System.out.println("Message reaction actionTimetoken: " + pnMessageAction.getActionTimetoken());
73        System.out.println("Message reaction messageTimetoken: " + pnMessageAction.getMessageTimetoken());]
74        System.out.println("Message reaction subscription: " + pnActionResult.getSubscription());
75        System.out.println("Message reaction channel: " + pnActionResult.getChannel());
76        System.out.println("Message reaction timetoken: " + pnActionResult.getTimetoken());
77    }
78

79    // File Sharing
80    @Override
81    public void file(PubNub pubnub, PNFileEventResult pnFileEventResult) {
82        System.out.println("File channel: " + pnFileEventResult.getChannel());
83        System.out.println("File publisher: " + pnFileEventResult.getPublisher());
84        System.out.println("File message: " + pnFileEventResult.getMessage());
85        System.out.println("File timetoken: " + pnFileEventResult.getTimetoken());
86        System.out.println("File file.id: " + pnFileEventResult.getFile().getId());
87        System.out.println("File file.name: " + pnFileEventResult.getFile().getName());
88        System.out.println("File file.url: " + pnFileEventResult.getFile().getUrl());
89    }
90});

show all 90 lines

Swift

1// Create a new listener instance
2let listener = SubscriptionListener()
3

4// Add listener event callbacks
5listener.didReceiveSubscription = { event in
6  switch event {
7  case let .messageReceived(message):
8    print("Message Received: \(message) Publisher: \(message.publisher ?? "defaultUserID")")
9  case let .connectionStatusChanged(status):
10    print("Status Received: \(status)")
11  case let .presenceChanged(presence):
12    print("Presence Received: \(presence)")
13  case let .subscribeError(error):
14    print("Subscription Error \(error)")
15  default:
16    break
17  }
18}
19

20// Start receiving subscription events
21pubnub.add(listener)

show all 21 lines

Objective-C

1// Listener's class should conform to `PNEventsListener` protocol
2// in order to have access to available callbacks.
3

4// Adding listener.
5[pubnub addListener:self];
6

7// Callbacks listed below.
8

9- (void)client:(PubNub *)pubnub didReceiveMessage:(PNMessageResult *)message {
10    NSString *channel = message.data.channel; // Channel on which the message has been published
11    NSString *subscription = message.data.subscription; // Wild-card channel or channel on which PubNub client actually subscribed
12    NSNumber *timetoken = message.data.timetoken; // Publish timetoken
13    id msg = message.data.message; // Message payload
14    NSString *publisher = message.data.publisher; // Message publisher
15}
16

17- (void)client:(PubNub *)pubnub didReceiveSignal:(PNSignalResult *)signal {
18    NSString *channel = message.data.channel; // Channel on which the signal has been published
19    NSString *subscription = message.data.subscription; // Wild-card channel or channel on which PubNub client actually subscribed
20    NSNumber *timetoken = message.data.timetoken; // Signal timetoken
21    id msg = message.data.message; // Signal payload
22    NSString *publisher = message.data.publisher; // Signal publisher
23}
24

25- (void)client:(PubNub *)pubnub didReceiveMessageAction:(PNMessageActionResult *)action {
26    NSString *channel = action.data.channel; // Channel on which the message has been published
27    NSString *subscription = action.data.subscription; // Wild-card channel or channel on which PubNub client actually subscribed
28    NSString *event = action.data.event; // Can be: added or removed
29    NSString *type = action.data.action.type; // Message reaction type
30    NSString *value = action.data.action.value; // Message reaction value
31    NSNumber *messageTimetoken = action.data.action.messageTimetoken; // Timetoken of the original message
32    NSNumber *actionTimetoken = action.data.action.actionTimetoken; // Timetoken of the message reaction
33    NSString *uuid = action.data.action.uuid; // UUID of user which added / removed message reaction
34}
35

36- (void)client:(PubNub *)pubnub didReceivePresenceEvent:(PNPresenceEventResult *)event {
37    NSString *channel = message.data.channel; // Channel on which presence changes
38    NSString *subscription = message.data.subscription; // Wild-card channel or channel on which PubNub client actually subscribed
39    NSString *presenceEvent = event.data.presenceEvent; // Can be: join, leave, state-change, timeout or interval
40    NSNumber *occupancy = event.data.presence.occupancy; // Number of users subscribed to the channel (not available for state-change event)
41    NSNumber *timetoken = event.data.presence.timetoken; // Presence change timetoken
42    NSString *uuid = event.data.presence.uuid; // UUID of user for which presence change happened
43

44    // Only for 'state-change' event
45    NSDictionary *state = event.data.presence.state; // User state (only for state-change event)
46

47    // Only for 'interval' event
48    NSArray<NSString *> *join = event.data.presence.join; // UUID of users which recently joined channel
49    NSArray<NSString *> *leave = event.data.presence.leave; // UUID of users which recently leaved channel
50    NSArray<NSString *> *timeout = event.data.presence.timeout; // UUID of users which recently timed out on channel
51}
52

53- (void)client:(PubNub *)pubnub didReceiveObjectEvent:(PNObjectEventResult *)event {
54    NSString *channel = event.data.channel; // Channel to which the event belongs
55    NSString *subscription = event.data.subscription; // Wild-card channel or channel on which PubNub client actually subscribed
56    NSString *event = event.data.event; // Can be: set or delete
57    NSString *type = event.data.type; // Entity type: channel, uuid or membership
58    NSNumber *timestamp = event.data.timestamp; // Event timestamp
59

60    PNChannelMetadata *channelMetadata = event.data.channelMetadata; // Updated channel metadata (only for channel entity type)
61    PNUUIDMetadata *uuidMetadata = event.data.uuidMetadata; // Updated channel metadata (only for uuid entity type)
62    PNMembership *membership = event.data.membership; // Updated channel metadata (only for membership entity type)
63}
64

65- (void)client:(PubNub *)pubnub didReceiveFileEvent:(PNFileEventResult *)event {
66    NSString *channel = event.data.channel; // Channel to which file has been uploaded
67    NSString *subscription = event.data.subscription; // Wild-card channel or channel on which PubNub client actually subscribed
68    id message = event.data.message; // Message added for uploaded file
69    NSString *publisher = event.data.publisher; // UUID of file uploader
70    NSURL *fileDownloadURL = event.data.file.downloadURL; // URL which can be used to download file
71    NSString *fileIdentifier = event.data.file.identifier; // Unique file identifier
72    NSString *fileName = event.data.file.name; // Name with which file has been stored remotely
73}
74

75- (void)client:(PubNub *)pubnub didReceiveStatus:(PNStatus *)status {
76    PNStatusCategory category = status.category; // One of PNStatusCategory fields to identify status of operation processing
77    BOOL isError = status.isError; // Whether any kind of error happened.
78    NSInteger statusCode = status.statusCode; // Related request processing status code
79    BOOL isTLSEnabled = status.isTLSEnabled; // Whether secured connection enabled
80    NSString *uuid = status.uuid; // UUID which configured for passed client
81    NSString *authKey = status.authKey; // Auth token configured for passed client
82    NSString *origin = status.origin; // Origin against which request has been sent
83    NSURLRequest *clientRequest = status.clientRequest; // Request which has been used to send last request (may be nil)
84    BOOL willAutomaticallyRetry = status.willAutomaticallyRetry; // Whether client will try to perform automatic retry
85

86    // Following is available when operation == PNSubscribeOperation,
87    // because status is PNSubscribeStatus instance in this case
88    PNSubscribeStatus *subscribeStatus = (PNSubscribeStatus *)status;
89    NSNumber *currentTimetoken = subscribeStatus.currentTimetoken; // Timetoken which has been used for current subscribe request
90    NSNumber *lastTimeToken = subscribeStatus.lastTimeToken; // Timetoken which has been used for previous subscribe request
91    NSArray<NSString *> *subscribedChannels = subscribeStatus.subscribedChannels; // List of channels on which client currently subscribed
92    NSArray<NSString *> *subscribedChannelGroups = subscribeStatus.subscribedChannelGroups; // List of channel groups on which client currently subscribed
93    NSString *channel = subscribeStatus.data.channel; // Name of channel to which status has been received
94    NSString *subscription = subscribeStatus.data.subscription; // Wild-card channel or channel on which PubNub client actually subscribed
95    NSNumber *timetoken = subscribeStatus.data.timetoken; // Timetoken at which event arrived
96    NSDictionary *userMetadata = subscribeStatus.data.userMetadata; // Metadata / envelope which has been passed along with event
97

98    // Following is available when isError == YES,
99    // because status is PNErrorStatus instance in this case
100    PNErrorStatus *errorStatus = (PNErrorStatus *)status;
101    id associatedObject = errorStatus.associatedObject; // Data which may contain related information (not decrypted message for example)
102    NSArray<NSString *> *erroredChannels = errorStatus.errorData.channels; // List of channels for which error reported (mostly because of Access Manager)
103    NSArray<NSString *> *erroredChannelGroups = errorStatus.errorData.channelGroups; // List of channel groups for which error reported (mostly because of Access Manager)
104    NSString *errorInformation = errorStatus.errorData.information; // Stringified information about error
105    id errorData = errorStatus.errorData.data; // Additional error information from PubNub service
106}

show all 106 lines

Unity

1pubnub.SubscribeCallback += SubscribeCallbackHandler;
2

3//Handler
4void SubscribeCallbackHandler(object sender, EventArgs e) {
5    SubscribeEventEventArgs mea = e as SubscribeEventEventArgs;
6

7    if (mea.Status != null) {
8        switch (mea.Status.Category) {
9            case PNStatusCategory.PNUnexpectedDisconnectCategory:
10            case PNStatusCategory.PNTimeoutCategory:
11                pubnub.Publish()
12                    .Channel("my_channel")
13                    .Message("Hello from the PubNub Unity SDK")
14                    .Async((result, status) => {
15                        if(!status.Error){
16                            Debug.Log(string.Format("DateTime {0}, In Publish Example, Timetoken: {1}", DateTime.UtcNow , result.Timetoken));
17                        } else {
18                            Debug.Log(status.Error);
19                            Debug.Log(status.ErrorData.Info);
20                        }
21                    });
22            break;
23        }
24    }
25    if (mea.MessageResult != null) {
26        Debug.Log("Channel" + mea.MessageResult.Channel);
27        Debug.Log("Payload" + mea.MessageResult.Payload);
28        Debug.Log("Publisher Id: " + mea.MessageResult.IssuingClientId);
29    }
30    if (mea.PresenceEventResult != null) {
31        Debug.Log("SubscribeCallback in presence" + mea.PresenceEventResult.Channel + mea.PresenceEventResult.Occupancy + mea.PresenceEventResult.Event);
32    }
33    if (mea.SignalEventResult != null) {
34        Debug.Log ("SubscribeCallback in SignalEventResult" + mea.SignalEventResult.Channel + mea.SignalEventResult.Payload);
35    }
36    if (mea.UserEventResult != null) {
37        Debug.Log(mea.UserEventResult.Name);
38        Debug.Log(mea.UserEventResult.Email);
39        Debug.Log(mea.UserEventResult.ExternalID);
40        Debug.Log(mea.UserEventResult.ProfileURL);
41        Debug.Log(mea.UserEventResult.UserID);
42        Debug.Log(mea.UserEventResult.ETag);
43        Debug.Log(mea.UserEventResult.ObjectsEvent);
44    }
45    if (mea.SpaceEventResult != null) {
46        Debug.Log(mea.SpaceEventResult.Name);
47        Debug.Log(mea.SpaceEventResult.Description);
48        Debug.Log(mea.SpaceEventResult.SpaceID);
49        Debug.Log(mea.SpaceEventResult.ETag);
50        Debug.Log(mea.SpaceEventResult.ObjectsEvent);
51    }
52    if (mea.MembershipEventResult != null) {
53        Debug.Log(mea.MembershipEventResult.UserID);
54        Debug.Log(mea.MembershipEventResult.Description);
55        Debug.Log(mea.MembershipEventResult.SpaceID);
56        Debug.Log(mea.MembershipEventResult.ObjectsEvent);
57    }
58    if (mea.MessageActionsEventResult != null) {
59        Debug.Log(mea.MessageActionsEventResult.Channel);
60        if(mea.MessageActionsEventResult.Data!=null){
61            Debug.Log(mea.MessageActionsEventResult.Data.ActionTimetoken);
62            Debug.Log(mea.MessageActionsEventResult.Data.ActionType);
63            Debug.Log(mea.MessageActionsEventResult.Data.ActionValue);
64            Debug.Log(mea.MessageActionsEventResult.Data.MessageTimetoken);
65            Debug.Log(mea.MessageActionsEventResult.Data.UUID);
66        }
67        Debug.Log(mea.MessageActionsEventResult.MessageActionsEvent);
68        Debug.Log(mea.MessageActionsEventResult.Subscription);
69    }
70}

show all 70 lines