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
)
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
)
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
)
}