Users API for PubNub Kotlin SDK

A User is a human, a device, or a control system that can access PubNub APIs. The Users of your system interact with each other using multiple clients on which your application is installed. Depending on the User type, you can enforce different rules, for example the ability for a single User to connect from multiple clients.

Calling Kotlin methods

Most PubNub Kotlin SDK method invocations return an Endpoint object, which allows you to decide whether to perform the operation synchronously or asynchronously. You must choose one of these or the operation will not be performed at all.

For example, the following code is valid and will compile, but the publish won't be performed:

pubnub.publish(
    message = "this sdk rules!",
    spaceId = "my_space"
)

To successfully publish a message, you must follow the actual method invocation with whether to perform it synchronously or asynchronously, for example:

pubnub.publish(
    message = "this sdk rules!",
    spaceId = "my_space"
).async { result, status ->
    if (status.error) {
        // handle error
    } else {
        // handle successful method result
    }
}

Fetch Users

Returns a paginated list of Users, optionally including custom fields for each.

Method(s)

pubnub.fetchUsers(
    limit: Int? = null,
    page: PNPage? = null,
    filter: String? = null,
    sort: Collection<PNSortKey> = listOf(),
    includeCount: Boolean = false,
    includeCustom: Boolean = false
).async { result, status -> }

Parameter	Type	Required	Default	Description
limit	Int	Optional	100	The number of objects to retrieve at a time.
page	PNPage?	Optional	null	The paging object used for pagination.
filter	String?	Optional	null	Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
sort	List<PNSortKey>	Optional	listOf()	List of properties to sort by. Available options are id, name, and updated. Use asc or desc to specify sort direction. For example: {name: 'asc'}
includeCount	Boolean	Optional	false	Request IncludeCount to be included in paginated response. By default, IncludeCount is omitted.
includeCustom	Boolean	Optional	false	Whether to include the Custom field in the fetch response.

Basic Usage

pubnub.fetchUsers()
        .async { result, status ->
            if (status.error) {
                //handle error
            } else if (result != null) {
                //handle result
            }
        }

Response

data class PNUserArrayResult(
    val status: Int,
    val data: Collection<PNUser>,
    val totalCount: Int?,
    val next: PNPage?,
    val prev: PNPage?
)

data class PNUser(
    val id: String,
    val name: String?,
    val externalId: String?,
    val profileUrl: String?,
    val email: String?,
    val custom: Any?,
    val updated: String?,
    val eTag: String?
)

Fetch User

Returns metadata for the specified User, optionally including custom fields for each.

Method(s)

pubnub.fetchUser(
    userId: String? = null,
    includeCustom: Boolean = false
).async { result, status -> }

Parameter	Type	Required	Default	Description
userId	String	Optional	pubnub.configuration.uuid	Unique User identifier. If not supplied, then UUID from configuration will be used.
includeCustom	Boolean	Optional	false	Whether to include the custom field in the fetch response.

Basic Usage

pubnub.fetchUser()
        .async { result, status ->
            if (status.error) {
                //handle error
            } else if (result != null) {
                //handle result
            }
        }

Response

data class PNUserResult(
    val status: Int,
    val data: PNUser?
)

data class PNUser(
    val id: String,
    val name: String?,
    val externalId: String?,
    val profileUrl: String?,
    val email: String?,
    val custom: Any?,
    val updated: String?,
    val eTag: String?
)

Create User

Create metadata for a User in the database, optionally including custom fields for each.

Method(s)

pubnub.createUser(
    userId: String? = null,
    name: String? = null,
    externalId: String? = null,
    profileUrl: String? = null,
    email: String? = null,
    custom: Any? = null,
    includeCustom: Boolean = false
).async { result, status -> }

Parameter	Type	Required	Default	Description
userId	String	Optional	pubnub.configuration.uuid	Unique User identifier. If not supplied, then UUID from configuration will be used.
name	String?	Optional	null	Display name for the user. Maximum 200 characters.
externalId	String?	Optional	null	User's identifier in an external system.
profileUrl	String?	Optional	null	The URL of the user's profile picture.
email	String?	Optional	null	The user's email address. Maximum 80 characters.
custom	Any?	Optional	null	Any object of key-value pairs with supported data types. Objects filtering language doesn’t support filtering by custom properties.
includeCustom	Boolean	Optional	false	Whether to include the custom field in the fetch response.

Basic Usage

pubnub.createUser()
        .async { result, status ->
            if (status.error) {
                //handle error
            } else if (result != null) {
                //handle result
            }
        }

Response

data class PNUserResult(
    val status: Int,
    val data: PNUser?
)

data class PNUser(
    val id: String,
    val name: String?,
    val externalId: String?,
    val profileUrl: String?,
    val email: String?,
    val custom: Any?,
    val updated: String?,
    val eTag: String?
)

Update User

Update existing metadata for a User in the database, optionally including custom fields for each.

Method(s)

pubnub.updateUser(
    userId: String? = null,
    name: String? = null,
    externalId: String? = null,
    profileUrl: String? = null,
    email: String? = null,
    custom: Any? = null,
    includeCustom: Boolean = false
).async { result, status -> }

Parameter	Type	Required	Default	Description
userId	String	Optional	pubnub.configuration.uuid	Unique User identifier. If not supplied, then UUID from configuration will be used.
name	String?	Optional	null	Display name for the user. Maximum 200 characters.
externalId	String?	Optional	null	User's identifier in an external system.
profileUrl	String?	Optional	null	The URL of the user's profile picture.
email	String?	Optional	null	The user's email address. Maximum 80 characters.
custom	Any?	Optional	null	Any object of key-value pairs with supported data types. Objects filtering language doesn’t support filtering by custom properties.
includeCustom	Boolean	Optional	false	Whether to include the custom field in the fetch response.

Basic Usage

pubnub.updateUser()
        .async { result, status ->
            if (status.error) {
                //handle error
            } else if (result != null) {
                //handle result
            }
        }

Response

data class PNUserResult(
    val status: Int,
    val data: PNUser?
)

data class PNUser(
    val id: String,
    val name: String?,
    val externalId: String?,
    val profileUrl: String?,
    val email: String?,
    val custom: Any?,
    val updated: String?,
    val eTag: String?
)

Remove User

Removes the metadata from a specified User.

Method(s)

pubnub.removeUser(
    userId: String? = null
).async { result, status -> }

Parameter	Type	Required	Default	Description
userId	String	Optional	pubnub.configuration.uuid	Unique User identifier. If not supplied, then UUID from configuration will be used.

Basic Usage

pubnub.removeUser()
        .async { result, status ->
            if (status.error) {
                //handle error
            } else if (result != null) {
                //handle result
            }
        }

Response

data class PNRemoveUserResult(val status: Int)