Documentation

Date: 23rd September 2017
Version number: 1.0

Frequently Asked Questions

What is Witness.ly?

Witness.ly is a new tool that reveals the behaviour of your website users. Instead of classical static heatmaps Witness.ly shows detailed second-by-second heatmap animation of user activity.

Get instant feedback on users' attention and take action immediately.

Will Witness.ly slow down my site?

Witness.ly script will only have almost negligible effect on your site's speed and performance. We take all the necessary steps in ensuring fast deliverability of our service on your sites with as little impact as possible:

  1. The script is loaded asynchronously. This means that the Witness.ly script does not stop your site from loading its own assets and therefore visitor's experience is not jeopardized.

  2. The script is small. The gziped version of Witness.ly script size is under 12kB, unzipped under 32kB. Note that most browsers support gziped content encoding.

  3. The script is served through a Content Distribution Network (CDN). Our script is served to your visitors from a system of strategically positioned servers around the world, not just from a single location. This allows the script to be loaded faster by your visitors while offering much better availability. We use Cloudflare, the largest CDN in the world with 120 data centers strategically positioned around the world.

Is my data safe?

Your data and users' recordings are safe with Witness.ly. There are a number of measures we take to ensure you are the only person who can access your site data and that your visitors' privacy is respected.

Data storage

All data Witness.ly collects is stored electronically in Frankfurt am Main, Germany, Europe. Data is stored on the Linode infrastructure. Datacenter operation is compliant with Germany’s Federal Data Protection Act (a.k.a., Bundesdatenschutzgesetz or BDSG).

The database containing visitor and usage data is only accessible from the application servers and no outside sources are allowed to connect to the database.

Does Witness.ly work on both http and https?

Witnessl.ly script works on sites with http and https protocol. Note that for security reasons witness.ly script itself is always loaded over the https protocol. To protect privacy of visitors of your sites user's session recordings is also transfered over https protocol only.

Does Witness.ly work on single-page apps, intranet sites, or password protected sites?

Witness.ly works on single-page apps, intranet sites, or password protected sites. No special settings are required for using Witness.ly script on any page. Witness.ly script will automatical transfer page and its assets to our servers. This works even for password protected sites or intranet sites.

If your site uses Content Security Policies (CSP) you need to update your CSP before installing Witness.ly script on your site. Instructions for updating CSP are available here.

How to install Witness.ly?

  1. Create FREE acount at witnessl.ly

  2. Include witness recording snippet from your witness account to your sites. Instructions for installing Witness.ly on specific platform are available here.

Can I install Witness.ly on multiple domains

Yes. The same Witness.ly recording snippet works on multiple domains.

Accounts

Adding and removing sites

You can add unlimited number of sites to your account. Instructions for installing Wintess code are to your sites are available here.

How to use Witness.ly for my clients?

Clients must install your witness recording snippet to their sites.

  1. Login to your Witness.ly account (or Signup for a free Witness.ly account).

  2. Copy Witness.ly tracking code from the Witness.ly dashboard.

  3. Send Witness.ly tracking code to your client.

  4. Ask your client to install tracking code to their website. Instructions for installation of Witness.ly tracking code are available here.

Change Account Owner

  1. Login to your Witness.ly account.

  2. Send us change owner request via Witnessly dashboard contact form.

  3. We'll verify the request and transfer account to new owner.

Deleting Your Account

  1. Login to your Witness.ly account.

  2. Send us change delete account request via Witnessly dashboard contact form.

  3. We'll verify the request and delete your account and all your data.

Billing

Witnessl.ly Service Plans

Overview of Witness.ly service plans are available here.

Free trials are also available. Please Signup for a free Witness.ly account and try Witness.ly for a month (no credit card is required).

Upgrading / Downgrading Your Witness.ly Plan

  1. Login to your Witness.ly account.

  2. Select new plan by in the dashboard. You'll be charged pro rata for the remaining time left in your current billing cycle.

Updating Invoice details (address, VAT number)

  1. Login to your Witness.ly account.

  2. Click on the Billing option in the menu at the left-hand side of the Dashboard.

  3. Update your invoice details.

Invoices

To browse all your invoices:

  1. Login to your Witness.ly account.

  2. Click on the Invoices button in the dashboard.

Payment Methods

We support the following payment methods:

  1. Amex (American Express)

  2. Diners

  3. Discover

  4. JCB

  5. Mastercard

  6. Maestro

  7. PayPal

  8. UnionPay

  9. Visa

Technical Information

Will Witness.ly slow down my site?

Witness.ly script, will only have almost negligible effect on your site's speed and performance. We take all the necessary steps in ensuring fast deliverability of our service on your sites with as little impact as possible:

  1. The script is loaded asynchronously. This means that the Witness.ly script does not stop your site from loading its own assets and therefore visitor's experience is not jeopardized.

  2. The script is small. The gziped version of Witness.ly script size is under 12kB, unzipped under 32kB. Note that most browsers support gziped content encoding.

  3. The script is served through a Content Distribution Network (CDN). Our script is served to your visitors from a system of strategically positioned servers around the world, not just from a single location. This allows the script to be loaded faster by your visitors while offering much better availability. We use Cloudflare, the largest CDN in the world with 120 data centers strategically positioned around the world.

Could Witness.ly affect my site's performance?

As every JavaScript code you add to your site has some effect to your site performance we cannot assure you that your site will not be affected in any way; howevwer, the Witness.ly script has been designed to have a minimal effect on your site performance.

Witness.ly usage tracking is performed by the following actions:

  • At regular intervals (20 times per second), cursor, touch, and scroll position is recorded. Recordings are queued at client, minimized, and sent to our server every 5 seconds.

  • Changes to the page's HTML and CSS are captured using the MutationObserver API which is built-in into every modern browser. MutationObserver is efficient as changes of HTML are batched and API events are triggered only after change to HTML page is alredy performed. Note that for older browsers (e.g. IE9) less efficient MutationObserver pollyfill must be used. MutationObserver polyfill scans HTML changes every 30 milliseconds.

Is my data safe?

Your data and users' recordings are safe with Witness.ly. There are a number of measures we take to ensure you are the only person who can access your site data and that your visitors' privacy is respected.

Data storage

All data Witness.ly collects is stored electronically in Frankfurt am Main, Germany, Europe. Data is stored on the Linode infrastructure. Datacenter operation is compliant with Germany’s Federal Data Protection Act (a.k.a., Bundesdatenschutzgesetz or BDSG).

The database containing visitor and usage data is only accessible from the application servers and no outside sources are allowed to connect to the database.

Visitor privacy

Witness.ly collects no “Personally Identifying Information” (or “PII”) from your visitors.

Does Witness.ly work on both http and https?

Witnessl.ly script works on sites with http and https protocol. Note that for security reasons witness.ly script itself is always loaded over the https protocol. To protect privacy of visitors of your sites user's session recordings is also transfered over https protocol only.

Does Witness.ly work on single-page apps, intranet sites, or password protected sites?

Witness.ly works on single-page apps, intranet sites, or password protected sites. No special settings are required for using Witness.ly script on any page.

Witness.ly Tracking Code

Witness.ly Tracking Code is a single line of HTML code you need to copy to your webpage. You can copy it anywhere on the page (even if you accidently copy tracking on the same page multiple times there is no problem with that).

We generally recommend putting the Tracking Code inside the <head> area of your site. It will still work if you place the Tracking Code elsewhere but your visitor recordings may be less accurate since recorder may not be able to capture the initial mouse movements and actions.

Your tracking code will look like this:

<script defer data-witness-id="xxxx" src="https://witness.ly/recorder.js"></script>

You just need to replace "xxxx" in the snippet above with your own Witness.ly owner id. Login to your Witness.ly account (or Signup for a free Witness.ly account). and copy owner id from the Witness.ly Dasboard.

Installing Witness.ly on multiple domains

The same Witness.ly recording snippet works on multiple domains.

Witness.ly Cookies

Witness.ly recording script set no cookies on the client sites.

List of cookies used at this site (https://witness.ly) is available here.

Witness.ly Requests

After installing the Witness.ly tracking script at your site your visitor's browser loads Witness.ly script located at https://witness.ly/recorder.js. The script make the following requests for tracking user's behaviour:

  • https://witnes.ly/session-upload this requests uploads session recording data to our servers,

  • https://witness.ly/xdomain_cookie.html this requests checks if end user has opted-out from using Witness.ly services,

  • https://witness.ly/blacklist/XXX_YYY.js this requests checks the site owner with id XXX has disabled Witness.ly services for hostname YYY.

Browser Support

Witness.ly supports the following browsers:

  • IE9+

  • Firefox 19+

  • Chrome 28+

  • Chrome (Android)44+

  • Android Browser 40+

  • Safari 6+

  • iOS Safari 8+

  • Opera 18+

Content Security Policies

Content Security Policies (CSP) are delivered as a header to your users' browser by your web-server. CSP declare which dynamic resources are allowed to load on your page.

If you are using a default CSP please add the following rules to your default-src rules:

  • script-src https://witness.ly 'unsafe-eval'

  • connect-src https://*.witness.ly.com:*

  • frame-src https://*.witness.ly.com:*

  • child-src https://*.witness.ly.com:*

  • img-src https://*.witness.ly.com:*

  • font-src https://*.witness.ly.com:*

  • style-src 'unsafe-inline'

Data Retention

Data retention timeframes for Witness.ly service plans:

  • Basic: 1 month

  • Standard: 3 months

  • Pro: 6 months

  • Enterprise: 12 months

Installing Witness.ly

Manual installation

  1. Login to your Witness.ly account (or Signup for a free Witness.ly account). Copy the Witness.ly tracking code from the Witness.ly dashboard.

  2. Copy the code from the Witness.ly dashboard to evey page of your Site.

We generally recommend putting the Tracking Code inside the <head> area of your site. It will still work if you place the Tracking Code elsewhere but your visitor recordings may be less accurate since recorder may not be able to capture the initial mouse movements and actions.

BigCommerce

  1. Login to your Witness.ly account (or Signup for a free Witness.ly account). Copy the Witness.ly tracking code from the Witness.ly dashboard.

  2. Log in to your BigCommerce account, and open your admin panel.

  3. Select “Store Setup” on the admin panel.

  4. Select “Design”.

  5. Select the “Edit HTML/CSS” button in the center of the page.

  6. Once in the HTML editor, select “HTMLHead.html” in the section titled “Panels in Template”. If you’re using a custom theme, it’s possible that HTMLHead.HTML is not the name of the file where the Witness.ly snippet should be pasted. Check with your theme’s developer to verify.

  7. Paste the Witness.ly code snippet (from Step 1) into the <head> of the theme.

Google Tag Manager

  1. Login to your Witnes.ly account (or Signup for a free Witness.ly account). Copy the Witness.ly tracking code from the Witness.ly dashboard.

  2. Login to Google Tag Manager.

  3. Inside the container that is connected to your website, select the “Custom HTML Tag” tag type option to place 3rd party scripts into the container.

  4. Paste the Witness.ly code snippet (from Step 1) into the HTML text box.

  5. Check the "Support document.write" checkbox below the HTML text box.

  6. Define when the rule will “fire” by clicking on Firing Rules [+Add] button and change the rule as needed. By default, Witness.ly should fire on all pages so there are no pages or events that are accidentally omitted from user sessions.

  7. Once saved, the Witness.ly JavaScript will be loaded on any page where the Google Tag Manager (GTM) container script is installed.

Hubspot

  1. Login to your Witnes.ly account (or Signup for a free Witness.ly account). Copy the Witness.ly tracking code from the Witness.ly dashboard.

  2. Go to the “Content Settings” section of Hubspot.

  3. Go to the “Page Publishing” section.

  4. Paste the Witness.ly code snippet from Step 1.

Instapage

  1. Login to your Witnes.ly account (or Signup for a free Witness.ly account). Copy the Witness.ly tracking code from the Witness.ly dashboard.

  2. Login to Instapages and open your landing page.

  3. Click on “Settings” from your edit screen.

  4. Click on the “JavaScript” button.

  5. Paste the Witness.ly code snippet from Step 1 into the “Header”.

Joomla

  1. Login to your Witnes.ly account (or Signup for a free Witness.ly account). Copy the Witness.ly tracking code from the Witness.ly dashboard.

  2. Log into the Joomla Administration panel.

  3. Click on the “Template Manager” link.

  4. Click the “Templates” tab.

  5. Locate the template your site is using, then click on its title.

  6. Click the “Edit main page template” link.

  7. Locate the </head> closing tag and insert your Witness.ly tracking code from Step 1 above it.

  8. Click the “Save & Close” button.

LightCMS

  1. Login to your Witnes.ly account (or Signup for a free Witness.ly account). Copy the Witness.ly tracking code from the Witness.ly dashboard.

  2. Log into your LightCMS website.

  3. Go to your “Content” page

  4. Click on the Page Settings cogwheel on the right

  5. Click the “Advanced” tab

  6. Scroll down to the “HTML head” section

  7. Paste the Witness.ly tracking code from Step 1 in this field.

  8. Click “Save my changes” at the bottom

Magento

  1. Login to your Witnes.ly account (or Signup for a free Witness.ly account). Copy the Witness.ly tracking code from the Witness.ly dashboard.

  2. Log in to your Magento account, and open your admin panel.

  3. Select System > Configuration.

  4. In the panel on the left, select Design.

  5. Click to expand the HTML Head section.

  6. In the Miscellaneous Scripts text box, paste the paste your Witness.ly recording snippet form Step 1.

  7. Click the Save Config button.

Shopify

  1. Login to your Witnes.ly account (or Signup for a free Witness.ly account). Copy the Witness.ly tracking code from the Witness.ly dashboard.

  2. Log in to your Shopify account, and open your admin panel.

  3. Select “Online Store” under the “Sales Channels” section of the admin panel.

  4. On the “Themes” section of the panel, click the ellipsis button in the upper right-hand corner of the page.

  5. Click “Edit HTML/CSS”.

  6. Click “theme.liquid” under the “Layout” section.*

  7. Paste your Witness.ly recording snippet from Step 1 into the <head> of the theme.

Squarespace

  1. Login to your Witnes.ly account (or Signup for a free Witness.ly account). Copy the Witness.ly tracking code from the Witness.ly dashboard.

  2. Log in to your Squarespace account, and open your admin panel.

  3. Select “Settings”.

  4. Under the “Website” section, select “Advanced”.

  5. Click “Code Injection”.

  6. Paste your Witness.ly recording snippet form Step 1 into the text box under “Header”. Inserting the script under “Header” will record every page. If you only want to record specific pages, follow the steps in the “Per-page Code Injection” Tutorial.

Unbounce

There are two options to integrate Witness.ly with Unbounce:

A: Unbounce Script Manager (Recommended)
  1. Login to your Witnes.ly account (or Signup for a free Witness.ly account). Copy the Witness.ly tracking code from the Witness.ly dashboard.

  2. Log in to your Unbounce account, go to Settings > Script Manager.

  3. Select Custom Script, and name it (“Witness” is a good name for it).

  4. Select Add Script in the top left of the page, and paste in the Witness.ly snippet that you copied in Step 1. Be sure that you’ve selected “Head” in the Placement drop-down and where you want the script to run in the Included on drop-down (selecting “All” means that Witness.ly will run on all the pages of the domain you’ve selected). On the right-hand side of Script Manager, select the domain where you want the script to run (e.g. yourwebsite.com).

  5. Once you’ve saved your changes, you will see the number of domains and pages that the Witness.ly script is running on.

B: Javascripts
  1. Login to your Witnes.ly account (or Signup for a free Witness.ly account). Copy the Witness.ly tracking code from the Witness.ly dashboard.

  2. Log in to your Unbounce account, click the name of the page where you’d like to run Witness.ly.

  3. Select Edit on the variants where you’d like to run Witness.ly.

  4. Click Javascripts on the lower left-hand part of the Unbounce editor, and then Add New Javascript.

  5. Click Add Script to this Variant, name your script (“Witness Snippet”, for example), and paste in the snippet you copied in the Step 1. Be sure that you’ve selected “Head” in the Placement drop-down.

  6. Select Save Code.

Weebly

  1. Login to your Witnes.ly account (or Signup for a free Witness.ly account). Copy the Witness.ly tracking code from the Witness.ly dashboard.

  2. Log into your Weebly Admin Dashboard.

  3. From the top navigation bar click “Settings”.

  4. From the left Panel click on “SEO”.

  5. Paste your Witness.ly recording snippet form Step 1.

  6. Click on “Save”.

  7. Publish your site.

WordPress + WooCommerce

There are two options to integrate Witness.ly with Wordpress + Woocommerce:

A: Manually editing header.php

  1. Login to your Witnes.ly account (or Signup for a free Witness.ly account). Copy the Witness.ly tracking code from the Witness.ly dashboard.

  2. Open the WordPress installation directory.

  3. Use any text editor (Notepad, Text Edit, vim, etc.) to open header.php

  4. Search for <head> to find the starting HTML <head> tag.

  5. Paste the Witness.ly recording snippet (from Step 1) into the file immediatey after <head> tag.

  6. Save the header.php file.

B: Editing header.php with a WordPress Plugin

  1. In case you do not have Wordpress plugin that can manipulate page headers installed yet install it now.

  2. Login to your Witnes.ly account (or Signup for a free Witness.ly account). Copy the Witness.ly tracking code from the Witness.ly dashboard.

  3. Navigate to the Settings section for the Wordpress plugin from Step 1 (you'll likely need to be an Admin). The plugin settings should offer a place to paste the Witness.ly recording snippet (from Step 2) into the <head> section of your pages.

We can't promise this will always be the case, but plugins usually have a way to insert Witness.ly recording script in the header of the page.

Heatmaps

How do Witness.ly Heatmaps work?

You can use Witness.ly to generate heatmaps of any type of pages - including password protected pages and dynamically generated pages. Witness.ly works as follows:

  1. Recording script collects data from your visitors. Mouse movements, keystrokes (without the actual typed in content of the user), and page HTML code changes are tracked and uploaded on our Servers.

  2. We bulid reports and heatmaps on ours servers.

Limitations

Witness.ly works on single-page apps, dynamic content applications, intranet sites, or password protected sites. No special settings are required for using Witness.ly script on any page.