Embedded Player

The Embedded Player renders Edpire’s complete assessment UI inside a container on your page. The SDK fetches the assessment, handles every interaction, grades the submission and shows per-question feedback, all from one call. The learner never leaves your app. This is the Exam Hall mode from Two ways to ship. For the question-by-question alternative, see Custom Flow.

Your server  ──mintEmbedToken()──▶  Edpire        (API key stays server-side)
     │
     ▼  token
Your browser ──mount({ token })──▶  player renders in your <div>
     │
     ▼  onComplete(result)
Your app handles the score

Why a server endpoint? You cannot call Edpire directly from the browser: your API key would sit in the JavaScript bundle for anyone to read. The token endpoint lets your server verify the learner from your own session, mint a short-lived single-use token, and send only that to the browser.

Fastest start: scaffold a ready-to-run example instead of wiring this by hand.

npx --package=@edpire/sdk create-edpire-app nextjs my-app        # Next.js App Router
npx --package=@edpire/sdk create-edpire-app vite-express my-app  # Vite + Express

Both ship inside the @edpire/sdk npm package. Each has a README with next steps.

Step 1. Mint tokens on your server

Every integration needs this, whatever your frontend is.

Next.js App Router
Express / Vite dev server
Any other runtime

// app/api/edpire/token/route.ts
import { createEdpireTokenHandler } from "@edpire/sdk/client"

export const POST = createEdpireTokenHandler({
  apiKey: process.env.EDPIRE_API_KEY!,   // server-side only, never NEXT_PUBLIC_
  resolveLearner: async (req) => {
    // Read the learner from YOUR session, never from the request body.
    const session = await auth.api.getSession({ headers: req.headers })
    return session?.user.id ?? null      // null returns 401
  },
})

import { createEdpireTokenHandler, toNodeHandler } from "@edpire/sdk/client"

const handler = toNodeHandler(createEdpireTokenHandler({
  apiKey: process.env.EDPIRE_API_KEY!,
  // `req` is a Web-standard Request rebuilt from the Node request, so Express
  // extras like `req.session` and `req.cookies` are NOT available here. Read
  // from headers and do your own session lookup.
  resolveLearner: async (req) => {
    const cookie = req.headers.get("cookie") ?? ""
    return await getUserIdFromCookie(cookie)
  },
}))

// Express: mount BEFORE any body parser (express.json() and friends). The handler
// reads the request stream itself; a parser that already drained it makes this hang.
app.post("/api/edpire/token", handler)

// Vite configureServer (dev only, use Express for production):
server.middlewares.use("/api/edpire/token", handler)

import { EdpireClient } from "@edpire/sdk/client"

const client = new EdpireClient({ apiKey: process.env.EDPIRE_API_KEY! })

// Inside your authenticated server route:
const learnerRef = session.userId   // from YOUR session, never the request body
const { token } = await client.mintEmbedToken(assessmentId, learnerRef)
return Response.json({ token })

@edpire/sdk/client is a Node package. On a non-Node backend (Django, Rails, Laravel) call POST /api/v1/embed/token directly with your API key. It is a single request.

Never trust the client for the learner ID. Resolve the learner from your server session. If you read a user ID from the request body, anyone can mint tokens as anyone else. createEdpireTokenHandler enforces this through resolveLearner.If some of your content is paid or restricted, check entitlement here too, not only on the page that renders the player. This endpoint is reachable on its own.

The token expires after 2 hours and is consumed when the learner submits. Mint a fresh one each time the learner opens the assessment. Minting does not invalidate a token already in use, so a learner with the assessment open in another tab is unaffected.

# .env
EDPIRE_API_KEY=edp_live_...   # server-side only, never NEXT_PUBLIC_ or VITE_

Step 2. Mount the player

React
Vue, Svelte, Angular, plain JS
Script tag, no build step

<EdpireAssessmentPlayer> handles token fetching, mounting, unmounting and StrictMode double-invoke cleanup for you.

import { EdpireAssessmentPlayer } from "@edpire/sdk/react"

<EdpireAssessmentPlayer
  tokenEndpoint="/api/edpire/token"
  assessmentId="your-assessment-uuid"
  onComplete={(r) => console.log("Score:", r.score, "/", r.max_score)}
  onError={(e) => console.error(e.code, e.message)}
  style={{ width: "100%", height: "100vh" }}
/>

That is the entire integration.

Use the imperative mount(). It returns an instance with unmount(), which is what you call from your framework’s teardown hook (onUnmounted, onDestroy, ngOnDestroy, a router leave guard).

import { EdpireAssessment } from "@edpire/sdk"

const { token } = await fetch("/api/edpire/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ assessmentId: "your-uuid" }),
}).then((r) => r.json())

const embed = EdpireAssessment.mount({
  token,
  container: "#assessment-root",   // CSS selector or HTMLElement
  onComplete: (result) => {
    console.log(`Score: ${result.score}/${result.max_score} (${result.percentage}%)`)
  },
  onError: (err) => console.error(err.code, err.message),
})

embed.unmount()   // when you are done, e.g. closing a modal

The UMD build carries its own React inside a closure, so your framework and your React version are irrelevant to it. It never touches window.React, so it cannot collide with a React app already on the page.

<div id="assessment-root" style="height: 100vh"></div>

<script src="https://cdn.jsdelivr.net/npm/@edpire/sdk@0.6.12/dist/umd/index.global.js"></script>
<script>
  EdpireSDK.EdpireAssessment.mount({
    token: tokenFromYourServer,
    container: "#assessment-root",
    onComplete: function (result) { console.log(result.score, "/", result.max_score) }
  })
</script>

EdpireSDK also exposes renderQuestion, flattenAssessment and buildSubmitPayload.

The bundle is roughly 700 KB gzipped, because it contains React, the maths renderer and the rich text engine. That is the price of needing no build step. Load it on the page that runs the assessment, not in your global layout, and pin an exact version in production rather than @latest. The SDK is pre-1.0, so minor releases can contain breaking changes.

Served straight from npm by jsDelivr or unpkg, so there is no CDN of your own to run. This is the same build used for Mobile and WebView.

React version support

Your React	What to use
19 or 18	`npm install @edpire/sdk`, import from `@edpire/sdk/react`
17 or older	The script tag above. `createRoot` does not exist before 18, so the npm path cannot work. The bundled React is isolated from yours, so there is no conflict
None at all	The script tag above

Container sizing

The player fills its container, so you are responsible for sizing it. A container with no explicit height, or one constrained by centering utilities, collapses to zero and hides the player.

#assessment-root { width: 100%; height: 100vh; }

<EdpireAssessmentPlayer className="h-screen w-full" ... />

If your CSS framework applies global centering or max-width to #root or body (common in Vite and CRA templates), override those rules for the player container. A width: 1126px; margin: auto wrapper visually cuts off the player and can break RTL layout.

Allowed origins

The embed player is origin-scoped: it only loads from domains you explicitly allow. A blank player, or ORIGIN_NOT_ALLOWED in onError, almost always means this list.

Go to edpire.com → Integrations → Security → Allowed Embed Origins
Add every origin your app runs on, including staging and local development:
- http://localhost:3000 (Next.js dev)
- http://localhost:5173 (Vite dev)
- https://yourapp.com (production)
Save and reload

Origins are matched exactly: scheme, host and port. https://app.example.com does not cover https://www.app.example.com.There are two separate lists. Allowed Embed Origins governs the browser SDK. Allowed API & Redirect Origins governs return_url and REST CORS. An origin present in the second but missing from the first looks registered and still fails.

Native WebViews send no origin, or an opaque one like capacitor://localhost. Both are handled, so there is nothing to register for mobile.

Reference

`EdpireAssessmentPlayerProps` (React)

Prop	Type	Required	Description
`tokenEndpoint`	`string`	Yes	URL of your server endpoint that returns `{ token }`. The component POSTs `{ assessmentId }` here.
`assessmentId`	`string`	Yes	Assessment UUID to embed. Sent to `tokenEndpoint` in the POST body. See Find an assessment ID.
`tokenBody`	`Record<string, unknown>`	No	Extra fields merged into the POST body, e.g. a course ID for server-side validation.
`onComplete`	`(result: EmbedResult) => void`	No	Called on successful submission.
`onError`	`(error: EmbedError) => void`	No	Called on non-recoverable errors.
`locale`	`"en" \| "fr" \| "ar"`	No	UI language. RTL applied automatically for `"ar"`. Set it from the assessment’s language, not your UI language.
`branding`	`TakeBranding`	No	Override org branding for white-labelling. See Branding.
`returnUrl`	`string`	No	Post-submit report button redirects here with `?submission_id=…&score=…&max_score=…` appended. Omit to hide the button.
`reportLabel`	`string`	No	Custom label for the report button.
`onBack`	`() => void`	No	Back button handler, shown only before submission.
`backLabel`	`string`	No	Custom back button label.
`overlayConfig`	`OverlayConfig`	No	Customise the grading overlay. See Branding.
`mediaHandler`	`QuestionRuntimeProps["mediaHandler"]`	No	Required for file-upload or recording OpenResponse questions.
`baseUrl`	`string`	No	Edpire instance URL. Defaults to `https://edpire.com`.
`className`	`string`	No	CSS class for the container `<div>`. Use this to size the player.
`style`	`React.CSSProperties`	No	Inline style for the container. Defaults to `{ width: "100%", height: "100%" }` when `className` is absent.

`MountOptions` (imperative)

Everything above applies, minus the React-only props. mount() takes the token directly rather than a tokenEndpoint.

Option	Type	Required	Description
`token`	`string`	Yes	Embed token from your server. Never hardcode.
`container`	`string \| HTMLElement`	Yes	CSS selector or DOM element to mount into.
`baseUrl`	`string`	No	Edpire instance URL. Defaults to `https://edpire.com`.
`locale`	`"en" \| "fr" \| "ar"`	No	UI language. RTL applied automatically for `"ar"`.
`branding`	`TakeBranding`	No	Override the org’s logo, colors and fonts.
`returnUrl`	`string`	No	As above.
`reportLabel`	`string`	No	Custom label for the report button.
`onBack`	`() => void`	No	Back button handler.
`backLabel`	`string`	No	Custom back button label.
`overlayConfig`	`OverlayConfig`	No	Customise the grading overlay.
`mediaHandler`	`QuestionRuntimeProps["mediaHandler"]`	No	Required for file-upload or recording questions.
`onComplete`	`(result: EmbedResult) => void`	No	Called on successful submission.
`onError`	`(error: EmbedError) => void`	No	Called on a non-recoverable error.

`mediaHandler`

Required only if your assessment contains OpenResponse questions with file-upload or audio/video recording. Without it, those question types silently fail to submit.

mediaHandler: {
  /**
   * Called when the learner selects a file (image, audio, video, document).
   * Upload it to your storage and return the permanent URL.
   */
  upload: async (file: File, type: string) => {
    const form = new FormData()
    form.append("file", file)
    form.append("type", type)

    const res = await fetch("/api/upload", { method: "POST", body: form })
    if (!res.ok) throw new Error("Upload failed")

    const { url, mimeType } = await res.json()
    return { url, mimeType }
  },
}

upload receives (file, type) and must resolve to { url, mimeType? }. There is no progress callback. If you want a progress bar, track it in your own upload code and render it outside the player.

`EmbedInstance`

interface EmbedInstance {
  unmount: () => void
}

Safe to call from inside onComplete: the SDK defers the actual React unmount so it never fires mid-render.

`EmbedResult`

Passed to onComplete. Note the fields are snake_case, mirroring the API response.

interface EmbedResult {
  submission_id: string
  score: number
  max_score: number
  percentage: number
  passed: boolean
  passing_score_percent: number
  attempt_number: number
  /** True when open-response nodes are still pending teacher review. */
  awaiting_manual_grading?: boolean

  /**
   * Per-question scores. Use this for scorecards, gradebooks, or recording
   * results. Has scores but not the visual feedback state.
   */
  exercise_results: Array<{
    exercise_id: string
    total_score: number
    max_score: number
    question_results: Array<{
      question_id: string
      score: number
      correct: boolean
      points: number
    }>
  }>

  /**
   * Per-node visual feedback. Use this to show learners what they got right
   * and wrong inline. The player renders this automatically; access it if you
   * are building a custom results screen.
   */
  exercise_feedback: Array<{
    exercise_id: string
    questions: Array<{
      question_id: string
      node_results: Array<{
        node_id: string
        status: "correct" | "partial" | "incorrect" | "awaiting_review"
        score: number
        max_score: number
        feedback?: string
        display_answer?: string
        detail?:
          | { type: "choiceSet"; correctChoiceIds: string[] }
          | {
              type: "matchingSet"
              pairFeedback: Array<{ leftId: string; rightId: string; correct: boolean }>
              correctPairings: Array<{ leftId: string; rightId: string }>
            }
      }>
    }>
  }>
}

If awaiting_manual_grading is true, the visible score is provisional: open-response answers still need a teacher. Listen for the submission.grading.completed webhook for the final score.

`EmbedError`

interface EmbedError {
  code:
    | "TOKEN_INVALID" | "TOKEN_EXPIRED" | "TOKEN_USED"
    | "ORIGIN_NOT_ALLOWED" | "ASSESSMENT_NOT_FOUND"
    | "MAX_ATTEMPTS_REACHED" | "NETWORK_ERROR" | "UNKNOWN"
  message: string
}

Code	Meaning	How to recover
`TOKEN_INVALID`	Token is malformed or unrecognized.	Mint a new token server-side.
`TOKEN_EXPIRED`	Token is older than 2 hours.	Mint a new token.
`TOKEN_USED`	Token was already consumed by a submission.	Mint one per open.
`ORIGIN_NOT_ALLOWED`	The page origin is not in Allowed Embed Origins.	Add it under Integrations → Origins. This is a different list from Allowed API & Redirect Origins.
`ASSESSMENT_NOT_FOUND`	Assessment is missing, unpublished, or not in your org.	Verify the ID and that it is published.
`MAX_ATTEMPTS_REACHED`	Learner has used all allowed attempts.	Show your own “no attempts left” UI.
`NETWORK_ERROR`	Could not reach Edpire.	Retry; check connectivity.
`UNKNOWN`	Anything else, e.g. container not found.	Inspect `message`.

Advanced: bring your own data with `AssessmentShell`

EdpireAssessmentPlayer fetches the assessment client-side after mount and handles everything. Drop down to AssessmentShell only when you need to control data loading yourself: server-rendering the assessment for a faster first paint, pre-fetching before the learner navigates, or plugging into your own caching layer. AssessmentShell expects data in the runtime shape (AssessmentContent), not the raw REST Assessment. That conversion is yours.

import { AssessmentShell } from "@edpire/sdk/react"
import type { SubmitResult } from "@edpire/sdk/react"

<AssessmentShell
  assessment={assessment}
  meta={{ title: "Unit 3 Quiz", category: "Grammar" }}
  locale="en"
  onSubmit={handleSubmit}
/>

Your onSubmit grades the attempt and returns a SubmitResult. Note that client.submit() returns GradeResult in snake_case while the shell expects SubmitResult in camelCase, so map between them on the server:

// POST /api/grade
const result = await client.submit(assessmentId, { learner_ref: session.userId, answers })

return Response.json({
  submissionId: result.submission_id,
  totalScore: result.score,
  maxScore: result.max_score,
  percentage: result.percentage,
  passed: result.passed,
  exerciseFeedback: [],   // GradeResult carries no per-node feedback
  awaitingManualGrading: false,
})

client.submit() returns per-question scores (exercise_results) but not the per-node visual feedback (exerciseFeedback) the shell uses to highlight answers inline. If you need both, use the Embedded Player above, which gets the full response automatically.

`AssessmentShellProps`

Prop	Type	Required	Description
`assessment`	`AssessmentContent`	Yes	The assessment content in runtime shape.
`meta`	`{ title: string; category: string \| null }`	Yes	Title and category for the top bar.
`onSubmit`	`(answers) => Promise<SubmitResult>`	Yes	Grades the attempt. Should throw on failure; the shell shows an error banner.
`locale`	`"en" \| "fr" \| "ar"`	No	Shell string language. Default `"en"`.
`branding`	`TakeBranding`	No	Logo, colors, fonts.
`timeLimitMinutes`	`number \| null`	No	Shows a countdown chip and auto-submits at zero.
`startedAt`	`string` (ISO)	No	If provided, the countdown resumes after a refresh instead of restarting.
`onViewReport`	`(result: SubmitResult) => void`	No	Called on “View Full Report”. Omit to hide the button.
`reportLabel`	`string`	No	Custom report button label.
`onBack`	`() => void`	No	Back button in the top bar, visible only before submission.
`backLabel`	`string`	No	Custom back button label.
`allowReset`	`boolean`	No	Show a Reset button.
`onReset`	`() => void`	No	Reset handler.
`onClose`	`() => void`	No	Show a close button and handle it.
`overlayConfig`	`OverlayConfig`	No	Customise the grading overlay.
`contained`	`boolean`	No	Scope overlays to the shell’s box instead of the viewport. Use when the player sits alongside other content.
`mediaHandler`	`QuestionRuntimeProps["mediaHandler"]`	No	Required for file-upload or recording questions.
`fallbackLogoUrl`	`string`	No	Logo shown when `branding.logoUrl` is absent.

interface SubmitResult {
  submissionId: string
  totalScore: number
  maxScore: number
  percentage: number
  passed: boolean
  /** If null or undefined, the report button is hidden. */
  returnUrl?: string | null
  exerciseFeedback: ExerciseFeedbackData[]
  /** When true, score banners hide the score. */
  awaitingManualGrading?: boolean
}

exerciseFeedback drives the inline per-question feedback. See the type catalog for ExerciseFeedbackData, QuestionFeedback and NodeFeedback.

Next steps

Custom Flow

Question-by-question instead, with your own UI around it.

Webhooks

Receive results server-side, which you want as the primary path.

Mobile and WebView

The same player in React Native, Flutter or native.

Troubleshooting

Blank player, token errors, styles behaving oddly.

​Step 1. Mint tokens on your server

​Step 2. Mount the player

​React version support

​Container sizing

​Allowed origins

​Reference

​EdpireAssessmentPlayerProps (React)

​MountOptions (imperative)

​mediaHandler

​EmbedInstance

​EmbedResult

​EmbedError

​Advanced: bring your own data with AssessmentShell

​AssessmentShellProps

​Next steps

Custom Flow

Webhooks

Mobile and WebView

Troubleshooting

Step 1. Mint tokens on your server

Step 2. Mount the player

React version support

Container sizing

Allowed origins

Reference

`EdpireAssessmentPlayerProps` (React)

`MountOptions` (imperative)

`mediaHandler`

`EmbedInstance`

`EmbedResult`

`EmbedError`

Advanced: bring your own data with `AssessmentShell`

`AssessmentShellProps`

Next steps