Advanced! Developers with backend access to your LMS/Website is required for this method to work

​
Getting Started

Before you begin the integration, you’ll need to gather some information from your Replay account:

​
1. Get Your Secret Key

  1. Navigate to Company Settings (may be labeled as “Manager Portal” in newer versions)
  2. Copy your Secret Key - this is what you’ll use to sign your JWT tokens
  3. Store this securely in your environment variables
Keep your secret key secure and never expose it in client-side code

​
2. Choose Your Activity Type

Replay supports embedding different types of activities. You can get the iframe code for each from different locations:
1

Copy the Iframe

Each activity requires a specific iframe configuration. Here’s the base template:
<iframe
  id="550e8400-e29b-41d4-a716-446655440000"
  data-ai-activity-locator="ai-activity-iframe"
  src="https://app.replay.sale/api/iframe/launch?activityId=403dded8-6a20-410d-a234-75c0f35f44f0&activityType=premade-roleplay&integrationJwt=<INPUT_INTEGRATION_JWT>"
  width="100%"
  height="100%"
  frameborder="0"
  border="none"
  allow="microphone; camera; clipboard-write; downloads; display-capture"
  style="position: absolute; left: 0; right: 0; bottom: 0; top: 0;"
>    </iframe>
Important: The id attribute should be a unique UUID (as shown in the example above). If you need to select or reference the iframe in your JavaScript code, use the data-ai-activity-locator="ai-activity-iframe" attribute instead of relying on the id, as this provides a more reliable selector that won’t change.
2

Generate a Signed JWT

You must generate a unique JWT for each user using your secret key. The JWT requires these claims:
  • learnerName - User’s name (first, last, or both) - used for personalization in the roleplay
  • uniqueIdentifier - Your database’s unique identifier for this user (UUID, email, etc.)
  • originDomain - Your company’s domain identifier (see details below)
Need a secret key or lost yours? Contact us through email (hello@replay.sale) or Slack
3

Implement the Integration

  1. Generate the signed JWT for your user
  2. Replace <INPUT_INTEGRATION_JWT> in the iframe src with your signed JWT
  3. Load the iframe
Best practice: Create a function that handles JWT generation and iframe src updates before loading. When selecting the iframe in your JavaScript code, always use document.querySelector('[data-ai-activity-locator="ai-activity-iframe"]') instead of getElementById() since the id is a unique UUID that will vary.
4

Test Your Integration

Load your page and verify that:
  • The iframe loads successfully
  • User information is correct
  • Recording permissions work
  • Downloads function properly
Need help? Contact us at hello@replay.sale

​
Code Examples

// Your backend route should use a function like this to sign the JWT
const signReplayJwt = () => {
  const uniqueIdentifier = "asdf1234"; // Replace with the actual unique identifier of your user
  const learnerName = "John Doe"; // Replace with your actual learner name
  const originDomain = "example.com"; // Replace with your domain (used for namespacing users)

  const payload = {
    uniqueIdentifier,
    learnerName,
    originDomain,
  };

  const secret = process.env.REPLAY_SECRET; // Replace with your actual secret that you got from Replay

  const integrationToken = jwt.sign(payload, secret, { expiresIn: "1h" });

  return integrationToken;
};

​
Frequently Asked Questions

​
Message Passing

After the user completes the roleplay, the iframe will send messages to the parent window containing information about the user’s performance and progress. To receive these messages, you’ll need to set up an event listener in your parent window.

​
Setting Up the Listener

Add this code to your parent window to receive messages from the Replay iframe: 
window.addEventListener('message', function(event) {
    // Only accept messages from your Replay domain
    if (event.origin !== 'https://app.replay.sale') return;

    console.log('Received message from iframe:', event.data);

    if (event.data.type === 'roleplay_result') {
        console.log('Score:', event.data.score);
        console.log('Full result:', event.data.result);
    }
});

​
When do we pass the message?

The message will be passed when the “Analysis” page is loaded for a roleplay that has been completed within the past 1 minute.

​
Message Interface

The message type will always be “roleplay_result” and will contain both the overall score and the complete result object.
interface IframeRoleplayResultMessageData {
  type: "roleplay_result";
  data: RoleplayResult;  // Uses the RoleplayResult interface defined in the Data Model documentation
}
Link to RoleplayResult Data Model