chore: refactor opaque user id (#138)

Redo of #136
Topsort · Jan 14, 2025 · 67e3203 · 67e3203
1 parent a5d4431
commit 67e3203
Showing 1 changed file with 10 additions and 46 deletions.
diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml
@@ -459,13 +459,13 @@ components:
     OpaqueUserID:
       type: string
       description:
-        An anonymized unique identifier that maps to the original user ID without revealing the original value and
-        should match the value used for events. The opaque user ID allows correlating user activity, such as Impressions,
-        Clicks and Purchases, whether or not they are actually logged in. It must be long lived (at least a year) so
-        that Topsort can attribute purchases. If your users are always logged in you may use a hash of your customer ID.
-        If your users may interact with your app or site while logged out we recommend generating a random identifier
-        (UUIDv4) on first load and store it on local storage (cookie, local storage, etc) and let it live for at least
-        a year.
+        The opaque user ID is an anonymized unique identifier that maps to the original user ID without revealing the
+        original value. This identifier allows Topsort to correlate user activity between auctions and user
+        interactions, independent of the user's logged-in status. For apps or sites where users might interact while
+        logged out, we recommend generating a random identifier (UUIDv7) on the first load, storing it on local storage
+        (cookie, local storage, etc), and letting it live for at least a year. Otherwise, if your users are always
+        logged in for interactions, you may use a hash of your customer ID. Correct purchase attribution requires
+        long-lived opaque user IDs consistent between auction and event requests.
       example: 71303ce0-de89-496d-8270-6434589615e8
 
     PlacementId:
@@ -1268,19 +1268,7 @@ components:
           description: RFC3339 formatted timestamp including UTC offset.
           example: '2009-01-01T12:59:59-05:00'
         opaqueUserId:
-          type: string
-          description: |
-            <p>The opaque user ID allows correlating user activity, such as Impressions, Clicks and Purchases,
-            whether or not they are actually logged in. It must be long lived (at least a year) so that Topsort can attribute purchases.
-            </p>
-            <p>
-            If your users are always logged in you may use a hash of your customer ID.
-            If your users may interact with your app or site while logged out we
-            recommend generating a random identifier (UUIDv4) on first load and store it on
-            local storage (cookie, local storage, etc) and let it live for at least a year.
-            </p>
-          minLength: 1
-          example: 71303ce0-de89-496d-8270-6434589615e8
+          $ref: '#/components/schemas/OpaqueUserID'
         id:
           type: string
           description: >
@@ -1323,19 +1311,7 @@ components:
           description: RFC3339 formatted timestamp including UTC offset.
           example: '2009-01-01T12:59:59-05:00'
         opaqueUserId:
-          type: string
-          description: |
-            <p>The opaque user ID allows correlating user activity, such as Impressions, Clicks and Purchases,
-            whether or not they are actually logged in. It must be long lived (at least a year) so that Topsort can attribute purchases.
-            </p>
-            <p>
-            If your users are always logged in you may use a hash of your customer ID.
-            If your users may interact with your app or site while logged out we
-            recommend generating a random identifier (UUIDv4) on first load and store it on
-            local storage (cookie, local storage, etc) and let it live for at least a year.
-            </p>
-          minLength: 1
-          example: 71303ce0-de89-496d-8270-6434589615e8
+          $ref: '#/components/schemas/OpaqueUserID'
         id:
           type: string
           description: >
@@ -1368,19 +1344,7 @@ components:
           example: '2021-10-12T07:20:50.52Z'
           format: date-time
         opaqueUserId:
-          type: string
-          description: |
-            <p>The opaque user ID allows correlating user activity, such as Impressions, Clicks and Purchases,
-            whether or not they are actually logged in. It must be long lived (at least a year) so that Topsort can attribute purchases.
-            </p>
-            <p>
-            If your users are always logged in you may use a hash of your customer ID.
-            If your users may interact with your app or site while logged out we
-            recommend generating a random identifier (UUIDv4) on first load and store it on
-            local storage (cookie, local storage, etc) and let it live for at least a year.
-            </p>
-          minLength: 1
-          example: 71303ce0-de89-496d-8270-6434589615e8
+          $ref: '#/components/schemas/OpaqueUserID'
         items:
           type: array
           description: Items purchased.