Update SharedId docs with Conversant content (#3137)

* Update userId.md updating the table and text of Sharedid (FKA pubcommon's) entry in the user id section. * Update sharedid.md adding docs from Conversant's site as requested in #2525 * Update userId.md updating sharedid examples to include a #3 describing the setConfig when a server is used * Update sharedid.md adding text around docuement.cookie use in safari * Update sharedid.md renaming user id module section and updating desc in table to prebid.js * Update sharedid.md noting that Pubcid script has a high technical cost and a variable revenue benifit * Update sharedid.md renaming pubcid server to SharedId Server * Update sharedid.md adding a comment to pixelURL clarifying what this param should be used for. * Update sharedid.md updating when sharedid script is appropriate * Update sharedid.md updating pubcid server to SharedId Server * Update sharedid.md updating pubcid server to SharedId Server * Update userId.md adding a link to sharedid.html * Update userId.md adding a second link to sharedid.html * Update sharedid.md adding additional language sharedid servers benefits wrt safari * changing link to relative * another link * wordsmithing * consistency and wordsmithing * Update sharedid.md adding text to CMS description. * more wordsmithing - The term "sharedId server" confused me. I changed most of these to "endpoint" instead of server. - Clarified the term "plugin", which has a meaning in PBJS that's quite different than the usage here. - Removed duplicate exhortations to use the weird "endpoint" thing. Co-authored-by: bretg <[email protected]>
prebid · Jul 27, 2021 · fede322 · fede322
1 parent 201ec27
commit fede322
Show file tree

Hide file tree

Showing 2 changed files with 284 additions and 20 deletions.
diff --git a/dev-docs/modules/userId.md b/dev-docs/modules/userId.md
@@ -1334,10 +1334,10 @@ pbjs.setConfig({
 
 ### SharedID
 
-This module stores an unique user id in the first party domain and makes it accessible to all adapters. Similar to IDFA and AAID, this is a simple UUID that can be utilized to improve user matching, especially for iOS and MacOS browsers, and is compatible with ITP (Intelligent Tracking Prevention). It’s lightweight and self contained. Adapters that support Publisher Common ID will be able to pick up the user ID and return it for additional server-side cross device tracking.
+This module stores an unique user id in the first party domain and makes it accessible to all adapters. Similar to IDFA and AAID, this is a simple UUID that can be utilized to improve user matching, especially for iOS and MacOS browsers, and is compatible with ITP (Intelligent Tracking Prevention). It’s lightweight and self contained. Adapters that support SharedId will be able to pick up the user ID and return it for additional server-side cross device tracking.
 
 There is no special registration or configuration for SharedID. Each publisher's privacy policy should take
-SharedID into account.
+SharedID into account.  Prebid  recommends implementing a method where users can easily opt-out of targeted advertising. Please refer to the User Opt-Out section located at the bottom of this page. For more information check out Prebid's dedicated [identity page](/identity/sharedid.html) 
 
 Add it to your Prebid.js package with:
 
@@ -1354,8 +1354,12 @@ In addition to the parameters documented above in the Basic Configuration sectio
 | name | Required | String | The name of this module. | `'pubCommonId'` |
 | params | Optional | Object | Customized parameters | |
 | params.create | Optional | Boolean | For publisher server support only.  If true, the publisher's server will create the (pubcid) cookie.  Default is true. | `true` |
-| params.pixelUrl | Optional | String | For publisher server support only.  This is a URL of a pixel for updating cookies' expiration times.  Fired after a new ID has been created or an existing ID is being extended.  No default. | `'https://example.com/ping'`
+| params.pixelUrl | Optional | String | For publisher server support only. Where to call out to for a server cookie -- see [Prebid Identity](/identity/sharedid.html) for more information. | `/wp-json/pubcid/v1/extend/`
 | params.extend | Optional | Boolean | If true, the expiration time of the stored IDs will be refreshed during each page load.  Default is false. | `false` |
+| storage | Required | Object | The publisher must specify some kind of local storage in which to store the results of the call to get the user ID. This can be either cookie or HTML5 storage. |
+| storage.expires | Integer | Required | How long the user ID information will be stored. | `365` |
+| storage.name | String | Required | The name of the cookie or html5 local storage where the user ID will be stored. | `_pubcid`
+| storage.type | String | Required | This is where the results of the user ID will be stored. Must be either: Must be either: "cookie" or "html5". For server side implementations, which have the best identifier life and revenue impact, this must be a cookie. | `cookie`
 
 #### SharedID Examples
 
@@ -1368,7 +1372,7 @@ pbjs.setConfig({
             name: "pubCommonId",
             storage: {
                 type: "cookie",
-                name: "_pubcid",         // create a cookie with this name
+                name: `"_pubcid"`,         // create a cookie with this name
                 expires: 365             // expires in 1 years
             }
         }]
@@ -1393,9 +1397,12 @@ pbjs.setConfig({
             }
         },{
             name: "pubCommonId",
+            params: {
+                pixelUrl: "/wp-json/pubcid/v1/extend/"
+            },
             storage: {
                 type: "cookie",
-                name: "_pubcid",      // create a cookie with this name
+                name: `"_pubcid"`,      // create a cookie with this name
                 expires: 180
             }
         }],
@@ -1404,6 +1411,26 @@ pbjs.setConfig({
 });
 {% endhighlight %}
 
+3) Publisher supports SharedID and first party domain cookie storage initiated by a first party server
+
+{% highlight javascript %}
+pbjs.setConfig({
+    userSync: {
+        userIds: [{
+            name: "pubCommonId",
+            params: {
+                pixelUrl: "/wp-json/pubcid/v1/extend/" //pixelUrl should be specified when the server plugin is used
+            },
+            storage: {
+                type: "cookie",
+                name: `"_pubcid"`,         // create a cookie with this name
+                expires: 365             // expires in 1 years
+            }
+        }]
+    }
+});
+{% endhighlight %}
+
 ### PubProvided ID
 
 The PubProvided Id module allows publishers to set and pass a first party user id into the bid stream. This module has several unique characteristics: