---
source_url: https://www.pubnub.com/docs/sdks/kotlin/entities/user-metadata
title: UserMetadata Entity
updated_at: 2026-05-22T11:06:54.330Z
sdk_name: PubNub Kotlin SDK
sdk_version: 13.3.0
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


# UserMetadata Entity

PubNub Kotlin SDK, use the latest version: 13.3.0

Install:

```bash
Add PubNub dependency to your build@13.3.0
```

As of version 9.0.0, the Kotlin software development kit (SDK) supports entities. Entities are SDK objects that bundle operations for a specific resource type and simplify working with PubNub application programming interfaces (APIs).

Use entities to perform common tasks without manually wiring requests. Some PubNub APIs are exposed via entities. Other operations remain available on the `pubnub` object.

## Create UserMetadata

Use this factory method to return a local `UserMetadata` entity for a single user metadata object. A `UserMetadata` entity centralizes operations related to App Context user metadata.

```kotlin
pubnub.userMetadata(userId: String): UserMetadata
```

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| userId | String | Yes |  | Identifier of the user metadata object to manage. |

#### Sample code

:::tip Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
:::

```kotlin
import com.pubnub.api.PubNub
import com.pubnub.api.UserId
import com.pubnub.api.v2.PNConfiguration

fun main() {
    println("PubNub UserMetadata Entity Example")
    println("================================")

    // 1. Configure PubNub
    val userId = UserId("user-metadata-entity-demo-user")
    val config = PNConfiguration.builder(userId, "demo").apply {
        publishKey = "demo"
        subscribeKey = "demo"
    }.build()

    // 2. Create PubNub instance
    val pubnub = PubNub.create(config)

    // 3. Create a User Metadata entity
    val userMetadataName = "user-123"
    val userMetadata = pubnub.userMetadata(userMetadataName)
    println("Created UserMetadata entity for: $userMetadataName")

    // 4. Set user metadata
    println("\nSetting user metadata...")
    pubnub.setUUIDMetadata(
        uuid = userMetadataName,
        name = "Jane Smith",
        email = "jane@example.com",
        includeCustom = true,
        custom = mapOf(
            "role" to "Developer",
            "department" to "Engineering",
            "location" to "New York"
        )
    ).async { result ->
        result.onSuccess { response ->
            println("SUCCESS: User metadata set")
            println("UUID: ${response.data?.id}")
            println("Name: ${response.data?.name}")
            println("Email: ${response.data?.email}")
            println("Custom: ${response.data?.custom}")
        }.onFailure { exception ->
            println("ERROR: Failed to set user metadata")
            println("Error details: ${exception.message}")
        }
    }

    // 5. Wait for operation to complete
    Thread.sleep(2000)

    // 6. Define a subscription to the user metadata
    val userMetadataSubscription = userMetadata.subscription()
    userMetadataSubscription.onMessage = { result ->
        println("\nReceived message on UserMetadata subscription: ${result.message.asString}")
    }

    userMetadataSubscription.subscribe()
    Thread.sleep(2000)

    // 7. Publish a message to the user metadata
    pubnub.publish(userMetadataName, "Some message").sync()

    // Clean up
    pubnub.destroy()
    println("\nPubNub connection closed")
}
```

## Available operations

The `UserMetadata` entity provides operations for PubNub App Context [user metadata](https://www.pubnub.com/docs/general/metadata/users-metadata).

| Operation (click for more information) | Description |
| --- | --- |
| [subscription(subscriptionOptions)](https://www.pubnub.com/docs/sdks/kotlin/api-reference/publish-and-subscribe#subscribe) | Returns a local user metadata [subscription object](https://www.pubnub.com/docs/general/channels/subscribe#subscription-types) with [optional parameters](https://www.pubnub.com/docs/general/channels/subscribe#subscription-options). You can then subscribe to receive real-time updates for that user metadata. |