Skip to content

Update Session User and RUM Global Context APIs #15013

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

Closed
liywjl wants to merge 19 commits into from
Closed

Update Session User and RUM Global Context APIs #15013

Changes from 14 commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
17b874c
Update Session User and RUM Global Context APIs
liywjl Aug 16, 2022
90e403a
Add description to APIs and format examples
liywjl Aug 16, 2022
88c147f
Add description to clearUser
liywjl Aug 16, 2022
9feb44f
Update content/en/real_user_monitoring/browser/modifying_data_and_con…
liywjl Aug 17, 2022
3e51956
Update content/en/real_user_monitoring/browser/modifying_data_and_con…
liywjl Aug 17, 2022
f5d092b
Update content/en/real_user_monitoring/browser/modifying_data_and_con…
liywjl Aug 17, 2022
f451963
Update content/en/real_user_monitoring/browser/modifying_data_and_con…
liywjl Aug 17, 2022
4dff088
Update content/en/real_user_monitoring/browser/modifying_data_and_con…
liywjl Aug 17, 2022
dd95391
Update content/en/real_user_monitoring/browser/modifying_data_and_con…
liywjl Aug 17, 2022
93b84e2
Update content/en/real_user_monitoring/browser/modifying_data_and_con…
liywjl Aug 17, 2022
c4e1f64
Update content/en/real_user_monitoring/browser/modifying_data_and_con…
liywjl Aug 17, 2022
1fc0dea
Update content/en/real_user_monitoring/browser/modifying_data_and_con…
liywjl Aug 17, 2022
58ec376
Update content/en/real_user_monitoring/browser/modifying_data_and_con…
liywjl Aug 17, 2022
d9f4e6d
Add titles, remove examples
liywjl Aug 17, 2022
46307bb
Update content/en/real_user_monitoring/browser/modifying_data_and_con…
liywjl Aug 17, 2022
1bc798c
remove duplicate title `Identify user sessions`
liywjl Aug 17, 2022
7e813fb
Update content/en/real_user_monitoring/browser/modifying_data_and_con…
liywjl Aug 23, 2022
fb3046b
Update content/en/real_user_monitoring/browser/modifying_data_and_con…
liywjl Aug 23, 2022
7824a4f
Update content/en/real_user_monitoring/browser/modifying_data_and_con…
liywjl Aug 23, 2022
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
200 changes: 119 additions & 81 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 @@ -345,7 +345,13 @@ 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.

## User session APIs

@bcaudan bcaudan Aug 17, 2022

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💬 suggestion: ‏what about having a sub section for each capability (like global context)?
something like:

## user sessions
### identify user session
### access user session
### override user session property
### clear user session

@bcaudan bcaudan Aug 17, 2022 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it could be nice to merge

## Identify user sessions
## User session APIs
### Identify user sessions

into

## User session
### Identify user sessions

it avoid to duplicate the "identify user sessions" header and regroup all things related to user session in a single section, like Global Context


### Identify user session

`datadogRum.setUser(<USER_CONFIG_OBJECT>)`

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

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

`datadogRum.getUser()`

Get the current RUM Session User object.

Comment thread
liywjl marked this conversation as resolved.
Outdated
{{< 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

Clear a previously set user with the `removeUser` API. All RUM events collected afterwards do not contain user information.
`datadogRum.clearUser()`

<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 +565,22 @@ For a sampled out session, all page views and associated telemetry for that sess

## Global context

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

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

Once RUM is initialized, add extra context to all RUM events collected from your application with the `addRumGlobalContext(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 +590,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 +605,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 +619,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" %}}

```
import { datadogRum } from '@datadog/browser-rum';
### Clear global context

const context = datadogRum.getRumGlobalContext();
```
You can clear the global context by using `clearGlobalContext`.

{{% /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