Improve docs for @segment/analytics-consent-wrapper-onetrust (#979)

segmentio · Oct 20, 2023 · caab12e · caab12e
1 parent c879377
commit caab12e
Show file tree

Hide file tree

Showing 2 changed files with 38 additions and 44 deletions.
diff --git a/packages/consent/consent-wrapper-onetrust/README.md b/packages/consent/consent-wrapper-onetrust/README.md
@@ -8,31 +8,57 @@
 
 ## Configure OneTrust + Segment
 
-### Ensure that the OneTrust Banner SDK is loaded first
 
+
+### Requirements
+Ensure that consent is enabled and that you have registered your integration-to-category mappings in Segment, which you can do through the Segment UI.
+
+Note: "categories" are called "groups" in OneTrust.
+
+If you don't see a "Consent Management" option like the one below, please contact support or your Solutions Engineer to have it enabled on your workspace.
+
+![Segment.io consent management UI](img/consent-mgmt-ui.png)
+
+- Debugging hints: this library expects the [OneTrust Banner SDK](https://community.cookiepro.com/s/article/UUID-d8291f61-aa31-813a-ef16-3f6dec73d643?language=en_US) to be available in order interact with OneTrust. This library derives the group IDs that are active for the current user from the `window.OneTrustActiveGroups` object provided by the OneTrust SDK. [Read this for more information [community.cookiepro.com]](https://community.cookiepro.com/s/article/UUID-66bcaaf1-c7ca-5f32-6760-c75a1337c226?language=en_US).
+
+
+## For snippet users
+### Add OneTrust snippet and integration to your page
 ```html
 <head>
-  <!-- This should be included before the Segment snippet -->
+  <!-- OneTrust Cookies Consent Notice start for example.com -->
   <script
     src="https://cdn.cookielaw.org/scripttemplates/otSDKStub.js"
     type="text/javascript"
     charset="UTF-8"
-    data-domain-script="0000-0000-000-test"
+    data-domain-script="0000-0000-000-0000"
   ></script>
-</head>
-```
-
-### Ensure that consent is enabled and that you have created your Integration -> Consent Category Mappings
+  <script type="text/javascript">
+    function OptanonWrapper() { }
+  </script>
 
-- Ensure that your integrations in the Segment UI have consent enabled, and that they map to your Consent Category IDs (also called Cookie Group IDs or Cookie Consent IDs).
-  The IDs look like "C0001", "C0002"and are configurable in OneTrust
-  ![onetrust category ids](img/onetrust-cat-id.jpg)
+  <!-- Add Segment's OneTrust Consent Wrapper -->
+  <script src="https://cdn.jsdelivr.net/npm/@segment/analytics-consent-wrapper-onetrust@latest/dist/umd/analytics-onetrust.umd.js"></script>
 
-- Debugging: this library expects the [OneTrust Banner SDK](https://community.cookiepro.com/s/article/UUID-d8291f61-aa31-813a-ef16-3f6dec73d643?language=en_US) to be available in order interact with OneTrust. This library derives the group IDs that are active for the current user from the `window.OneTrustActiveGroups` object provided by the OneTrust SDK. [Read this for more information [community.cookiepro.com]](https://community.cookiepro.com/s/article/UUID-66bcaaf1-c7ca-5f32-6760-c75a1337c226?language=en_US).
+  <!--
+    Add / Modify Segment Analytics Snippet
+    * Find and replace: analytics.load('<MY_WRITE_KEY'>) -> withOneTrust(analytics).load('<MY_WRITE_KEY'>)
+  -->
+  <script>
+    !function(){var analytics=window.analytics...
+    ....
+    withOneTrust(analytics).load('<MY_WRITE_KEY'>) // replace analytics.load()
+    ....
+  </script>
+</head>
+```
 
+#### ⚠️ Reminder: _you must modify_ `analytics.load('....')` from the original Segment snippet. See markup comment in example above.
 ## For `npm` library users
 
-1. Install the package
+1. Ensure that OneTrust Snippet is loaded. [See example above.](#add-onetrust-snippet-and-integration-to-your-page)
+
+1. Install the package from npm
 
 ```sh
 # npm
@@ -57,38 +83,6 @@ withOneTrust(analytics).load({ writeKey: '<MY_WRITE_KEY'> })
 
 ```
 
-## For snippet users (window.analytics)
-
-1. In your head
-
-```html
-<head>
-  <!-- Add OneTrust -->
-  <script
-    src="https://cdn.cookielaw.org/scripttemplates/otSDKStub.js"
-    type="text/javascript"
-    charset="UTF-8"
-    data-domain-script="YOUR-DOMAIN-SCRIPT-ID"
-  ></script>
-
-  <!-- Add OneTrust Consent Wrapper -->
-  <script src="https://cdn.jsdelivr.net/npm/@segment/analytics-consent-wrapper-onetrust@latest/dist/umd/analytics-onetrust.umd.js"></script>
-
-  <!--
-    Add / Modify Segment Analytics Snippet
-    * Find and replace: analytics.load('<MY_WRITE_KEY'>) -> withOneTrust(analytics).load('<MY_WRITE_KEY'>)
-  -->
-  <script>
-    !function(){var analytics=window.analytics...
-    ....
-    withOneTrust(analytics).load('<MY_WRITE_KEY'>) // replace analytics.load()
-    ....
-  </script>
-</head>
-```
-
-#### ⚠️ Reminder: _you must modify_ `analytics.load('....')` from the original Segment snippet. See markup comment in example above.
-
 ## Other examples:
 
 > Note: Playgrounds are meant for experimentation / testing, and as such, may be a bit overly complicated.

diff --git a/packages/consent/consent-wrapper-onetrust/img/consent-mgmt-ui.png b/packages/consent/consent-wrapper-onetrust/img/consent-mgmt-ui.png