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 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 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.
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 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 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 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.