You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Applications which install the web client using CDN must interact with the web client through its command queue. The command queue is a function which stores commands that will be executed asynchronously by the web client.
3
+
Applications interact with the web client either through its command queue (embedded script install), or its API (JavaScript module install).
4
4
5
-
## Commands
5
+
**Embedded script command queue**
6
+
7
+
The command queue is accessed through a global variable (named `cwr` by default). The command queue is a function which stores commands that will be executed asynchronously by the web client. Commands may be sent to the web client using the command queue after the snippet has executed.
8
+
9
+
**JavaScript module API**
10
+
11
+
Commands may be sent to the web client using the API after the `AwsRum` class has been instantiated.
12
+
13
+
## Examples
6
14
7
-
Commands may be sent to the web client after the snippet has executed. In the following example, the snippet has disabled automated page view recording and has not provided AWS credentials. Following the snippet, the application manually records a page view and forwards AWS credentials to the web client.
15
+
In the following example, the snippet has disabled automated page view recording
16
+
and has not provided AWS credentials. Following the snippet, the application
17
+
manually records a page view and forwards AWS credentials to the web client.
18
+
19
+
**Embedded script example**
8
20
```html
9
21
<script>
10
22
(function(n,i,v,r,s,c,u,x,z){...})(
@@ -23,14 +35,29 @@ Commands may be sent to the web client after the snippet has executed. In the fo
| Command | Parameter Type | Example <divstyle="width:265px"></div> | Description |
27
54
| --- | --- | --- | --- |
28
-
| allowCookies | Boolean | `cwr('allowCookies', true);` | Enable the web client to set and read two cookies: a session cookie named `cwr_s` and a user cookie named `cwr_u`.<br/><br/>`cwr_s` stores session data including an anonymous session ID (uuid v4) created by the web client. This allows CloudWatch RUM to compute sessionized metrics like errors per session.<br/><br/>`cwr_u` stores an anonymous user ID (uuid v4) created by the web client. This allows CloudWatch RUM to count return visitors.<br/><br/>`true`: the web client will use cookies<br/>`false`: the web client will not use cookies
29
-
| disable | None | `cwr('disable');` | Stop recording and dispatching RUM events.
30
-
| dispatch | None | `cwr('dispatch');` | Flush RUM events from the cache and dispatch them to CloudWatch RUM using [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).
31
-
| dispatchBeacon | None | `cwr('dispatchBeacon');` | Flush RUM events from the cache and dispatch them to CloudWatch RUM using [`sendBeacon`](https://developer.mozilla.org/en-US/docs/Web/API/Beacon_API).
32
-
| enable | None | `cwr('enable');` | Start recording and dispatching RUM events.
33
-
| recordPageView | String | `cwr('recordPageView', '/home');` | Record a page view event.<br/><br/>By default, the web client records page views when (1) the page first loads and (2) the browser's [history API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) is called. The page ID is `window.location.pathname`.<br/><br/>In some cases, the web client's instrumentation will not record the desired page ID. In this case, the web client's page view automation must be disabled using the `disableAutoPageView` configuration, and the application must be instrumented to record page views using this command.
34
-
| recordError | Error \| ErrorEvent \| String | `try {...} catch(e) { cwr('recordError', e); }` | Record a caught error.
35
-
| registerDomEvents | Array | `cwr('registerDomEvents', [{ event: 'click', cssLocator: '[label="label1"]' }]);` | Register target DOM events to record. The target DOM events will be added to existing target DOM events. The parameter type is equivalent to the `events` property type of the [interaction telemetry configuration](https://github.com/aws-observability/aws-rum-web/blob/main/docs/cdn_installation.md#interaction).
36
-
| setAwsCredentials | [Credentials](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html)\| [CredentialProvider](https://www.npmjs.com/package/@aws-sdk/credential-providers) | `cwr('setAwsCredentials', cred);` | Forward AWS credentials to the web client. The web client requires AWS credentials with permission to call the `PutRumEvents` API. If you have not set `identityPoolId` and `guestRoleArn` in the web client configuration, you must forward AWS credentials to the web client using this command.
55
+
| allowCookies | Boolean | `cwr('allowCookies', true);`<br/><br/>`awsRum.allowCookies(true)` | Enable the web client to set and read two cookies: a session cookie named `cwr_s` and a user cookie named `cwr_u`.<br/><br/>`cwr_s` stores session data including an anonymous session ID (uuid v4) created by the web client. This allows CloudWatch RUM to compute sessionized metrics like errors per session.<br/><br/>`cwr_u` stores an anonymous user ID (uuid v4) created by the web client. This allows CloudWatch RUM to count return visitors.<br/><br/>`true`: the web client will use cookies<br/>`false`: the web client will not use cookies
56
+
| disable | None | `cwr('disable');`<br/><br/>`awsRum.disable();` | Stop recording and dispatching RUM events.
57
+
| dispatch | None | `cwr('dispatch');`<br/><br/>`awsRum.dispatch();` | Flush RUM events from the cache and dispatch them to CloudWatch RUM using [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).
58
+
| dispatchBeacon | None | `cwr('dispatchBeacon');`<br/><br/>`awsRum.dispatchBeacon();` | Flush RUM events from the cache and dispatch them to CloudWatch RUM using [`sendBeacon`](https://developer.mozilla.org/en-US/docs/Web/API/Beacon_API).
59
+
| enable | None | `cwr('enable');`<br/><br/>`awsRum.enable();` | Start recording and dispatching RUM events.
60
+
| recordPageView | String | `cwr('recordPageView', '/home');`<br/><br/>`awsRum.recordPageView('/home');` | Record a page view event.<br/><br/>By default, the web client records page views when (1) the page first loads and (2) the browser's [history API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) is called. The page ID is `window.location.pathname`.<br/><br/>In some cases, the web client's instrumentation will not record the desired page ID. In this case, the web client's page view automation must be disabled using the `disableAutoPageView` configuration, and the application must be instrumented to record page views using this command.
| registerDomEvents | Array | `cwr('registerDomEvents', [{ event: 'click', cssLocator: '[label="label1"]' }]);`<br/><br/>`awsRum.registerDomEvent([{ event: 'click', cssLocator: '[label="label1"]' }]);` | Register target DOM events to record. The target DOM events will be added to existing target DOM events. The parameter type is equivalent to the `events` property type of the [interaction telemetry configuration](https://github.com/aws-observability/aws-rum-web/blob/main/docs/cdn_installation.md#interaction).
63
+
| setAwsCredentials | [Credentials](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html)\| [CredentialProvider](https://www.npmjs.com/package/@aws-sdk/credential-providers) | `cwr('setAwsCredentials', cred);`<br/><br/>`awsRum.setAwsCredentials(cred);` | Forward AWS credentials to the web client. The web client requires AWS credentials with permission to call the `PutRumEvents` API. If you have not set `identityPoolId` and `guestRoleArn` in the web client configuration, you must forward AWS credentials to the web client using this command.
0 commit comments