This is an automated email from the ASF dual-hosted git repository. poorejc pushed a commit to branch test in repository https://gitbox.apache.org/repos/asf/incubator-flagon-useralejs.git
commit eefb408f9562b1eea87bdc40d2b7f655ece8d94b Author: Gedd Johnson <[email protected]> AuthorDate: Mon Mar 22 16:13:34 2021 +0000 updates custom labeling docs --- example/log-label-example/README.md | 99 +++++++++++------------------------- example/log-label-example/index.html | 38 +++++++------- 2 files changed, 50 insertions(+), 87 deletions(-) diff --git a/example/log-label-example/README.md b/example/log-label-example/README.md index 443f610..f196d27 100644 --- a/example/log-label-example/README.md +++ b/example/log-label-example/README.md @@ -1,10 +1,12 @@ # Custom Log Label Examples -Examples illustrating how to add custom labels to logs generated by `userale`. +The following are examples illustrating how to add custom labels to logs generated by UserALE.js. Custom labels are +useful in cases where one would prefer to use a more descriptive label for an element users interact with or when +logging information about a specific feature. ## Adding Custom Labels to Logs -### Method 1 +### Example 1 Consider the following HTML: @@ -15,83 +17,44 @@ Consider the following HTML: </div> ``` -The following code snippet will add a custom field and send a log whenever the new feature button is clicked: +The following code snippet will add a custom field, `customLabel`, and send a log whenever the new feature button is +clicked: ```js -document.addEventListener('click', function (e) { - if (e.target.innerHTML === 'New Feature') { - window.userale.map(log => ({...log, logType: 'custom', customLabel: 'New Feature'})); - window.userale.packageLog(e, window.userale.details(window.userale.options(), e.type)); - window.userale.map(); - } else { - return false +window.userale.map((log, e) => { + // determine whether we want to add custom labels to the log + if (e && e.target.innerHTML !== 'New Feature') { + return log; // normal logging } + // if the event occurred on the New Feature, add custom labeling + return { + ...log, + customLabel: 'New Feature', + logType: 'custom', + }; }); ``` -Taking this example apart: +### Example 2 -This is the function that will decorate the custom labelling function. It adds another event listener to the DOM and -looks for the text "New Feature" in `click` events. +Let's say you want to generate logs on custom events, or events not currently supported by UserALE.js. In this case, you +can add an event listener and use the `customPackageLog` function as shown below: ```js -document.addEventListener('click', function (e) { - if (e.target.innerHTML === 'New Feature') { - // ... - } else { - return false - } -}); -``` - -If the new feature doesn't include any identifiable text, you can also use: - -```js -if (e.target.className === 'new-feature-class') -``` - -When the new event listener's callback is invoked and the event has been identified as being fired on the new feature, -the following block enables custom logging: - -```js -window.userale.map(log => ({...log, logType: 'custom', customLabel: 'New Feature'})); -window.userale.packageLog(e, window.userale.details(window.userale.options(), e.type)); -window.userale.map(); -``` - -The `userale.map` function will map over the current log adding the custom log type and label. Then, `userale. -packageLog` -packages and sends the log. The `userale.map` call resets Userale's `map` API back to -its original state. Failure to do this risks applying the custom label to all other `click` events. - -Finally, note that this function in its current form will generate duplicate events, one that has the typical log -schema and another with the added custom fields - -### Method 2 -Consider the following HTML: - -```html - -<div> - <input class="new-feature-checkbox" type="checkbox"> -</div> -``` - -The following code snippet will add custom fields and send a log whenever the checkbox is interacted with: - -```js - document.addEventListener('change', function (e) { - if (e.target.className === 'new-feature-checkbox') { + document.addEventListener('customEvent', function (e) { window.userale.packageCustomLog({ - type: 'change', - customLabel: 'New Feature', - customField1: 'New Checkbox', + type: 'customEvent', + customLabel: 'custom label', + customField1: 'custom field', }, () => ({customDetails: Date.now()}), true); - } else { - return false } -}); +); ``` -As shown in Method 1, the `document.addEventListener` is the function that decorates the `userale.packageCustomLog` -function. The `userale.packageCustomLog` function enables you to send a custom log on demand, as well as, add a custom details function that is invoked when the log is being created. \ No newline at end of file +This event listener will now be invoked on the `customEvent` and send a custom log to the backend. Note that the +`packageCustomLog` function also adds the typical metadata used in the UserALE.js logs. + +Note that we only advise adding custom event listeners in the following scenarios: + +1. For events not captured natively by UserALE.js (as seen above) +2. For sending custom logs *only* \ No newline at end of file diff --git a/example/log-label-example/index.html b/example/log-label-example/index.html index a323cfd..1631254 100644 --- a/example/log-label-example/index.html +++ b/example/log-label-example/index.html @@ -13,34 +13,34 @@ <button>New Feature</button> </div> <div> - <input class="new-feature-checkbox" type="checkbox"> + <input type="checkbox" onchange="document.dispatchEvent(new Event('customEvent'))"> </div> </body> <script> - window.userale.filter(log => ['click', 'change'].includes(log.type)) + window.userale.filter(log => ['click', 'customEvent'].includes(log.type)) - // Method 1 - document.addEventListener('click', function (e) { - if (e.target.innerHTML === 'New Feature') { - window.userale.map(log => ({...log, logType: 'custom', customLabel: 'New Feature'})); - window.userale.packageLog(e, window.userale.details(window.userale.options(), e.type)); - window.userale.map(); - } else { - return false + // Example 1 + window.userale.map((log, e) => { + // determine whether we want to add custom labels to the log + if (e && e.target.innerHTML !== 'New Feature') { + return log; // normal logging } + // if the event occurred on the New Feature, add custom labeling + return { + ...log, + customLabel: 'New Feature', + logType: 'custom', + }; }); - // Method 2 - document.addEventListener('change', function (e) { - if (e.target.className === 'new-feature-checkbox') { + // Example 2 + document.addEventListener('customEvent', function (e) { window.userale.packageCustomLog({ - type: 'change', - customLabel: 'New Feature', - customField1: 'New Checkbox', + type: 'customEvent', + customLabel: 'custom label', + customField1: 'custom field', }, () => ({customDetails: Date.now()}), true); - } else { - return false } - }); + ); </script> </html> \ No newline at end of file
