JavaScriptNode.jsNode.jsPhoneGapReactTitaniumVueWebNode.js V4 Objects (BETA)

Objects provides easy-to-use, serverless storage for data you need to build innovative, reliable, scalable Chat applications. Use Object information across your connected experience features. You can easily save, read, update, and delete information about your application users, shared communication spaces, and their relationships, without the need to stand up a database. Simply build and go.

 Objects is an optional feature, currently in a BETA release—you can use your own user management system, and simply use the usual publish and subscribe. If you'd like to use PubNub's serverless storage, Objects provides a full-featured solution.

This tutorial provides information on the following topics:

Objects provides functionality to let your application:

  • Create, read, update, and delete users and spaces

  • Manage space memberships for a user

  • Manage members in a space

  • Store channel cursors for users

  • Listen to events for data changes

  • Use granular controls to secure your data

Chat applications begin and end with the users who communicate through them. Each user has attributes, some of which are common to all chat applications: real name, user handle, and so forth. Other attributes may be unique to your application—level achieved in a game, user type, and more.

With PubNub Objects, you create a stored entry for each user and enrich it with all the attributes you need to make their experience engaging and valuable. Over time, update their information or remove them as they leave the audience. All with a simple set of APIs, and no self-administered database.

In most PubNub use cases, a user is identified by a UUID. The Objects term for this identifier is a User ID.

In order to communicate, chat users select a subset of other users to join. There might be a general space for talking to every other user; a space for a subset of users; and a personal space, where the user chats with just one individual.

With PubNub Objects, you can track the spaces that are in play within your application. Assign them common names, descriptions, and any custom information needed to make your application work effectively.

There is no pre-built association between spaces and PubNub channels. In most cases, you'll want to set the space_id equal to the channel name. Then, if you subscribe to a channel, you'll also get updates about the space with that ID.

Users can belong to multiple spaces, and spaces can have multiple members. Use Memberships to access the relationships between objects.

On opening their clients, application users can immediately see which spaces they are members of, access lists of other users who are with them in a specific space, and access information about spaces and other users alike.

There are two perspectives from which to perform membership operations. For example, consider a retrieval operation:

  • From the user perspective: given a user, return all the spaces the user is a member of.

  • From the space perspective: given a space, return all the users in that space.

This section provides information on the following topics:

PubNub Objects allows you to perform create, read, update, and delete operations on users, spaces, and memberships (i.e., associations between users and spaces).

It is possible to define custom fields on objects. These custom fields are stored as an array of key/value pairs. The custom fields support standard data-types: string, number, date.

PubNub generates events automatically when records are created, updated or removed from storage. Client applications can receive these events in real time and update the front-end application accordingly.

This section provides information on the following topics:

Events are published on user-inbox channels or space channels. Clients will need to subscribe to these channels to receive the events.

My user channel - subscribe to the {user_id} channel to receive individual events for that user. Typically, only the user should have read access to their user inbox channel.

Space channels - subscribe to the {space_id} channel to receive events for that space. All users who belong to that space should have read access to the space channel.

Once you have subscribed to user and space channels, the client will receive events for user, space and membership updates. Add listeners to receive events for each resource.

pubnub.addListener({
  user: function(userEvent) {
      // this will trigger when:
      // . user updated
      // . user deleted
  },
  space: function(spaceEvent) {
      // this will trigger when:
      // . space updated
      // . space deleted
  },
  membership: function(membershipEvent) {
      // this will trigger when:
      // . user added to a space
      // . user removed from a space
      // . membership updated on a space
  }
});
EventsDescription
User Updated

Generated when user properties are updated.

User Deleted

Generated when a user record is deleted.

Space Updated

Generated when space properties are updated.

Space Deleted

Generated when a space record is deleted

User Added to Space

Generated when a user-space relationship is created

User Removed from Space

Generated when a user-space relationship is deleted

User Membership Updated on Space

Generated when a user-space relationship is updated

channel: string;
message: {
  data: object;
  event: string;
  type: string;
};
publisher: string | undefined;
subscription: null;
timetoken: string;

Space User Event:

{  
  "source":"objects",
  "version":"1.0",
  "event":"delete",
  "type":"user",
  "data":{  
    "id":"user-1",
    "updated":"2019-02-20T23:11:20.893755"
  }
}

Space Sample Event:

{  
  "source":"objects",
  "version":"1.0",
  "event":"update",
  "type":"space",
  "data":{  
    "id":"space-1",
    "name":"Product channel",
    "description":"A meeting room for the product team",
    "updated":"2019-02-20T23:11:20.893755"
  }
}

Membership Sample Event:

{  
  "source":"objects",
  "version":"1.0",
  "event":"create",
  "type":"membership",
  "data":{  
    "spaceId":"space-1",
    "userId":"user-1",
    "created":"2019-02-20T23:11:20.893755",
    "updated":"2019-02-20T23:11:20.893755"
  }
}

Object events are enabled by default on new keys. If you don't need them, you can disable these events by toggling the appropriate setting from the PubNub Admin Dashboard:

  • User Events

  • Space Events

  • Membership Events

This section provides information on the following topics:

Clients will need to be granted permissions to access Object APIs if PubNub Access Manager (PAM) is enabled on your key. Refer to the Grant v3 API documentation for more information.

An admin server can use the Grant V3 API to manage object-level permissions. Clients can be granted access to all user, space, and membership resources or to a limited set of resources depending on your application logic.

Permissions are as follows:
  • create - provides the ability to create objects

  • read - provides the ability to fetch objects

  • write - provides the ability to update objects

  • manage - provides the ability to add, remove or update object relationships

  • delete - provides the ability to delete objects

The following are a few ways to combine permissions into sets to provide different levels of access for clients connecting to PubNub. Note that in the sample roles that follow, "all spaces" and "all users" can be defined with patterns. For example, this pattern matches all characters: ^.*$.

A standard user can be granted read, write and manage access to their own user record. They can also be granted read access on all users and spaces so they have the ability to fetch the entire list of records from the database.

  • My user: Read, Write, Manage
  • All users: Read
  • All spaces: Read

An admin user can be granted read, write and manage access to all users and spaces.

  • All users: Create, Read, Write, Manage
  • All spaces: Create, Read, Write, Manage
  • All channels: Read, Write

A super admin user may be granted access additional access to delete all resources.

  • All users: Create, Read, Write, Manage, Delete
  • All spaces: Create, Read, Write, Manage, Delete
  • All channels: Read, Write

Clients may be granted access to individual spaces to control the operations that are allowed on a space. In this case, the sample user roles could look like this:

Standard users have Read and Write permissions on the space.

Admin users have Read, Write, and Manage permissions on the space.

Super admin users have Read, Write, Manage, and Delete permissions on the space.

OperationPermission required
Create a Space
Create permission on the space
Get a Space
Read permission on the space
Get all Spaces
Read permission on all spaces
Get members in a Space
Read permission on the space
Delete a Space
Delete permission on the space
Update a Space
Write permission on the space
Add members to a Space
Write and Manage permissions on the space
Remove members from a Space
Write and Manage permissions on the space
Create a user
Create permissions on the user
Get a user
Read permissions on the user
Get all users
Read permissions on all users
Get space memberships for a user
Read permissions on the user
Delete a user
Delete permissions on the user
Update a user
Write permissions on the user
Update space memberships for a user
Write permissions on the user
Remove space memberships for a user
Write permissions on the user
Add space memberships for a user
Write and Manage permissions on the user
Read permissions on the space