Hosted Embedding

Learn how to embed Teacharium lessons on your website or application using secure iframe-based embedding with JWT authentication.

Overview

Teacharium provides a complete solution for embedding interactive lessons on external websites. The embedding system uses:

• JWT tokens for secure, time-limited access
• Iframe embedding for isolated, secure content delivery
• JavaScript SDK for easy integration
• PostMessage API for communication between the embedded lesson and parent page

Prerequisites

Before you begin, you’ll need:

1. A Teacharium account with at least one published lesson version
2. Public API credentials (public key and secret key)
3. The Lesson ID of a published lesson (find this by clicking Embed on a version in the Lesson Delivery tab). Optionally, a Version ID to pin to a specific published version
4. A website or application where you want to embed lessons

Quick Start

Step 1: Install the SDK

Install the Teacharium Embed SDK in your project:

npm install @teacharium/embed-sdk

Or include it directly via CDN:

<script src="https://unpkg.com/@teacharium/embed-sdk@latest/dist/teacharium-embed-sdk.umd.js"></script>

Step 2: Generate a Token

On your backend server, generate a signed JWT token for the lesson. Include a lessonId and optionally a versionId to pin to a specific published version. If versionId is omitted, the most recently published version is used:

const response = await fetch(
  "https://www.teacharium.io/api/public/sign-token",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${publicKey}.${secretKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      lessonId: "your-lesson-id",
      versionId: "your-published-version-id", // Optional: omit to always use the latest version
      learnerId: "learner_abc123", // Required: anonymous identifier for the learner
      userAttributes: {
        userId: "user_67890",
        sessionId: "session_abc123",
        accountType: "premium",
      },
      timeout: 7200, // 2 hours
    }),
  },
);
 
const { token, expiresAt } = await response.json();

Important Security Notes:

• Always generate tokens on your backend server. Never expose your API secret key in client-side code.
• Do not include PII (Personally Identifiable Information) such as email addresses, full names, phone numbers, or addresses in userAttributes. Use anonymous identifiers like user IDs or session IDs instead. This protects user privacy and complies with data protection regulations.

Step 3: Embed the Lesson

Add a container element to your HTML:

<div id="lesson-container"></div>

Then embed the lesson using the SDK:

import { embedLesson } from "@teacharium/embed-sdk";
 
const embed = embedLesson({
  container: "#lesson-container",
  token: token, // Token from Step 2
  // baseUrl defaults to https://www.teacharium.io
  // lessonId and versionId are automatically extracted from the token
  width: "100%",
  height: "600px",
  onLoad: () => console.log("Lesson loaded"),
  onComplete: (data) => console.log("Lesson completed", data),
  onProgress: (data) => console.log("Progress update", data),
  onError: (error) => console.error("Error", error),
  onEvent: (type, payload) => console.log("Event", type, payload),
});

Note: The SDK automatically uses https://www.teacharium.io as the base URL and extracts the lessonId and versionId from the token, so you typically don’t need to specify these values unless you’re using a self-hosted instance.

Token Generation

Tokens are generated using the /api/public/sign-token endpoint. See the Sign Token API documentation for complete details.

Key points:

• Tokens are tied to a specific lesson and organization
• When versionId is included, the token is pinned to that exact version, ensuring learners see the exact content you intended
• When versionId is omitted, the most recently published version is served each time the lesson loads
• Default expiration is 2 hours (configurable up to 24 hours)
• User attributes are embedded in the token for tracking and personalization
• Tokens cannot be modified without re-signing