feat: add opaqueUserId and placementId fields to auction request desc…

…ription (#135)

Document opaque_user_id and placement_id on auction calls

topsort-api-v2.yml

@@ -408,6 +408,23 @@ components:
         - mobile
       default: desktop
 
+    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.
+      example: 71303ce0-de89-496d-8270-6434589615e8
+
+    PlacementId:
+      type: integer
+      format: int32
+      description: The marketplace's ID of the placement where the ad will appear.
+
     GeoTargeting:
       type: object
       description: An object describing geographical information associated with this auction.
@@ -446,6 +463,10 @@ components:
           $ref: '#/components/schemas/Products'
         geoTargeting:
           $ref: '#/components/schemas/GeoTargeting'
+        opaqueUserId:
+          $ref: '#/components/schemas/OpaqueUserID'
+        placementId:
+          $ref: '#/components/schemas/PlacementId'
       required:
         - type
         - slots
@@ -498,6 +519,10 @@ components:
           minLength: 1
         products:
           $ref: '#/components/schemas/Products'
+        opaqueUserId:
+          $ref: '#/components/schemas/OpaqueUserID'
+        placementId:
+          $ref: '#/components/schemas/PlacementId'
       required:
         - type
         - slots