Memberships API for PubNub Kotlin SDK

PubNub allows you to store the relation between Users and Spaces through Memberships. Using the Memberships API, you can track and display all available User-to-Space and Space-to-User associations and provide additional details about the type of relation a User and the Space have, like, for example, being an administrator of the Space.

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

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

Fetch User Memberships

Returns memberships for the specified User optionally including custom fields.

Method(s)

PubNub.fetchMembershipsOfUser(
    userId: String,
    limit: Int? ,
    page: PNPage?,
    filter: String?,
    includeCount: Boolean,
    includeCustom: Boolean,
    includeSpaceDetails: SpaceDetailsLevel?
).async { result, status -> }

Parameter	Type	Required	Default	Description
`userId`	`String`	yes		User to fetch memberships of.
`limit`	`Int`	Optional	100	The number of memberships 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.
`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.
`includeSpaceDetails`	`SpaceDetailsLevel?`	Optional	`null`	The level of Space details to return. Possible values are: `SpaceDetailsLevel.SPACE` which include basic Space information and `SpaceDetailsLevel.SPACE_WITH_CUSTOM` which includes additional `custom` field.

Basic Usage

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

Response

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

data class Membership(
    val user: User?,
    val space: Space?,
    val custom: Map<String, Any>?,
    val updated: String?,
    val eTag: String?,
    val status: String?
)

Fetch Space Memberships

Returns memberships for the specified Space optionally including custom fields.

Method(s)

PubNub.fetchMembershipsOfSpace({
    spaceId: String,
    limit: Int? = null,
    page: PNPage? = null,
    filter: String? = null,
    includeCount: Boolean = false,
    includeCustom: Boolean = false,
    includeUserDetails: UserDetailsLevel?
})

Parameter	Type	Required	Default	Description
`spaceId`	`String`	yes		Space to fetch memberships of.
`limit`	`Int`	Optional	100	The number of memberships 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.
`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.
`includeUserDetails`	`UserDetailsLevel?`	Optional	`null`	The level of User details to return. Possible values are: `UserDetailsLevel.USER` which include basic Space information and `UserDetailsLevel.USER_WITH_CUSTOM` which includes additional `custom` field.

Basic Usage

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

Response

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

data class Membership(
    val user: User?,
    val space: Space?,
    val custom: Map<String, Any>?,
    val updated: String?,
    val eTag: String?,
    val status: String?
)

Add User Memberships

Adds memberships for the specified User.

Method(s)

PubNub.addMembershipsOfUser(
    spaceIdsWithCustoms: List<SpaceIdWithCustom>,
    userid: String
)

Parameter	Type	Required	Default	Description
`spaceIdsWithCustoms`	List	Yes		List of Space IDs to add the User the membership to. The list can contain strings (`spaceId` only) or objects which can include custom data, for example: `{ id: "my-space-3", custom: { owner: "PubNubUser" } }`
`userId`	String	Optional	current `userId`	User to add the membership to. If not supplied then current user's `userId` is used.

Basic Usage

PubNub.addMembershipsOfUser(spaceIdsWithCustoms = listOf(SpaceIdWithCustom(spaceId = "mySpace")))
        .async { result, status ->
            if (status.error) {
                //handle error
            } else if (result != null) {
                //handle result
            }
        }

Response

data class MembershipsResult(
    val status: Int
)

Add Space Memberships

Adds memberships for the specified Space.

Method(s)

PubNub.addMembershipsOfSpace(
    spaceId: String,
    userIdsWithCustoms: List<UserIdWithCustom>
)

Parameter	Type	Required	Default	Description
`spaceId`	String	Yes		Space ID.
`userIdsWithCustoms`	List	Yes		List of users to add the membership to the `spaceId` to. The list can contain strings (`userId` only) or objects which can include custom data, for example: `{ id: "userId-3", custom: { role: "Super Admin" } }`

Basic Usage

PubNub.addMembershipsOfSpace(spaceId = "mySpace", userIdsWithCustoms = listOf(UserIdWithCustom(userId = "userId-1"), UserIdWithCustom("userId-2")))
        .async { result, status ->
            if (status.error) {
                //handle error
            } else if (result != null) {
                //handle result
            }
        }

Response

data class MembershipsResult(
    val status: Int
)

Update User Memberships

Updates memberships for the specified User.

Method(s)

PubNub.updateMembershipsOfUser(
    spaceIdsWithCustoms: List<SpaceIdWithCustom>,
    userId: String
)

Parameter	Type	Required	Default	Description
`spaceIdsWithCustoms`	List	Yes		Array of `spaces` to update the memberships to. Array can contain strings (space name only) or objects which can include custom data, for example: `{ id: "my-space-3", custom: { owner: "PubNubUser" } }`.
`userId`	String	Optional	current `userId`	Unique user identifier. If not supplied then current user's `userId` is used.

Basic Usage

PubNub.updateMembershipsOfUser(spacerIdsWithCustoms = listOf(SpaceIdWithCustom(spaceId = "spaceId-1"), SpaceIdWithCustom("spaceId-2")), userId = "userId-1" )
        .async { result, status ->
            if (status.error) {
                //handle error
            } else if (result != null) {
                //handle result
            }
        }

Response

data class MembershipsResult(
    val status: Int
)

Update Space Memberships

Updates memberships for the specified Space.

Method(s)

PubNub.updateMembershipsOfSpace(
    spaceId: String,
    userIdsWithCustoms: List<UserIdWithCustom>
)

Parameter	Type	Required	Default	Description
`spaceId`	String	Optional		Space ID.
`userIdsWithCustoms`	List	Yes		List of users to update the membership to the `spaceId` to. Array can contain strings (userId only) or objects which can include custom data, for example: `{ id: "userId-3", custom: { role: "Super Admin" } }`.

Basic Usage

PubNub.updateMembershipsOfUser(spaceId = "mySpace", userIdsWithCustoms = listOf(UserIdWithCustom(userId = "userId-1"), UserIdWithCustom("userId-2")))
        .async { result, status ->
            if (status.error) {
                //handle error
            } else if (result != null) {
                //handle result
            }
        }

Response

data class MembershipsResult(
    val status: Int
)

Remove User Memberships

Removes memberships from the specified User.

Method(s)

PubNub.removeMembershipsOfUser(
    spaceIds: List<String>,
    userId: String
)

Parameter	Type	Required	Default	Description
`spaceIds`	List	Yes		Spaces to remove the user from.
`userId`	String	Yes	current `userId`	Unique user identifier. If not supplied then current user's `userId` is used.

Basic Usage

PubNub.removeMembershipsOfUser(spaceIds = listOf("mySpace-1", "mySpace-2"), userId = "userId-1" )
        .async { result, status ->
            if (status.error) {
                //handle error
            } else if (result != null) {
                //handle result
            }
        }

Response

data class MembershipsResult(
    val status: Int
)

Remove Space Memberships

Removes memberships from the specified Space.

Method(s)

PubNub.removeMembershipsOfSpace(
    spaceId: String,
    userIds: List<String>
)

Parameter	Type	Required	Default	Description
`spaceId`	String	Yes		Space ID.
`userIds`	List	Yes		Users to remove from space.

Basic Usage

PubNub.removeMembershipsOfSpace(spaceId = "mySpace", userIds = listOf("userId-1", "userId-2") )
        .async { result, status ->
            if (status.error) {
                //handle error
            } else if (result != null) {
                //handle result
            }
        }

Response

data class MembershipsResult(
    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 Membership events

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

Subscribe to the channel:

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

Add a dedicated Memberships listener:

        pubnub.addMembershipEventsListener {
            when (it) {
                is MembershipModified -> {}
                is MembershipRemoved -> {}
            }
        }

Membership created or updated event

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

data class MembershipModified(
    override val spaceId: SpaceId,
    override val timetoken: Long,
    val data: Data
) : MembershipEvent() {
    data class Data(
        val space: Space,
        val user: User,
        val custom: Map<String, Any>?,
        val status: String?
    )
}

Membership removed event

The following is the structure of the remove event:

data class MembershipRemoved(
    override val spaceId: SpaceId,
    override val timetoken: Long,
    val data: Data
) : MembershipEvent() {
    data class Data(
        val space: Space,
        val user: User
    )
}