Consistent test-integration init of new WIAPI for easier testing of code. Improve documentation for getUrlParams function.

Author: jschulte

source/includes/_debugging.md

@@ -4,7 +4,7 @@
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   API.subscribe('page-load-v1', function (ev) {
     if (ev.payload.searchPage) {
       API.log('My integration has loaded and this is a search results page.');

source/includes/_events.md

@@ -177,7 +177,7 @@ To receive data for events, you must opt-in to event subscriptions. Each event i
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   API.subscribe('page-load-v1', function(ev) {
     API.log(ev);
   });
@@ -200,7 +200,7 @@ The page load event is useful to determine the context of the current page. By m
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   API.subscribe('dealership-info-v1', function(ev) {
     API.log(ev);
   });
@@ -223,7 +223,7 @@ The dealership info event is useful if you need to know the name and address of
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   API.subscribe('vehicle-shown-v1', function(ev) {
     API.log(ev);
   });
@@ -247,7 +247,7 @@ On a vehicle deals page, a single event is fired because you are viewing a singl
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   API.subscribe('vehicle-data-updated-v1', function(data) {
     API.log(data.payload.pageData); // Outputs the Page Data object to the console.
     API.log(data.payload.vehicleData); // Outputs the updated Vehicle Data object to the console.

source/includes/_locations.md

@@ -10,7 +10,7 @@ See the <a href="#ddc-api-insert-key-name-callback-elem-meta">insert documentati
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   API.insert('vehicle-media', function(elem, meta) {
     // This element is positioned below the vehicle image area on vehicle search pages.
   });
@@ -21,7 +21,7 @@ See the <a href="#ddc-api-insert-key-name-callback-elem-meta">insert documentati
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   API.subscribe('page-load-v1', function(ev) {
     if (ev.payload.searchPage) {
       API.insert('vehicle-media', function(elem, meta) {
@@ -49,7 +49,7 @@ This element is positioned below the vehicle image area on vehicle search pages.
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   API.insert('vehicle-badge', function(elem, meta) {
     // This element is positioned below the vehicle tech specs area on vehicle search and detail pages.
   });
@@ -60,7 +60,7 @@ This element is positioned below the vehicle image area on vehicle search pages.
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   API.subscribe('page-load-v1', function(ev) {
     if (ev.payload.searchPage || ev.payload.detailPage) {
       API.insert('vehicle-badge', function(elem, meta) {
@@ -94,7 +94,7 @@ This element is positioned below the vehicle tech specs area on vehicle search a
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   API.insert('vehicle-pricing', function(elem, meta) {
     // This element is positioned below the vehicle pricing area on vehicle search and detail pages.
   });
@@ -105,7 +105,7 @@ This element is positioned below the vehicle tech specs area on vehicle search a
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   API.subscribe('page-load-v1', function(ev) {
     // Only execute the code on search results and vehicle details pages.
     if (ev.payload.searchPage || ev.payload.detailPage) {
@@ -133,7 +133,7 @@ This element is positioned below the vehicle pricing area on vehicle search and
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   API.insert('vehicle-media-container', function(elem, meta) {
     // This element is the media gallery container on vehicle deals pages.
     // Injecting into this location will replace the media gallery with the elements you insert.
@@ -145,7 +145,7 @@ This element is positioned below the vehicle pricing area on vehicle search and
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   API.subscribe('page-load-v1', function(ev) {
     if (ev.payload.detailPage) {
       API.insert('vehicle-media-container', function(elem, meta) {
@@ -167,7 +167,7 @@ This element is the media gallery container on vehicle deals pages. Injecting in
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   API.insert('primary-banner', function(elem, meta) {
     // This element is typically positioned in a prominent location above the vehicle listings on the Search Results Page.
     // On the Details page, it is near the top of the vehicle information, below the media gallery.
@@ -179,7 +179,7 @@ This element is the media gallery container on vehicle deals pages. Injecting in
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   API.subscribe('page-load-v1', function(ev) {
     if (ev.payload.searchPage || ev.payload.detailPage) {
       API.insert('primary-banner', function(elem, meta) {

source/includes/_methods.md

@@ -6,7 +6,7 @@
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   API.subscribe('event-name-and-version', function(event) {
     API.log(event);
   });
@@ -162,7 +162,7 @@ Field Name | Purpose | Field Format
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   API.insert('location-name', function(elem, meta) {
     API.log(elem); // The DOM element where markup may be inserted.
     API.log(meta); // The payload object for the current insertion point.
@@ -182,7 +182,7 @@ This acts as an event subscription, so as the application displays new vehicles
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   API.insertOnce('location-name', function(elem, meta) {
     API.log(elem); // The DOM element where markup may be inserted.
     API.log(meta); // The payload object for the current insertion point.
@@ -247,7 +247,7 @@ Field Name | Purpose | Field Format
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   var button = API.create('button', {
     text: 'Visit Google',
     src: 'https://www.google.com/',
@@ -272,7 +272,7 @@ Currently only the "button" type is supported, however other types will soon be
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   API.append(targetEl, appendEl);
 })(window.DDC.API);
 ```
@@ -281,7 +281,7 @@ Currently only the "button" type is supported, however other types will soon be
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   API.insert('target-location-name', function(elem, meta) {
     var lowPrice = Math.round(meta.finalPrice - 1000);
     var highPrice = Math.round(meta.finalPrice + 1000);
@@ -307,7 +307,7 @@ When calling the insert method, the goal is to insert some markup into a locatio
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   // Loads a JavaScript file
   API.loadJS('https://www.company.com/script.js')
     .then(function() {
@@ -324,7 +324,7 @@ The loadJS method is a simple way to include additional JavaScript files require
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   // Loads a CSS stylesheet
   API.loadCSS('https://www.company.com/integration.css')
     .then(function() {

source/includes/_requirements.md

@@ -41,7 +41,7 @@ Your code should be minimal and perform only actions necessary to bootstrap your
 
 ```javascript
 (function(WIAPI) {
-	var API = new WIAPI();
+	var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
 	// API.subscribe(...);
 	// Your code here
 })(window.DDC.API);

source/includes/_samples.md

@@ -12,7 +12,7 @@ document.body.style.overflow = 'hidden';
 function sendResizeMessage() {
   window.parent.postMessage({
     type: 'IFRAME_HEIGHT_RESIZE',
-    target: 'growing-iframe',
+    target: 'test-integration-iframe', // Note: Replace 'test-integration-frame' with your actual iframe identifier.
     frameHeight: document.body.offsetHeight + 10 /* a little extra for good measure */
   }, '*');
 }
@@ -35,12 +35,12 @@ if (window.ResizeObserver) {
 
 ```javascript
 (function (WIAPI) {
-  API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
 
   API.insert('content', function (elem, meta) {
     var iframeElem = document.createElement('iframe');
     iframeElem.src = 'https://www.yourdomain.com/path-to-iframe.htm';
-    iframeElem.classList.add('my-integration-name-iframe');
+    iframeElem.classList.add('test-integration-iframe'); // Note: Replace 'test-integration-frame' with your actual iframe identifier.
     API.append(elem, iframeElem);
   });
 
@@ -66,7 +66,7 @@ if (window.ResizeObserver) {
 
 An integration may want to insert an iframe that resizes as its contents change. One possible way to accomplish this is for the iframe and the integration to work together as shown in the sample code from the pane on the right side of this page. You can see the sample code running [here](https://webapitestddc.cms.dealer.com/growing-iframe-example.htm).
 
-### iframe Responsibilities:
+### IFrame Responsibilities:
 
 * **Determine when content dimensions change** - One way to do this is using [`ResizeObserver`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver). `ResizeObserver` is not supported in IE11, so one possible solution is to fallback to polling. Polling is not ideal, but it will work for this small percentage of our traffic.
 * **Communicate the new dimension to the outer page** - iframes can communicate with the parent page using [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage).

source/includes/_utilities.md

@@ -8,7 +8,7 @@ In addition to the event based system for working with sites, some utility metho
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   API.subscribe('vehicle-data-updated-v1', function(data) {
 
     API.log(data.payload.pageData); // Logs the Page Data object
@@ -36,7 +36,7 @@ This can be used to obtain an array of attributes for the currently displayed ve
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI('test-integration');
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier to obtain the correct configuration data.
   var testConfig = {
     dealerId: "12345",
     showOnSRP: true,
@@ -60,7 +60,7 @@ This fetches a JavaScript object of your integration's configuration for the cur
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   API.utils.getDealerData().then(function(dealerData) {
     // Logs the Dealership Info Event object for the current website.
     API.log(dealerData);
@@ -76,7 +76,7 @@ This fetches the <a href="#dealership-info-event">Dealership Info Event object</
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   API.utils.getJwtForVehicles().then(function(jwtObject) {
     API.log(jwtObject);
     // Returns a data structure like this:
@@ -96,7 +96,7 @@ This fetches an object containing the array of VINs on the current page and a co
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   API.utils.getPageData().then(function(pageData) {
     // Outputs the Page Data Object for the current page.
     API.log(pageData);
@@ -108,15 +108,29 @@ This fetches the <a href="#page-event">Page Event object</a> for the current web
 
 ## API.utils.getUrlParams()
 
-NOTE: This method does not return a promise as the URL Params are immediately available and do not require Promise behavior.
+NOTE: This method returns immediately, not as a Promise, because the URL Params are already available and do not require asynchronous behavior.
+
+Running this function at a URL such as this:
+
+[https://www.roimotors.com/?query=This%20is%20the%20query&hello=world&foo=bar](https://www.roimotors.com/?query=This%20is%20the%20query&hello=world&foo=bar)
+
+Will return the following object:
+
+```{
+  query: "This is the query",
+  hello: "world",
+  foo: "bar"
+}```
+
 
 > Usage:
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
-  var urlParams = API.utils.getUrlParams();
-  API.log(urlParams); // Logs the configuration object for your integration (if there is one).
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
+  var urlParams = API.utils.getUrlParams(); // Returns the current URL parameters as object attributes, so you can easily access the values.
+  API.log(urlParams); // Log the entire object.
+  API.log(urlParams.query); // Access just the `query` parameter, for example.
 })(window.DDC.API);
 ```
 
@@ -126,7 +140,7 @@ NOTE: This method does not return a promise as the URL Params are immediately av
 
 ```javascript
 (function(WIAPI) {
-  var API = new WIAPI();
+  var API = new WIAPI('test-integration'); // Note: Replace 'test-integration' with your actual integration identifier.
   var config = API.utils.getVehicleData().then(function(vehicleData) {
     // Outputs the current set of vehicle data.
     API.log(vehicleData);