One builder, one trusted app flow
Your site hosts the SDK. The SDK creates an isolated iframe and a launch action in your top-level page. Exam Scholars creates the exam and sends only its opaque reference and HTTPS launch URL back.
Requirements
- A website where you can add an SDK script and container.
- HTTPS in production for reliable app-link behaviour.
- Universal/App Links configured for
https://examscholars.com/deeplink/exam/{reference}.
No registration, partner key, secret, account, or expiring embed session is required.
Setup
- Load the versioned v1 SDK once.
- Choose an always-visible container or a click-to-open button.
- Let the SDK render the app launch action after exam creation.
Callbacks and DOM events remain available when you need custom behaviour, but they are not required for a standard integration.
Choose how the builder appears
The SDK handles iframe creation, resizing, secure events, and the app launch button. Choose the option that fits your page.
Option 1: Show the builder immediately
The form loads in place and the SDK adds the launch action when the exam is ready.
<script src="https://examscholars.com/sdk/v1/examscholars.js"></script>
<div id="exam-builder"></div>
<div id="exam-launch"></div>
<script>
ExamScholars.ExamBuilder.mount('#exam-builder', {
launchButton: '#exam-launch'
});
</script>Option 2: Start with one button
The builder loads only after the visitor clicks. It expands below the button and automatically adds the app launch action after creation.
<button type="button" data-examscholars-builder>
Create an Exam
</button>
<script src="https://examscholars.com/sdk/v1/examscholars.js"></script>SDK options and events
| Option | Purpose |
|---|---|
launchButton | Selector/element where the SDK adds its launch button after creation. |
onReady() | The iframe has loaded and can accept learner input. |
onExamCreated(exam) | Receives a validated, frozen { reference, launchUrl } when custom handling is needed. |
onError(error) | Receives { code, message } for custom error handling. |
initialHeight | Initial iframe height before automatic resize (default 680). |
Use mount() for an immediately visible builder or attach() for a programmatically controlled trigger. Adding data-examscholars-builder to a button calls attach() automatically. The container also emits examscholars:ready, examscholars:exam-created, and examscholars:error DOM events. Multiple builders are isolated and duplicate event IDs are ignored.
Deep-link behaviour and fallback
builder.launch() navigates the top page to the Exam Scholars HTTPS link. Android App Links, iOS Universal Links, and supported desktop link associations can open the installed app. When no association or app is available, the existing responsive Exam Scholars launch page remains visible and offers its normal install/open fallback.
Browsers restrict app launches that are not tied to a real click. Do not call launch() automatically from onExamCreated.
Error handling
| Code/status | Meaning |
|---|---|
VALIDATION_ERROR | The learner’s exam settings need correction. |
INVALID_MESSAGE | An unexpected or untrusted launch payload was rejected. |
| 422 | The embed origin or exam configuration is invalid. |
| 429 | Too many exam-creation attempts from the same address. |
Security notes
- The SDK supplies the exact parent origin and the iframe confirms it against the browser referrer when available.
- The iframe uses route-specific CSP
frame-ancestors. Other Exam Scholars pages are not made frameable. - Both SDK and iframe validate message origin; the SDK also validates the sender window, schema, reference, and launch URL.
- The integration uses no keys, secrets, accounts, sessions, third-party cookies, or partner tracking.
Testing checklist
- Test the embed from development, staging, and production origins.
- Test valid creation and field validation.
- Mount two builders and confirm callbacks stay with their own iframe.
- Test installed and uninstalled app behaviour from a real click.
- Verify cold and warm launches on Android/iOS and supported Windows/macOS browsers.
- Confirm the app lands on the existing Start Exam page with the configured subjects, sessions, count, mode, and duration.
Troubleshooting
The iframe is blocked
Use the SDK rather than copying the iframe URL. The SDK supplies the parent origin required by the embed-only framing policy.
The app does not open
Confirm the action came directly from a click, the HTTPS domain association is installed for the platform, and no in-app browser blocks external app links. The web launch page is the fallback.