PubNub App Context

App Context is a feature that lets you store and manage data (also called metadata) for users, channels, and relationships between them (membership) directly within the PubNub platform.

This way, you can provide personalized and context-rich interactions in real-time applications without needing external databases, enhancing user experience while ensuring data security and compliance.

Configuration

To use App Context, you must enable and configure it on a chosen app's keyset in the Admin Portal.

Option	Description
Bucket Region	Geographical region where your App Context data is stored and managed. Choosing a region closer to your user base can reduce latency and improve performance. Once you select a region and save the settings, you cannot change it.
User Metadata Events	Enables or disables the generation and dispatch of events related to changes in user metadata. When enabled, any create, update, or delete operation on user metadata will trigger an event, which can be consumed by subscribers in real time to react to changes immediately. Head to Real-time updates section to find out about user event types and how to receive them.
Channel Metadata Events	Controls whether events are generated when channel metadata is created, updated, or deleted. Similar to user metadata events, these allow applications to subscribe to these events and respond dynamically to channel characteristics or properties changes, facilitating real-time updates across clients. Head to Real-time updates section to find out about channel event types and how to receive them.
Membership Events	Determines if events related to memberships (associations between users and channels) will be generated and sent. This option is crucial for applications that need to manage and respond to changes in which users are part of which channels, supporting dynamic access control and personalized user experiences. Just like with other event types, you must subscribe to them for your app to receive and handle them. Head to Real-time updates section to find out about membership event types and how to receive them.
Disallow Get All Channel Metadata	This option blocks your app from accessing metadata of all channels in apps with enabled Access Manager. If you enable Access Manager and uncheck this option, you can get all channel metadata without the need to define that in the permissions schema included in the authentication token.
Disallow Get All User Metadata	This option blocks your app from accessing metadata of all users in apps with enabled Access Manager. If you enable Access Manager and uncheck this option, you can get all user metadata without the need to define that in the permissions schema included in the authentication token.
Enforce referential integrity for memberships	When enabled, you can set new membership only when both the specified user ID and channel ID exist as standalone user and channel metadata entities. Deleting a parent user or channel metadata entity automatically deletes any child membership associations for that deleted entity. When disabled, memberships can be created even for the non-existent user and channel entities, while deleting a user or channel entity does not automatically delete any associated membership objects.

Functional components

App Context is an umbrella term for these three metadata types:

• Channel metadata — Maintain channel-related data, including names, descriptions, or custom attributes that support the dynamics of a particular channel within your application.

• User metadata — Store and manage user-specific information such as name, email, or custom attributes using the serverless storage provided by the App Context.

• Membership metadata — Handle the relationships between users and channels, facilitating the addition, update, or removal of users from channels and vice versa.

Data management

You can manage App Context data in PubNub through SDK methods, REST API endpoints and calls, or the BizOps Workspace GUI. Your choice of method depends on your operational needs and technical preferences.

SDKs

SDKs are best for real-time, in-app interactions. PubNub provides SDKs for various programming languages and platforms, making it easy to manage App Context data programmatically within your applications.

In the left navigation of each set of SDK docs, you can find the App Context section listing all methods for managing App Context data. For reference, check JavaScript.

REST API

REST API is ideal for server-to-server interactions, or integration with systems not supported by the SDKs.

PubNub's REST API provides another way to manage App Context data. This is useful for server-side operations where an SDK may not be integrated or for administrative tasks that can be performed from various platforms that can make HTTP requests.

• Users API
• Channels API
• Memberships API

BizOps Workspace

BizOps Workspace is perfect for operational teams without technical expertise who prefer to manage user, channel, and membership data through a GUI.

BizOps Workspace is available in the Admin Portal UI and contains these App Context-related views:

• User management — for creating, updating, and deleting user and membership data
• Channel management — for creating, updating, and deleting channel and membership data

Real-time updates

PubNub generates events when changes (such as updates, deletions, or additions) occur to metadata for users, channels, and their memberships (user-channel relationships). Clients can subscribe to receive these events in real time, react dynamically to these changes, and update their front-end application accordingly.

App Context events

PubNub defined the following App Context events:

Event	Type	When it's fired
User Metadata Set	User	Metadata is set for a user
User Metadata Deleted	User	Metadata is deleted for a user
Channel Metadata Set	Channel	Metadata is set for a channel
Channel Metadata Deleted	Channel	Metadata is deleted for a channel
User Added to Channel	Membership	A membership record is created or updated between a user and a channel
User Removed from Channel	Membership	A membership record is removed between a user and a channel

All App Context events use the following format:

{
  "channel": "sample-channel",
  // event payload
  "message": {
    // API from which data is originating
     "source": "objects",
     // event structure version
     "version": "2.0",
     // type of occurring event, e.g. "set" or "delete"
     "event": "sample-event",
     // category of data, e.g. "membership" or "channel"
     "type": "sample-type",
     // specific event-related data
     "data": {
      // e.g. "type": {member.Type},

show all 24 lines

The fields are defined as follows:

• event indicates what happened, and can be set or delete
• type indicates where the event happened, and can be uuid (user), channel, or membership
• data contains event-specific information

User metadata event notifications

When the User Metadata Events option is enabled on a keyset, any modification to a user entity (set and delete) results in sending event notifications to any membership associations, so both that user and any channel they are a member of.

For example, if a user with User ID test-user-1 is a member of channels test-channel-1 and test-channel-2, and that user entity is modified, a set event for type uuid is published to the three channels: test-user-1 (user-associated channel), test-channel-1, and test-channel-2. Similarly, a delete event is published to those three channels if that User ID is deleted.

Subscribe to App Context events

Subscribing to App Context events in PubNub involves using a PubNub SDK to listen for real-time changes in metadata related to users, channels, or memberships.

Detailed steps on how to set up event subscriptions are listed in the documentation of a given SDK, but the general steps are as follows:

1. Initialize PubNub — Set up your PubNub instance using your publish and subscribe keys.

2. Add a listener — Implement an event listener (also called event handler) that will handle incoming messages and events related to App Context (used to called Objects) features, such as user metadata, channel metadata, and memberships. For more information on adding an event listener, head to the Receive section.

3. Subscribe to channels — Determine the channels or channel patterns that will receive App Context events and subscribe to them.

   You can choose whether to subscribe to the channel (if you are interested in receiving all membership info from that channel) or a user (if you are interested in listening to changes/events concerning the user’s data or their memberships). Subscribing to a user involves setting up a subscription to a particular channel for user change events, which typically is the user’s user ID.

Subscribing to App Context events primarily relies on using SDKs and event listeners. However, you can also use PubNub Functions to consume, modify, and analyze messages or events in real-time by writing JavaScript code that executes directly on the PubNub network.

API limits

PubNub imposes soft and hard limits for user and channel metadata in an App Context API, including size constraints for records and field character limits and recommended maximums for user memberships and channel members. For details, head to API Limits.