> ## Documentation Index
> Fetch the complete documentation index at: https://docs.edpire.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How assessments reach your learners

> The recommended integration, and the two alternatives worth knowing about.

There is **one recommended way** to put Edpire assessments inside your product, and two alternatives that exist for narrower situations. Start with the recommended one.

<Info>
  Building an integration end to end? Read the [Integration Runbook](/developer/platform-runbook)
  instead. It covers who does what, in what order, and how long it takes.
</Info>

***

## Recommended · Embedded Player

Mount Edpire's assessment player inside your own page. The learner never leaves your product. The SDK fetches the assessment, renders the UI, grades the submission and shows per-question feedback from a single call.

This is the right choice for essentially every platform integration, and it is the only one we actively recommend.

**Web:**

```tsx theme={null}
import { EdpireAssessmentPlayer } from "@edpire/sdk/react"

<EdpireAssessmentPlayer
  tokenEndpoint="/api/edpire/token"
  assessmentId={lesson.edpire_assessment_id}
  onComplete={(r) => console.log(r.score, "/", r.max_score)}
  style={{ width: "100%", height: "100vh" }}
/>
```

**Mobile** is the same player in a WebView, using the same token endpoint on your backend. It is a delivery channel of this integration, not a separate one. See [Mobile](/developer/mobile).

**Your backend mints the token**, resolving the learner from your own session so your API key never reaches the browser:

```typescript theme={null}
import { createEdpireTokenHandler } from "@edpire/sdk/client"

export const POST = createEdpireTokenHandler({
  apiKey: process.env.EDPIRE_API_KEY!,
  resolveLearner: async (req) => await getUserIdFromRequest(req),
})
```

Full detail: [Embedded Player](/developer/sdk/embedded-player).

***

## Alternative · Custom Flow

Build your own learner experience — Duolingo-style drills, flashcards, hearts and lives, practice modes — using Edpire's question renderer and the `/check` endpoint for per-question grading.

You get full control over pacing, navigation and visuals. You also take on the UI work, and `/check` carries an anti-brute-force limit of 3 checks per question, per session, per rolling hour.

Choose this when the *shape* of the experience is your product, not just the content inside it. Otherwise the Embedded Player will get you further faster.

Full detail: [Custom Flow](/developer/sdk/custom-flow).

***

## Alternative · Share a link

Every published assessment has a share link that works in any browser with nothing to install:

```
https://{your-slug}.edpire.com/take/{shareCode}?learner_ref={userId}&return_url={yourUrl}
```

This needs no SDK and no frontend work, which makes it a good way to prove the engine works on day one, or to hand an assessment to a teacher to paste into an email or an LMS page.

**It is not the right shape for a platform integration.** It takes the learner out of your product and onto ours, which is usually the opposite of what you are trying to achieve. If you use it to prototype, note that moving to the Embedded Player later reuses the same `learner_ref` and the same webhooks, so nothing is wasted.

| Parameter     | Required    | Description                                                                                                                                                   |
| ------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shareCode`   | Yes         | From the dashboard, once the assessment is published                                                                                                          |
| `learner_ref` | Recommended | Your stable internal user ID                                                                                                                                  |
| `return_url`  | Recommended | Where to send the learner afterwards. Must match an entry in **Allowed API & Redirect Origins**, or it is silently dropped and the learner is never sent back |

Edpire appends `submission_id`, and `score` / `max_score` when grading is final:

```
https://yourplatform.com/results?submission_id=sub_xxx&score=14&max_score=20
```

<Note>
  If the assessment contains open-ended questions, `score` and `max_score` are **deliberately
  omitted**, because the score is not final until a teacher grades it. Only `submission_id` is
  appended. Wait for the `submission.grading.completed` webhook.
</Note>

***

## Quick comparison

|                               | Embedded Player  | Custom Flow        | Share a link     |
| ----------------------------- | ---------------- | ------------------ | ---------------- |
| Learner stays in your product | Yes              | Yes                | No               |
| You build the assessment UI   | No               | Yes                | No               |
| Works on mobile               | Yes, via WebView | Yes                | Yes              |
| Frontend work required        | Minimal          | Substantial        | None             |
| Recommended for platforms     | **Yes**          | Only for custom UX | Prototyping only |