PrerequisitesBefore you begin, you need a P3chat Account and a basic understanding of HTML and JavaScript. If you're new to JavaScript, MDN's JavaScript wiki has a lot of information, including links to tutorials and a Guide.Usage notesWidget API is enabled automatically by using new style of P3chat snippet, that users embed into web pages during P3chat set up.The default snippet should be obtained from P3chat Dashboard > Departments page. It looks the following:<script id="p3-snippet"> var p3chat = p3chat || []; p3chat.push(['_setAccount', 'xxxxxxxxx']); p3chat.push(['_trackPage']); (function (d, t, id) { if (d.getElementById(id)) return; var e = d.createElement(t), s = d.getElementsByTagName(t)[0]; e.src = "//p3chat.com/dist/p3.js"; e.id = id; s.parentNode.insertBefore(e, s); }(document, 'script', 'p3chat-snippet'));</script>Note: not-highlighted part should be left as-is; it is responsible for loading main P3chat script onto the page. The part highlighted in grey is the 'API part' and can be modified according to API specification that follows.Warn: incomplete copy-paste or mistake in the snippet may result in failure to load P3chat script and thus non-functional widget.Method call formatMethod calls are different form conventional object.methodName(param) format.This is due to asynchronous nature of P3chat loader script (p3.js). While async is good for performance, it produces a problem - it is not possible to know when object.methodName is available. Method Queue pattern is used to address this issue and that's why method calls have their distinctive look:var p3chat = p3chat || [];p3chat.push(['_methodName', param1, param2]);Here we create a global array (if not created before) and push values into it. Each value is a new array that represents a single API call. First item of the array must be a method name and all other items are (optionally) passed to the given method as parameters. This way, when p3.js is loaded, it accesses a global p3chat variable and unwinds array to call methods and pass data to them.The same pattern is used in many modern JavaScript API (Google Analytics and Facebook SDK to name a few). To know more about this and other patterns read the following awesome article.Methods_setAccount (departmentID) [required]Description: Enables P3chat functionality on the page. Sets the route for visitor activities (page views, chat initiations, etc.) - only operators assigned to the department, having passed ID, will see these activities. Should be called once per page load.Warn: P3chat widget will not function properly if this method is not called on a page or wrong ID is passed.Parameters:departmentID (string, required) - ID of department, should be obtained from Dashboard>Departments page.Example:p3chat.push(['_setAccount', 'xxxxxxxxx']);_trackPage ([pageURL, pageTitle]) [optional, but typically needed]Description: Triggers the page view activity thus allowing Rich Web Client operators to see the visitor and Automatic Rules to be evaluated. Visitor will be invisible to operators and Automatic Rules if the method is not called. Note: user will still be able to initiate the conversation and it will be properly routed to available operator. May be called several times during user session.Parameters: pageURL (string, optional) - Names the page URL that user is visiting. Defaults to window.location.pathname if not passed. The URL should not contain domain part. See window.location documentation for exact format specification. Note: Automatic Rules will be evaluated against this URL if passed and operators will see this URL in Web Client console.pageTitle (string, optional) - Names the title of the page (for Web Client console). Defaults to document.title if not passed.Examples:p3chat.push(['_trackPage']);p3chat.push(['_trackPage', '/cart/item/iphone', 'My Title']);p3chat.push(['_trackPage', '/cart/item/iphone' /*default title*/]);p3chat.push(['_trackPage', undefined /*default URL*/, 'My Title']);Typical usage scenarios:Widget is used on Single Page web site. That is, pages are not loaded from server every time user navigates a link. Instead, JavaScript on page generates new view and updates location in address bar. To not miss user navigation on such web sites, call this method every time location changes.Do not track certain visitors. For example, if Rules should not fire for certain visitor (say, company worker), write a conditional JavaScript that omits _trackPage call when they visit a page (e.g. by cookie).Do not track specific pages. For example, if Rules should not fire on a specific page (say, order page, it's not desired to distract visitor on it), write a conditional JavaScript that omits _trackPage call after checking page URL.URLs of the site are long and hardly readable or hard to write Rules for. Pass the URL that suites your needs or better readable in Rich Web Client console.
