Spaces API for PubNub JavaScript SDK

A Space is where online interactions within a given business domain happen. A Space may, for example, be an abstract representation of your home (for IoT device purposes), a chat channel about football (in chat applications), or a multiplayer game instance.

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 Spaces API

To enable Spaces 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-spaces"
implementation "com.pubnub:pubnub-kotlin"

Fetch Spaces

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

Method(s)

pubnub.fetchSpaces(
    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.fetchSpaces()
        .async { result, status ->
            if (status.error) {
                //handle error
            } else if (result != null) {
                //handle result
            }
        }

Response

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

data class PNSpace(
    val id: String,
    val name: String?,
    val status: String?,
    val type: String?,
    val description: String?,
    val custom: Any?,
    val updated: String?,
    val eTag: String?
)

Fetch Space

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

Method(s)

pubnub.fetchSpace(
    spaceId: String,
    includeCustom: Boolean = false
).async { result, status -> }

Parameter	Type	Required	Default	Description
`spaceId`	`String`	yes		Space ID.
`includeCustom`	`Boolean`	Optional	`false`	Whether to include the custom field in the fetch response.

Basic Usage

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

Response

data class PNSpaceResult(
    val status: Int,
    val data: PNSpace?
)

data class PNSpace(
    val id: String,
    val name: String?,
    val status: String?,
    val type: String?,
    val description: String?,
    val custom: Any?,
    val updated: String?,
    val eTag: String?
)

Create Space

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

Method(s)

pubnub.createSpace(
    spaceId: String,
    name: String? = null,
    type: String? = null,
    status: String? = null,
    description: String? = null,
    custom: Any? = null,
    includeCustom: Boolean = false
).async { result, status -> }

Parameter	Type	Required	Default	Description
`spaceId`	`String`	yes		Space ID.
`name`	`String?`	Optional	`null`	Name for the Space.
`type`	`String?`	Optional	`null`	Category used to classify the purpose of the Space.
`status`	`String?`	Optional	`null`	Condition the Space is in.
`description`	`String?`	Optional	`null`	Description of the Space.
`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.createSpace(spaceId = "mySpace")
        .async { result, status ->
            if (status.error) {
                //handle error
            } else if (result != null) {
                //handle result
            }
        }

Response

data class PNSpaceResult(
    val status: Int,
    val data: PNSpace?
)

data class PNSpace(
    val id: String,
    val name: String?,
    val status: String?,
    val type: String?,
    val description: String?,
    val custom: Any?,
    val updated: String?,
    val eTag: String?
)

Update Space

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

Method(s)

pubnub.updateSpace(
    spaceId: String,
    name: String? = null,
    type: String? = null,
    status: String? = null,
    description: String? = null,
    custom: Any? = null,
    includeCustom: Boolean = false
).async { result, status -> }

Parameter	Type	Required	Default	Description
`spaceId`	`String`	yes		Space ID.
`name`	`String?`	Optional	`null`	Name for the Space.
`type`	`String?`	Optional	`null`	Category used to classify the purpose of the Space.
`status`	`String?`	Optional	`null`	Condition the Space is in.
`description`	`String?`	Optional	`null`	Description of the Space.
`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.updateSpace(spaceId = "mySpace")
        .async { result, status ->
            if (status.error) {
                //handle error
            } else if (result != null) {
                //handle result
            }
        }

Response

data class PNSpaceResult(
    val status: Int,
    val data: PNSpace?
)

data class PNSpace(
    val id: String,
    val name: String?,
    val status: String?,
    val type: String?,
    val description: String?,
    val custom: Any?,
    val updated: String?,
    val eTag: String?
)

Remove Space

Removes the metadata from a specified Space.

Method(s)

pubnub.removeSpace(
    spaceId: String
).async { result, status -> }

Parameter	Type	Required	Default	Description
`spaceId`	`String`	yes		Space ID.

Basic Usage

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

Response

data class PNRemoveSpaceResult(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 Spaces events

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

Subscribe to the channel:

pubnub.subscribe(
    channels = listOf(`matrix`)
)

Add dedicated Space listener:

        pubnub.addSpaceEventsListener { 
            when(it) {
                is SpaceModified -> {}
                is SpaceRemoved -> {}
            }
        }

Spaces created or updated event

The following is the structure of the Space create/update event:

data class SpaceModified(
    override val spaceId: SpaceId,
    override val timetoken: Long,
    val data: Data
) : SpaceEvent() {
    data class Data(
        val spaceId: SpaceId,
        val name: String?,
        val description: String?,
        val custom: Map<String, Any>?,
        val status: String?,
        val type: String?
    )
}

Spaces removed event

The following is the structure of the Space remove event:

data class SpaceRemoved(
    override val spaceId: SpaceId,
    override val timetoken: Long,
    val data: Data
) : SpaceEvent() {
    data class Data(val spaceId: SpaceId)
}