Control the quiz prompt from your own page
A developer guide to setting when the Overlay prompt shows, driving it from your own script and listening for its page events.
This guide is for developers. A widget in Overlay mode shows a small prompt that opens the quiz. Your page can set when and where that prompt shows on the widget's tag, show and hide it from your own script, open the quiz from your own button, and hear when the prompt appears.
Start by setting the widget's Widget Mode to Overlay. See Float a quiz over the page or the video.
Set it on the tag
Attributes on the widget's tag win over the settings saved with the widget, so one widget can behave differently on different templates.
<lexy-widget id="your-widget-id" appear="pause" dock="player"></lexy-widget>
<script src="https://cdn.lexy.fm/embed.js" async></script>
| Attribute | Values | What it does |
|---|---|---|
appear | ready, now, watched, pause, end, manual | When the prompt appears. The first five match the choices under When it appears. With manual, the prompt waits for your script to call show(). |
appear-after | Seconds, such as 45 | How long the viewer watches before the prompt appears, for appear="watched". |
dock | corner, player | The page corner, or on the video player. |
position | bl | Puts the prompt at the bottom left. It sits at the bottom right to begin with. |
appear value | The prompt appears |
|---|---|
ready | When the reader has at least one question they can play |
now | As soon as the page has questions |
watched | After the seconds in appear-after, or 30 seconds |
pause | When the viewer pauses after watching at least five seconds, and when the video ends |
end | When the video ends, or when nearly all of it has been watched |
manual | When your script calls show() |
Show, hide and open it from your script
The script adds LexyWidget.prompt to the page once it has loaded.
| Call | What it does |
|---|---|
LexyWidget.prompt.show(id) | Shows the prompt now, whatever the setting. |
LexyWidget.prompt.hide(id) | Hides the prompt until show(), or until the reader leaves the page. |
LexyWidget.prompt.state(id) | Returns { shown, why, ready, locked, total }. |
LexyWidget.prompt.open(id) | Opens the quiz, for a button of your own. It returns false when there is nothing to open, which is a page with no questions yet or a quiz the reader has finished. |
The id is the one in the widget's tag. Leave it out and the call goes to every prompt on the page. A show() or hide() made before the widget has started is kept and applied when it starts.
Here is a pause screen of your own. Set appear="manual" on the tag, then show the prompt on pause and hide it on play.
var video = document.querySelector('video');
video.addEventListener('pause', function () {
if (window.LexyWidget && LexyWidget.prompt) LexyWidget.prompt.show();
});
video.addEventListener('play', function () {
if (window.LexyWidget && LexyWidget.prompt) LexyWidget.prompt.hide();
});
Hear when the prompt shows
The widget tells the page with two page events. Each is sent on the widget's tag and bubbles up to document.
| Page event | When it happens | What it carries |
|---|---|---|
lexy:prompt_shown | The prompt appears. | widgetId, why, ready, locked, total, lang |
lexy:prompt_hidden | Your script hid the prompt, or the reader finished the quiz. | widgetId, why, lang |
| Field | What it is |
|---|---|
widgetId | The widget's number, as on My Widgets. |
why | On lexy:prompt_shown, the reason it appeared, one of now, ready, watched, pause, end or manual. On lexy:prompt_hidden, manual or complete. |
ready | Questions the reader can play now. |
locked | Questions still waiting to unlock. |
total | Questions in this reader's game. |
lang | The quiz's language. |
document.addEventListener('lexy:prompt_shown', function (e) {
console.log('Quiz prompt shown', e.detail.why, e.detail.ready);
});
The last lexy:prompt_shown detail stays on the widget's tag as lexyPrompt, for a script that starts listening late.
Open the quiz from your own button
lexy:questions_ready tells your page how many questions are ready each time the number changes, including while the prompt is waiting to appear. Use it to switch your own button on, then open the quiz with open().
<button id="quiz-button" hidden>Take the quiz</button>
<script>
var button = document.getElementById('quiz-button');
document.addEventListener('lexy:questions_ready', function (e) {
button.hidden = e.detail.ready < 1;
});
button.addEventListener('click', function () {
LexyWidget.prompt.open();
});
</script>
- With voice on, the quiz opens on a start screen. It shows the game's title and a Play the quiz button. The reader's tap on that button turns on sound and the microphone, and the quiz begins.
- With voice off, the quiz begins at once.
- Call it from the reader's tap. Over a fullscreen video the browser lets the quiz open only straight after a tap, so call
open()inside your button's click handler.
What your page can see
Your page hears the counts, which are how many questions are ready, locked and in the game. The questions, the answers and the reader's progress stay inside the quiz, and each question opens only when the reader has reached its part of the story.
For game starts, answers and scores, see Track Lexy games in your own analytics.
Common questions
Does show() work before any question is ready?
Yes. The prompt shows, and its line says what unlocks the questions, such as 5 more unlock as you watch. The Start button opens the quiz once a question is ready.
Which id do I pass?
The id in the widget's tag, as copied from My Widgets. The widget's number works too.
Do the events also go to Google Tag Manager?
These two are page events only, like lexy:questions_ready. Game starts, answers and scores go to Tag Manager as well.
Thanks for letting us know.
Thanks. Write to support@lexy.fm with what you were looking for, and we will answer and improve this page.