Embedding a Zendesk widget in your MadCap Flare top navigation output

July 20, 2017    madcap flare zendesk google analytics javascript

If your organization is using MadCap Flare’s top navigation output for user documentation, and Zendesk for technical support, you’ll want to add the Zendesk widget to your docs so that users can request support if they get stuck. This post explains how to do that, as well as add some useful customizations.

Before you start

Although you’ll be working with several pieces of JavaScript code, you don’t actually need to know anything about writing JavaScript. However, you should be comfortable with writing basic HTML in a text editor.

Part 1: Embedding the Zendesk widget in your docs

I won’t go into detail about how to prepare and set up the widget itself – Zendesk does an adequate job of explaining that themselves. You should start with that and return here after you’ve generated the JavaScript code for your widget.

Once you have your code, you need to embed it in your Flare master pages. Here’s how to do that:

  1. In your Flare project, create a new folder with this path: Content\Resources\Scripts.
  2. In this folder, create a new text file called zendesk.js.
  3. Copy and paste the JavaScript code into the file and save it.
  4. Open your main master page file in a text editor and, in the <head> section, add this line:

    <script src="../Scripts/zendesk.js"></script>
  5. Repeat for any additional master pages in which you want to embed the widget.

When you now build the project, every page using the master page in which you included the script will contain a [? Help] button in the bottom-right corner. Clicking the button brings up the widget where readers can submit tickets (and do anything else you configured the widget to allow).

What’s next?

If your only goal was to enable your readers to create Zendesk tickets from your docs, then: congratulations, you’re finished! The following two parts are completely optional. Part 3 is especially recommended if you’re working with Google Analytics.

Part 2: Replacing the default widget button

If you’re not happy to use Zendesk’s default, floating, locked-position button, you can create your own button instead.

  1. Hide the original button by adding these lines to your project stylesheet:

         display: none;

    This will hide the <iframe> that contains the button, but not the widget itself.

  2. Open your master page in a text editor.

  3. Add a new HTML element that will serve as the widget button. Choose an element whose appearance you can easily control. An obvious choice might be a <button> element, but I use a <span>. A <div> would also work fine.

  4. Add this property to your element: onclick="zE.activate()". Example:

    <span onclick="zE.activate()">Button text</span>

    NOTE: zE.activate() is the JavaScript function that causes the widget’s ticket form to appear.

  5. Add the same element to any additional master pages on which the button should appear. (If you have a lot of master pages, consider using a snippet.)

When you build the project, the original button will be gone. Click on your new custom button to activate the Zendesk widget.

Part 3: Sending an event to Google Analytics for every ticket

In the body text of each Zendesk ticket created through the widget, you’ll see the URL of the page on which it was submitted. This is very helpful, but if you’re using Google Analytics to track the behavior of your readers, you’ll also want to see where your tickets are coming from directly in GA. You can achieve this by sending an event to GA whenever someone clicks the Submit button in the widget.

  1. Open the zendesk.js file you created earlier.
  2. Add this code at the end:

    $(document).ready(function() {
      setTimeout(function() {
          var iframe=$('iframe#webWidget');
          $('footer div.ButtonGroup input', iframe.contents()).on('mousedown', function() { ga('send', 'event', 'Zendesk', 'submit'); })
      }, 5000);

    NOTE: See About the code for an explanation.

  3. Save the file.

After you build and publish your project, the event messages will appear in Google Analytics under Behavior > Events. In case it wasn’t obvious, the code will only work if you have already implemented Google Analytics in your Flare project. Refer to the aforementioned blog post by Mike Kelley to see how to do that.

About the code

The code you’re looking at (graciously provided by Justin Fitzgerald from the wonderful WriteTheDocs community) is actually JQuery code, rather than pure JavaScript. Normally, you wouldn’t be able to use JQuery unless you included the JQuery library in your project first. But because Flare’s top navigation output relies on JQuery for its interactive elements, it’s included by default. Handy!

The code runs as soon as the page loads, but has a built-in delay of 5000 milliseconds. This gives the widget time to load. If you run the code before the widget loads, it won’t work, because it’ll be referring to HTML elements that don’t exist yet. Feel free to adjust the delay if 5000 ms seems long to you – just change the value at the end of the code. But bear in mind that computers and connections can be slow, and it takes at least 5 seconds to fill in a ticket anyway, so…

This is the part of the code where the magic happens:

ga('send', 'event', 'Zendesk', 'submit');

I’m sure you can get the gist of that line by just reading it, but make sure you check out Google’s breakdown of event tracking in Google Analytics. The information there will also tell you how to adjust or add event parameters if you want to.

The remaining lines are for making sure the event is fired on the correct HTML element, i.e.:

<iframe id="webWidget">  
    <div class="ButtonGroup">      
      <input><!-- This one! --></input>      

Drop me a line

I hope you find the above helpful. If you have a question, comment or suggestion, feel free to leave a comment below.

comments powered by Disqus