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.

Player link breakdown

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}}

Link breakdown

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

Step 1 - Create a new link and tag it.

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"

Step 1.2 Click "Create Maze link"

Step 1.3 Select "Require name and email" and add a Tag to the 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.

Step 1.4 Copy the new link

Step 1.5 Test your link - copy and paste in your Browser

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.

Step 2 - Create an Embedded lesson.

Step 2.1 Paste Maze link in a Lightbox, iFrame, or as a link.

Step 2.2 - Map the system variables in the link.

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.

Step 2.3 Copy the text below and Paste it at the end of your Maze link in the URL field

&removemargin=true&name={{first_name}}%20{{last_name}}&email={{email}}

Your link should look similar to this:

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

Advanced - Prevent users from skipping the Maze.

The Mazetec player uses the javascript PostMessage() function to send events to the browser for certain player actions within a Maze.

Use these events can 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.

How does the javascript integration work?

The goal is to prevent the learners from skipping the Maze (web object) until the embedded Maze is completed.

Mazetec uses the JavaScript function PostMessage() to send data to the parent page. This method ensures that browsers cannot block this communication and allows us to communicate back to the parent page when the user hits an exit node (finish, fail, creditover, redirect, or timeout).

Sample Javascript Code

/*************************************************************************
  *
  * MAZETEC CONFIDENTIAL
  * __________________
  *
  *  Copyright (c) 2021 MAZETEC LLC
  *  All Rights Reserved.
  *
  * NOTICE:  All information contained herein is, and remains
  * the property of MAZETEC LLC and its suppliers,
  * if any.  The intellectual and technical concepts contained
  * herein are proprietary to MAZETEC LLC
  * and its suppliers and may be covered by U.S. and Foreign Patents,
  * patents in process, and are protected by trade secret or copyright law.
  * Dissemination of this information or reproduction of this material
  * is strictly forbidden unless prior written permission is obtained
  * from MAZETEC LLC.
  *
  * This file is subject to additional terms and conditions defined
  * at mazetec.org.
  */



// Include code here mark the activity incomplete or hide the next button or disable the completed button
// You can re-enable the code when the user finishes the activity.


// This code below registers Mazetec iframe messages listener with the browser parent frame
// this will allow the parent frame listen for messages from
// the Mazetec player.
// We use window.top incase there are multiple iframes in the window.
window.top.addEventListener("message", (e) => {
    if (!e.origin.includes("mazetec")) {
        // If mazetec is not found in the message then we ignore it
        // otherwise we process the message below.
        return;
     }
      // Here we check for the End Type 'et' in the message data.
      // If the end type is 'finish' it means the learner reached the
      // finish node. 
      // Other end types are fail, timeout, redirect, and creditover.
      if (e.data.et === "finish") {
          // Include code here mark the Maze completed and to unhide the next button or enable the completed button
          
          //For testing and Troubleshooting
          //console.log(e, "User reached the finish node");
          
        }
         // For Troubleshooting
        // 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.