chore: refactor opaque user id

refactor auctions and events and update UUID version
Topsort · Jan 7, 2025 · 2727fbc · 2727fbc
1 parent 46ac064
commit 2727fbc
Showing 1 changed file with 17 additions and 40 deletions.
diff --git a/topsort-api-v2.yml b/topsort-api-v2.yml
@@ -409,14 +409,25 @@ components:
       default: desktop
 
     OpaqueUserID:
+      type: string
+      description:
+        An anonymized unique identifier that maps to the original user ID without revealing the original value. 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 (UUIDv7) on first
+        load and store it on local storage (cookie, local storage, etc) and let it live for at least a year.
+      example: 71303ce0-de89-496d-8270-6434589615e8
+
+    OpaqueUserIDAuction:
       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
+        (UUIDv7) on first load and store it on local storage (cookie, local storage, etc) and let it live for at least
         a year.
       example: 71303ce0-de89-496d-8270-6434589615e8
 
@@ -464,7 +475,7 @@ components:
         geoTargeting:
           $ref: '#/components/schemas/GeoTargeting'
         opaqueUserId:
-          $ref: '#/components/schemas/OpaqueUserID'
+          $ref: '#/components/schemas/OpaqueUserIDAuction'
         placementId:
           $ref: '#/components/schemas/PlacementId'
       required:
@@ -520,7 +531,7 @@ components:
         products:
           $ref: '#/components/schemas/Products'
         opaqueUserId:
-          $ref: '#/components/schemas/OpaqueUserID'
+          $ref: '#/components/schemas/OpaqueUserIDAuction'
         placementId:
           $ref: '#/components/schemas/PlacementId'
       required:
@@ -1220,17 +1231,7 @@ components:
           description: RFC3339 formatted timestamp including UTC offset.
           example: '2009-01-01T12:59:59-05:00'
         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 auctions. 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.
-          minLength: 1
-          example: 71303ce0-de89-496d-8270-6434589615e8
+          $ref: '#/components/schemas/OpaqueUserID'
         id:
           type: string
           description: >
@@ -1273,19 +1274,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: >
@@ -1318,19 +1307,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.