> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.superpath.io/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Embedding the Pathway and Assignment Players in Your App

# Embedding the Pathway and Assignment Players in Your App

**In this article:**
* Overview
* Before you start
* How embedding works
* Step 1: Sign an embed token
* Step 2: Build the embed URL
* Step 3: Add the frame to your page
* Step 4: Listen for messages
* What the learner sees
* Reloads and restarts
* Things to keep in mind
* FAQs

## Overview

As a SuperPath partner, you can show a learner's Pathway or assignment inside your own web or mobile app, in an iframe. The learner is signed in automatically, without a password, and sees only the Pathway player or the assignment player: no SuperPath menus, account menu or sign-out.

Your server signs a short-lived token for the learner with your partner secret. Your page frames a SuperPath URL carrying that token. SuperPath checks the token, signs the learner in for that frame only, opens the learning, and tells your page what happens through `postMessage`.

This guide is for developers. It builds on [Implementing Auto Login for Partners](https://help.superpath.io/en/article/implementing-auto-login-for-partners-jpvex/), which uses the same partner secret and many of the same token claims.

## Before you start

You will need:

* **Your Partner ID and partner secret.** Both are on the **Developer** tab of **Partner Portal → Settings**. See *How to Manage Your Partner Credentials and Domains*.
* **Embedding switched on for your partner account, with your sites listed.** Contact SuperPath support with the exact origins of the pages that will contain the frame, for example `https://app.yourcompany.com`. Each must be a full `https://` origin: scheme, host and optional port, with no path. Up to 20 can be listed. Until at least one is listed, embedding is off. The current list is shown under **Embedded learning** on the **Developer** tab.
* **A customer account linked to your partner account,** with the learner in it (or automatic user creation turned on, as for auto login).
* **The learning already given to the learner.** An embed opens a Pathway or assignment the learner already has. It never assigns anything.
* **A JWT library** on your server, such as `jsonwebtoken` for Node.js or `PyJWT` for Python.

## How embedding works

1. Your server signs an embed token for the learner and the learning you want to open.
2. Your page sets an iframe's `src` to `/embed/partner/{partnerId}` on the customer's SuperPath address, with the token and your page's origin.
3. SuperPath only lets that page be framed by the origins listed for your partner account.
4. SuperPath checks the token, signs the learner in for this frame only, and opens the learning.
5. SuperPath posts `superpath:ready` to your page. When the learner finishes, it posts `superpath:completed`. If the session cannot start or has to end, it posts `superpath:session-ended` with a reason.

## Step 1: Sign an embed token

Sign a JWT with your partner secret using **HS256**, the only algorithm accepted.

| Claim | Required | Description |
|---|---|---|
| `exp` | Yes | Expiry, as a Unix timestamp in seconds, **at most 10 minutes** from now. A token without `exp`, or with a later one, is refused. |
| `email` | Yes | The learner's email address. |
| `firstName` | Yes | The learner's first name. |
| `lastName` | Yes | The learner's last name. |
| `tenantId` | Yes | The six-character Account ID of the learner's customer account. The account must belong to your partner account and be active. |
| `target` | Yes | What to open: `{ "type": "pathway" or "assignment", "id": "<id>" }`. See below. |
| `externalId` | No | Your own id for the learner, used if SuperPath creates the user. |

Put `exp` at the top level of the token. The other claims can be at the top level or inside a `data` object, as with auto login.

**Choosing the target:**

| `type` | `id` can be | What opens |
|---|---|---|
| `pathway` | The learner's own Pathway id (the same id auto login deep links use) | The Pathway overview |
| `pathway` | The Pathway's id | The learner's most recent copy of that Pathway |
| `assignment` | The learner's assignment id | The assignment |

The id may contain only letters, numbers, `-` and `_`, up to 128 characters. If the learner does not have that learning, the embed does not open (reason `target_not_found`). For compatibility, `learningType` and `learningId` from an auto login token are accepted in place of `target`.

Example, using Node.js and `jsonwebtoken`:

```js
const jwt = require('jsonwebtoken');

const token = jwt.sign(
  {
    data: {
      email: 'jane@example.com',
      firstName: 'Jane',
      lastName: 'Smith',
      tenantId: 'pznmtt',
      target: { type: 'pathway', id: 'Xy12AbCdEf34GhIjKl56' },
    },
  },
  process.env.SUPERPATH_PARTNER_SECRET,
  { algorithm: 'HS256', expiresIn: '5m' }
);
```

Sign tokens on your server only. Never ship the partner secret in a mobile app or a web page.

## Step 2: Build the embed URL

```http
https://{host}/embed/partner/{partnerId}?t={token}&parentOrigin={origin}
```

| Placeholder | Replace with |
|---|---|
| `{host}` | The customer account's custom domain if it has one. Otherwise `app.superpath.io`, or `app-au.superpath.io` or `app-eu.superpath.io` for accounts in the AU or EU region. |
| `{partnerId}` | Your Partner ID. |
| `{token}` | The signed embed token. |
| `{origin}` | The origin of the page that contains the frame, exactly as listed for your partner account, for example `https://app.yourcompany.com`. URL-encode it. |

`parentOrigin` is what SuperPath posts messages to. It must exactly match one of your listed origins, and, in browsers that report it, the page actually framing SuperPath. If it does not match, the learning still opens but your page receives no messages. SuperPath never posts to `*`.

When the page loads, SuperPath removes the token from the frame's address and sends no referrer.

## Step 3: Add the frame to your page

```html
<iframe
  id="superpath-player"
  src="https://app.superpath.io/embed/partner/YOUR_PARTNER_ID?t=TOKEN&parentOrigin=https%3A%2F%2Fapp.yourcompany.com"
  style="width: 100%; height: 100%; border: 0">
</iframe>
```

Only the `/embed/partner/` page can be framed, and only by your listed origins. Every other SuperPath page refuses to load in a frame, so always start a frame from a fresh embed URL.

## Step 4: Listen for messages

SuperPath posts messages to your page with `window.parent.postMessage`. Check that each message comes from the SuperPath host you framed before trusting it.

```js
const SUPERPATH_ORIGIN = 'https://app.superpath.io'; // the {host} you used

window.addEventListener('message', (event) => {
  if (event.origin !== SUPERPATH_ORIGIN || !event.data) return;

  switch (event.data.type) {
    case 'superpath:ready':
      // the learning is open: hide your loading state
      break;
    case 'superpath:completed':
      // record the completion, close the screen, show your next step
      break;
    case 'superpath:session-ended':
      // mint a new token and set the iframe src again, or close the screen
      console.log('SuperPath session ended:', event.data.reason);
      break;
  }
});
```

| Message | Sent when | Data |
|---|---|---|
| `superpath:ready` | The learner is signed in and the learning has opened. | `target`: `{ type, id }`, where `id` is the learner's own Pathway or assignment id. |
| `superpath:completed` | A Pathway: when the completed page shows (it shows again if the learner comes back to it). An assignment: when the learner finishes it in the frame. | `target` and `status`. A Pathway's `target` is `{ type: "pathway", id, pathwayId }`; an assignment's is `{ type: "assignment", id, entityType, entityId }`. `status` is `completed`, or `awaitingApproval` if the learning needs approval. |
| `superpath:session-ended` | The session could not start, or has ended. | `reason`, below. |

**Reasons sent with `superpath:session-ended`:**

| Reason | Meaning | What to do |
|---|---|---|
| `token_invalid` | The token is missing, wrongly signed, has no `exp` or one more than 10 minutes ahead, is missing a required claim, or names an account that is not yours or not active. | Fix the token. |
| `token_expired` | The token's `exp` has passed. | Mint a new token and reload the frame. |
| `not_enabled` | Embedding is not switched on for your partner account. | Contact SuperPath support. |
| `user_unavailable` | The learner could not be signed in: they do not exist (and automatic user creation is off), are disabled, or have no sign-in account. | Check the learner in the customer account. |
| `target_not_found` | The learner does not have that Pathway or assignment. | Check the `target`, or assign the learning first. |
| `rate_limited` | Too many sign-ins from one network address in a short time. | Wait and try again. |
| `tenant_unavailable` | The customer account is locked or being moved. | Try again later. |
| `signed_out` | The learner's session has ended. | Mint a new token and reload the frame. |
| `reload` | The content changed while the learner was viewing it, so it needs reloading. | Mint a new token and reload the frame. |
| `unload` | The frame's page is going away, for example because you changed the `src` or closed the screen. | Usually nothing, if you caused it. |
| `sign_in_failed` | Anything else went wrong while signing in. | Retry once, then contact SuperPath support with the time. |

## What the learner sees

* The Pathway player or the assignment player only. There are no SuperPath menus, no breadcrumbs or Back links, no account menu and no sign-out. Notes, comments and discussions still work.
* When a Pathway is finished, the completed page says "You can close this page." instead of offering a way back to SuperPath.
* Links that would leave the player, such as certificates and some downloads or links in the content, open in a new window outside the frame. Pages outside the players show "This page is not available here." with a **Back** button.
* If the learning cannot be opened, a neutral card says "This learning could not be opened" (or that the link has expired). The learner never sees a SuperPath sign-in form.
* SCORM and MindSmith content opens inside the frame, in the same players learners use in SuperPath.

## Reloads and restarts

The embedded session lives only in the frame's memory. It uses no cookies and saves nothing in the browser, so it never affects a normal SuperPath session in the same browser, and it is gone when the frame reloads.

That means you cannot reload the frame in place. To restart, mint a new token and set the iframe's `src` to a new embed URL. Do this whenever you receive `superpath:session-ended` with a reason other than `unload`, or whenever your own screen needs to show the learning again.

An embed token can be used more than once until it expires, so a reload within a few minutes can reuse it, but minting a fresh one each time is simpler and safer.

## Things to keep in mind

* **Keep tokens short-lived.** The maximum is 10 minutes. Five is plenty: the token is only needed while the frame loads.
* **The token is in the URL.** Use HTTPS everywhere and do not log or store embed URLs.
* **Only your listed origins can frame SuperPath.** Changes to the list, made by SuperPath support, can take up to 10 minutes to apply.
* **Native mobile apps.** If your app's WebView loads a page from one of your listed origins that contains the iframe, everything above works. If the WebView loads the embed URL directly, without an iframe, the learning works but there is no parent page, so no messages are sent. A WebView that shows a local file has no origin that can be listed, so host the containing page on your own site.
* **New windows.** Links that open outside the frame use a new window. In a WebView, make sure new windows are allowed or opened in the system browser, or those links will do nothing.
* **Rotating your partner secret** stops every embed token signed with the old one. See *How to Manage Your Partner Credentials and Domains*.

## FAQs

**Can an embed assign a Pathway to the learner?**
No. It only opens learning the learner already has. Assign it first, through SuperPath or the API, and then embed it.

**Can I embed My Learning, the Library or an Event?**
No. Only the Pathway player and the assignment player can be embedded.

**Why am I not receiving any messages?**
Check that `parentOrigin` exactly matches the origin of the page containing the frame, that this origin is listed for your partner account, and that your listener compares `event.origin` with the SuperPath host you used in the URL.

**Do I need a different token for auto login and for embedding?**
They are signed the same way with the same secret, but an embed token must have `exp` no more than 10 minutes ahead and must include `target`. An auto login token does not have to.

**Who do I contact to add a new site?**
SuperPath support. Send the full origin, for example `https://portal.yourcompany.com`.