Skip to content

Update Session User and RUM Global Context APIs #15085

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 23, 2022
Merged

Update Session User and RUM Global Context APIs #15085

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
198 changes: 116 additions & 82 deletions content/en/real_user_monitoring/browser/modifying_data_and_context.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -326,7 +326,7 @@ window.DD_RUM &&
{{% /tab %}}
{{< /tabs >}}

## Identify user sessions
## User session

Adding user information to your RUM sessions can help you:
* Follow the journey of a given user
Expand All @@ -345,7 +345,11 @@ The following attributes are optional but Datadog recommends providing at least

Increase your filtering capabilities by adding extra attributes on top of the recommended ones. For instance, add information about the user plan, or which user group they belong to.

To identify user sessions, use the `setUser` API:
When making changes to the user session object, all RUM events collected after the change contain the updated information.

### Identify user session

`datadogRum.setUser(<USER_CONFIG_OBJECT>)`

{{< tabs >}}
{{% tab "NPM" %}}
Expand Down Expand Up @@ -388,28 +392,111 @@ window.DD_RUM && window.DD_RUM.setUser({
{{% /tab %}}
{{< /tabs >}}

### Remove the user identification
### Access user session

`datadogRum.getUser()`

{{< tabs >}}
{{% tab "NPM" %}}
```
datadogRum.getUser()
```

{{% /tab %}}
{{% tab "CDN async" %}}
```
DD_RUM.onReady(function() {
DD_RUM.getUser()
})
```
{{% /tab %}}
{{% tab "CDN sync" %}}

```
window.DD_RUM && window.DD_RUM.getUser()
```

{{% /tab %}}
{{< /tabs >}}

### Add/Override user session property

`datadogRum.setUserProperty('<USER_KEY>', <USER_VALUE>)`

{{< tabs >}}
{{% tab "NPM" %}}
```
datadogRum.setUserProperty('name', 'John Doe')
```

{{% /tab %}}
{{% tab "CDN async" %}}
```
DD_RUM.onReady(function() {
DD_RUM.setUserProperty('name', 'John Doe')
})
```
{{% /tab %}}
{{% tab "CDN sync" %}}

```
window.DD_RUM && window.DD_RUM.setUserProperty('name', 'John Doe')
```

{{% /tab %}}
{{< /tabs >}}

### Remove user session property

`datadogRum.removeUserProperty('<USER_KEY>')`

{{< tabs >}}
{{% tab "NPM" %}}
```
datadogRum.removeUserProperty('name')
```

{{% /tab %}}
{{% tab "CDN async" %}}
```
DD_RUM.onReady(function() {
DD_RUM.removeUserProperty('name')
})
```
{{% /tab %}}
{{% tab "CDN sync" %}}

```
window.DD_RUM && window.DD_RUM.removeUserProperty('name')
```

{{% /tab %}}
{{< /tabs >}}

### Clear user session property

`datadogRum.clearUser()`

Clear a previously set user with the `removeUser` API. All RUM events collected afterwards do not contain user information.
<div class="alert alert-info">The RUM Browser SDK v4.17.0 introduced `clearUser` and deprecated `removeUser`</div>

{{< tabs >}}
{{% tab "NPM" %}}
```
datadogRum.removeUser()
datadogRum.clearUser()
```

{{% /tab %}}
{{% tab "CDN async" %}}
```
DD_RUM.onReady(function() {
DD_RUM.removeUser()
DD_RUM.clearUser()
})
```
{{% /tab %}}
{{% tab "CDN sync" %}}

```
window.DD_RUM && window.DD_RUM.removeUser()
window.DD_RUM && window.DD_RUM.clearUser()
```

{{% /tab %}}
Expand Down Expand Up @@ -474,20 +561,22 @@ For a sampled out session, all page views and associated telemetry for that sess

## Global context

### Add global context
### Add global context property

Once RUM is initialized, add extra context to all RUM events collected from your application with the `addRumGlobalContext(key: string, value: any)` API:
After RUM is initialized, add extra context to all RUM events collected from your application with the `setGlobalContextProperty(key: string, value: any)` API:

<div class="alert alert-info">The RUM Browser SDK v4.17.0 introduced `setGlobalContextProperty` and deprecated `addRumGlobalContext`</div>

{{< tabs >}}
{{% tab "NPM" %}}

```
import { datadogRum } from '@datadog/browser-rum';

datadogRum.addRumGlobalContext('<CONTEXT_KEY>', <CONTEXT_VALUE>);
datadogRum.setGlobalContextProperty('<CONTEXT_KEY>', <CONTEXT_VALUE>);

// Code example
datadogRum.addRumGlobalContext('activity', {
datadogRum.setGlobalContextProperty('activity', {
hasPaid: true,
amount: 23.42
});
Expand All @@ -497,12 +586,12 @@ datadogRum.addRumGlobalContext('activity', {
{{% tab "CDN async" %}}
```
DD_RUM.onReady(function() {
DD_RUM.addRumGlobalContext('<CONTEXT_KEY>', '<CONTEXT_VALUE>');
DD_RUM.setGlobalContextProperty('<CONTEXT_KEY>', '<CONTEXT_VALUE>');
})

// Code example
DD_RUM.onReady(function() {
DD_RUM.addRumGlobalContext('activity', {
DD_RUM.setGlobalContextProperty('activity', {
hasPaid: true,
amount: 23.42
});
Expand All @@ -512,10 +601,10 @@ DD_RUM.onReady(function() {
{{% tab "CDN sync" %}}

```
window.DD_RUM && window.DD_RUM.addRumGlobalContext('<CONTEXT_KEY>', '<CONTEXT_VALUE>');
window.DD_RUM && window.DD_RUM.setGlobalContextProperty('<CONTEXT_KEY>', '<CONTEXT_VALUE>');

// Code example
window.DD_RUM && window.DD_RUM.addRumGlobalContext('activity', {
window.DD_RUM && window.DD_RUM.setGlobalContextProperty('activity', {
hasPaid: true,
amount: 23.42
});
Expand All @@ -526,86 +615,31 @@ window.DD_RUM && window.DD_RUM.addRumGlobalContext('activity', {

Follow the [Datadog naming convention][16] for a better correlation of your data across the product.

### Replace global context

Once RUM is initialized, replace the default context for all your RUM events with the `setRumGlobalContext(context: Context)` API:

{{< tabs >}}
{{% tab "NPM" %}}

```
import { datadogRum } from '@datadog/browser-rum';

datadogRum.setRumGlobalContext({ '<CONTEXT_KEY>': '<CONTEXT_VALUE>' });
### Remove global context property

// Code example
datadogRum.setRumGlobalContext({
codeVersion: 34,
});
```
You can remove a previously defined global context property.

{{% /tab %}}
{{% tab "CDN async" %}}
```
DD_RUM.onReady(function() {
DD_RUM.setRumGlobalContext({ '<CONTEXT_KEY>': '<CONTEXT_VALUE>' });
})
<div class="alert alert-info">The RUM Browser SDK v4.17.0 introduced `removeGlobalContextProperty` and deprecated `removeRumGlobalContext`</div>

// Code example
DD_RUM.onReady(function() {
DD_RUM.setRumGlobalContext({
codeVersion: 34,
})
})
```
{{% /tab %}}
{{% tab "CDN sync" %}}
Follow the [Datadog naming convention][16] for a better correlation of your data across the product.

```
window.DD_RUM &&
DD_RUM.setRumGlobalContext({ '<CONTEXT_KEY>': '<CONTEXT_VALUE>' });
### Replace global context

// Code example
window.DD_RUM &&
DD_RUM.setRumGlobalContext({
codeVersion: 34,
});
```
Replace the default context for all your RUM events with the `setGlobalContext(context: Context)` API:

{{% /tab %}}
{{< /tabs >}}
<div class="alert alert-info">The RUM Browser SDK v4.17.0 introduced `setGlobalContext` and deprecated `setRumGlobalContext`</div>

Follow the [Datadog naming convention][16] for a better correlation of your data across the product.

### Read global context

Once RUM is initialized, read the global context with the `getRumGlobalContext()` API:

{{< tabs >}}
{{% tab "NPM" %}}
### Clear global context

```
import { datadogRum } from '@datadog/browser-rum';
You can clear the global context by using `clearGlobalContext`.

const context = datadogRum.getRumGlobalContext();
```

{{% /tab %}}
{{% tab "CDN async" %}}
```
DD_RUM.onReady(function() {
var context = DD_RUM.getRumGlobalContext();
});
```
{{% /tab %}}
{{% tab "CDN sync" %}}
### Read global context

```
var context = window.DD_RUM && DD_RUM.getRumGlobalContext();
```
Once RUM is initialized, read the global context with the `getGlobalContext()` API:

{{% /tab %}}
{{< /tabs >}}
<div class="alert alert-info">The RUM Browser SDK v4.17.0 introduced `getGlobalContext` and deprecated `getRumGlobalContext`</div>

## Further Reading

Expand Down