{"_id":"5697476b8560a60d00e2c262","project":"5668fab608f90021008e882f","user":"56839cf74aecbd0d00a4659e","category":{"_id":"569742bd0b09a41900b2446c","__v":9,"pages":["5697455824490c3700170a69","569747128400d52d00dd56a4","5697476b8560a60d00e2c262","569747a4c8ded91700307b92","5697489c59a6692d003fad96","56a1500244f3d80d00a2c388","56a2c51906150b0d002ad264","56b548b75f1cf00d00cc4773","56b54ae37719bb1900143093"],"project":"5668fab608f90021008e882f","version":"5668fab608f90021008e8832","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-14T06:39:57.496Z","from_sync":false,"order":6,"slug":"tuning-liftigniter-javascript","title":"Rendering,Tracking and A/B Testing Widgets (JavaScript)"},"parentDoc":null,"version":{"_id":"5668fab608f90021008e8832","__v":19,"project":"5668fab608f90021008e882f","createdAt":"2015-12-10T04:08:22.769Z","releaseDate":"2015-12-10T04:08:22.769Z","categories":["5668fab708f90021008e8833","569740f124490c3700170a64","569742b58560a60d00e2c25d","569742bd0b09a41900b2446c","569742cd69393517000c82b3","569742f459a6692d003fad8f","569743020b09a41900b2446d","5697430b69393517000c82b5","56a17776470ae00d00c30642","56a2c48a831e2a0d0069b1ad","56b535757bccae0d00e9a1cd","56e1ff6aa49fdc0e005746b5","57e1c88115bf6522002a5e4e","57fa65275ba65a17008b988f","57fbeea34002550e004c032e","58474584889b6c2d00fb86e9","58475dcc64157f0f002f1907","587e7b5158666c2700965d4e","58a349fc30852819007ba083"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.18.0","version":"1.18"},"__v":7,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-01-14T06:59:55.771Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"See our documentation of full integration with A/B testing\",\n  \"body\": \"For a big-picture overview of the entire integration, see our documentation on [full integration with A/B testing](https://liftigniter.readme.io/docs/ab-testing). The A/B testing instructions contain full code with tracking, rendering, A/B test slicing, and overwriting callbacks. After going through that code you can return to this section to better understand how tracking works.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Importance of Tracking\",\n  \"body\": \"The tracking functionality is useful for two reasons:\\n<ul>\\n<li>It allows us to report analytics for our widgets, such as click-through rate. It also allows you to use third-party analytics services such as Google Analytics to understand our recommendations.</li>\\n<li>It is essential for training our algorithms and improving our recommendation quality.</li>\\n</ul>**It is essential that you activate the tracking functionality when you push the widgets into production**, if you want to make full and proper use of LiftIgniter.\"\n}\n[/block]\nFor technical specifications of the underlying function, see our [$p(\"track\")](doc:ptrack) documentation.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"1. Tracking Widgets\"\n}\n[/block]\nWidgets can be tracked with `track` function of our SDK. Because the elements need to be ready before you can call `track`, **the track function should be called inside the callback of a `register` command**, as shown in the code snippet.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Notes on function arguments\",\n  \"body\": \"<ul><li>elements: An array of DOM elements that you want tracked. Each tracked element\\nshould be the entire DOM element corresponding to a particular recommendation. E.g. in the mustache template in the previous section, the elements would match the selector ‘#li-recommendation-unit > div.recommended_item’.</li>\\n<li>name: Name of the page area being tracked </li>\\n<li>source: Name of algorithm active during this impression. Please use ‘LI’ for LiftIgniter. </li>\\n<li>_debug: Optional, for help with testing. When true, alerts will appear for\\nvisible and click events on elements being tracked. **Please turn this off before pushing your code to production**.</li> </ul>\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$p('track', {\\n  \\t// track LI recommendations\\n\\t\\telements: document.querySelectorAll('#li-recommendation-unit > div.recommended_item'), // Change to the selector you are using in the rendered content\\n    name: 'your widget name',\\n    source: 'LI', // or base if you are tracking the base slice\\n    _debug : true  // Optional: show alerts on click or visible events. REMOVE this before pushing to production\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Example including $p('register')\\n\\n// Register calls for different widgets.\\n$p('register', {\\n\\tmax: 6, // Number of items you want to show\\n\\twidget: 'bottom-widget',\\n\\topts : {},\\n\\tcallback: function(resp) {\\n\\t\\tvar el = document.querySelector('#li-bottom-recommendation-unit');\\n\\t\\tvar template = document.querySelector('#li-bottom-recommendation-template').innerHTML;\\n\\t\\tel.innerHTML = $p('render', template, resp);\\n    console.log(\\\"Debug was set to true; disable it in production!\\\");\\n\\t\\t$p('track', {\\n\\t\\t\\telements: document.querySelectorAll('#li-bottom-recommendation-unit > div.recommended_item'), \\n      name: 'bottom-widget',\\n\\t\\t\\tsource: 'LI',\\n\\t\\t\\topts: {},\\n\\t\\t\\t_debug : true\\n\\t\\t});\\n  }\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nNote that `elements` field is the list of elements that contains the recommendation. Our tracking function identifies all the anchors within specified DOM and attaches listeners that will tell us what kind of recommendations the user have viewed, and take feedback from every click they make on them.\n\nSource is the name of the algorithm that was used to create recommendation. For A/B testing, we use default name 'LI' for LiftIgniter and 'base' for your own algorithm. Any other name will be logged to our system. But won't be rendered instantly on the board until it is registered.\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"2. Testing that the right events are triggering\"\n}\n[/block]\n* When the items being rendered first enter the viewport, you should see an alert pop up saying something like \"visible for default-widget:LI\". This means that an event was triggered telling the LiftIgniter system that the items entered the viewport.\n* If you click on any of the recommended items, you should see an alert pop up saying something like \"click for default-widget:LI\". This means that an event was triggered telling LiftIgniter that the user clicked on the recommendation. To make debugging easier, we recommend right-clicking so that you do not accidentally navigate away from the page.\n* You can see the exact events that are being sent to LiftIgniter by going to your Network Panel in Chrome Developer Tools and filtering to petametrics.com. This will include both the widget-specific events and pageview and heartbeat events. For more background, see the [Widget Events](doc:widget-events) page, which builds on some other pages in the web debugging section. \n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Troubleshooting\",\n  \"body\": \"<ul><li>If you see the alert for click but not for visible, it could be that the alert for visible is being suppressed due to other console messages. For console testing, put the tracking logic outside the callback after registering and fetching the results.</li>\\n<li>If you got the alerts for click and visible but did not see our tags in the URL after you clicked to it, this may be because your site automatically rewrites or strips off tags. This is not a problem for our tracking and training our algorithms, but it will make third-party verification of the numbers harder and means that some of the analytics we compute won’t be available.</li>\\n<li>Please call the track function on a particular element at most once! Otherwise we might record multiple counts for every actual click and other events.</li></ul>\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Turn off _debug before pushing to production!\",\n  \"body\": \"Remember to turn off the _debug: true and any other console.log statements before pushing your code to production.\"\n}\n[/block]","excerpt":"","slug":"tracking-widgets","type":"basic","title":"Tracking Widgets"}
[block:callout] { "type": "warning", "title": "See our documentation of full integration with A/B testing", "body": "For a big-picture overview of the entire integration, see our documentation on [full integration with A/B testing](https://liftigniter.readme.io/docs/ab-testing). The A/B testing instructions contain full code with tracking, rendering, A/B test slicing, and overwriting callbacks. After going through that code you can return to this section to better understand how tracking works." } [/block] [block:callout] { "type": "warning", "title": "Importance of Tracking", "body": "The tracking functionality is useful for two reasons:\n<ul>\n<li>It allows us to report analytics for our widgets, such as click-through rate. It also allows you to use third-party analytics services such as Google Analytics to understand our recommendations.</li>\n<li>It is essential for training our algorithms and improving our recommendation quality.</li>\n</ul>**It is essential that you activate the tracking functionality when you push the widgets into production**, if you want to make full and proper use of LiftIgniter." } [/block] For technical specifications of the underlying function, see our [$p("track")](doc:ptrack) documentation. [block:api-header] { "type": "basic", "title": "1. Tracking Widgets" } [/block] Widgets can be tracked with `track` function of our SDK. Because the elements need to be ready before you can call `track`, **the track function should be called inside the callback of a `register` command**, as shown in the code snippet. [block:callout] { "type": "info", "title": "Notes on function arguments", "body": "<ul><li>elements: An array of DOM elements that you want tracked. Each tracked element\nshould be the entire DOM element corresponding to a particular recommendation. E.g. in the mustache template in the previous section, the elements would match the selector ‘#li-recommendation-unit > div.recommended_item’.</li>\n<li>name: Name of the page area being tracked </li>\n<li>source: Name of algorithm active during this impression. Please use ‘LI’ for LiftIgniter. </li>\n<li>_debug: Optional, for help with testing. When true, alerts will appear for\nvisible and click events on elements being tracked. **Please turn this off before pushing your code to production**.</li> </ul>" } [/block] [block:code] { "codes": [ { "code": "$p('track', {\n \t// track LI recommendations\n\t\telements: document.querySelectorAll('#li-recommendation-unit > div.recommended_item'), // Change to the selector you are using in the rendered content\n name: 'your widget name',\n source: 'LI', // or base if you are tracking the base slice\n _debug : true // Optional: show alerts on click or visible events. REMOVE this before pushing to production\n});", "language": "javascript" } ] } [/block] [block:code] { "codes": [ { "code": "// Example including $p('register')\n\n// Register calls for different widgets.\n$p('register', {\n\tmax: 6, // Number of items you want to show\n\twidget: 'bottom-widget',\n\topts : {},\n\tcallback: function(resp) {\n\t\tvar el = document.querySelector('#li-bottom-recommendation-unit');\n\t\tvar template = document.querySelector('#li-bottom-recommendation-template').innerHTML;\n\t\tel.innerHTML = $p('render', template, resp);\n console.log(\"Debug was set to true; disable it in production!\");\n\t\t$p('track', {\n\t\t\telements: document.querySelectorAll('#li-bottom-recommendation-unit > div.recommended_item'), \n name: 'bottom-widget',\n\t\t\tsource: 'LI',\n\t\t\topts: {},\n\t\t\t_debug : true\n\t\t});\n }\n});", "language": "javascript" } ] } [/block] Note that `elements` field is the list of elements that contains the recommendation. Our tracking function identifies all the anchors within specified DOM and attaches listeners that will tell us what kind of recommendations the user have viewed, and take feedback from every click they make on them. Source is the name of the algorithm that was used to create recommendation. For A/B testing, we use default name 'LI' for LiftIgniter and 'base' for your own algorithm. Any other name will be logged to our system. But won't be rendered instantly on the board until it is registered. [block:api-header] { "type": "basic", "title": "2. Testing that the right events are triggering" } [/block] * When the items being rendered first enter the viewport, you should see an alert pop up saying something like "visible for default-widget:LI". This means that an event was triggered telling the LiftIgniter system that the items entered the viewport. * If you click on any of the recommended items, you should see an alert pop up saying something like "click for default-widget:LI". This means that an event was triggered telling LiftIgniter that the user clicked on the recommendation. To make debugging easier, we recommend right-clicking so that you do not accidentally navigate away from the page. * You can see the exact events that are being sent to LiftIgniter by going to your Network Panel in Chrome Developer Tools and filtering to petametrics.com. This will include both the widget-specific events and pageview and heartbeat events. For more background, see the [Widget Events](doc:widget-events) page, which builds on some other pages in the web debugging section. [block:callout] { "type": "danger", "title": "Troubleshooting", "body": "<ul><li>If you see the alert for click but not for visible, it could be that the alert for visible is being suppressed due to other console messages. For console testing, put the tracking logic outside the callback after registering and fetching the results.</li>\n<li>If you got the alerts for click and visible but did not see our tags in the URL after you clicked to it, this may be because your site automatically rewrites or strips off tags. This is not a problem for our tracking and training our algorithms, but it will make third-party verification of the numbers harder and means that some of the analytics we compute won’t be available.</li>\n<li>Please call the track function on a particular element at most once! Otherwise we might record multiple counts for every actual click and other events.</li></ul>" } [/block] [block:callout] { "type": "warning", "title": "Turn off _debug before pushing to production!", "body": "Remember to turn off the _debug: true and any other console.log statements before pushing your code to production." } [/block]