Introduction

Welcome to Askem documentation. Here you'll find:

How to install Askem on your site
How to integrate it with your existing web marketing and analytics stack.

Install guides

There are two ways to install Askem on any content management system.

Please note that either one installation method is sufficient for your CMS.

Embed code installation
Google Tag Manager installation

Requirements

Whitelist your domain(s) and get your API key

For Askem to work, you need to whitelist your domain at app.askem.com.
Ensure you have whitelisted your production domain correctly to enable data collection.
You'll find your API Key on the same page. In the case of multiple content sections, you can switch between content sections (and API keys) by using the dropdown menu on the top bar.

Notice: For test purposes you can list your domain as a test domain. In that case the tool gets rendered on your test environment, but no data gets saved.

Allow us to see, where the requests are coming from

We need to know where the requests from your site are coming from. The more detailed the information is, the better we can help you analyze the data. We use the following methods to define the source of the requests:

A <link rel="canonical"> tag on the page to mark the canonical url of the page. This is required to save the data related to the page and avoid duplicate data.
A Referer header matching with whitelisted domain needs to be sent with all requests to Askem. This is usually the default behaviour, but strict Referrer-Policy settings will block this. This is the preferred way for us to detect where the requests are coming from. This is also used to analyze traffic sources.

Embed code install

Place this snippet exactly where you want the plugin to be shown.

<div class="askem"></div>
<script type="text/javascript">
  (function() {
    window.askem = {
      settings: {
        apiKey: 'abcdefgh12345678'
      }
    };
    var s = document.createElement('script');
    s.src = 'https://cdn.askem.com/plugin/askem.js';

    document.body.appendChild(s);
  }());
</script>

Make sure to replace abcdefgh12345678 with your API key.

You can place the embed code to your page templates on any content management system. Here's how it works.

Basic embed code

Plugin settings (window.askem.settings)

Property	Required	Type	Description	Default
apiKey	yes	String	API Key that was created upon the registration.
canonicalUrl	no	String	Canonical url of the page or post.	By default the plugin uses the value of `<link ref="canonical">` element. The default value can be overdriven by this property. If no link element or property is not provided, the url of the page is used instead.

To make the analytics dashboard more useful, you can embed more metadata.

Single-page apps

The embed code instantiates the buttons on load automatically. In single page apps, buttons must be updated on page change by calling window.askem.reset() function.

Reset the buttons

window.askem.reset();

The function does the following:

Sets the reading time for the previous page
Sets the referrer of the next page to match the previous page
Reloads the buttons
Sends a page load event for the next page

Update manually set metadata and reset the buttons

window.askem.settings.categories = ['New category'];
window.askem.reset();

If you have manually set any page related metadata in window.askem.settings, you have to update them before calling the reset function.

Showing the tool only on selected pages

The most robust way to show the buttons on specific pages is to add the embed code to selected page templates. However it is not always a possible solution.

Another way to select the pages is by adding conditions to the installation code. Common way to choose the pages is based on their url path. Our recommended way to is to use Regular Expressions for that.

For example load the plugin on pages when the url includes /article/ or /blog/.

<div class="askem"></div>
<script type="text/javascript">
  (function() {
    var urlPattern = new RegExp('/(article|blog)/');
    var urlPath = window.location.pathname;
    if (urlPath.match(urlPattern)) {
      window.askem = {
        settings: {
          apiKey: 'abcdefgh12345678'
        }
      };
      var s = document.createElement('script');
      s.src = 'https://cdn.askem.com/plugin/askem.js';
      document.body.appendChild(s);
    }
  }());
</script>

Google Tag Manager install

Google Tag Manager installation works the same as using the embed code, with one caveat: you'll have to manually specify where the buttons will be shown.

1. Select the element where you want the buttons to be shown

The buttons will be embedded to the bottom of the element you specify. Check the id or the class of the div element and place it inside the querySelector. Type .class if you're using a class, or #id if using an id.

2. Log in to your Google Tag Manager account and click "Add new tag"

Install reaction buttons with Google Tag Manager - step 2

3. Click the "Choose a tag type to begin setup..." icon

Install reaction buttons with Google Tag Manager - step 3

4. From the "Choose tag type" menu, select "Custom HTML"

Install reaction buttons with Google Tag Manager - step 4

<script type="text/javascript">
  (function() {
    var container = document.querySelector('id-or-class');
    if (container) {
      var div = document.createElement('div');
      div.setAttribute('class','askem');
      container.appendChild(div);
      window.askem = {
        settings: {
          apiKey: 'abcdefgh12345678'
        }
      };
      var s = document.createElement('script');
      s.src = 'https://cdn.askem.com/plugin/askem.js';
      document.body.appendChild(s);
    }
  }());
</script>

Make sure to replace abcdefgh12345678 with your API key and id-or-class with your element selector.

5. In the Tag Configuration HTML field, paste the script on the right

Make sure to replace abcdefgh12345678 with your API key and id-or-class with your element selector. Give the tag a name.

Install reaction buttons with Google Tag Manager - step 5

6. Click "Choose a trigger to make this tag fire..." to set your trigger

Install reaction buttons with Google Tag Manager - step 6

7. Click the plus icon to create a new trigger

Install reaction buttons with Google Tag Manager - step 7

8. Select "Page view"

Install reaction buttons with Google Tag Manager - step 8

9. Select when the tools is loaded

You can either load the tool on all pages, but it is often recommended to specify the pages where the tool should be loaded.

Install reaction buttons with Google Tag Manager - step 8

Refer to Google's full guide to triggers for more information.

10. Click "Save" in the trigger settings and in the tag settings

11. Click "Preview" or "Submit"

If you're feeling confident, you can click "Submit" and the reaction buttons should now be visible on your site. You can also click "Preview" and the changes will be visible only to you. Remember to click "Submit" when you want to publish the changes.

Install reaction buttons with Google Tag Manager - step 7

And that's it, done!

Add metadata

Additional metadata can be embedded in the code as seen below.

<div class="askem"></div>
<script type="text/javascript">
  (function() {
    window.askem = {
      settings: {
        apiKey: 'askem-test-123',
        title: 'Testing Askem buttons',
        canonicalUrl: 'https://askem.com/example',
        author: 'Test Author',
        date: '2022-09-22T08:00:34.282Z',
        categories: ['testing', 'categories'],
        postId: 'ab1234',
        contentUpdated: '2023-10-10T12:00:34.282Z',
      }
    };

    var s = document.createElement('script');
    s.src = 'https://cdn.askem.com/plugin/askem.js';

    document.body.appendChild(s);
  }());
</script>

Make sure to replace the example values with real values. Values are often easily exported from the CMS or they could be fetch from the page with JavaScript.

Plugin settings

Property	Required	Type	Description	Default
canonicalUrl	no	String	Canonical url of the page or post.	By default the plugin uses the value of `<link ref="canonical">` element. The default can be overridden with this property.
title	no	String	Title of the page or post.	Defaults to the value of supported metadata, if it exists. If neither metadata or title property exist, the title of the page is used instead.
author	no	String	Name of the author of the page or post.	Defaults to supported metadata value.
date	no	String or Number	ISO 8601 datetime string or Unix timestamp Type in milliseconds.	Defaults to the value of supported metadata if it exists.
categories	no	[String]	Categories of the page or post	Defaults to the value of supported metadata if it exists.
postId	no	String	Custom ID to identify the post/page instead of URL. The use of this is recommended, if the URL is likely to be changed over time.
contentUpdated	no	String or Number	ISO 8601 datetime string or Unix timestamp Type in milliseconds.

Default fonts

Example for disabling the default fonts

<div class="askem"></div>
<script type="text/javascript">
  (function() {
    window.askem = {
      settings: {
        apiKey: 'abcdefgh12345678',
        disableFonts: true
      }
    };
    var s = document.createElement('script');
    s.src = 'https://cdn.askem.com/plugin/askem.js';

    document.body.appendChild(s);
  }());
</script>

By default we use a third-party font, Open Sans. Open Sans is part of our default look. The font is licenced with an open source licence and font files are hosted on our own CDN.

Following settings can be used to disable these fonts to be loaded.

Property	Required	Type	Description	Default
disableFonts	no	Boolean	Flag for disabling fonts	false

Supported metadata formats

Schema.org (JSON-LD)

<head>
  ...
  <script type="application/ld+json">
    {
      "@context": "http://schema.org",
      "@type": "NewsArticle", // this can vary
      "headline": "The Test Article",
      "articleSection": "Blog",
      "datePublished": "2020-02-14T14:18:17+02:00",
      "image": "https://example.com/thumbnail.png",
      "author": {
        "@type": "Person",
        "name": "Article Author",
      },
    }
  </script>
  ...
</head>

Schema.org and Open Graph are protocols for presenting metadata in machine-readable form. They are used by Facebook, Linkedin and many other social platforms. Metadata is presented with <script> or <meta> tags within the <head> section of an HTML document (see examples to the right).

If present, metadata in these formats will be automatically parsed in the following order (first found is used).

1. Schema.org tags (JSON-LD, Microdata or RDFa format)

Schema.org (Microdata)

<head>
  ...
  <meta itemprop="headline" content="The Test Article" />
  <meta itemprop="articleSection" content="Blog" />
  <meta itemprop="datePublished" content="2020-02-14T14:18:17+02:00" />
  <meta itemprop="image" content="http://localhost/schema-microdata.gif" />
  <meta itemprop="author" content="Article Author" />
  ...
</head>

Schema.org (RDFa)

<head>
  ...
  <meta property="headline" content="The Test Article" />
  <meta property="articleSection" content="Blog" />
  <meta property="datePublished" content="2020-02-14T14:18:17+02:00" />
  <meta property="image" content="http://localhost/schema-microdata.gif" />
  <meta property="author" content="Article Author" />
  ...
</head>

Askem supports the following Schema.org tags:

Property	Metadata	Type
author	Author of the page or article	Text or Schema.org author property
articleSection	Category of the content	Text
datePublished	Publish date and time of a page or article	ISO 8601 datetime string
headline	Title of the page or article	Text
image	Thumbnail image for the content. This is used in our reports.	Url

2. Open Graph tags

Open Graph

<head>
  ...
  <meta property="og:title" content="The Test Article" />
  <meta property="og:url" content="https://www.example.com/canonical-url/of-page" />
  <meta property="og:image" content="https://example.com/thumbnail.png" />
  <meta property="article:published_time" content="2019-09-18T13:16:44Z" />
  <meta property="article:section" content="News" />
  <meta property="article:author" content="Article Author" />
  ...
</head>

Make sure to replace the example values with real values. Most Content Management Systems (CMS) also have easy-to-use plugins to automatically add Schema.org/Open Graph tags.

Askem supports the following Open Graph tags:

Property	Metadata	Type
article:author	Author of the page or article	Text
article:section	Category of the content	Text
article:published_time	Publish date and time of a page or article	ISO 8601 datetime string
og:title	Title of the page or article	Text
og:image	Thumbnail image for the content. This is used in our reports.	Url
og:url	Canonical URL of the page or article	Url

Integrations

Matomo / Piwik Pro

Askem can be set up to send reaction and feedback send button clicks as events to Matomo or Piwik Pro. Either tool should be installed on the site as Askem only pushes custom events to command queue as instructed in the documentation of both tools:

Reaction button click event

Reaction button clicks are sent as a custom event with following properties:

Example of data pushed to command queue:

  _paq.push(['trackEvent', 'Askem', 'Reaction', 'Like']);

Property	Description	Value
Event category	Name of the tool	"Askem"
Event action	Whether a reaction is clicked on or off	"Reaction" or "Unreaction"
Event name	Given reaction	e.g. "Like"
Event value	Not used	undefined
Custom dimension (Piwik Pro only)	Not used	undefined

Feedback send button click event

Feedback send button clicks are sent as a custom event with following properties:

Example of data pushed to command queue:

  _paq.push(['trackEvent', 'Askem', 'Feedback sent']);

Property	Description	Value
Event category	Name of the tool	"Askem"
Event action	Declare feedback being sent	"Feedback sent"
Event name	Not used	undefined
Event value	Not used	undefined
Custom dimension (Piwik Pro only)	Not used	undefined

Customization

Custom styling

The look of Askem plugin can be customized with CSS similarly as a regular webpage. Use the provided template as a starting point for your customizations. You can add the custom style declarations to your website's style sheets.

The most important selectors are listed here:

/*
  Askem CSS Style Guide
*/
/* General styles */
.askem-plugin {
  /* You can add your general and the Askem wrapper styling here, such as font-family. */
}
.askem-plugin .askem-header {
  /* This affects all headers in the plugin */
}

/* Reaction button */
.askem-plugin .askem-reactions-group .askem-reaction-button {
  /* Add reaction button styles here. */
}

/* Label */
.askem-plugin .askem-reactions-group .askem-reaction-button .askem-label {
  /* Add reaction button label text styles here. */
}

/* For hover/active styles, just add :hover after .askem-reaction-button */
/* For selected button styles, add .selected to .askem-reaction (e.g. .askem-plugin .askem-reactions-group .askem-reaction.selected .askem-reaction-button) */

/* Feedback form */
/* Textarea */
.askem-plugin .askem-inputs .askem-input-field {
  /* Add textarea styles here. */
}
/* Disclaimer text */
.askem-plugin .askem-inputs .askem-input-disclaimer {
  /* Add disclaimer text styles here */
}

/* Submit button */
.askem-plugin .askem-inputs .askem-input-submit {
  /* Add feedback form submit button styles here. */
}

Disclaimer

We do not recommend using Javascript to manually change the behaviour of the plugin. It will most likely cause compatibility issues and can lead to corrupted analytics data. If you are about to change the behaviour, ask us first.

Support

Tell us your wishes

We are interested to hear your specific needs as our development is driven by them. If you have some specific needs for customization, please don't hesitate to contact us at support@askem.com

Troubleshooting

Askem tool is not showed on the page

Make sure all the requirements ar met. Usually either the domain is not whitelisted correctly or there are no Referer header or canonical url available.

Askem tool is shown on the page, but no data gets saved

This is usually because your domain has been whitelisted as a test domain. With test domain the tool is shown for demo purposes, but no data is saved.

Data from a single page generates duplicate entries

Make sure all the requirements ar met. We identify unique pages based on canonical urls. Without correctly formatted canonical url, we cannot reliably know if multiple urls point to the same page.