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!",
    channel = "my_channel"
)

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!",
    channel = "my_channel"
).async { result, status ->
    if (status.error) {
        // handle error
    } else {
        // handle successful method result
    }
}

Enable Users API

To enable Users API, add the following to your project's build.gradle file:

api platform("com.pubnub:pubnub-kotlin-bom:0.1.0")
implementation "com.pubnub:pubnub-users"
implementation "com.pubnub:pubnub-kotlin"

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 -> }
ParameterTypeRequiredDefaultDescription
limitIntOptional100The number of objects to retrieve at a time.
pagePNPage?OptionalnullThe paging object used for pagination.
filterString?OptionalnullExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
sortList<PNSortKey>OptionallistOf()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'}
includeCountBooleanOptionalfalseRequest IncludeCount to be included in paginated response. By default, IncludeCount is omitted.
includeCustomBooleanOptionalfalseWhether 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 type: String?,
    val status: 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 -> }
ParameterTypeRequiredDefaultDescription
userIdStringOptionalpubnub.configuration.useridUnique User identifier.
If not supplied, then userId from configuration will be used.
includeCustomBooleanOptionalfalseWhether 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 type: String?,
    val status: 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,
    type: String? = null,
    status: String? = null,
    externalId: String? = null,
    profileUrl: String? = null,
    email: String? = null,
    custom: Any? = null,
    includeCustom: Boolean = false
).async { result, status -> }
ParameterTypeRequiredDefaultDescription
userIdStringOptionalpubnub.configuration.useridUnique User identifier.
If not supplied, then userId from configuration will be used.
nameString?OptionalnullDisplay name for the user. Maximum 200 characters.
typeStringOptionalnullCategory used to classify the purpose of a User.
statusStringOptionalnullCondition the User is in.
externalIdString?OptionalnullUser's identifier in an external system.
profileUrlString?OptionalnullThe URL of the user's profile picture.
emailString?OptionalnullThe user's email address. Maximum 80 characters.
customAny?OptionalnullAny object of key-value pairs with supported data types. Objects filtering language doesn’t support filtering by custom properties.
includeCustomBooleanOptionalfalseWhether 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 type: String?,
    val status: 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,
    type: String? = null,
    status: String? = null,
    externalId: String? = null,
    profileUrl: String? = null,
    email: String? = null,
    custom: Any? = null,
    includeCustom: Boolean = false
).async { result, status -> }
ParameterTypeRequiredDefaultDescription
userIdStringOptionalpubnub.configuration.useridUnique User identifier.
If not supplied, then userId from configuration will be used.
nameString?OptionalnullDisplay name for the user. Maximum 200 characters.
typeStringOptionalnullCategory used to classify the purpose of a User.
statusStringOptionalnullCondition the User is in.
externalIdString?OptionalnullUser's identifier in an external system.
profileUrlString?OptionalnullThe URL of the user's profile picture.
emailString?OptionalnullThe user's email address. Maximum 80 characters.
customAny?OptionalnullAny object of key-value pairs with supported data types. Objects filtering language doesn’t support filtering by custom properties.
includeCustomBooleanOptionalfalseWhether 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 type: String?,
    val status: 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 -> }
ParameterTypeRequiredDefaultDescription
userIdUserIdOptionalpubnub.configuration.useridUnique User identifier.
If not supplied, then userId 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)

Events

PubNub sends out system-wide events when Memberships, Spaces/Channels, and Users are created, updated, or removed. You can choose to receive these events to trigger additional logic.

Enabling/Disabling events

You can configure whether events are generated in the Admin Portal.

Receive Users events

To receive User events on, for example, matrix channel:

  1. Subscribe to the channel:
pubnub.subscribe(
    channels = listOf(`matrix`)
)
  1. Add a dedicated Users listener:
        pubnub.addUserEventsListener { 
            when(it) {
                is UserModified -> {}
                is UserRemoved -> {}
            }
        }

Users created or updated event

The following is the structure of the User created or updated event:

data class UserModified(
    override val spaceId: String,
    override val timetoken: Long,
    val data: Data
) : UserEvent() {

    data class Data(
        val userId: UserId,
        val name: String?,
        val externalId: String?,
        val profileUrl: String?,
        val email: String?,
        val custom: Map<String, Any>?,
        val status: String?,
        val type: String?
    )
}

Users removed event

The following is the structure of the Users removed event:

data class UserRemoved(
    override val spaceId: String,
    override val timetoken: Long,
    val data: Data
) : UserEvent() {
    data class Data(val userId: UserId)
}

Objects Filtering Language Definition

The filtering language for Objects is similar to the stream filtering language.

Note the following:

  • Date/time properties, such as updated, must be compared to valid date/time strings formatted according to ISO 8601.

  • The LIKE operator supports wildcards denoted by the * character. A wildcard matches any sequence of arbitrary Unicode characters, including the empty sequence. The literal asterisk is matched when escaped using the backslash (\) character.

  • Values used with LIKE must be properly encoded just like any other string value. Thus, to escape an asterisk, the raw value must contain \\*.

  • The entire expression must be properly URL-encoded when used in the query string.

Custom property filtering

You can't filter by custom properties.

<expression>           ::= <and_expression> ( "||" <and_expression> )*
<and_expression>       ::= <binary_condition> ( "&&" <binary_condition> )*
<binary_condition>     ::= "!" <binary_condition> | "(" <expression> ")" | <relational_condition>
<relational_condition> ::= <property_path> <relational_operator> <value>
<property_path>        ::= <property_name> ( "." <property_name> )*
<property_name>        ::= <identifier> | "[" <string> "]"
<value>                ::= <string> | <number> | "true" | "false" | "null"

Tokens

<identifier>           ::=  <letter> | "$" | "_" ( <letter> | "$" | "_" | <digit> )*
<relational_operator>  ::= "==" | "!=" | "<=" | ">=" | "<" | ">" | "LIKE"
<string>               ::= <double_quote> ( "\" <double_quote> | "\" <special_char>
                            | "\" "u" <hex_digit> <hex_digit> <hex_digit> <hex_digit>
                            | <unicode_char> - <double_quote> - "\" )* <double_quote>
                            | "'" ( "\" "'" | "\" <special_char>
                            | "\" "u" <hex_digit> <hex_digit> <hex_digit> <hex_digit>
                            | <unicode_char> - "'" - "\" )* "'"
<number>               ::= ( "+" | "-" )? ( <digit> )* ( "." )? <digit> ( <digit> )*
                            ( "e" | "E" ( "+" | "-" )? <digit> ( <digit> )* )?
<letter>               ::= Unicode Letter (category; any kind of letter from any language)
<digit>                ::= "0" .. "9"
<hex_digit>            ::= <digit> | "A" .. "F"
<double_quote>         ::= the " character
<unicode_char>         ::= any character in the Unicode range from U+0020 to U+10FFFF inclusive
<special_char>         ::= "\" | "/" | "b" | "f" | "n" | "r" | "t"

Sample object filtering operations

The following date/time comparison returns results that were modified on or after August 31st, 2019 (UTC):

updated >= "2019-08-31T00:00:00Z"

The following wildcard expression returns results whose name starts with the letter X:

name LIKE 'X*'

The following escaped wildcard expression returns results whose name contains an asterisk:

name LIKE '*\\**'