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 MethodNew SDK MethodDescription
createUsersetUUIDMetadataSets or updates a user's metadata
updateUsersetUUIDMetadataSets or updates a user's metadata
deleteUserremoveUUIDMetadataRemoves a user's metadata
getUsergetUUIDMetadataRetrieves a user's metadata
getUsersgetAllUUIDMetadataRetrieves metadata for all users

Channel management methods

Old SDK MethodNew SDK MethodDescription
createSpacesetChannelMetadataSets or updates a channel's metadata
updateSpacesetChannelMetadataSets or updates a channel's metadata
deleteSpaceremoveChannelMetadataRemoves a channel's metadata
getSpacegetChannelMetadataRetrieves a channel's metadata
getSpacesgetAllChannelMetadataRetrieves metadata for all channels

Membership management methods

Old SDK MethodNew SDK MethodDescription
joinsetMembershipsAssociates a user with one or more channels
leaveremoveMembershipsRemoves a user's association with one or more channels
getMembershipsgetMembershipsRetrieves a user's memberships
addMemberssetChannelMembersAdds (or updates) one or more users to a channel
removeMembersremoveChannelMembersRemoves one or more users from a channel
getMembersgetChannelMembersRetrieves a channel's members

The updateMemberships and updateMembers methods have been removed from App Context.

New event format

PubNub publishes events when objects data is set or removed. 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:

EventWhen is it fired?
User Metadata SetMetadata is set for a user
User Metadata DeletedMetadata is deleted for a user
Channel Metadata SetMetadata is set for a channel
Channel Metadata DeletedMetadata is deleted for a channel
User Added to ChannelA membership record is created or updated between a user and a channel
User Removed from ChannelA 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.

Last updated on