Site Monitors

Intro to Site Monitors

Tenon's Site Monitor feature allows customers to quickly and easily test their entire site simply by placing a small snippet of JavaScript code on their site, similar to adding Google Analytics to your site. Simply add our JavaScript snippet and the testing is automatic. It is important to be careful, though, as this can eat up your API calls pretty quickly. Read the directions below to understand how to make the most of your SiteMonitor.

How Monitors Work

Tenon's Site Monitors are the single easiest way to do the following:

  • Test your entire website. Site Monitors will test every page on which our JavaScript snippet appears.
  • Verify new pages are tested as soon as they're added. If new content is added to the site, and the JavaScript snippet appears on the page (or the template that holds it) then the new pages will be tested as soon as they appear on the site
  • Re-test pages that have changed. You can set the Site Monitor to test pages whenever they're changed.
  • Test behind a login.

Monitor Flow

Here's a high level description of how Tenon Site Monitors ensure they can effectively test, even behind a login.

  1. With the Tenon Site Monitor snippet added to your page, whenever the page is viewed, it will attempt to test that page
  2. The Site Monitor sends the URL over to an internal service to "ping" the URL
  3. If the ping returns HTTP status code of 200, the URL is sent to Tenon's Test API
  4. If the ping returns HTTP status code of 401, the page source is assembled as a payload and sent to Tenon's Test API

A number of additional parameters can be used to dictate how & when testing is done, for instance testing only pages that are new, etc.

Security and Privacy

It is very important that you understand the Security and Privacy implications of using Site Monitors for testing behind a login, especially on production systems. You should review our Privacy and Security documentation before continuing.

Security

Tenon site monitors will send a request to the Tenon API for any web page the Site Monitor code exists on. This includes pages behind a login and even pages behind a firewall or VPN. If the viewing computer can access the outside world, the payload will be sent. You should never put the Site Monitor code on a site intended to hold sensitive information.

Privacy

All traffic to & from Tenon's service is handled over SSL. We store certain portions of test results, but you can turn this storage off in your project settings. Regardless, you should ensure that the Site Monitor snippet is not used on any page that displays Personally Identifiable Information (PII).

Set it up on Tenon's side

To set up your Site Monitor, log in to Tenon and go to "Settings" and then "Site Monitors". The following form will appear:

Screenshot of the Add Site Monitor Page

Understanding Site Monitor Settings

  • Name: This is the name for your monitor. Make it something that you'll remember easily.
  • URL for the Site: This is the URL for the site you're monitoring. This is not used for testing but rather to remind you specifically what site (or, even part of a site) you're testing.
  • Project to track results: Select a project for the monitor to log its results into. Generally it is a good idea to set up a unique project just for the Site Monitor.
  • Test Only New Pages? Answer "Yes" if you want the monitor to only test pages that it has never seen before. This will have the effect of testing the entire site as soon as the monitor is installed, and then every new page as soon as the pages are added to the site. Caution: this works on the page URLs, so it will not ignore URL query string parameters. Equivalent to onlyNew in the JavaScript configuration object
  • Hash Selector: Site Monitors will "hash" a page in order to determine whether a page is unique and/ or if a page it has seen before has changed since last test. Unfortunately a lot of things can cause a page's hash to change. This parameter allows you to dictate what determines how we decide "uniqueness". This can take anything you'd put into querySelectorAll(). Generally, you want to avoid including content that changes or updates based on JavaScript, especially session tokens and A/B testing. Equivalent to hashFrom in the JavaScript configuration object
  • How long (in seconds) should we wait before re-testing a page? Allows you to set a total number of seconds between tests of the same page, even if that page has changed since the last time we've seen it. Equivalent to interval in the JavaScript configuration object
  • Inline Assets? Equivalent to inline in the JavaScript configuration object

Use extreme caution! if you do not provide sensible values in the above fields or in the JavaScript configuration object, your Site Monitor will quickly gobble up API calls. Some ideas to get the most power from Site Monitors:

  1. Select "Yes" for the option to Test Only New Pages. Wait a day or so for testing to occur. Then, aggressively go through the issues that Tenon has logged and fix them. Delete your original project & monitor. Set up a new project & new monitor to find issues that are introduced by maintenance and new content additions
  2. Do not say "Yes" to Inlining Assets on a production site. While this is extremely useful for testing behind a login or behind a VPN, the inlining process uses the visitor's CPU. This will slow down the performance of your site.
  3. There are 86400 seconds in a day. To do regularly scheduled testing, multiply 86400 by the number of days between each test run and enter that as the value for "How long (in seconds) should we wait before re-testing a page?" Hint: 604800 is 1 week, 2592000 is 1 month.
Screenshot of Site Monitor list and code example described below

When the Site Monitor list is shown it will now include a list of your monitors as well as a code sample you can use to cut and paste into your site. The code sample will look like this:

<script>
    window.tenonSiteMonitor = {
        siteKey: 'yLl2zSAMIrDs'
    }
</script>
<script src='https://www.tenon.io/api/monitor.js'></script>

Install the Site Monitor code snippet

To install the Site Monitor code, simply add the code snippet to your website, right before the closing body tag.

Testing your Site Monitor

When you install the Site Monitor snippet on a page, each time the page is viewed in a browser, it will return an appropriate HTTP response as well as a JSON response body to reflect the status of the request.

  1. 200
  2. 202Reset Content. This means that the onlyNew parameter was set to true and that this page is not new so it will not be tested.
  3. 205Reset Content. This means that the onlyNew parameter was set to true and that this page is not new so it will not be tested.
  4. 304Not Modified. This means that the page has not been modified since the last time it wast tested or that the interval time between tests has not expired, so the page will not be tested.
  5. 400Bad Request. The submission to the Site Monitor was either missing an important parameter (i.e. siteKey) or a parameter supplied was invalid.
  6. 401Unauthorized. The submission is not authorized (typically when the user-agent string resembles a bot) or the siteKey is invalid.
  7. 402Payment Required. This means that you do not have any more API calls available and must either upgrade or buy boosts.
  8. 403Forbidden. This response is only returned if you are using an enterprise version of Tenon and the administrator of your instance has turned off the ability to use Site Monitors
  9. 500Internal Server Error. This means there is something wrong on our side.

Configuring the monitor via JavaScript

All of the site monitor's configurations can be overridden on your side when implementing the snippet. This is a great way to override the settings of your monitor to do something unique per-page or per-section. There is no need to use these settings unless you want to override the options you chose when you first created your Site Monitor

  • onlyNew: Takes a boolean value. Allows you to tell the Site Monitor that you only want to test new pages that it has never seen. This has the highest level of precedence. If you set this to true it will never test the same page twice. By default this is set to false
  • hashFrom: Takes a string value. As described above, Site Monitors will "hash" a page in order to determine whether a page is unique and/ or if it has changed. Unfortunately a lot of things can cause a page's hash has change. This parameter allows you to dictate what determines how we decide "uniqueness". This can take anything you'd put into querySelectorAll(). Generally, you want to avoid including content that changes or updates based on JavaScript, especially session tokens and A/B testing.
  • interval: Takes an integer value. Allows you to set a total number of seconds between tests of the same page, even if that page has changed since the last time we've seen it.
  • inline: Takes an boolean value. If set to true, it will "inline" all page assets and send them as part of the payload to be tested.
  • src: Takes a string value. You can completely override the URL from the site monitor and instead give the monitor the exact source code to be tested. This is an excellent way to test only a specific portion of the page.
  • fragment: Takes a boolean value. Set this to true when sending over src if you source you have set is only part of a page.
  • docID: Takes a string value. Allows you to set a specific docID on the request. This value should be unique to every page you test and follows the requirements as described at Understanding Request Parameters
  • instance: Takes a string value. For customers on a Private Instance, it allows you to set the value to the hostname of your instance. There is no need to set this unless your Private Instance is within the same network of your tested page(s)

Examples

Only test pages once a month (30 days * 24 hours * 60 minutes * 60 seconds):

<script>
    window.tenonSiteMonitor = {
        siteKey: 'yLl2zSAMIrDs',
        interval: 2592000
    }
</script>

Determine "uniqueness" based on a has of the div element with an ID of 'container':

<script>
    window.tenonSiteMonitor = {
        siteKey: 'yLl2zSAMIrDs',
        hashFrom: #container
    }
</script>

Only test new pages:

<script>
    window.tenonSiteMonitor = {
        siteKey: 'yLl2zSAMIrDs',
        onlyNew: true
    }
</script>

Benefits and Use Cases for the Site Monitors

By far the biggest benefit to using Site Monitors is to be able to test all pages of your site, regardless of whether they're new or whether they require a login to view. Tenon's Site Monitor checks to see if our test API can access the page. If not, it tests the document source instead. In other words, there's no need for any sort of custom integration or fancy Selenium scripting to log in and test authenticated areas. Tenon's Site Monitors allow you to test everything.

The second really powerful benefit is in being able to monitor the accessibility of new content. If your site has a lot of different people adding new content on a regular basis, you can set it up to test new content as soon as it is added to the site, ensuring that you're on top of accessibility issues as soon as they happen.

Contact us with questions