diff --git a/README.md b/README.md index a68a211..9ce6a79 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,41 @@ # New Jersey Feedback Widget +## Further Documentation +Additional documentation related to using the feedback widget and data collected. + +- [Getting Started with the Feedback Widget](https://docs.google.com/document/d/1gg-u9hEfCQ9-o014gAOonLX8whqPZuQDxxMrTQyp_BI/edit?tab=t.0) +- [Analyzing Feedback Widget data with Looker Studio](https://docs.google.com/document/d/1m4NMp7ul72jd7Xs5e0hnK-yTVs5DS9NzypkM5CVpai8/edit?tab=t.0#heading=h.7d0k4lo2ipwb) +- [Analyzing Feedback Widget data with the AI Assistant](https://docs.google.com/document/d/1w1ZJcs0oG4RGYne1Ksm1PfvfVpeoIUJhUhrtQi1XKD0/edit?tab=t.0#heading=h.gg2y1ft2ehff) + ## About this component A generic, reusable [web component](https://developer.mozilla.org/en-US/docs/Web/Web_Components) that can be added to any New Jersey page to get quick, in-page feedback from the user. This is inspired by the [CA Design System's similar component](https://designsystem.webstandards.ca.gov/components/page-feedback/readme/). It is mobile-responsive, accessible (tested with [axe](https://www.deque.com/axe/) tool), and supports English and Spanish language. See the [Feedback API](https://github.com/newjersey/feedback-api) Github repository for the code that handles and saves this data. ### User flow -1. _Rating_: At the bottom of a webpage, the widget asks user to rate their experience of the page with "Yes" and "No" buttons. Upon clicking an option, the rating is saved to a Google Sheet and Google Analytics (page URL, datetime, and selection). Note: See `only-save-rating-to-analytics` attribute below for customization. -2. _Comment_: Widget asks user to optionally share feedback in a free text field. Upon submitting, this text is recorded to Google Sheets. Note: Users often have specific questions about their situation rather than feedback. Note: See `contact-link` attribute below for customization. -3. _Email_: Widget asks user to optionally share their email to join a user testing group. Upon submitting, this email is recorded to Google Sheets. +1. _Rating_: At the bottom of a webpage, the widget asks user to rate their experience of the page with "Yes" and "No" buttons. Upon clicking an option, the rating is saved to a Google Sheet and Google Analytics (along with page URL, and submission datetime). + + **Note:** See `only-save-rating-to-analytics` attribute below for customization. +2. **[OPTIONAL]** _Comment_: Widget asks user to optionally share feedback in a free text field. Upon submitting, this text is recorded to Google Sheets. + + **Note:** Users often have specific questions about their situation rather than feedback. + + **Note:** See `contact-link` attribute below for customization. +3. **[OPTIONAL]** _Email_: Widget asks user to optionally share their email to join a user testing group. Upon submitting, this email is recorded to Google Sheets. + +| User Submission Type | Required? | Saved to Google Analytics? | Saved to Google Sheets? +| ------- | ------- | ------- | ------ | +| **Rating** | Yes | Yes | Yes, customizable | +| **Comment** | No | No | Yes | +| **Email** | No | No | Yes | ### Spanish content -The component supports English and Spanish content and switching between the two. To switch the language of the component's content, use JavaScript to send a custom event using the code below. For example, we can send this event in a click handler for a button. +The component supports both English and Spanish content and offers users the ability to toggle between the two. To switch the language used within the component, use JavaScript to send a custom event using the code below: ```javascript +// sending a custom changeLanguage event in a click handler for a language toggle button + document.getElementById("languageButton").addEventListener("click", (e) => { const customEvent = new CustomEvent("changeLanguage", { detail: "es" /* "en" for English or "es" for Spanish */, @@ -24,34 +45,27 @@ document.getElementById("languageButton").addEventListener("click", (e) => { }); ``` -### Where it's used - -- NJ DOL, TDI/FLI, MyLeaveBenefits, [Maternity Timeline Tool (Welcome)](https://nj.gov/labor/myleavebenefits/worker/maternity/timeline-welcome.shtml) -- NJ DOL, TDI/FLI, MyLeaveBenefits, [Maternity Timeline Tool (Tool)](https://nj.gov/labor/myleavebenefits/worker/maternity/timeline-tool.shtml) -- NJ DOL, TDI/FLI, MyLeaveBenefits, [What happens after I apply?](https://nj.gov/labor/myleavebenefits/worker/resources/claims-status.shtml) -- NJ DOL, TDI/FLI, MyLeaveBenefits, [Announcing a new way to log in](https://www.nj.gov/labor/myleavebenefits/worker/resources/login-update.shtml) -- NJ DOL, UI, [Claim Status](https://uistatus.dol.state.nj.us/) -- Office of Innovation, [Office website](https://innovation.nj.gov/) - ### Customizable attributes -- `contact-link` - Assign to a string with the URL that you want to direct users to if they have a specific question. By default, a the following URL will be used: https://nj.gov/nj/feedback.html. -- `only-save-rating-to-analytics` - Rather than saving ratings without comments to the Google Sheets database, you can choose to only save to Google Analytics (whichever property is added to your site) with the value `"true"`. `"true"` is recommended if expecting high traffic. Defaults to `"false"`. -- `show-comment-disclaimer` - This can be `"true"` or `"false"` to determine whether to display the disclaimer text underneath Step 2 of the form where we prompt users to submit an open-ended comment. The disclaimer directs users to a separate contact form link (see `contact-link` above) if they have specific questions. Defaults to `"true"` if not provided. -- `skip-email-step` - This can be `"true"` or `"false"` to determine whether to prompt the user to enter their email to join a testing group after submitting a comment. If `"false"`, submitting the comment will take the user straight to a thank you confirmation view. Defaults to `"false"` if not provided. +| Attribute | Description | Possible values | Defaults to | Example | Recommendations +| --------- | ----------- | --------------- | ----------- | ------- | --------------- +| `contact-link` | A string that can be used to set a custom URL that users are directed to if they have a specific question that they would like to have addressed. | Any URL | [NJ Contact Us page URL](https://nj.gov/nj/feedback.html) | [innovation homepage repo](https://github.com/newjersey/innovation.nj.gov/blob/de88f1e11f5b0260cd0a74125876ab127a4164f3/_includes/footer.html#L8) | N/A | +| `only-save-rating-to-analytics` | A boolean that can be used to save ratings without comments only to Google Analytics rather than saving to the Google Sheets database | `"true"` or `"false"` | `"false"` | [UI Claim Status web app repo](https://github.com/newjersey/dol-ui-claim-status-web-app/blob/d293ff3df8bcc3c6c03bfb2aac4976787012d6b7/src/NJFooter.tsx#L42) | Setting to `"true"` is recommended for high traffic pages +| `show-comment-disclaimer` | A boolean that can be used to determine whether disclaimer text should be displayed in the feedback widget when users are prompted to submit a comment. This disclaimer will direct users to a separate contact form link if they have specific questions. | `"true"` or `"false"` | `"true"` | N/A | N/A +| `skip-email-step` | A boolean that can be used to determine whether to prompt the user to enter their email to join a testing group after submitting a comment. | `"true"` or `"false"` | `"false"` | N/A | N/A -## For users: how to add this to your website +## How to add this to your website ### With Node/NPM -1. Install the latest version via the command `npm i @newjersey/feedback-widget --save`. -2. In the file you want to refer to the widget (for example, `App.tsx`/`App.jsx` in Create React App), import the JavaScript file to be used. +1. Install the latest version of the widget via the command `npm i @newjersey/feedback-widget --save`. +2. In the file where you would like to add a reference to the widget (likely `App.tsx`/`App.jsx` in a Create React App project), import the Javascript file to be used: ```javascript import "@newjersey/feedback-widget/feedback-widget.min.js"; ``` -3. If using TypeScript, add the following type definition to the same file that you imported +3. If using TypeScript, add the following type definition to the same file you imported ```typescript declare global { @@ -93,11 +107,11 @@ declare global { > ``` -## For developers: how to improve this component +## [FOR DEVELOPERS] How to improve this component ### Minifying the JS file -Before pushing changes to `feedback-widget.js`, make sure you update the minified file (this will be automated eventually). +Before pushing changes to `feedback-widget.js`, make sure you update the minified file: 1. `npm install uglify-js -g` (global install, not part of npm project) 2. `cd feedback-widget && nvm use 16`