docs: interactionId parameter for interaction

This PR adds documentation as part of changes introduced in #163.

docs/configuration.md

@@ -140,6 +140,42 @@ telemetries: [
 | --- | --- | --- | --- |
 | enableMutationObserver | Boolean | `false` | When `false`, the web client will record events on only DOM elements that existed when the `window.load` event was fired.<br/><br/>When `true`, the web client will record events on all DOM elements, including those added to the DOM after the `window.load` event was fired. The web client does this by using a [`MutationObserver`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) to listen for changes to the DOM. Using this feature does not typically have a perceptible impact on application performance, but may have a small impact when (1) the plugin is listening for an unusually large number DOM events (i.e., multiple thousands), or (2) the number and size of the DOM mutations are unusually large (i.e., multiple thousands). |
 | events | Array | `[]` | An array of target DOM events to record. Each DOM event is defined by an *event* and a *selector*. The event must be a [DOM event](https://www.w3schools.com/jsref/dom_obj_event.asp). The selector must be one of (1) `cssLocator`, (2) `elementId` or (3) `element`.<br/><br/>When two or more selectors are provided for a target DOM event, only one selector will be used. The selectors will be honored with the following precedence: (1) `cssLocator`, (2) `elementId` or (3) `element`. For example, if both `cssLocator` and `elementId` are provided, only the `cssLocator` selector will be used.<br/><br/>**Examples:**<br/>Record all elements identified by CSS selector `[label="label1"]`:<br/> `[{ event: 'click', cssLocator: '[label="label1"]' }]`<br/><br/>Record a single element with ID `mybutton`:<br/>`[{ event: 'click', elementId: 'mybutton' }]`<br/><br/>Record a complete clickstream<br/>`[{ event: 'click', element: document }]`. |
+| interactionId | Function | `() => undefined` | A function to generate a custom ID for the DOM event. <br/><br/>**Example:**<br/> Retrieve custom ID stored in the `data-rum-id` attribute of a DOM element. <br/> `(element) => element.target.getAttribute('data-rum-id')`|
+
+For example, we can create a function to capture the `data-rum-id` from the nearest parent element if the clicked element doesn't have one, and pass the function into the `interactionId` parameter. Below is an example of a function that checks the nearest 5 ancestors of a DOM element and breaks when the `data-rum-id` attribute is found.
+
+```javascript
+private getRumId(event: Event): string {
+    if (event.composedPath) {
+        const eventPath = event.composedPath();
+        let firstMatchingElement: Element | null;
+
+        for(let i=0; i<5; i++){
+          const element = eventPath[i] as Element;
+          if(element?.hasAttribute && element?.hasAttribute("data-rum-id")){
+            firstMatchingElement = element;
+            break;
+          }
+        }
+
+        if (firstMatchingElement) {
+            return firstMatchingElement.getAttribute('data-rum-id');
+        }
+    }
+    return '';
+}
+```
+You can pass this function into the `interactionId` parameter, as shown in the following telemetry config array.
+```javascript
+telemetries: [
+    [ 
+        'interaction', { 
+            events: [{ event: 'click', element: document }],
+            interactionId: (element) => getRumId(element)
+        }
+    ]
+]
+```
 
 ## Performance