Objects v2 Migration Guide

Objects 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 Objects v2, 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 version 2 now, we strongly suggest that you do that.

What's new in Objects v2

The new version of Objects brings consistency to SDK methods, simplifies the event format, and updates the REST APIs. Note that Objects doesn't currently support authorization using PubNub Access Manager (PAM). This functionality will be implemented soon.

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 Objects, 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 Objects 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 Objects v2.

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 Objects v2, you receive events in a single format, and can use a single listener for all Objects events.

The following JavaScript code adds an Objects v2 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 UUID 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 Objects v2 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 Objects v2, 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 Objects v2 don't support Objects v1.

REST API endpoints

Please refer to the REST API documentation for the new /v2/objects REST API endpoints.