PubNub LogoDocs
SupportContact SalesLoginTry Our APIs

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 -> }
ParameterTypeRequiredDefaultDescription
userIdStringyesUser to fetch memberships of.
limitIntOptional100The number of memberships 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.
includeCountBooleanOptionalfalseRequest IncludeCount to be included in paginated response. By default, IncludeCount is omitted.
includeCustomBooleanOptionalfalseWhether to include the Custom field in the fetch response.
includeSpaceDetailsSpaceDetailsLevel?OptionalnullThe 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
)

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?
})
ParameterTypeRequiredDefaultDescription
spaceIdStringyesSpace to fetch memberships of.
limitIntOptional100The number of memberships 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.
includeCountBooleanOptionalfalseRequest IncludeCount to be included in paginated response. By default, IncludeCount is omitted.
includeCustomBooleanOptionalfalseWhether to include the Custom field in the fetch response.
includeUserDetailsUserDetailsLevel?OptionalnullThe 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
)

Add User Memberships

Adds memberships for the specified User.

Method(s)

PubNub.addMembershipsOfUser(
    spaceIdsWithCustoms: List<SpaceIdWithCustom>,
    userid: String
)
ParameterTypeRequiredDefaultDescription
spaceIdsWithCustomsListYesList 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" } }
userIdStringOptionalcurrent userIdUser 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>
)
ParameterTypeRequiredDefaultDescription
spaceIdStringYesSpace ID.
userIdsWithCustomsListYesList 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
)
ParameterTypeRequiredDefaultDescription
spaceIdsWithCustomsListYesArray 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" } }.
userIdStringOptionalcurrent userIdUnique 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>
)
ParameterTypeRequiredDefaultDescription
spaceIdStringOptionalSpace ID.
userIdsWithCustomsListYesList 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
)
ParameterTypeRequiredDefaultDescription
spaceIdsListYesSpaces to remove the user from.
userIdStringYescurrent userIdUnique 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>
)
ParameterTypeRequiredDefaultDescription
spaceIdStringYesSpace ID.
userIdsListYesUsers 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:

  1. Subscribe to the channel:
pubnub.subscribe(
    channels = listOf(`matrix`)
)
  1. 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
    )
}
  • Enable Memberships API
  • Fetch User Memberships
    • Method(s)
    • Basic Usage
    • Response
  • Fetch Space Memberships
    • Method(s)
    • Basic Usage
    • Response
  • Add User Memberships
    • Method(s)
    • Basic Usage
    • Response
  • Add Space Memberships
    • Method(s)
    • Basic Usage
    • Response
  • Update User Memberships
    • Method(s)
    • Basic Usage
    • Response
  • Update Space Memberships
    • Method(s)
    • Basic Usage
    • Response
  • Remove User Memberships
    • Method(s)
    • Basic Usage
    • Response
  • Remove Space Memberships
    • Method(s)
    • Basic Usage
    • Response
  • Events
    • Receive Membership events
    • Membership created or updated event
    • Membership removed event
© PubNub Inc. - Privacy Policy