GuidedTrack Docs

Triggering a JavaScript Event🔗

*trigger is used to run JavaScript that is sitting within the HTML file that a GuidedTrack program is embedded in. Thus it enables GuidedTrack programs to effectively do anything JavaScript can do, as long as you put the appropriate JavaScript within the HTML file that the GuidedTrack program is embedded in.

This feature is for those who are embedding their programs on other websites, and it's best for those who have a working knowledge of HTML and JavaScript (or at minimum who feel comfortable enough copying and pasting JavaScript obtained through other sources).

So in other words, be warned that this section gets quite technical!

The *trigger command is used to "trigger" JavaScript code to run on the current page. For example, it could trigger the sending of data to external sources, such as Google Analytics for tracking activity in your program. In its simplest form, it looks something like this:

*trigger: quizEnd
	*send: {"importantVariable" -> important_variable_value}

In this example, "quizEnd" is the name we chose to give to our triggering event, and in the HTML page that's embedding our program there will be JavaScript code matching this name that will be actively listening for this event to be called. When the website notices this event, it will grab the data from the *send keyword and do with it as you've commanded (for example, perhaps sending the accompanying data from your program to an external source that you've specified).

The data used with the *send function is always written in the form of an association, with a name or description of the data on the left of the -> accompanied by its value to the right.

For a simple example of how you might *trigger a Google Analytics event, you could do the following:

This is the final page!
-- Trigger the finished event, which will let Google Analytics know we've finished the program
*trigger: finished
You've finished the program!

There would also be JavaScript on your website that included this along with other JavaScript:

// Include the following on the page that embeds the program inside of a <script>…</script> tag
$(window).on("finished", function () {
	ga("send", "event", "progress", "view", "page", "end")
})

Here's a more complex example of using *trigger with Google Analytics:

-- Notify Google Analytics that we've progressed to page one
-- The category, action, label, and value can be anything, depending on how you want to track this data
*trigger: analytics
	*send: { "category" -> "progress", "action" -> "view", "label" -> "page", "value" -> "one" }

First page.
*button: Next

-- Notify Google Analytics that we've progressed to page two
*trigger: analytics
	*send: { "category" -> "progress", "action" -> "view", "label" -> "page", "value" -> "two" }

Second page.
*button: Next

-- Notify Google Analytics that we've finally reached the final page
*trigger: analytics
	*send: { "category" -> "progress", "action" -> "view", "label" -> "page", "value" -> "end" }

Final page.

And here's a description of what you'd put in the JavaScript on your website:

// The first parameter to the event handler is the event itself
// The data sent along with the event is the second parameter (data)
$(window).on("analytics", function (event, data) {
	ga("send", "event", data.category, data.action, data.label, data.value)
})

To get the above example to work, you'd also have to include in the HTML page the JavaScript that Google provides to activate Analytics and the Google Analytics function that's being used.

Here are a few more ideas of ways to use *trigger, with more detailed versions of the JavaScript code that gets added to the website.