RolePlay JavaScript embedding

JavaScript embedding is the most advanced way of integration, and allows you to control exactly how the RolePlay will be integrated, as well as receiving updates on everything that is going on in the games. Coupled with our backend API, you can safely track playthrough info, results, player information and more.

Some example use cases include:

• Embed the RolePlays as part of your custom learning system, and track user scores
• Include RolePlays as part of your online onboarding journey
• Use RolePlays as a part of a campaign or survey, and track user responses

---

Getting started

1. First, get a RolePlay embed UUID. To get one, copy the play URL of any RolePlay, and use the very last part of the URL. For example, https://play.apprendly.com/roleplays/play/e6a838ac-8c2e-474c-953c-b46619eccaa4 would result in e6a838ac-8c2e-474c-953c-b46619eccaa4 being the correct ID.

2. Either in the <head> section or towards the end of your <body> element, add the embed.js script, and set some default variables:

<script src="//play.apprendly.com/embed.js"></script>
<script>
  window.apprendly = window.apprendly || {};
  window.apprendly.addEmbed =
    window.addApprendlyEmbed ||
    function (id, options) {
      window.apprendly.autoLoadIds.push({ id, options });
    };
</script>

3. Wherever you want to render the player itself, place a div with the class "apprendly-embed" and a data-apprendly-embed property set to the embed UUID:

<div
  className="apprendly-embed"
  data-apprendly-embed="e6a838ac-8c2e-474c-953c-b46619eccaa4"
></div>

4. To load the embed, call window.addApprendlyEmbed:

window.addApprendlyEmbed("e6a838ac-8c2e-474c-953c-b46619eccaa4", {});

(You can add any player data you want in the second parameter)

5. That’s it! You can add event listeners etc. to be able to react to actions happening in the RolePlays, like someone completing a game.

---

Sizing the player

The embed replaces the contents of your <div> with this:

<div class="apprendly-embed" data-apprendly-embed="...">
  <div class="apprendly-player-wrapper">
    <i class="apprendly-sizer"></i>
    <iframe class="apprendly-frame"></iframe>
  </div>
</div>

Out of the box the player is 16:9. That ratio comes from the apprendly-sizer element, which props the shape open with padding-bottom: 56.25%, while the wrapper around it is height: 100%. A percentage height only resolves against a parent that has a definite height of its own - so while your container has no height, the sizer is what decides it.

To get a different shape, give your own container a height. The wrapper takes that height instead, the sizer stops contributing, and the frame fills whatever box you asked for. You do not need to override anything in embed.css:

/* Whole viewport on a phone, 3:4 portrait from 1024px up. */
.apprendly-embed {
  width: 100%;
  height: 100%;
}

@media (min-width: 1024px) {
  .apprendly-embed {
    height: min(92dvh, 122vw);
    width: auto;
    aspect-ratio: 3 / 4;
  }
}

Two things worth knowing when you do this:

• Cap the height against the viewport width as well as its height. Above, the width is derived from the height, so on a tall narrow screen a height of 92dvh would push the player wider than the window. 122vw is the same limit expressed as a width: 92 / 0.75 = 122.
• The player can resize itself. It may ask to go fullscreen, which adds a fullscreen class to .apprendly-player-wrapper and an apprendly-fullscreen class to <body>. While that is active your box no longer applies, so avoid locking body { overflow } from your own code - the fullscreen styles set it themselves.

---

Methods

addEmbed(embedId, options = {})

Used for initializing embeds on demand. Used in combination with a <div> on the page which uses the same embedId in its data-apprendly-embed property (see example code).

options

Pass an object with any options you want to include. The supported options are:

restartGame(embedId, options = {})

Use to restart an embedded game. Not supported on mobile.

options

Any options passed here will override the options passed to the embed originally through the addEmbed method.

resetPlayer(embedId, playerData, options = {})

Use to reset the data about the current player, if multiple users will be playing on the same device.

playerData

Any data to be set on the new player. See options.playerData under addEmbed().

options

Any options passed here will override the options passed to the embed originally through the addEmbed method.

---

Events

Events are sent using JavaScript window messages: https://developer.mozilla.org/en-US/docs/Web/API/Window/message_event

Receiving events

Add event listeners on the window to receive event messages. The data will always contain the property apprendly (boolean set to true).

window.addEventListener("message", (event) => {
  if (event.data.apprendly) {
     // Do stuff
  }
});

System events

Events related to the general state of the web player.

Example data:

{
  "apprendly": true,
  "type": "playerReady"
}

Game events

Game events are events of type “gameEvent”, with various eventName to distinguish between them.

Event: playthroughReady

Triggered when a game is started and a playthrough ID is ready. This will be used for tracking, and you can use it with the backend API to retrieve info about a playthrough.

Event data:

Example event data:

{
  "apprendly": true,
  "id": "e6a838ac-8c2e-474c-953c-b46619eccaa4",
  "type": "gameEvent",
  "eventName": "playthroughReady",
  "data": {
    "id": "91ab3189-4033-dcf9-8a51-c9afcd0be3c5",
    "playerId": "",
    "playerData": {},
    "embedId": "e6a838ac-8c2e-474c-953c-b46619eccaa4"
  }
}

Event: gameCompleted

Triggered when a user finishes a game. Contains information about the completed/passed status as well as score info.

If you’d like to use a backend API check to make sure the result is correct, contact us for more info.

NB: Make sure to check “passed” to see if someone has gotten through a game with an acceptable score. “Completed” only means that they’ve completed the game (no matter if they’ve passed or failed the test).

Example event data:

{
  "apprendly": true,
  "id": "e6a838ac-8c2e-474c-953c-b46619eccaa4",
  "type": "gameEvent",
  "eventName": "gameCompleted",
  "data": {
    "playerData": {
      "firstName": "Test",
      "lastName": "Tester"
    },
    "playerId": "",
    "duration": 26,
    "score": 3411,
    "maxScore": 5000,
    "completed": true,
    "passed": true
  }
}