Difference between revisions of "ATC/Current/SDK/Web tracking API"
(Published) |
(Published) |
||
Line 3: | Line 3: | ||
|DisplayName=Web Tracking API | |DisplayName=Web Tracking API | ||
|TocName=Web Tracking API | |TocName=Web Tracking API | ||
− | |Context=Learn how to track | + | |Context=Learn how to track visitor activity using an API. |
|ComingSoon=No | |ComingSoon=No | ||
|Platform=PureConnect, GenesysCloud, GenesysEngage-cloud | |Platform=PureConnect, GenesysCloud, GenesysEngage-cloud | ||
Line 9: | Line 9: | ||
|sectionHeading=About the Web Tracking API | |sectionHeading=About the Web Tracking API | ||
|alignment=Vertical | |alignment=Vertical | ||
− | |structuredtext=The Web Tracking API lets you track what visitors do on your website. Tracking data is collected through a series of interactions occurring on your website such as pageviews, button clicks, and custom events. These interactions are grouped into visits and act as a container for the actions | + | |structuredtext=The Web Tracking API lets you track what visitors do on your website. Tracking data is collected through a series of interactions occurring on your website such as pageviews, button clicks, and custom events. These interactions are grouped into visits and act as a container for the actions that a specific visitor takes on your website. |
− | Visits do not have a predefined duration. Depending on your visitor, the visit may be a few seconds or a couple of hours long. A new visit | + | Visits do not have a predefined duration. Depending on your visitor, the visit may be a few seconds or a couple of hours long. A new visit is created when the visitor has been idle for 30 minutes or more, but they all are linked to the same visitor. |
|Status=No | |Status=No | ||
}}{{Section | }}{{Section | ||
Line 17: | Line 17: | ||
|anchor=ObtainConsent | |anchor=ObtainConsent | ||
|alignment=Vertical | |alignment=Vertical | ||
− | |structuredtext={{NoteFormat|To | + | |structuredtext={{NoteFormat|To achieve compliance with GDPR requirements, consider whether you need to obtain a visitor's consent before tracking their data. For more information on using {{MintyDocsProduct}} in a GDPR-compliant manner, see {{#mintydocs_link:topic=GDPR|manual=AdminGuide|version=Current|link text=GDPR.}}|1}} |
− | + | To implement tracking after receiving consent, modify the tracking snippet so that the <tt>`ac('init')`</tt> and <tt>`ac('pageview')`</tt> are only called when consent is given, as shown in the following example: | |
− | To implement tracking after receiving consent, modify the tracking snippet so that the <tt>`ac('init')`</tt> and <tt>`ac('pageview')`</tt> are only called | ||
<source lang="javascript"> | <source lang="javascript"> | ||
Line 42: | Line 41: | ||
|Status=No | |Status=No | ||
}}{{Section | }}{{Section | ||
− | |sectionHeading=Stop tracking | + | |sectionHeading=Stop tracking when a visitor revokes consent |
|anchor=StopTracking | |anchor=StopTracking | ||
|alignment=Vertical | |alignment=Vertical | ||
Line 55: | Line 54: | ||
|anchor=CollectionMethods | |anchor=CollectionMethods | ||
|alignment=Vertical | |alignment=Vertical | ||
− | |structuredtext=The Journey JavaScript SDK lets you customize how you collect tracking data for your website. The most basic form of tracking is page view tracking. For page view tracking, {{MINTYDOCSPRODUCT}} records each page a visitor visits. You can also use the Journey JavaScript SDK to record custom visitor activities such as button clicks. For more information see | + | |structuredtext=The Journey JavaScript SDK lets you customize how you collect tracking data for your website. The most basic form of tracking is page view tracking. For page view tracking, {{MINTYDOCSPRODUCT}} records each page a visitor visits. You can also use the Journey JavaScript SDK to record custom visitor activities such as button clicks. For more information see {{Link-SomewhereInThisVersion|manual=SDK|topic=Web_tracking_API|anchor=record|display text=Track custom events}}. |
|Status=No | |Status=No | ||
}}{{Section | }}{{Section | ||
− | |sectionHeading=Track pages | + | |sectionHeading=Track viewed pages |
|alignment=Vertical | |alignment=Vertical | ||
− | |structuredtext=The <tt>pageview</tt> method tracks the | + | |structuredtext=The <tt>pageview</tt> method tracks the webpages that your visitors view. To send a <tt>pageview</tt>, call the <tt>ac</tt> function and pass <tt>pageview</tt> as the first argument. |
<source lang="javascript"> | <source lang="javascript"> | ||
ac('pageview'); | ac('pageview'); | ||
Line 69: | Line 68: | ||
|anchor=record | |anchor=record | ||
|alignment=Vertical | |alignment=Vertical | ||
− | |structuredtext=The <tt>record</tt> method allows you to track custom events, usually as a result of a person interacting with an element or control in your website | + | |structuredtext=The <tt>record</tt> method allows you to track custom events, usually as a result of a person interacting with an element or control in your website. For example, the click of a button. |
+ | |||
The <tt>record</tt> method takes two parameters: | The <tt>record</tt> method takes two parameters: | ||
− | *The name of the event to record as a string. '''Note:''' See | + | *The name of the event to record as a string. '''Note:''' See {{Link-SomewhereInThisVersion|manual=SDK|topic=Web_tracking_API|anchor=Guidelines|display text=Guidelines for custom event names}}. |
*An (optional) key-value hash of properties for the event. | *An (optional) key-value hash of properties for the event. | ||
− | *An (optional) callback function that | + | *An (optional) callback function that invokes when the request is completed. |
− | *An (optional) callback timeout, in milliseconds, to configure how long to wait | + | *An (optional) callback timeout, in milliseconds, to configure how long to wait when the event takes too long to complete. This option is useful to capture events (such as file downloads) before navigating to a different page/URL, ensuring that the visitor is always redirected. |
<source lang="javascript"> | <source lang="javascript"> | ||
Line 81: | Line 81: | ||
</source> | </source> | ||
− | You | + | You can also provide extra metadata with your custom event: |
<source lang="javascript"> | <source lang="javascript"> | ||
ac('record', 'button_clicked', { | ac('record', 'button_clicked', { | ||
Line 89: | Line 89: | ||
</source> | </source> | ||
− | The following code sample shows how to record a file | + | The following code sample shows how to record a file download and navigate to the file <tt>URL /files/pricing.pdf</tt> when capturing the event, or after 400 milliseconds: |
<source lang="javascript"> | <source lang="javascript"> | ||
ac('record', 'file.downloaded', { | ac('record', 'file.downloaded', { | ||
Line 101: | Line 101: | ||
}}{{Section | }}{{Section | ||
|sectionHeading=Guidelines for custom event names | |sectionHeading=Guidelines for custom event names | ||
+ | |anchor=Guidelines | ||
|alignment=Vertical | |alignment=Vertical | ||
− | |structuredtext={{NoteFormat|Event names | + | |structuredtext={{NoteFormat|Event names cannot exceed 255 characters. You can use any combination of lowercase alphanumeric characters and an underscore. Keep event names short and descriptive. |1}} |
The suggested format for custom event names is: ''<tt>object-delimiter-action</tt>'', where object is the object that was interacted with, and action is the type of interaction that occurred. | The suggested format for custom event names is: ''<tt>object-delimiter-action</tt>'', where object is the object that was interacted with, and action is the type of interaction that occurred. | ||
Revision as of 16:00, December 17, 2020
Contents
Learn how to track visitor activity using an API.
About the Web Tracking API
The Web Tracking API lets you track what visitors do on your website. Tracking data is collected through a series of interactions occurring on your website such as pageviews, button clicks, and custom events. These interactions are grouped into visits and act as a container for the actions that a specific visitor takes on your website.
Visits do not have a predefined duration. Depending on your visitor, the visit may be a few seconds or a couple of hours long. A new visit is created when the visitor has been idle for 30 minutes or more, but they all are linked to the same visitor.
Obtain consent before tracking visitors
To implement tracking after receiving consent, modify the tracking snippet so that the `ac('init')` and `ac('pageview')` are only called when consent is given, as shown in the following example:
(function(a,t,c,l,o,u,d){a['_genesysJourneySdk']=o;a[o]=a[o]||function(){
(a[o].q=a[o].q||[]).push(arguments)},a[o].l=1*new Date();u=t.createElement(c),
d=t.getElementsByTagName(c)[0];u.async=1;u.src=l;u.charset='utf-8';d.parentNode.insertBefore(u,d)
})(window, document, 'script', 'https://apps.inindca.com/journey/sdk/js/web/v1/ac.js', 'ac');
if (consentGiven) {
// Call the ac('init') function to enable tracking
ac('init', 'a061a3fe-7a80-4b50-9d3b-df88c0f9efad', { region: 'use1' });
ac('pageview');
}
You are responsible for setting the value for the `consentGiven` variable based on the visitor's choice.
Enable web tracking
To enable Web tracking on your website, initialize the Tracking SDK and then call the pageview method when a visitor navigates to a new page.
Stop tracking when a visitor revokes consent
If a visitor revokes consent at any point, invoke the destroy command to stop tracking and remove all cookies, as shown in the following example.
// to disable tracking and delete Genesys Predictive Engagement cookies
ac('destroy');
Types of tracked data
The Journey JavaScript SDK lets you customize how you collect tracking data for your website. The most basic form of tracking is page view tracking. For page view tracking, Genesys Predictive Engagement records each page a visitor visits. You can also use the Journey JavaScript SDK to record custom visitor activities such as button clicks. For more information see Track custom events.
Track viewed pages
The pageview method tracks the webpages that your visitors view. To send a pageview, call the ac function and pass pageview as the first argument.
ac('pageview');
Track custom events
The record method allows you to track custom events, usually as a result of a person interacting with an element or control in your website. For example, the click of a button.
The record method takes two parameters:
- The name of the event to record as a string. Note: See Guidelines for custom event names.
- An (optional) key-value hash of properties for the event.
- An (optional) callback function that invokes when the request is completed.
- An (optional) callback timeout, in milliseconds, to configure how long to wait when the event takes too long to complete. This option is useful to capture events (such as file downloads) before navigating to a different page/URL, ensuring that the visitor is always redirected.
ac('record', 'section_opened');
You can also provide extra metadata with your custom event:
ac('record', 'button_clicked', {
companyName: 'Acme Inc,',
employees: '100-500'
});
The following code sample shows how to record a file download and navigate to the file URL /files/pricing.pdf when capturing the event, or after 400 milliseconds:
ac('record', 'file.downloaded', {
name: 'Pricing',
fileType: 'pdf'
}, function () {
navigateTo('/files/pricing.pdf');
}, 400);
Guidelines for custom event names
The suggested format for custom event names is: object-delimiter-action, where object is the object that was interacted with, and action is the type of interaction that occurred.
Examples of custom event names include:
- "detected_errors"
- "section_failed"
- "section_submitted"
- "product_added"
- "product_removed"
- "address_selected"