App Context Migration Guide

App Context (formerly Objects v2) provides easy‑to‑use, serverless storage for metadata on users, channels, and memberships. You don’t need to run an external database. Use it to attach properties to users and channels and retrieve them any time to deliver richer experiences.

With App Context, PubNub simplified and streamlined the service to integrate with core capabilities. Use this guide to migrate if you currently use Objects v1.

Objects v1 deprecation

Objects v1 is not supported anymore. If you haven't migrated to App Context now, we strongly suggest that you do that.

What’s new in App Context

App Context brings consistent SDK methods, a simplified event format, and updated REST APIs. App Context currently doesn’t support authorization using Access Manager.

Spaces replaced with channels. App Context replaces the concept of spaces with channels. You can use channels as ephemeral identifiers, or optionally store channel metadata.

Better ties to other services. SDK methods integrate with existing services and reuse the UUID defined in your instance. You don’t need to specify a separate user ID in each operation.

User and channel metadata is optional. You don’t need to store user or channel metadata in PubNub to create memberships. You can keep user data in external systems.

Migrating your code

To migrate to App Context, upgrade your SDK and update your code to use the new SDK methods and event format. See Migrating your data if you want to move existing data to the new database.

New SDK methods

The following tables show old‑to‑new SDK methods using the JavaScript SDK as an example. Other SDKs may vary slightly in naming.

User management methods

Old SDK Method	New SDK Method	Description
createUser	setUUIDMetadata	Sets or updates a user's metadata
updateUser	setUUIDMetadata	Sets or updates a user's metadata
deleteUser	removeUUIDMetadata	Removes a user's metadata
getUser	getUUIDMetadata	Retrieves a user's metadata
getUsers	getAllUUIDMetadata	Retrieves metadata for all users

Channel management methods

Old SDK Method	New SDK Method	Description
createSpace	setChannelMetadata	Sets or updates a channel's metadata
updateSpace	setChannelMetadata	Sets or updates a channel's metadata
deleteSpace	removeChannelMetadata	Removes a channel's metadata
getSpace	getChannelMetadata	Retrieves a channel's metadata
getSpaces	getAllChannelMetadata	Retrieves metadata for all channels

Membership management methods

Old SDK Method	New SDK Method	Description
join	setMemberships	Associates a user with one or more channels
leave	removeMemberships	Removes a user's association with one or more channels
getMemberships	getMemberships	Retrieves a user's memberships
addMembers	setChannelMembers	Adds (or updates) one or more users to a channel
removeMembers	removeChannelMembers	Removes one or more users from a channel
getMembers	getChannelMembers	Retrieves a channel's members

The updateMemberships and updateMembers methods have been removed.

New event format

PubNub triggers events when object data is set, updated, or removed. Setting data to the same value does not trigger an event. Clients receive events in real time and can update the UI accordingly.

With App Context, you receive events in a single format and can use one listener for all App Context events.

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.

The following JavaScript code adds an App Context listener:

pubnub.addListener({
  objects: (o) => {
    var channel = o.channel; // The channel
    var channelGroup = o.subscription; // The channel group
    var timetoken = o.timetoken; // The event timetoken
    var publisher = o.publisher; // The User ID that made the call
    var event = o.message.event; // The event (set or delete) that occurred
    var type = o.message.type; // The type of metadata involved
    var data = o.message.data; // The associated event data
  }
});

The following events are defined:

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

All App Context events use the following format:

{
  channel: string,
  message: {
     event: string,
     type: string,
     data: object
  }
  subscription: string,
  timetoken: number
}

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, channel, or membership
data contains event-specific information

Migrating your data

If you use Objects v1 today, you can continue with SDK versions that still support it.

When you upgrade SDKs to App Context, your data is not migrated automatically. If you want to retain your data, PubNub Support will help migrate your objects data. Open a support ticket and include the Subscribe key from the Admin Portal.

There is no charge for data migration. After migration, data is no longer accessible from Objects v1 SDK methods or REST APIs. Most SDKs that support App Context do not support Objects v1.

REST API endpoints

Please refer to the REST API documentation (App Context for Users, Channels, Memberships) for the new /v2/objects REST API endpoints.

Objects v1 deprecation

What’s new in App Context​

Migrating your code​

New SDK methods​

User management methods​

Channel management methods​

Membership management methods​

New event format​