User ID section

_data/sidebar.yml

@@ -2022,3 +2022,41 @@
   isSectionHeader: 0
   sectionTitle:
   subgroup: 0
+
+#-------------- Prebid Identity --------------|
+
+- sbSecId: 9
+  title:
+  link:
+  isHeader: 0
+  isSectionHeader: 1
+  sectionTitle: Prebid Identity
+  sectionId: prebid-identity
+  subgroup: 1000
+  sbCollapseId: prebid-identity
+
+- sbSecId: 9
+  title: invis
+  link:
+  isHeader: 1
+  headerId: invis
+  isSectionHeader: 0
+  sectionTitle:
+  subgroup: 0
+
+- sbSecId: 9
+  title: Identity Overview
+  link: /identity/prebid-identity.html
+  isHeader: 0
+  isSectionHeader: 0
+  sectionTitle:
+  subgroup: 0
+
+- sbSecId: 9
+  title: SharedID
+  link: /identity/sharedId.html
+  isHeader: 0
+  isSectionHeader: 0
+  sectionTitle:
+  subgroup: 0
+

_layouts/home.html

@@ -42,6 +42,14 @@ <h1>Prebid Documentation</h1>
           <p class="mt-4"><a href="/prebid-mobile/download.html">Download Mobile SDK</a></p>
         </div>
       </div>
+      <div class="card text-center">
+        <div class="card-body">
+          <div class="card-media"><img src="/assets/images/user-identity.png" width=100 alt="Prebid User Identity Icon"></div>
+          <div class="card-title"><h3>Prebid User Identity</h3></div>
+          <p class="mb-4">Supporting the open web while respecting user privacy.</p>
+          <a href="/identity/prebid-identity.html" class="btn btn-outline-brand">View Docs</a>
+        </div>
+      </div>
     </div>
 
     <div class="row text-center mt-7">

identity/prebid-identity.md

@@ -0,0 +1,63 @@
+---
+layout: page_v2
+title: Prebid User Identity
+description: What is Prebid User Identity
+sidebarType: 9
+---
+
+# Prebid User Identity Overview
+
+Prebid's aim is to enable the protection of user privacy while still supporting publisher's ability to make revenue,
+keeping the Open Web healthy.
+
+To do this, Prebid offers a number of identity-related products that encourage awareness of privacy regulations such as GDPR, CCPA, and COPPA. The most important projects are:
+
+- [Prebid.js User Identity Module](/dev-docs/modules/userId.html). This module supports more than 20 different flavors of global IDs with different features that publishers can work with.
+- [SharedID](/identity/sharedId.html). This native hosted ID offering from Prebid is simple, free, robust, and privacy-minded.
+- **Coming soon:** [Unified ID 2.0](https://prebid.org/blog/prebid-org-to-serve-as-operator-of-unified-id-2-0/)
+
+## Prebid.js and Identity
+
+Publishers have several ways to include user identity as part of
+the header bidding auction:
+
+1. Install one or more [User ID modules](/dev-docs/modules/userId.html). These modules obtain
+the user's ID from the service and make it available to participating bidders. Publishers
+can define [permissions](/dev-docs/modules/userId.html#permissions) to control which bidders receive which IDs.
+2. Install the [ID Import Module](/dev-docs/modules/idLibrary.html). This module can be
+used to generate a map of identities present on the page.
+3. Pass [First Party Data](/features/firstPartyData.html), such as interests, to bidders for more relevant advertising.
+4. Include [User Syncing](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Configure-User-Syncing) to allow bid adapters to establish IDs. Publishers have control over which bidders may sync, which syncing mechanisms are allowed, and when the syncing occurs. Syncing is subject to privacy controls such as GDPR, CCPA, and COPPA.
+
+## Prebid Server and Identity
+
+Prebid Server has user sync functionality, allowing server-side bidders to establish
+IDs given appropriate permission from the user for setting cookies.
+
+Prebid Server can receive extended ID arrays (eids) from Prebid.js and provide them to
+participating server-side bid adapters. It also supports permissioning to determine
+which eids can be sent to which bidders.
+
+User IDs are not sent to bid adapters in privacy scenarios such as COPPA and
+GDPR requests lacking appropriate consent. For more details see [Prebid Server Privacy](/prebid-server/features/pbs-privacy.html).
+
+## Prebid SDK and Identity
+
+In application environments, performance-based advertisers rely on a device’s IDFA to target,
+frequency cap, and determine attribution, similar to how cookies are used in desktop
+environments. However, IDFAs are persistent to the device. Prebid SDK will read the IDFA from
+the device when available. Additionally, Prebid SDK supports third party identity IDs.
+
+Prebid Server will strip the IDFA and/or third party identity IDs when enforcing regulations such as GDPR and CCPA.
+
+## AMP, Prebid, and Identity
+
+Prebid Server supports a user [cookie-sync](/prebid-server/developers/pbs-cookie-sync.html) functionality, including integration with
+a consent management platform. This allows server-side bidders to establish IDs given
+the appropriate cookie-setting permissions from the user.
+
+## Further Reading
+
+- [PBJS User ID module](/dev-docs/modules/userId.html)
+- [SharedID](/identity/sharedId.html)
+- [Prebid Server Privacy](/prebid-server/features/pbs-privacy.html)

identity/sharedId.md

@@ -0,0 +1,141 @@
+---
+layout: page_v2
+title: SharedID
+description: What is SharedID
+sidebarType: 9
+---
+
+# Prebid SharedID
+{: .no_toc}
+
+* TOC
+{:toc}
+
+{: .alert.alert-warning :}
+As of Prebid.js 5.0, PubCommon ID is no longer supported -- it's been merged into SharedID. Also, SharedID no longer syncs to sharedid.org like it did in Prebid.js 4.x.
+
+## What is it?
+
+SharedId is a convenient Prebid-owned first party identifier within the [Prebid UserId Module framework](/dev-docs/modules/userId.html).
+
+## How does it work?
+
+The SharedID ID system sets a user id cookie in the publisher’s domain.
+Since the cookie is set in the publisher's first party domain it does not fall in scope of browser restrictions on third party cookies.
+
+### Prebid.js 5.x
+
+The SharedID module reads and/or sets a random ID in
+the cookie name defined by the publisher when initializing
+the module:
+
+```
+pbjs.setConfig({
+    userSync: {
+        userIds: [{
+            name: 'sharedId',
+            storage: {
+                name: '_sharedID', // name of the 1st party cookie
+                type: 'cookie',
+                expires: 30
+            }
+        }]
+    }
+});
+```
+
+The 'source' value transmitted through OpenRTB (user.ext.eids) is pubcid.org. For example:
+```
+user: {
+    ext: {
+        eids: {
+            "source":"pubcid.org",
+            "uids":[
+               {
+                  "id":"01EAJWWNEPN3CYMM5N8M5VXY22",
+                  "atype":1
+               }
+           ]
+        }
+    }
+}
+```
+
+{: .alert.alert-info :}
+The 'pubcid.org' EID source was adopted by more buyers than 'sharedid.org', so
+when PubCommon was folded into SharedID, we kept the more commonly recognized
+source value.
+
+### Before Prebid.js 5.0
+
+In addition to setting a first party cookie, SharedID in Prebid.js 4.x also sets a third party cookie where possible, syncing the first and third party cookies (subject to browser capability and user opt-out).
+
+SharedID in Prebid.js 4.x was transmitted through the header-bidding ecosystem on user.ext.eids with a different 'source':
+```
+user: {
+    ext: {
+        eids: {
+            "source":"sharedid.org",
+            "uids":[
+               {
+                  "id":"01EAJWWNEPN3CYMM5N8M5VXY22",
+                  "atype":1,
+                  "ext":{
+                     "third":"01EAJWWNEPN3CYMM5N8M5VXY22"
+                  }
+               }
+           ]
+        }
+    }
+}
+```
+
+### Detailed Walkthrough
+
+This diagram summarizes the workflow for SharedID:
+
+![SharedID](/assets/images/sharedid5.png){: .pb-lg-img :}
+
+1. The page loads the Prebid.js package, which includes the SharedId module.
+2. The page enables one or more user ID modules with pbjs.setConfig({usersync}) per the module documentation. The publisher can control which bidders are allowed to receive each type of ID.
+3. If permitted, the SharedID module retrieves and/or sets the designated first party cookie for this user.
+4. When a header bidding auction is run, the ID modules are invoked to add their IDs into the bid requests.
+5. Bid adapters send the additional IDs to the bidding endpoints, along with other privacy information such as GDPR consent, US Privacy consent, and the Global Privacy Control header.
+6. SharedID is used by the bidder for ad targeting, frequency capping, and/or sequential ads.
+7. Bids are sent to the publisher's ad server, where the best ad is chosen for rendering.
+
+{: .alert.alert-info :}
+In Prebid.js 4.x, when SharedID performed third-party syncing there
+was an extra step in the diagram between steps 3 and 4 where the module would connect to a server on sharedid.org. This step was
+removed in Prebid.js 5.0.
+
+### Privacy Discussion
+
+There are several privacy scenarios in which a user ID is not created or read:
+
+1. The User ID module suppresses all cookie reading and setting activity
+when the [GDPR Enforcement Module](/dev-docs/modules/gdprEnforcement.html) is in place and there's no consent for Purpose 1.
+2. The User ID module infrastructure supports a first-party opt-out, by setting the `_pbjs_id_optout` cookie or local storage to any value. No other cookies will be set if this one is set.
+3. The SharedID module will suppress the ID when the COPPA flag is set.
+
+For all other privacy-sensitive scenarios, it is encumbent upon bid adapters and endpoints
+to be aware of and enforce relevant regulations such as CCPA and Global Privacy Control.
+
+## Opt-Out
+
+Prebid recommends that publishers provide their users with information about how IDs are utilized, including targeting, frequency capping, and special ad features like sequential ads.
+
+If the publisher's legal staff has determined that a user opt-out is necessary beyond existing
+mechanisms like GDPR and CCPA, the use of first party cookies requires that opt-out flow be owned
+by the publisher.
+
+Publishers that decide to build a first-party opt-out workflow might follow a process like this:
+- User is presented with an option to turn off ad targeting
+- If the user opts out, the page can do one of two things:
+    - set a _pbjs_id_optout first party cookie
+    - avoid calling pbjs.setConfig to initialize the user ID modules
+
+## Related Topics
+
+- [Prebid Identity Overview](/identity/prebid-identity.html)
+- [Prebid.js User ID modules](/dev-docs/modules/userId.html)

identity/sharedIdPubCommon.md

@@ -0,0 +1,133 @@
+---
+layout: page_v2
+title: SharedID and PubCommon ID
+description: What are SharedID and PubCommon ID
+sidebarType: 9
+---
+
+# Prebid SharedID and PubCommon ID
+{: .no_toc}
+
+* TOC
+{:toc}
+
+## What are they?
+
+SharedId and PubCommon are ID systems that are part of the [Prebid UserId Module framework](/dev-docs/modules/userId.html).
+
+Both systems are owned by Prebid.org, and maintained by a community of developers led by Magnite and Conversant. Prebid.org's [privacy policy](TBD) applies to these systems.
+
+## How do they work?
+
+The SharedID and PubCommon ID systems set a user id cookie in the publisher’s domain.
+Since the cookie is set in the publisher's first party domain it is safe from browser restrictions on third party cookies. The follow sections describe the differences between the two systems.
+
+### SharedID
+
+In addition to setting a first party cookie, SharedID also sets a third party cookie.
+SharedId keeps these two cookies in sync wherever possible, giving SSPs and DSPs a way to track
+consenting users across domains using a first party cookie. This mechanism will only work as long as
+third party cookies can be set. For now this applies only to the Chrome browser, and only until
+Chrome starts restricting third party cookies, which we expect to be sometime in the spring of 2022.
+
+Today, SharedId supports a universal opt-out signal. However, that opt-out signal is premised on third party cookies. (More on this topic below.)
+
+SharedID is transmitted through the header-bidding ecosystem on user.ext.eids like this:
+```
+user: {
+    ext: {
+        eids: {
+            "source":"sharedid.org",
+            "uids":[
+               {
+                  "id":"01EAJWWNEPN3CYMM5N8M5VXY22",
+                  "atype":1,
+                  "ext":{
+                     "third":"01EAJWWNEPN3CYMM5N8M5VXY22"
+                  }
+               }
+           ]
+        }
+    }
+}
+```
+
+### PubCommon ID
+
+PubCommon started out supporting just first-party cookies, but now also supports setting a third party cookie and keeping them in sync in the same way as
+SharedId. However, this syncing functionality is **off** by default. It can be turned on as desired.
+
+PubCommon does not support a universal opt-out, but does support a first-party opt-out, by setting the _pbjs_id_optout to any value.
+
+PubCommon is transmitted through the header-bidding ecosystem on user.ext.eids like this:
+```
+user: {
+    ext: {
+        eids: {
+            "source":"pubcid.org",
+            "uids":[
+               {
+                  "id":"01EAJWWNEPN3CYMM5N8M5VXY22",
+                  "atype":1
+               }
+           ]
+        }
+    }
+}
+```
+Note that PubCommon does not carry the `third` party cookie value.
+
+### Detailed Walkthrough
+
+This diagram summarizes the workflow for SharedID and PubCommon:
+
+![SharedID](/assets/images/sharedid.png){: .pb-lg-img :}
+
+1. The page loads the Prebid.js package, which includes the SharedId and/or PubCommon modules.
+2. The page enables one or more user ID modules with pbjs.setConfig({usersync}) per the module documentation. The publisher can control which bidders are allowed to receive each type of ID.
+3. If permitted, the SharedID and/or PubCommon module retrieves and/or sets the designated first party cookie for this user.
+4. If permitted, the SharedID module connects to sharedid.org to see if the user has a third party identification.
+5. When a header bidding auction is run, the ID modules are invoked to add their IDs into the bid requests.
+6. Bid adapters send the additional IDs to the bidding endpoints, along with other privacy information such as GDPR consent, US Privacy consent, and the Global Privacy Control header.
+7. The SharedID and PubCommon IDs are used by the bidder for ad targeting, frequency capping, and/or sequential ads.
+8. Bids are sent to the publisher's ad server, where the best ad is chosen for rendering.
+
+### Privacy Discussion
+
+The only privacy scenario where the Prebid User ID module will suppress ID activity is that
+cookies cannot be read or set when the [GDPR Enforcement Module](/dev-docs/modules/gdprEnforcement.html) is in place without consent for Purpose 1.
+
+For all other privacy-sensitive scenarios, it is encumbent upon ID providers and bid adapters
+to be aware of and enforce relevant regulations such as COPPA, CCPA, and Global Privacy Control.
+
+## Why maintain two modules that are functionally equivalent?
+
+When Prebid.org assumed ownership of PubCommon, it already had hundreds of publishers using it.
+Instead of merging the two ID systems, which would have required wrapper updates by publishers,
+we decided to add the functionality of Sharedid into PubCommon, giving publishers the choice
+of whether to enable it or not.
+
+In the future as third party cookies become more restricted, we anticipate that the two modules will merge.  
+
+## Opt-Out
+
+Prebid recommends that publishers provide their users with information about how IDs are utilized, which includes targeting, frequency capping, and special ad features like sequential ads.
+
+If the publisher's legal staff has determined that a user opt-out is necessary beyond existing
+mechanisms like GDPR and CCPA, first party cookies require that opt-out flow be owned
+by the publisher.
+
+Third party SharedID cookies support an opt-out page hosted at [sharedid.org](https://id.sharedid.org).
+Clicking “Opt Out” will flag the user's third party SharedId cookie as unusable. The next time the SharedId code runs on each publisher's page,
+the module will recognize that the browser/user has opted out and will flag that publisher's first party cookie as equally unusable.
+
+Publishers that decide to build a first-party opt-out workflow might follow a process like this:
+- User is presented with an option to turn off ad targeting.
+- If the user opts out, the page can do one of two things:
+    - set a _pbjs_id_optout first party cookie
+    - avoid calling pbjs.setConfig to initialize the user ID modules
+
+## Related Topics
+
+- [Prebid Identity Overview](/identity/prebid-identity.html)
+- [Prebid.js User ID modules](/dev-docs/modules/userId.html)