help!
Knotch Unit API

Wanna see it in action? Click here to see a live example of the Knotch Unit API.

#The knotch-ignore HTML Attribute

The knotch-ignore attribute can be put on a placeholder <div>, such that a Knotch Measurement Unit will not be injected into the page until explicitly enabled by the publisher. Enablement is done using either Knotch.addUnit() or Knotch.setFocus().

For example, consider the below HTML document. It illustrates how the <div> element is given a knotch-ignore attribute: 

<!DOCTYPE html>
<html>
  <head>
    <title>Example Publisher Page</title>

    <!-- Page assets included here... !-->
  </head>
  <body>
    <!-- Normal page content here... !-->

    <div knotch-ignore="true" name="disabled unit" class="knotch_1"></div>

    <!-- Normal page content continues... !-->

    <script src="https://www.knotch-cdn.com/unit/latest/knotch.js"></script>
  </body>
</html>

The corresponding Knotch Measurement Unit with ID 1 will not be injected on page load. The Unit will not appear on the page, and no data will be collected.

#Knotch.addUnit()

Syntax

Knotch.addUnit(unitId)

Parameters

Attribute(s) Description Type Required
id The Knotch ID of the unit that will be added String Yes

Usage

Upon enablement, the knotch-ignore flag is removed from the container with corresponding ID, and a Knotch Unit is injected.

In the HTML below, our script will addUnit() to the Knotch Unit with ID 1 after two seconds. 

<!DOCTYPE html>
<html>
  <head>
    <title>Example Publisher Page</title>
  </head>
  <body>
    <div knotch-ignore name="Unit 1" class="knotch_1"></div>

    <script src="https://www.knotch-cdn.com/unit/latest/knotch.js"></script>
    <script>
      setTimeout(function(){ Knotch.addUnit(1); }, 2000);
    </script>
  </body>
</html>

Once the two seconds have lapsed, our HTML will look like this: 

<!DOCTYPE html>
<html>
  <head>
    <title>Example Publisher Page</title>
  </head>
  <body>
    <!-- Our unit with ID 1 is now added !-->
    <div name="Unit 1" class="knotch_1">
        <!-- Knotch Unit iframe -->
    </div>

    <script src="https://www.knotch-cdn.com/unit/latest/knotch.js"></script>
    <script>
      setTimeout(function(){ Knotch.addUnit(1); }, 2000);
    </script>
  </body>
</html>

#Knotch.removeUnit()

Syntax

Knotch.removeUnit(unitId)

Parameters

Attribute(s) Description Type Required
id The Knotch ID of the unit that will be removed String Yes

Usage

Upon removal, the corresponding unit is un-injected from the page, adding a knotch-ignore flag to the placeholder container.

In the HTML below, our script will remove the Knotch unit with ID 1 after two seconds. 

<!DOCTYPE html>
<html>
  <head>
    <title>Example Publisher Page</title>
  </head>
  <body>
    <div name="Unit 1" class="knotch_1">
        <!-- Knotch Unit iframe & data -->
    </div>

    <script src="https://www.knotch-cdn.com/unit/latest/knotch.js"></script>
    <script>
      setTimeout(function(){ Knotch.removeUnit(1); }, 2000);
    </script>
  </body>
</html>

Once the two seconds have lapsed, our HTML will look like this: 

<!DOCTYPE html>
<html>
  <head>
    <title>Example Publisher Page</title>
  </head>
  <body>
    <!-- Our unit with ID 1 is now disabled and the unit itself is removed -->
    <div knotch-ignore name="Unit 1" class="knotch_1"></div>

    <script src="https://www.knotch-cdn.com/unit/latest/knotch.js"></script>
    <script>
      setTimeout(function(){ Knotch.removeUnit(1); }, 2000);
    </script>
  </body>
</html>

#Knotch.setFocus()

Syntax

Knotch.setFocus(unitId)

Parameters

Attribute(s) Description Type Required
id The Knotch ID of the unit that will be added. All other units on the page will be removed. String Yes

Usage

First, make sure to add the attribute knotch-ignore='true' to any placeholders that we don't want to be enabled on page load.

In the HTML below, the script will setFocus() to the Knotch Unit with ID 2 after ten seconds, disabling the other Units on the page. 

<!DOCTYPE html>
<html>
  <head>
    <title>Example Publisher Page</title>
  </head>
  <body>
    <div name="Unit 1" class="knotch_1">
        <!-- Knotch Unit iframe -->
    </div>

    <div knotch-ignore name="Unit 2" class="knotch_2"></div>

    <script src="https://www.knotch-cdn.com/unit/latest/knotch.js"></script>
    <script>
      setTimeout(function(){ Knotch.setFocus(2); }, 10000);
    </script>
  </body>
</html>

Once ten seconds have passed, our HTML will look like this: 

<!DOCTYPE html>
<html>
  <head>
    <title>Example Publisher Page</title>
  </head>
  <body>
    <!-- Our unit with ID 1 is now disabled !-->
    <div knotch-ignore name="Unit 1" class="knotch_1"></div>

    <!-- Our unit with ID 2 is now enabled !-->
    <div name="Unit 2" class="knotch_2">
        <!-- Knotch Unit iframe -->
    </div>

    <script src="https://www.knotch-cdn.com/unit/latest/knotch.js"></script>
    <script>
      setTimeout(function(){ Knotch.setFocus(2); }, 10000);
    </script>
  </body>
</html>

#Knotch.enableUnit()

Syntax

Knotch.enableUnit(unitId)

Parameters

Attribute(s) Description Type Required
id The Knotch ID of the unit that will be enabled String Yes

Usage

Upon enablement, a Unit will re-display, and continue tracking data where it left off.

In the HTML below, our script will enableUnit() to the Knotch Unit with ID 1 after two seconds. 

<!DOCTYPE html>
<html>
  <head>
    <title>Example Publisher Page</title>
  </head>
  <body>
    <div name="Unit 1" class="knotch_1" style="{ hidden: true }">
        <!-- Knotch Unit iframe -->
    </div>

    <script src="https://www.knotch-cdn.com/unit/latest/knotch.js"></script>
    <script>
      setTimeout(function(){ Knotch.enableUnit(1); }, 2000);
    </script>
  </body>
</html>

Once the two seconds have lapsed, our HTML will look like this: 

<!DOCTYPE html>
<html>
  <head>
    <title>Example Publisher Page</title>
  </head>
  <body>
    <!-- Our unit with ID 1 is now enabled !-->
    <div name="Unit 1" class="knotch_1">
        <!-- Knotch Unit iframe -->
    </div>

    <script src="https://www.knotch-cdn.com/unit/latest/knotch.js"></script>
    <script>
      setTimeout(function(){ Knotch.enableUnit(1); }, 2000);
    </script>
  </body>
</html>

#Knotch.disableUnit()

Syntax

Knotch.disableUnit(unitId)

Parameters

Attribute(s) Description Type Required
id The Knotch ID of the unit that will be disabled String Yes

Usage

Upon being disabled, a Unit will hide itself from the page a pause all data collection.

In the HTML below, our script disabled the Knotch Unit with ID 1 after two seconds. 

<!DOCTYPE html>
<html>
  <head>
    <title>Example Publisher Page</title>
  </head>
  <body>
    <div name="Unit 1" class="knotch_1">
        <!-- Knotch Unit iframe & data -->
    </div>

    <script src="https://www.knotch-cdn.com/unit/latest/knotch.js"></script>
    <script>
      setTimeout(function(){ Knotch.disableUnit(1); }, 2000);
    </script>
  </body>
</html>

Once the two seconds have lapsed, our HTML will look like this: 

<!DOCTYPE html>
<html>
  <head>
    <title>Example Publisher Page</title>
  </head>
  <body>
    <!-- Our unit with ID 1 is now disabled and the unit itself disappears -->
    <div knotch-ignore name="Unit 1" class="knotch_1"></div>

    <script src="https://www.knotch-cdn.com/unit/latest/knotch.js"></script>
    <script>
      setTimeout(function(){ Knotch.disableUnit(1); }, 2000);
    </script>
  </body>
</html>