Custom integration guide

How to integrate a Maze into an existing course or another LMS system.

Purpose

In this article we describe how to integrate a Mazetec Maze with another course or platform.

  1. Create a seamless experience between two systems
  2. Track the learner to and from the systems
  3. Data uniformity.

Let's get started.

Objectives

  • Integrate one or more Mazes into your existing Learning Management System (LMS) or course system by embedding or integrating a Maze directly into your course.
  • Pass the learner's* details (name and email) from your course system into Mazetec.
  • For passing learner results data by xAPI into your LRS. See "Add your LMS or LRS to receive xAPI data"


Pro Integration Tip: If you have integrated your Mazetec account with a Learning Repository Store (LRS), the learner's name and email will be captured in Mazetec analytics and be included in the learner's xAPI records that are passed to your LRS. See the "Add your LMS or LRS to receive xAPI data" article for more detail.



Assumptions
  • You can create an embedded lesson or page with a lightbox or iframe.
  • Your course system allows you to pass basic learner (student) data over HTTP.
User flow from the learner's perspective
  1. Learner starts in your LMS and clicks 'Next' to move to the embedded page.
  2. Lesson/ page loads with the Mazetec player embedded.
  3. Mazetec captures the learner's name and email from your system in the background.
  4. Learner clicks 'Start' and finishes Mazetec RolePlay - All of your learner's attempts are captured (with name and email) in Mazetec Analytics (these can be automatically exported with LRS integration)
  5. Learner clicks “Next” button to move forward in the course.

If you want to prevent users from being able to skip the Mazetec activity please contact us and we can work with you to develop a custom integration.

Mazetec Player - Data Variables

Directly pass data into Mazetec through the player to capture the learner's name and email.

Name URL (GET) Variable Type Description
Name name Text (String), 80 Char Name of the learner saved with the learner's records in Mazetec analytics
Email email Email format. Validates "@" and "." This is the learner's email that is saved with the learner's record.

How is data passed into Mazetec using URL variables?

Data is passed into Mazetec by setting HTTP GET variables in the Maze link.

Map of Mazetec variables to other course system variables

Mazetec URL (GET) Variable Potential Variables Example
&name= {{first_name}}%20{{last_name}} Jane Doe
&email= {{email}} jane.doe@example.com

Note 1: The %20 represents a space character. Note 2: {{first_name}}, {{last_name}}, and {{email}} are example variables that would come from your LMS or course system to pass data into Mazetec.

Create a seamless look and feel.

Recommendations

  • Add &reducemargin=true to the link when embedding the player.
  • Add &removeheader=true to remove the header. If credits and/or the timer is enabled the header will appear in the top center as a minimalist tab.

Given the following example link:

https://app.mazetec.org/player?uuid=a23a75c3-f083-4272-8644-1acf9128be12&removemargin=true&removeheader=true&name={{first_name}}%20{{last_name}}&email={{email}}
Base Maze URL Enable Responsiveness Minimize header Capture Learner Name Capture Learner Email
https://app.mazetec.org/player?uuid=e0e6242c-c6a3-46b5-9290-82c031d10a6f &removemargin=true &removeheader=true &name={{first_name}}%20{{last_name}} &email={{email}}
Live Embedded Maze Example

Common Integration Steps

Starting in Mazetec, open the Maze you wish to integrate and click "Link" >>> "Distribute Maze" or from the dashboard click the "..." more button and "Distribute Maze".

Step 1.1 Click the "..." More menu on your Dashboard and click "Distribute Maze"

more menu distribute maze

create new maze link

You much select "Require name and email", if this isn't selected the system will ignore the variables.

It's also important to Tag the link so you can identify it later and also parse the results. We recommend adding "Integration", and the name of the system and course as tags so you can identify it later and filter the analytics. configure the link by selecting Require name and email

copy-new-link.jpg

You should see a popup modal in Mazetec Player asking for your Name and Email like in the following image.

If you do not see the popup go back and check the settings on your link to ensure "Require name and email" is selected.

Note: The learner will not see this popup, the data will be passed in the background.

name-and-email-modal.jpg

Step 2 - Create an Embedded lesson.

Lastly, we will map the variable in the link.

In your system, as an example we assume the variables to be {{first_name}}, {{last_name}}, and {{email}}. Note: Your system variables will vary.

Background Validation Steps

Once the data are passed to Mazetec via the link the following events occur in the background: 1. The Name and Email modal is automatically populated with the data for the learner. 2. Mazetec then validates the values to validate the expected type. 3. Mazetec automatically closes the modal and the user is on the Start node.

&removemargin=true&name={{first_name}}%20{{last_name}}&email={{email}}
https://app.mazetec.org/player?uuid=a23a75c3-f083-4272-8644-1acf9128be12&removemargin=true&name={{first_name}}%20{{last_name}}&email={{email}}

Step 3 - Advanced - Prevent users from skipping the Maze.

The Mazetec player exposes hooks to certain player actions and the location of the player within a Maze.

Use these hooks to prevent the learner from skipping an embedded Maze by hiding or disabling the next button in your LMS, until the learner has completed the Maze within your course system.

Prevent the skip, with the following script that will prevent learners from being able to skip the Maze before they Finish.

      // Register Mazetec iframe messages listener
      window.addEventListener("message", (e) => {
        if (!e.origin.includes("mazetec")) {
          return;
        }

        // Event trigger fired when the user reaches the finish node in the LMS
        if (e.data.et === "finish") {
          console.log(e, "-----FINISH-----");
          // Include here code to unhide the next button
        }

        console.log(e, "Event from Mazetec");
      });

Error handling

If the values that are passed are not a valid type or are of null value, the Name and Email modal popup will display so the user can manually enter in their information.

Last modified on February 25, 2021