# UserContextApi

Use this API to access and listen to the user's context.

## UserContextApi API

### `addUserContextUpdateListener()`

> ```java
> void addUserContextUpdateListener(UserContextUpdateListener listener)
> ```
>
> Adds a listener that will be invoked when the user's current context is updated. The user context updates delivered by this listener will not be filtered according to any (user context) criteria and will not include any provisional events (see [isProvisional](/important-topics/sdk/api-reference/android/eventtimeline/event.md#isprovisional)).
>
> If the listener instance provided has been previously added, then it will be replaced. The user context criteria of interest (for the said listener) will also be replaced.
>
> Calling this function has the same effect as calling `addUserContextUpdateListener(false, listener)`.
>
> Note: calling this method on an uninitialized SDK will throw an [SdkException](/important-topics/sdk/api-reference/android/sdkexception.md).

<table><thead><tr><th width="214">Parameters</th><th></th></tr></thead><tbody><tr><td>listener</td><td>A <a href="/pages/-MdxGO48MWFtU1-z6Wt_"><code>UserContextUpdateListener</code></a> that gets triggered when the user context has changed.</td></tr></tbody></table>

### `addProvisionalAwareUserContextUpdateListener()`

> ```java
> void addProvisionalAwareUserContextUpdateListener(UserContextUpdateListener listener)
> ```
>
> Adds a listener that will be invoked when the user's current context is updated. The user context updates delivered by this listener will not be filtered according to any (user context) criteria, and may include provisional events (see [isProvisional](/important-topics/sdk/api-reference/android/eventtimeline/event.md#isprovisional)).
>
> If the listener instance provided has been previously added, then it will be replaced. The user context criteria of interest (for the said listener) will also be replaced.
>
> Calling this function has the same effect as calling `addUserContextUpdateListener(false, listener)`.
>
> Note: calling this method on an uninitialized SDK will throw an [SdkException](/important-topics/sdk/api-reference/android/sdkexception.md).

<table><thead><tr><th width="214">Parameters</th><th></th></tr></thead><tbody><tr><td>listener</td><td>A <a href="/pages/-MdxGO48MWFtU1-z6Wt_"><code>UserContextUpdateListener</code></a> that gets triggered when the user context has changed.</td></tr></tbody></table>

### `addUserContextUpdateListener()`

> ```java
> void addUserContextUpdateListener(List<UserContextUpdateCriteria> criteria, UserContextUpdateListener listener)
> ```
>
> Adds a listener that will be invoked when the user's current context is updated. You can filter the context criteria you are interested in.
>
> The user context updates delivered by this listener will not include any provisional events (see [isProvisional](/important-topics/sdk/api-reference/android/eventtimeline/event.md#isprovisional)).
>
> If the listener instance provided has been previously added, then it will be replaced. The user context criteria of interest will also be replaced.
>
> Calling this function has the same effect as calling `addUserContextUpdateListener(false, criteria, listener)`.
>
> Note: calling this method on an uninitialized SDK will throw an [SdkException](/important-topics/sdk/api-reference/android/sdkexception.md).

| Parameters |                                                                                                                                                                                 |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| criteria   | A list that filters which [`UserContextUpdateCriteria`](/important-topics/sdk/api-reference/android/usercontextapi/usercontextupdatecriteria.md) to return.                     |
| listener   | A [`UserContextUpdateListener`](/important-topics/sdk/api-reference/android/usercontextapi/usercontextupdatelistener.md) that gets triggered when the user context has changed. |

### `addProvisionalAwareUserContextUpdateListener()`

> ```java
> void addProvisionalAwareUserContextUpdateListener(List<UserContextUpdateCriteria> criteria, UserContextUpdateListener listener)
> ```
>
> Adds a listener that will be invoked when the user's current context is updated. You can filter the context criteria you are interested in.
>
> The user context updates delivered by this listener may include provisional events (see [isProvisional](/important-topics/sdk/api-reference/android/eventtimeline/event.md#isprovisional)).
>
> If the listener instance provided has been previously added, then it will be replaced. The user context criteria of interest will also be replaced.
>
> Calling this function has the same effect as calling `addUserContextUpdateListener(false, criteria, listener)`.
>
> Note: calling this method on an uninitialized SDK will throw an [SdkException](/important-topics/sdk/api-reference/android/sdkexception.md).

| Parameters |                                                                                                                                                                                 |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| criteria   | A list that filters which [`UserContextUpdateCriteria`](/important-topics/sdk/api-reference/android/usercontextapi/usercontextupdatecriteria.md) to return.                     |
| listener   | A [`UserContextUpdateListener`](/important-topics/sdk/api-reference/android/usercontextapi/usercontextupdatelistener.md) that gets triggered when the user context has changed. |

### `requestUserContext()`

> ```java
> PendingOperation<UserContext, RequestUserContextError> requestUserContext()
> ```
>
> Retrieves the user's current context. Provisional events are not included in the result (see [isProvisional](/important-topics/sdk/api-reference/android/eventtimeline/event.md#isprovisional)).
>
> Note: calling this method on an uninitialized SDK will throw an [SdkException](/important-topics/sdk/api-reference/android/sdkexception.md).

### `requestUserContextIncludingProvisionalEvents()`

> ```java
> PendingOperation<UserContext, RequestUserContextError> requestUserContextIncludingProvisionalEvents()
> ```
>
> Retrieves the user's current context. Provisional events may be included in the result (see [isProvisional](/important-topics/sdk/api-reference/android/eventtimeline/event.md#isprovisional)).
>
> Note: calling this method on an uninitialized SDK will throw an [SdkException](/important-topics/sdk/api-reference/android/sdkexception.md).

### `removeUserContextUpdateListener()`

> ```java
> void removeUserContextUpdateListener(UserContextUpdateListener listener)
> ```
>
> Removes a previously set user context update listener.
>
> Note: calling this method on an uninitialized SDK will throw an [SdkException](/important-topics/sdk/api-reference/android/sdkexception.md).

| Parameters |                                                                                                                                                                                 |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| listener   | A [`UserContextUpdateListener`](/important-topics/sdk/api-reference/android/usercontextapi/usercontextupdatelistener.md) that gets triggered when the user context has changed. |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sentiance.com/important-topics/sdk/api-reference/android/usercontextapi.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.