Custom code

configure specifies your custom code

The purpose of the static website is to present the assessment to the participant's browser. A static website can't save participant data.

To save data -- which is essential for anything other than a demo -- you must operate another server: an API server or "backend" that can:

• ingest participant data
• persist data to a database
• provide security and authentication so only authorized users can retrieve the data

The configure property is where you provide a function so that the static website executes your custom code in response to events such as:

• The assessment generates participant data
• The assessment ends
• The participant quits the assessment early

Specifically, the configure property is a callback function.

Many custom and complex behaviors can be added with configure, but we'll focus on some common ones.

The session object

Within the callback, think of the session object as the overall manager for presenting assessments in the browser. session is notified when events happen within an m2c2kit assessment.

We will instruct session to execute custom code in response to these events.

Showing data in the developer console

For testing and debugging, it's useful to print the data to the browser developer console with console.log(). Whenever an assessment generates data, session can respond to an ActivityData event if we provide another callback. This callback takes the event object, which we refer to as ev. ev has many properties, but of most interest is the newData property: this is the data that the assessment just generated, in JSON format.

Below, we instruct the session to print the string form of the new data to the console whenever new data is generated.

configure: (context, session, assessment) => {
  session.onActivityData((ev) => {
    console.log("  newData: " + JSON.stringify(ev.newData));
  });
}

Saving data to an API endpoint (server)

In addition to logging to the console, it's important to persist the data to a database. In modern browsers, the fetch function sends this data to your API server.

configure: (context, session, assessment) => {
  session.onActivityData((ev) => {
    fetch("https://<www.your-api-server.com>/<your_endpoint>", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify(ev.newData),
    });
  });
}

info

The API server is something you must provide, configure, and manage.

If you are interested in using an API server managed by the m2c2 team, please contact us.

Redirecting the participant's browser when an assessment ends

A typical research protocol is to direct the participant to the m2c2kit static website to complete an assessment, and then return them to another website when the assessment ends.

To do this, session can respond to its End event:

configure: (context, session, assessment) => {
  session.onEnd(() => {
    window.location.href = "https://<www.your-redirected-website.com>";
  });
}

Putting it all together

To specify all of the above should happen, we can combine them into a single callback provided to the configure property:

  configure: (context, session, assessment) => {
    session.onActivityData((ev) => {
      console.log("  newData: " + JSON.stringify(ev.newData));
      fetch("https://<www.your-api-server.com>/<your_endpoint>", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify(ev.newData),
      });

      session.onEnd(() => {
        window.location.href = "https://<www.your-redirected-website.com>";
      });
    });
  }  

warning

We did not talk about advanced usage of the context and assessment objects, but they must be provided, even if they are unused.

If you remove them and instead write configure: (session) => {, your code will not work properly!