Create Id-Library.md

dev-docs/modules/idLibrary.md

@@ -0,0 +1,94 @@
+---
+layout: page_v2
+page_type: module
+title: ID Library
+description: ID Graphing Adapter
+module_code : currency
+display_name : ID Library
+enable_download : true
+sidebarType : 1
+Maintainer: eng-dmp@magnite.com
+
+---
+
+
+# ID Library
+{:.no_toc}
+
+The ID Library module gathers and generates a map of identities present on the page.  The primary usecase for this adapter is for Publishers who have included multiple UserId subadapters in their prebid.js implementation, and want to store the resulting user ids serverside for modeling or graphing purposes.  The ID Library module, anchors the response of `refreshUserIds()` to a presistant identifier (md5 encrypted) and returns an map of uids.  This map of uids comes in the form of a POST message in JSON format and must be output to a publisher configured endpoint. 
+
+The module attempts to extract a persistant identifier in the following ways:
+
+1. From a publisher defined target element
+2. Searches for HTML input (text/email) element
+3. Searches entire document for email using regex
+
+To get started, add the module to your Prebid.js wrapper. From the command line:
+
+{: .alert.alert-info :}
+gulp build --modules=idLibrary
+
+
+## Application Flow
+
+In the idLibrary module, the persistant id is fetched from the page and synced with the user ids as follows:
+
+1. Check for a valid 'idLibrary' configuration
+1. If the configuration defines `target`, get the HTML element with the named id
+   1. If a valid ID entry (e.g. email) exists in the target element, we're good, go on to step 5.
+   1. Otherwise if no valid value is found, add a listener on the element
+       1. Once the listener finds a valid value, go on to step 5.
+1. Else, scan the values of all text and email input elements on the page. If one of them has a valid persistent ID value, we found it. Go on to step 5.
+1. Else, scan the whole body tag for a valid persistent ID value. If one is found go on to step 5.
+1. If a valid persistent ID value has been found, then MD5 hash it, combine it with user IDs from the user ID module and POST to the specified endpoint.
+
+
+## Configuration:
+
+{: .table .table-bordered .table-striped }
+| Param  | Required | Description |
+| --- | --- | --- |
+| url | yes | The url endpoint is used to post the MD5 hasheds|
+| target | no | Contains the element id from which the presistant value is to be read.|
+| debounce | no | Time in milliseconds the module will wait before searching for the presistant value and user ids|
+| fullscan | no | Allows the publisher to turn off the full page scan |
+
+Please note, A full scan (Step 4 above) of the body element is configured on by default but can be disabled by setting `"fullscan: false"`
+
+## Example
+
+```javascript
+ pbjs.setConfig({
+    idLibrary:{
+        url: 'url',
+        target: 'username',
+	debounce: 250
+    }
+});
+```
+
+### Post data format
+
+After the data is collected, it will be POSTed to the configured URL in this format:
+
+```json
+{
+  "hid": "MD5 hash",
+  "uids": "user ids array"
+}
+```
+
+```json
+{
+	"hid":"5dd72a98c8146bafa84313fc15eb27c2",
+	"uids":
+	{
+		"id5id":"ID5-ZHMOQ7afBOa_gZxzTSelo5KFcVwCQgM7d-BUkWtjAA",
+		"sharedid":
+			{
+				"id":"01EE77EKRHXEZVJYMSQVRJ9536",
+				"third":"01EE77EKRHXEZVJYMSQVRJ9536"
+			}
+	}
+}
+```

dev-docs/modules/index.md

@@ -39,6 +39,7 @@ If you are looking for bidder adapter parameters, see [Bidders' Params]({{site.b
 | [**Advanced Size Mapping**](/dev-docs/modules/sizeMappingV2.html) | Display Responsive AdUnits in demanding page environments. |
 | [**Price Floors Module**](/dev-docs/modules/floors.html) | Configure and enforce minimum bids. |
 | [**GPT Pre-Auction Module**](/dev-docs/modules/gpt-pre-auction.html) | Adds a PB Ad Slot and matching GAM ad unit name to each ad unit's first-party data before bid requests are sent to the adapters. |
+| [**ID Library**](/dev-docs/modules/idLibrary.html) | Retrieve user ids deployed on your site, and return them to a configurable endpoint for ID Graphing |  
 
 ## Video Modules