App Context Migration Guide

App Context (formerly Objects v2) provides easy-to-use, serverless storage to store metadata for users, channels, and memberships without the need to stand up an external database. You can use this feature to tie additional properties to a user and channels to access it at any time and provide a richer experience for your customers.

With the introduction of App Context, PubNub has simplified and streamlined the service to integrate it with our core services. Use this guide to migrate to the new version if you're already using Objects v1 to store your data.

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

The new version of App Context brings consistency to SDK methods, simplifies the event format, and updates the REST APIs. Note that App Context doesn't currently support authorization using Access Manager.

Improvements to spaces and channels. The new version completely replaces the concept of spaces with channels. You can use channels as ephemeral strings, or you can optionally store additional metadata for your channels in our database.

Better ties to other services. The new SDK methods are better integrated with existing services, and reuse the UUID defined in your PubNub instance. You don't need to specify a separate user ID in each operation.

User and channel metadata is optional. While you have the ability to do so, it's not required to store user or channel metadata in our system. You can create membership records even if your user data resides in an external user management systems.

Migrating your code

To migrate to the new version of App Context, upgrade your SDK and update your application code to use the new SDK methods and event format. Refer to Migrating your data if you wish to move your existing App Context data to the new database.

New SDK methods

The following tables outline the correspondence between old and new SDK methods, using the JavaScript SDK as an example; other SDKs may vary slightly in their naming conventions.

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 from App Context.

New event format

PubNub also triggers events when object data is changed: set, updated, or removed from the database. At the same time, making a request to set the same data that already exist, doesn't trigger any event. Clients can receive these events in real time and update their front-end application accordingly.

With App Context v2, you receive events in a single format, and can use a single 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’re already using Objects v1 for your applications, you can continue to do so with the versions of the PubNub SDKs you're currently using.

When you upgrade your SDKs to support App Context, your existing data won't migrate to the new schema automatically. If you wish to retain your data, our PubNub Support team will assist you to migrate your objects data. To migrate your data, open a support ticket and give PubNub Support the appropriate Subscribe key from the Admin Portal.

There is no charge for data migration. Please note that when you migrate your data, it will no longer be accessible from Objects v1 SDK methods or REST APIs. Also, note that most SDKs which support App Context v2 don't 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.