CM-1091 Extend LiveIntent's User Id Module To Return sharedId

dev-docs/modules/userid-submodules/liveintent.md

@@ -82,7 +82,7 @@ pbjs.setConfig({
 
 ### Multiple user IDs
 
-The attributes `uid2`, `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, and `index` are treated specially by LiveIntent's user ID sub-module. Each of these attributes will result in a separate ID returned by the sub-module.
+The attributes `uid2`, `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index` and `sharedId` are treated specially by LiveIntent's user ID sub-module. Each of these attributes will result in a separate ID returned by the sub-module.
 
 For example, in case `uid2` is configured to be requested in addition to the `nonID`, the `request.userId` object would look like the following:
 
@@ -100,9 +100,70 @@ For example, in case `uid2` is configured to be requested in addition to the `no
 }
 ```
 
-NOTE: `uid2` is exposed as part of `lipb` as well as separately as `uid2`. `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, and `index` behave the same way.
+NOTE: `uid2` is exposed as part of `lipb` as well as separately as `uid2`. `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index` and `sharedId` behave the same way.
 
-For the attributes `lipbid` (nonID), `uid2`, `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, and `index`, there is also support for their conversion into OpenRTB EIDS format. Please refer to [User ID Module](../userId.md) documentation for more information on conversion, and [Example of eids array generated by UserId Module](https://github.com/prebid/Prebid.js/blob/master/modules/userId/eids.md) for output format examples.
+For the attributes `lipbid` (nonID), `uid2`, `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index` and `sharedId` there is also support for their conversion into OpenRTB EIDS format. Please refer to [User ID Module](../userId.md) documentation for more information on conversion, and [Example of eids array generated by UserId Module](https://github.com/prebid/Prebid.js/blob/master/modules/userId/eids.md) for output format examples.
+
+### SharedID
+
+The [SharedId](https://docs.prebid.org/identity/sharedid.html.) can also be provided by the liveconnect user ID module.
+
+In order to use this functionality tell the module which identifier you want
+to use as a sharedId in the config params:
+
+```javascript
+{
+  "params": {
+    "sharedId": {
+      "strategy": "cookie", // "cookie" | "localstorage" -- Where the identifier should be read from
+      "name": "foobar" // key in the chosen storage backend
+    }
+  }
+}
+```
+
+Additionally, add it to the requested attributes:
+
+```javascript
+{
+    //...
+    "params": {
+        "sharedId": {
+          "strategy": "cookie",
+          "name": "foobar"
+        },
+        "requestedAttributesOverrides": {'sharedId': true}
+    }
+    //...
+}
+```
+
+The user id result will contain both the SharedId directly in the lipb object and separately in a format compatible with the sharedId module (pubcid). Note that the ID is
+called `pubcid` in results, _not_ `sharedId` due to historical reasons:
+
+```javascript
+{"lipb":{"pubcid":"foobar"},"pubcid":{"id":"foobar","ext":{"provider":"liveintent.com"}}}
+```
+
+The same applies for the eids:
+
+```javascript
+[{"source":"pubcid.org","uids":[{"id":"foobar","atype":1,"ext":{"provider":"liveintent.com"}}]}]
+```
+
+NOTE: If COPPA applies, LiveIntent’s user ID module will not return the SharedId.
+
+Module prioritization for SharedId works just as it does for others.
+
+```javascript
+{
+    //...
+    "idPriority": {
+        pubcid: ['sharedId', 'liveIntentId']
+    }
+    //...
+}
+```
 
 ### Request uid2
 
@@ -139,7 +200,7 @@ NOTE: For optimal performance, the LiveIntent ID sub-module should be called at
 | params.ajaxTimeout |Optional| Number |This configuration parameter defines the maximum duration of a call to the `IdentityResolution` endpoint. By default, 5000 milliseconds.|`5000`|
 | params.partner | Optional| String |The name of the partner whose data will be returned in the response.|`prebid`|
 | params.identifiersToResolve |Optional| Array[String] |Used to send additional identifiers in the request for LiveIntent to resolve against the LiveIntent ID and additional attributes.|`['my-id']`|
-| params.requestedAttributesOverrides | Optional | Object | Object containing booleans used to override the default resolution. Attributes set to `true` will be added to the resolved list, while attributes set to `false` will be removed. Valid attributes are `nonId`, `uid2`, `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, and `index`. | `{'uid2': true}` |
+| params.requestedAttributesOverrides | Optional | Object | Object containing booleans used to override the default resolution. Attributes set to `true` will be added to the resolved list, while attributes set to `false` will be removed. Valid attributes are `nonId`, `uid2`, `medianet`, `magnite`, `bidswitch`, `pubmatic`, `openx`, `sovrn`, `index` and `sharedId`. | `{'uid2': true}` |
 | params.emailHash |Optional| String |The hashed email address of a user. We can accept the hashes, which use the following hashing algorithms: md5, sha1, sha2.|`1a79a4d60de6718e8e5b326e338ae533`|
 | params.url | Optional| String |Use this to change the default endpoint URL if you can call the LiveIntent Identity Exchange within your own domain.|`https://idx.my-domain.com`|
 | params.liCollectConfig |Optional| Object |Container of all collector params.||
@@ -148,6 +209,12 @@ NOTE: For optimal performance, the LiveIntent ID sub-module should be called at
 | params.liCollectConfig.fpiExpirationDays |Optional| Number |The expiration time of an identifier created and updated by LiveConnect. By default, 730 days.|`729`|
 | params.liCollectConfig.collectorUrl |Optional| String |The parameter defines where the signal pixels are pointing to. The params and paths will be defined subsequently. If the parameter is not set, LiveConnect will by default emit the signal towards `https://rp.liadm.com`.| `https://rp.liadm.com`|
 | params.liCollectConfig.appId |Optional| String |LiveIntent's media business entity application ID.|`a-0012`|
+| params.sharedId.name | Optional | String | The parameter is cookie/localstorage key name | `'__super_duper_cookie'`|
+| params.sharedId.strategy | Optional | String | The parameter defines where to get the identifier from. Either from the cookie jar, `'cookie'`, or from the local storage, `'localstorage'`. | `'localstorage'`|
+| storage | Required | Object | This object defines where and for how long the results of the call to get a user ID will be stored. | |
+| storage.type | Required | String | This parameter defines where the resolved user ID will be stored (either `'cookie'` or `'html5'` localstorage).| `'cookie'` |
+| storage.name | Required | String | The name of the cookie or html5 localstorage where the resolved user ID will be stored. | `'pbjs_li_nonid'` |
+| storage.expires | Recommended | Integer | How long (in days) the user ID information will be stored. The recommended value is `1` | `1` |
 
 ## LiveIntent ID examples
 
@@ -202,6 +269,10 @@ NOTE: For optimal performance, the LiveIntent ID sub-module should be called at
               fpiExpirationDays: 730,
               collectorUrl: "https://rp.liadm.com",
               appId: "a-0012"
+            },
+            sharedId: {
+              strategy: "cookie"
+              name: "foobar"
             }
           }
         }]