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
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.
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>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>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)
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.
Methods
All methods are called on the window.apprendly object (window.apprendly.addEmbed, etc).
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:
Option | Type | Default | Description |
playerId | string | number | null | Identifier for the current player, to be able to distinguish them in analytics and results. These IDs are one-way encrypted before sending to Apprendly's system, so you can use unique identifiers such as emails or user IDs to be able to find the player again in our analytics - without actually storing any user data on our end. |
autostart | boolean | false | Automatically load the game to start playing. Not supported on mobile. |
playerData | object | {} | Any extra relevant data about the player. This will be stored with the playthroughs, and possible to query in analytics. For example, name, group, etc. |
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"
}
Event name | Description |
playerLoaded | The player has been loaded, and is being set up. |
playerReady | The player is ready to be used. |
quitGame | The user has quit the game, either after finish playing or from the game menu. |
disconnected | The user has disconnected from the game, either because of their own connection failing, the session timing out (too long time being idle), or because of a server error. |
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
id | string | The playthrough ID, which you can use in subsequent calls. |
playerId | string | The player external ID, if any. |
playerData | object | Any data stored on the player. |
embedId | string | The embed ID |
Example event data
{
"apprendly": true,
"id": "e6a838ac-8c2e-474c-953c-b46619eccaa4",
"type": "gameEvent",
"eventName": "playthroughReady",
"data": {
"id": "91ab3189-4033-dcf9-8a51-c9afcd0be3c5",
"playerId": "",
"playedData": {},
"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).
passed | boolean | Whether or not the player has a passing score. |
completed | boolean | Whether or not the whole game has been played through. |
playerId | string | The player external ID, if any. |
playerData | object | Any data stored on the player. |
score | number | The total score. |
maxScore | number | The max total score possible. |
duration | number | The duration of the playthrough, in seconds. |
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,
}
}