App Context API for Swift Native SDK
Starting a new app? Use DataSync
DataSync is the successor to App Context. It covers the same users, channels, and memberships, and adds typed schemas, JSON Patch updates with ETags, field-level projections, and per-class expiry. Refer to the feature-by-feature comparison for details.
DataSync is currently available to new accounts and to accounts that are not actively using App Context. If your keysets already use App Context, keep using it for now. App Context remains fully supported.
This page describes App Context (formerly Objects v2). To upgrade from Objects v1, refer to the migration guide.
App Context provides easy-to-use, serverless storage for user and channel data you need to build innovative, reliable, scalable applications. Use App Context to store metadata about your application users and channels, and their membership associations, without the need to stand up your own databases.
PubNub also triggers events when object data is set or removed from the database. Clients can receive these events in real-time and update their front-end application accordingly.
UUID and User ID
PubNubUUIDMetadataBase is deprecated but will continue to work as a typealias for PubNubUserMetadataBase.
User
Get metadata for all users
Returns a paginated list of user metadata objects, optionally including the custom data object for each.
Required keyset configuration
Method(s)
To Get All User Metadata you can use the following method(s) in the Swift SDK:
1func allUserMetadata(
2 include: PubNub.UserIncludeFields = PubNub.UserIncludeFields(),
3 filter: String? = nil,
4 sort: [PubNub.ObjectSortField] = [],
5 limit: Int? = 100,
6 page: PubNubHashedPage? = Page(),
7 custom requestConfig: PubNub.RequestConfiguration = PubNub.RequestConfiguration(),
8 completion: ((Result<(users: [PubNubUserMetadata], next: PubNubHashedPage?), Error>) -> Void)?
9)
include#- Whether to include additional fields.
filter#- Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined in the filtering reference
sort#- List of properties to sort response objects. The following properties are valid for sorting:
.id,.name,.type,.status, and.updated. page#- The paging object used for pagination that allows for cursor-based pagination where the pages are navigated using a cursor, such as a
nextvalue. limit#- The number of objects to retrieve at a time.
custom#- An object that allows for per-request customization of PubNub configuration or network session. For more information, refer to the Request Configuration section.
completion#- The async
Resultof the method call.
UserIncludeFields
PubNub.UserIncludeFields is a struct that defines which additional fields should be included in the response when fetching user metadata. It allows fine-grained control over what data is returned, helping optimize response payload size and network efficiency.
Completion handler result
Success
A Tuple containing an Array of PubNubUserMetadata, and the next pagination PubNubHashedPage (if one exists).
1public protocol PubNubUserMetadata {
2
3 /// The unique identifier of the User
4 var metadataId: String { get }
5
6 /// The name of the User
7 var name: String { get set }
8
9 /// The classification of User
10 var type: String? { get set }
11
12 /// The current state of the User
13 var status: String? { get set }
14
15 /// The external identifier for the object
show all 32 lines1public protocol PubNubHashedPage {
2
3 /// The hash value representing the next set of data
4 var start: String? { get }
5
6 /// The hash value representing the previous set of data
7 var end: String? { get }
8
9 /// The total count of all objects withing range
10 var totalCount: Int? { get }
11}
Failure
An Error describing the failure.
Sample code
1
Get user metadata
Returns metadata for the specified User, optionally including the custom data object for each.
Method(s)
To Get User Metadata you can use the following method(s) in the Swift SDK:
1func fetchUserMetadata(
2 _ metadataId: String?,
3 include: PubNub.UserIncludeFields = PubNub.UserIncludeFields(),
4 custom requestConfig: PubNub.RequestConfiguration = PubNub.RequestConfiguration(),
5 completion: ((Result<PubNubUserMetadata, Error>) -> Void)?
6)
metadataIdrequired#- Unique User Metadata identifier. If not supplied, then it will use the request configuration and then the default configuration.
include#- Whether to include additional fields.
custom#- An object that allows for per-request customization of PubNub configuration or network session. For more information, refer to the Request Configuration section.
completion#- The async
Resultof the method call.
Completion handler result
Success
The PubNubUserMetadata object belonging to the identifier.
1public protocol PubNubUserMetadata {
2
3 /// The unique identifier of the User
4 var metadataId: String { get }
5
6 /// The name of the User
7 var name: String { get set }
8
9 /// The classification of User
10 var type: String? { get set }
11
12 /// The current state of the User
13 var status: String? { get set }
14
15 /// The external identifier for the object
show all 32 linesFailure
An Error describing the failure.
Sample code
1
Set user metadata
Unsupported partial updates of custom metadata
The value of the custom metadata parameter sent in this method always overwrites the value stored on PubNub servers. If you want to add new custom data to an existing one, you must:
- Get the existing metadata and store it locally.
- Append the new custom metadata to the existing one.
- Set the entire updated custom object.
Set metadata for a User in the database, optionally including the custom data object for each.
Method(s)
To Set User Metadata you can use the following method(s) in the Swift SDK:
1func setUserMetadata(
2 _ metadata: PubNubUserMetadata,
3 ifMatchesEtag: String? = nil,
4 include: PubNub.UserIncludeFields = PubNub.UserIncludeFields(),
5 custom requestConfig: PubNub.RequestConfiguration = PubNub.RequestConfiguration(),
6 completion: ((Result<PubNubUserMetadata, Error>) -> Void)?
7)
metadatarequired#- User Metadata to set.
ifMatchesEtag#- The entity tag to be used to ensure updates only happen if the object hasn't been modified since it was read. Use the eTag you received from an applicable get metadata method to check against the server entity tag. If the eTags don't match, an HTTP 412 error is thrown.
include#- Whether to include additional fields.
custom#- An object that allows for per-request customization of PubNub configuration or network session. For more information, refer to the Request Configuration section.
completion#- The async
Resultof the method call.
API limits
To learn about the maximum length of parameters used to set user metadata, refer to REST API docs.
Completion handler result
Success
The PubNubUserMetadata object belonging to the identifier.
1public protocol PubNubUserMetadata {
2
3 /// The unique identifier of the User
4 var metadataId: String { get }
5
6 /// The name of the User
7 var name: String { get set }
8
9 /// The classification of User
10 var type: String? { get set }
11
12 /// The current state of the User
13 var status: String? { get set }
14
15 /// The external identifier for the object
show all 32 linesFailure
An Error describing the failure.
Sample code
1
Remove user metadata
Removes the metadata from a specified UUID.
Method(s)
To Remove User Metadata you can use the following method(s) in the Swift SDK:
1func removeUserMetadata(
2 _ metadataId: String?,
3 custom requestConfig: PubNub.RequestConfiguration = PubNub.RequestConfiguration(),
4 completion: ((Result<String, Error>) -> Void)?
5)
metadataIdrequired#- Unique User Metadata identifier. If not supplied, then it will use the request configuration and then the default configuration.
custom#- An object that allows for per-request customization of PubNub configuration or network session. For more information, refer to the Request Configuration section.
completion#- The async
Resultof the method call.
Completion handler result
Success
The User identifier of the removed object.