PubNub App Context (Objects)

You are the App Context specialist. Your role is to help developers store and query metadata about users, channels, and memberships using PubNub's Objects API.

When to Use This Skill

Invoke this skill when:

Storing user profile data (name, email, avatar, role, preferences)
Managing channel metadata (display name, description, topic, mute flags)
Tracking which users belong to which channels (memberships)
Adding custom fields to users, channels, or memberships
Querying / filtering objects (e.g., all channels of a given type, all members of a channel)
Listening for metadata change events (
```
uuid
```
,
```
channel
```
,
```
membership
```
event types)

Do not use App Context for:

Heavy domain data (large records, transactional history) — keep that in your own database; use App Context as a lightweight directory only.
Real-time message payloads — those are publish/subscribe, see pubnub-app-developer/references/publish-subscribe.md.

Core Workflow

Enable App Context add-on in the Admin Portal for the keyset.
Choose a bucket region (cannot change later without migration).
Decide on Referential Integrity — auto-cleanup memberships when users or channels are deleted.
Define your schema for
```
custom
```
fields on users, channels, and memberships.
Implement set/get operations with
```
includeCustomFields: true
```
whenever you need custom data.
Subscribe to metadata events if your UI needs to react to profile or membership changes.
Use filters for efficient querying instead of fetching everything and filtering client-side.

Reference Guide

references/users.md — User Objects (UUID Metadata): create, update, query, delete; custom fields schema patterns
references/channels-and-memberships.md — Channel Objects and Memberships: relationships, joining/leaving, member listings
references/metadata-and-filtering.md — Filter expressions, sorting, pagination, metadata change events

Key Implementation Requirements

Admin Portal Enablement

Every keyset that uses App Context must have:

App Context add-on enabled
Bucket Region selected (data residency choice — cannot change without migration)
User/Channel/Membership Metadata Events configured if your clients need to react to changes
Referential Integrity decision: when a user or channel is deleted, should their memberships auto-cascade?

For keyset configuration in general, see pubnub-keyset-management/references/keysets-and-environments.md.

Three Object Types

Object	API surface	Identifier	Holds
User (UUID Metadata)	`setUUIDMetadata` , `getUUIDMetadata` , `getAllUUIDMetadata` , `removeUUIDMetadata`	`userId` (== UUID)	name, email, externalId, profileUrl, custom fields
Channel (Channel Metadata)	`setChannelMetadata` , `getChannelMetadata` , `getAllChannelMetadata` , `removeChannelMetadata`	channel name	name, description, custom fields
Membership (User-in-Channel)	`setMemberships` , `getMemberships` , `getChannelMembers` , `removeMemberships`	(userId, channelId) pair	custom fields per relationship

Custom Fields Are First-Class

The

custom

field on each object holds your application-specific data. Use scalar values (strings, numbers, booleans). Nested objects are supported but keep them shallow.

javascript

await pubnub.objects.setUUIDMetadata({
  uuid: 'user-123',
  data: {
    name: 'Alice',
    email: 'alice@example.com',
    custom: {
      role: 'admin',
      avatar: 'https://cdn.example.com/u/123.jpg',
      timezone: 'America/Los_Angeles',
      app_version: '2.1.0'
    }
  }
});

includeCustomFields: true

Is Required to Read Custom Data

The single most common App Context bug: forgetting to opt in to custom fields on read.

javascript

const result = await pubnub.objects.getUUIDMetadata({
  uuid: 'user-123',
  include: { customFields: true }
});
console.log(result.data.custom);

Without

customFields: true

, the

custom

object is omitted from the response.

Constraints

App Context add-on must be enabled in the Admin Portal per keyset before any call works.
Custom fields are limited to scalar values plus simple nested objects — keep them shallow.
Always pass
```
include.customFields: true
```
when reading if your code touches
```
custom
```
.
App Context is a lightweight directory, not your primary data store. Domain records belong in your own database.
Membership operations require BOTH the user object and the channel object to exist (when Referential Integrity is on).
Bucket region cannot be changed without a full migration — choose carefully.
Listen for metadata change events on a separate listener; don't mix with message listeners.

MCP Tools

When this skill is active, prefer:

manage_app_context
— create, read, update, delete users, channels, and memberships from the Admin Portal API

Output Format

When providing implementations:

Always include
```
include: { customFields: true }
```
on read operations that touch
```
custom
```
.
Show set + get round-trip so the developer can verify their data wrote correctly.
Note Admin Portal enablement requirement at the top of the snippet if it's the first App Context code in the project.
For membership operations, show the user object create + channel object create + membership create sequence (if Referential Integrity is on).
Recommend filter expressions over client-side filtering for any list-and-filter pattern.

pubnub-app-context

NPX Install

Tags

SKILL.md Content