Merge pull request #4841 from segmentio/client-hints

Add a.js client hints documentation

Author: stayseesong

src/connections/sources/catalog/libraries/website/javascript/index.md

@@ -559,6 +559,14 @@ For example:
 analytics.load('writekey', { disableAutoISOConversion: true })
 ```
 
+#### Client hints
+Some `userAgent` strings are frozen and contain less information. If you would like to request more information when it's available, you can pass an array of strings with fields you would like to request to the `highEntropyValuesClientHints` option. The example array below contains all possible values.
+
+For example:
+
+```js
+analytics.load('writekey', { highEntropyValuesClientHints: ['architecture', 'bitness', 'model', 'platformVersion', 'uaFullVersion', 'fullVersionList', 'wow64'] })
+```
 
 ## Retries
 

src/connections/spec/common.md

@@ -75,7 +75,25 @@ Here's an example of these common fields in raw JSON:
     },
     "groupId": "12345",
     "timezone": "Europe/Amsterdam",
-    "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 9_1 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13B143 Safari/601.1"
+    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/113.0.0.0 Safari/537.36",
+    "userAgentData": {
+      "brands": [
+        {
+          "brand": "Google Chrome",
+          "version": "113"
+        },
+        {
+          "brand": "Chromium",
+          "version": "113"
+        },
+        {
+          "brand": "Not-A.Brand",
+          "version": "24"
+        }
+      ],
+      "mobile": false,
+      "platform": "macOS"
+    }
   },
   "integrations": {
     "All": true,
@@ -134,6 +152,7 @@ Context is a dictionary of extra information that provides useful context about
 | `groupId`   | String  | Group / Account ID. <br><br> This is useful in B2B use cases where you need to attribute your non-group calls to a company or account. It is relied on by several Customer Success and CRM tools.                                                                                                               |
 | `traits`    | Object  | Dictionary of `traits` of the current user. <br><br> This is useful in cases where you need to `track` an event, but also associate information from a previous `identify` call. You should fill this object the same way you would fill traits in an [identify call](/docs/connections/spec/identify/#traits). |
 | `userAgent` | String  | User agent of the device making the request.                                                                                                                                                                                                                                                                    |
+| `userAgentData` | Object | The user agent data of the device making the request. This always contains `brands`, `mobile`, `platform`, and may contain `bitness`, `model`, `platformVersion`,`uaFullVersion`, `fullVersionList`, `wow64`, if [requested](/docs/connections/sources/catalog/libraries/website/javascript/#client-hints) and available. <br><br> This populates if the [Client Hints API](https://developer.mozilla.org/en-US/docs/Web/API/User-Agent_Client_Hints_API){:target="_blank"} is available on the browser. <br><br> This may contain more information than is available in the `userAgent` in some cases.                                                                                                                                |
 | `channel`   | String  | where the request originated from: server, browser or mobile                                                                                                                                                                                                                                                    |
 
 
@@ -180,6 +199,7 @@ Other libraries only collect `context.library`, any other context variables must
 | screen.width             |              | ✅             | ✅                 |
 | traits                   |              | ✅             | ✅                 |
 | userAgent                | ✅            |               | ✅                 |
+| userAgentData*           | ✅           |                |                    |
 | timezone                 |              | ✅             | ✅                 |
 
 - IP Address isn't collected by Segment's libraries, but is instead filled in by Segment's servers when it receives a message for **client side events only**.
@@ -188,6 +208,8 @@ Other libraries only collect `context.library`, any other context variables must
   
 - The Android library collects `screen.density` with [this method](/docs/connections/spec/common/#context-fields-automatically-collected).
 
+- userAgentData is only collected if the [Client Hints API](https://developer.mozilla.org/en-US/docs/Web/API/User-Agent_Client_Hints_API){:target="_blank"} is available on the browser.
+
 To pass the context variables which are not automatically collected by Segment's libraries, you must manually include them in the event payload. The following code shows how to pass `groupId` as the context field of Analytics.js's `.track()` event:
 
 ```js