@qaiddev/quests-embed 1.7.0 → 1.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +9 -2
- package/dist/embed-loader.d.ts +33 -0
- package/dist/embed.js +2 -0
- package/dist/embed.js.map +1 -0
- package/dist/prefetch.d.ts +13 -0
- package/dist/qaid-quests.js +135 -131
- package/dist/qaid-quests.js.map +1 -1
- package/dist/qaid-quests.umd.cjs +3 -3
- package/dist/qaid-quests.umd.cjs.map +1 -1
- package/dist/types.d.ts +21 -0
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -30,7 +30,8 @@ new QaidQuests({
|
|
|
30
30
|
<div id="form"></div>
|
|
31
31
|
|
|
32
32
|
<script
|
|
33
|
-
src="https://unpkg.com/@qaiddev/quests-embed/dist/
|
|
33
|
+
src="https://unpkg.com/@qaiddev/quests-embed/dist/embed.js"
|
|
34
|
+
defer
|
|
34
35
|
data-endpoint="https://qaid.dev/api/responses"
|
|
35
36
|
data-api-key="YOUR_API_KEY"
|
|
36
37
|
data-config-url="/forms/intake.json"
|
|
@@ -40,6 +41,8 @@ new QaidQuests({
|
|
|
40
41
|
|
|
41
42
|
The embed auto-initializes when it detects a `data-endpoint` attribute on its script tag and either `data-config-url` or an inline JSON config.
|
|
42
43
|
|
|
44
|
+
`dist/embed.js` is a 0.8 KB loader (gzipped). It loads the quest code (about 16 KB) when the container comes within a screen's height of the viewport, or once the page has loaded and the browser is idle, whichever is first. Without a `data-container` it loads at once. It starts fetching the questions (`data-config-url`) and theme (`data-theme-url`) at the same moment as the quest code, so they arrive together. A questionnaire may also carry its theme as `themeDocument`, so one request brings both; a `themeUrl` or `themeDocument` set on the tag still wins. Pointing the tag straight at `dist/qaid-quests.umd.cjs` still works and loads everything up front.
|
|
45
|
+
|
|
43
46
|
### JSON Config (Script Tag)
|
|
44
47
|
|
|
45
48
|
For complex configurations or inline questionnaires, use a separate JSON config element:
|
|
@@ -69,7 +72,7 @@ For complex configurations or inline questionnaires, use a separate JSON config
|
|
|
69
72
|
}
|
|
70
73
|
}
|
|
71
74
|
</script>
|
|
72
|
-
<script src="https://unpkg.com/@qaiddev/quests-embed/dist/
|
|
75
|
+
<script src="https://unpkg.com/@qaiddev/quests-embed/dist/embed.js" defer></script>
|
|
73
76
|
```
|
|
74
77
|
|
|
75
78
|
## How It Works
|
|
@@ -253,6 +256,8 @@ For programmatic embedding — e.g. launching a quest from another widget — th
|
|
|
253
256
|
| Option | Type | Default | Description |
|
|
254
257
|
|--------|------|---------|-------------|
|
|
255
258
|
| `metadata` | `Record<string, unknown>` or a `Promise` of one | — | Extra key/value pairs sent verbatim in the create-response `POST` body. The server decides which keys it persists; unknown keys are ignored. Used, for example, by `@qaiddev/thumbs-embed` to pass `{ feedbackId }` so the QAid backend joins the quest answers to the feedback record. A promise lets you open the quest before you have the ids: the form shows at once and only the create-response call waits for it. Check `QaidQuests.supports.asyncMetadata` first if you load the widget at runtime. |
|
|
259
|
+
| `pageUrl` | `string` | `window.location.href` | The page the response is about. It is stored with the response and checked against the project's Domain Restriction. Set it when the quest runs somewhere else, such as inside a native app's web view. |
|
|
260
|
+
| `visitorId` | `string` | an id kept in this browser | The visitor id sent with the response. Pass your own to tie it to feedback you sent with the same id. |
|
|
256
261
|
| `onComplete` | `(answers) => void` | — | Called once when the quest is completed and the server accepted the submit (just after the thank-you screen renders), with a copy of the submitted answers — answers to questions hidden by `visibleIf` are left out. Not called while the submit is failing. Fires in both modal and inline modes. |
|
|
257
262
|
| `onClose` | `() => void` | — | Called once when the embed is torn down — visitor close, host `destroy()`, or teardown after completion. Lets a host that launched the quest drop its reference. |
|
|
258
263
|
|
|
@@ -332,6 +337,8 @@ Object options take JSON. In HTML, wrap the value in single quotes so the JSON's
|
|
|
332
337
|
| `data-theme-url` | `themeUrl` |
|
|
333
338
|
| `data-theme-document` | `themeDocument`, as a JSON object |
|
|
334
339
|
| `data-metadata` | `metadata`, as a JSON object |
|
|
340
|
+
| `data-page-url` | `pageUrl` |
|
|
341
|
+
| `data-visitor-id` | `visitorId` |
|
|
335
342
|
|
|
336
343
|
`onComplete` and `onClose` are functions, so they can only be passed from code (`new QaidQuests({ ... })`).
|
|
337
344
|
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Single-tag embed loader (`dist/embed.js`).
|
|
3
|
+
*
|
|
4
|
+
* A tiny classic `<script>` that holds back the quest code (the UMD bundle,
|
|
5
|
+
* `qaid-quests.umd.cjs`) until it is needed, so a quest further down the page
|
|
6
|
+
* costs the page nothing while it loads. The bundle is injected when the first
|
|
7
|
+
* of these happens:
|
|
8
|
+
*
|
|
9
|
+
* - the quest's container comes within a screen's height of the viewport;
|
|
10
|
+
* - the page has finished loading and the browser is idle, so the quest is
|
|
11
|
+
* ready before the visitor scrolls to it;
|
|
12
|
+
* - right away, when there is no container to watch (the modal install) or
|
|
13
|
+
* the browser has no IntersectionObserver.
|
|
14
|
+
*
|
|
15
|
+
* When it injects the bundle it also starts fetching the quest's questions
|
|
16
|
+
* (`data-config-url`) and theme (`data-theme-url`), so they download beside
|
|
17
|
+
* the code instead of after it. The bundle picks the requests up from
|
|
18
|
+
* `window.__qaidQuestsPrefetch` (see prefetch.ts).
|
|
19
|
+
*
|
|
20
|
+
* The injected bundle initializes itself from the `data-*` attributes copied
|
|
21
|
+
* across from this tag (or from a `<script type="application/json">` config
|
|
22
|
+
* block already on the page), exactly as if the page had loaded it directly.
|
|
23
|
+
*
|
|
24
|
+
* Usage:
|
|
25
|
+
* <div id="quest-mount"></div>
|
|
26
|
+
* <script src="https://unpkg.com/@qaiddev/quests-embed/dist/embed.js" defer
|
|
27
|
+
* data-endpoint="/api/responses" data-config-url="/forms/intake.json"
|
|
28
|
+
* data-container="#quest-mount"></script>
|
|
29
|
+
*
|
|
30
|
+
* IMPORTANT: this file must stay ES5-clean and dependency-free, like the
|
|
31
|
+
* thumbs-embed loader it mirrors: it is the first thing to run on every
|
|
32
|
+
* browser. Written with var/function on purpose.
|
|
33
|
+
*/
|
package/dist/embed.js
ADDED
|
@@ -0,0 +1,2 @@
|
|
|
1
|
+
(function(){"use strict";(function(){if(typeof document=="undefined")return;function f(){var e=document.currentScript;if(e&&e.src)return e;for(var t=document.getElementsByTagName("script"),n=t.length-1;n>=0;n--){var r=t[n].src||"";if(r.indexOf("quests-embed")!==-1&&/\/embed(\.min)?\.js(\?|#|$)/.test(r))return t[n]}return null}var c=f();if(!c||!c.src)return;var a=c,l=a.src.substring(0,a.src.lastIndexOf("/")+1),u=!1;function i(){if(!u){u=!0;for(var e=document.createElement("script"),t=a.attributes,n=0;n<t.length;n++){var r=t[n];r.name.indexOf("data-")===0&&e.setAttribute(r.name,r.value)}e.src=l+"qaid-quests.umd.cjs",(document.head||document.documentElement).appendChild(e),d(a.getAttribute("data-config-url")),d(a.getAttribute("data-theme-url"))}}function d(e){if(!(!e||typeof fetch!="function")){var t=window,n=t.__qaidQuestsPrefetch||(t.__qaidQuestsPrefetch={});if(!n[e]){var r=fetch(e,{headers:{Accept:"application/json"}});r.catch(function(){}),n[e]=r}}}function v(){function e(){var t=window;typeof t.requestIdleCallback=="function"?t.requestIdleCallback(i,{timeout:3e3}):setTimeout(i,200)}document.readyState==="complete"?e():window.addEventListener("load",e)}function s(){var e=a.getAttribute("data-container"),t=e?document.querySelector(e):null;if(!t||typeof IntersectionObserver=="undefined"){i();return}var n=new IntersectionObserver(function(r){for(var o=0;o<r.length;o++)if(r[o].isIntersecting){n.disconnect(),i();return}},{rootMargin:"100% 0px"});n.observe(t),v()}document.readyState==="loading"?document.addEventListener("DOMContentLoaded",s):s()})()})();
|
|
2
|
+
//# sourceMappingURL=embed.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"embed.js","sources":["../src/embed-loader.ts"],"sourcesContent":["/**\n * Single-tag embed loader (`dist/embed.js`).\n *\n * A tiny classic `<script>` that holds back the quest code (the UMD bundle,\n * `qaid-quests.umd.cjs`) until it is needed, so a quest further down the page\n * costs the page nothing while it loads. The bundle is injected when the first\n * of these happens:\n *\n * - the quest's container comes within a screen's height of the viewport;\n * - the page has finished loading and the browser is idle, so the quest is\n * ready before the visitor scrolls to it;\n * - right away, when there is no container to watch (the modal install) or\n * the browser has no IntersectionObserver.\n *\n * When it injects the bundle it also starts fetching the quest's questions\n * (`data-config-url`) and theme (`data-theme-url`), so they download beside\n * the code instead of after it. The bundle picks the requests up from\n * `window.__qaidQuestsPrefetch` (see prefetch.ts).\n *\n * The injected bundle initializes itself from the `data-*` attributes copied\n * across from this tag (or from a `<script type=\"application/json\">` config\n * block already on the page), exactly as if the page had loaded it directly.\n *\n * Usage:\n * <div id=\"quest-mount\"></div>\n * <script src=\"https://unpkg.com/@qaiddev/quests-embed/dist/embed.js\" defer\n * data-endpoint=\"/api/responses\" data-config-url=\"/forms/intake.json\"\n * data-container=\"#quest-mount\"></script>\n *\n * IMPORTANT: this file must stay ES5-clean and dependency-free, like the\n * thumbs-embed loader it mirrors: it is the first thing to run on every\n * browser. Written with var/function on purpose.\n */\n\n(function () {\n if (typeof document === \"undefined\") return;\n\n // Locate this script tag: prefer document.currentScript (valid for a plain\n // classic script), else find the last <script> whose src looks like embed.js.\n function findSelf(): HTMLScriptElement | null {\n var cur = document.currentScript as HTMLScriptElement | null;\n if (cur && cur.src) return cur;\n var scripts = document.getElementsByTagName(\"script\");\n for (var i = scripts.length - 1; i >= 0; i--) {\n var src = scripts[i].src || \"\";\n if (src.indexOf(\"quests-embed\") !== -1 && /\\/embed(\\.min)?\\.js(\\?|#|$)/.test(src)) {\n return scripts[i];\n }\n }\n return null;\n }\n\n var self = findSelf();\n if (!self || !self.src) return;\n var tag = self;\n\n // Base = the directory that holds embed.js, e.g.\n // \"https://unpkg.com/@qaiddev/quests-embed@1.9.0/dist/\", so the bundle comes\n // from the same (CDN-versioned) place.\n var base = tag.src.substring(0, tag.src.lastIndexOf(\"/\") + 1);\n\n var loaded = false;\n function load(): void {\n if (loaded) return;\n loaded = true;\n var entry = document.createElement(\"script\");\n // Carry the config across so the bundle's auto-init sees it.\n var attrs = tag.attributes;\n for (var j = 0; j < attrs.length; j++) {\n var a = attrs[j];\n if (a.name.indexOf(\"data-\") === 0) entry.setAttribute(a.name, a.value);\n }\n entry.src = base + \"qaid-quests.umd.cjs\";\n (document.head || document.documentElement).appendChild(entry);\n prefetch(tag.getAttribute(\"data-config-url\"));\n prefetch(tag.getAttribute(\"data-theme-url\"));\n }\n\n // Must match PREFETCH_KEY and the request in prefetch.ts.\n function prefetch(url: string | null): void {\n if (!url || typeof fetch !== \"function\") return;\n var w = window as unknown as Record<string, Record<string, Promise<Response> | undefined> | undefined>;\n var store = w.__qaidQuestsPrefetch || (w.__qaidQuestsPrefetch = {});\n if (store[url]) return;\n var request = fetch(url, { headers: { Accept: \"application/json\" } });\n // The embed handles a failure (it retries); this only stops a request\n // nobody picks up from reporting an unhandled rejection.\n request.catch(function () {});\n store[url] = request;\n }\n\n function whenIdleAfterLoad(): void {\n function idle(): void {\n var w = window as Window & {\n requestIdleCallback?: (cb: () => void, opts?: { timeout: number }) => number;\n };\n if (typeof w.requestIdleCallback === \"function\") w.requestIdleCallback(load, { timeout: 3000 });\n else setTimeout(load, 200);\n }\n if (document.readyState === \"complete\") idle();\n else window.addEventListener(\"load\", idle);\n }\n\n function start(): void {\n var selector = tag.getAttribute(\"data-container\");\n var container = selector ? document.querySelector(selector) : null;\n if (!container || typeof IntersectionObserver === \"undefined\") {\n load();\n return;\n }\n var observer = new IntersectionObserver(\n function (entries) {\n for (var k = 0; k < entries.length; k++) {\n if (entries[k].isIntersecting) {\n observer.disconnect();\n load();\n return;\n }\n }\n },\n { rootMargin: \"100% 0px\" },\n );\n observer.observe(container);\n whenIdleAfterLoad();\n }\n\n // The container may come after the tag in the page, so look once it's parsed.\n if (document.readyState === \"loading\") document.addEventListener(\"DOMContentLoaded\", start);\n else start();\n})();\n"],"names":["findSelf","cur","scripts","i","src","self","tag","base","loaded","load","entry","attrs","j","a","prefetch","url","w","store","request","whenIdleAfterLoad","idle","start","selector","container","observer","entries","k"],"mappings":"0BAkCC,UAAY,CACX,GAAI,OAAO,UAAa,YAAa,OAIrC,SAASA,GAAqC,CAC5C,IAAIC,EAAM,SAAS,cACnB,GAAIA,GAAOA,EAAI,IAAK,OAAOA,EAE3B,QADIC,EAAU,SAAS,qBAAqB,QAAQ,EAC3CC,EAAID,EAAQ,OAAS,EAAGC,GAAK,EAAGA,IAAK,CAC5C,IAAIC,EAAMF,EAAQC,CAAC,EAAE,KAAO,GAC5B,GAAIC,EAAI,QAAQ,cAAc,IAAM,IAAM,8BAA8B,KAAKA,CAAG,EAC9E,OAAOF,EAAQC,CAAC,CAEpB,CACA,OAAO,IACT,CAEA,IAAIE,EAAOL,EAAA,EACX,GAAI,CAACK,GAAQ,CAACA,EAAK,IAAK,OACxB,IAAIC,EAAMD,EAKNE,EAAOD,EAAI,IAAI,UAAU,EAAGA,EAAI,IAAI,YAAY,GAAG,EAAI,CAAC,EAExDE,EAAS,GACb,SAASC,GAAa,CACpB,GAAI,CAAAD,EACJ,CAAAA,EAAS,GAIT,QAHIE,EAAQ,SAAS,cAAc,QAAQ,EAEvCC,EAAQL,EAAI,WACPM,EAAI,EAAGA,EAAID,EAAM,OAAQC,IAAK,CACrC,IAAIC,EAAIF,EAAMC,CAAC,EACXC,EAAE,KAAK,QAAQ,OAAO,IAAM,GAAGH,EAAM,aAAaG,EAAE,KAAMA,EAAE,KAAK,CACvE,CACAH,EAAM,IAAMH,EAAO,uBAClB,SAAS,MAAQ,SAAS,iBAAiB,YAAYG,CAAK,EAC7DI,EAASR,EAAI,aAAa,iBAAiB,CAAC,EAC5CQ,EAASR,EAAI,aAAa,gBAAgB,CAAC,EAC7C,CAGA,SAASQ,EAASC,EAA0B,CAC1C,GAAI,GAACA,GAAO,OAAO,OAAU,YAC7B,KAAIC,EAAI,OACJC,EAAQD,EAAE,uBAAyBA,EAAE,qBAAuB,CAAA,GAChE,GAAI,CAAAC,EAAMF,CAAG,EACb,KAAIG,EAAU,MAAMH,EAAK,CAAE,QAAS,CAAE,OAAQ,kBAAA,EAAsB,EAGpEG,EAAQ,MAAM,UAAY,CAAC,CAAC,EAC5BD,EAAMF,CAAG,EAAIG,GACf,CAEA,SAASC,GAA0B,CACjC,SAASC,GAAa,CACpB,IAAIJ,EAAI,OAGJ,OAAOA,EAAE,qBAAwB,WAAYA,EAAE,oBAAoBP,EAAM,CAAE,QAAS,IAAM,EACzF,WAAWA,EAAM,GAAG,CAC3B,CACI,SAAS,aAAe,WAAYW,EAAA,EACnC,OAAO,iBAAiB,OAAQA,CAAI,CAC3C,CAEA,SAASC,GAAc,CACrB,IAAIC,EAAWhB,EAAI,aAAa,gBAAgB,EAC5CiB,EAAYD,EAAW,SAAS,cAAcA,CAAQ,EAAI,KAC9D,GAAI,CAACC,GAAa,OAAO,sBAAyB,YAAa,CAC7Dd,EAAA,EACA,MACF,CACA,IAAIe,EAAW,IAAI,qBACjB,SAAUC,EAAS,CACjB,QAASC,EAAI,EAAGA,EAAID,EAAQ,OAAQC,IAClC,GAAID,EAAQC,CAAC,EAAE,eAAgB,CAC7BF,EAAS,WAAA,EACTf,EAAA,EACA,MACF,CAEJ,EACA,CAAE,WAAY,UAAA,CAAW,EAE3Be,EAAS,QAAQD,CAAS,EAC1BJ,EAAA,CACF,CAGI,SAAS,aAAe,UAAW,SAAS,iBAAiB,mBAAoBE,CAAK,EACrFA,EAAA,CACP,GAAA"}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Requests the script-tag loader (`embed-loader.ts`) starts while the quest
|
|
3
|
+
* code is still downloading, so the questions and theme are on their way, or
|
|
4
|
+
* already here, by the time the code asks for them.
|
|
5
|
+
*
|
|
6
|
+
* The loader keeps them on `window`, keyed by the exact URL from the tag's
|
|
7
|
+
* `data-config-url` / `data-theme-url`, which is the same string the embed
|
|
8
|
+
* fetches. Each is taken once: a response body can only be read once.
|
|
9
|
+
*/
|
|
10
|
+
/** The window property the loader writes and the embed reads. */
|
|
11
|
+
export declare const PREFETCH_KEY = "__qaidQuestsPrefetch";
|
|
12
|
+
/** Fetch `url` as the embed would, or take the loader's request for it. */
|
|
13
|
+
export declare function fetchJson(url: string): Promise<Response>;
|