@widgetic/embed-sdk 2.0.17 → 2.1.1
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 +26 -4
- package/dist/browser/chunks/ABTestManager.js +1 -1
- package/dist/browser/chunks/api.js +1 -1
- package/dist/browser/chunks/core.js +1 -1
- package/dist/browser/chunks/renderers.js +1 -1
- package/dist/browser/chunks/scanner.js +1 -1
- package/dist/browser/chunks/workflows.js +1 -0
- package/dist/browser/embed-bootstrap.js +1 -1
- package/dist/browser/embed-sdk.js +1 -1
- package/dist/esm/chunks/ABTestManager.js +1 -1
- package/dist/esm/chunks/api.js +1 -1
- package/dist/esm/chunks/core.js +1 -1
- package/dist/esm/chunks/renderers.js +1 -1
- package/dist/esm/chunks/scanner.js +1 -1
- package/dist/esm/chunks/workflows.js +1 -0
- package/dist/esm/embed-bootstrap.js +1 -1
- package/dist/esm/embed-sdk.js +1 -1
- package/dist/esm/types/abTesting/abVisitor.d.ts +2 -0
- package/dist/esm/types/core/autoscale-manager.d.ts +6 -0
- package/dist/esm/types/embed-sdk.d.ts +1 -0
- package/dist/esm/types/sdk/embed-sdk.d.ts +1 -0
- package/dist/esm/types/utils/declarative-embed-parser.d.ts +5 -0
- package/dist/esm/types/utils/host-bridge-snapshot.d.ts +34 -1
- package/dist/esm/types/utils/host-workflow-watch.d.ts +62 -0
- package/dist/esm/types/utils/hydrate-published-host.d.ts +1 -0
- package/dist/esm/types/utils/mount-direct-widget.d.ts +19 -0
- package/dist/esm/types/utils/public-embed-lookup.d.ts +16 -0
- package/dist/esm/types/utils/published-host-bridge.d.ts +21 -3
- package/dist/esm/types/utils/workflow-code-loader.d.ts +14 -0
- package/dist/esm/types/utils/workflow-code-loader.umd.d.ts +32 -0
- package/dist/esm/types/utils/workflow-embed-registry.d.ts +15 -0
- package/dist/esm/types/utils/workflow-page-events.d.ts +41 -0
- package/dist/esm/types/utils/workflow-shared-contract.d.ts +35 -0
- package/dist/esm/types/utils/workflow-shared-services.d.ts +84 -0
- package/dist/esm/types/workflows/umd-entry.d.ts +1 -0
- package/dist/esm/types/workflows/visitor-position.d.ts +32 -0
- package/dist/esm/types/workflows/workflow-autoscale.d.ts +41 -0
- package/dist/esm/types/workflows/workflow-counts.d.ts +65 -0
- package/dist/esm/types/workflows/workflow-host.d.ts +71 -0
- package/dist/esm/types/workflows/workflow-lookup.d.ts +53 -0
- package/dist/esm/types/workflows/workflow-signals.d.ts +34 -0
- package/dist/esm/types/workflows/workflow-stage.d.ts +154 -0
- package/dist/umd/embed-bootstrap.js +1 -1
- package/dist/umd/embed-sdk-workflows.js +1 -0
- package/dist/umd/embed-sdk.js +1 -1
- package/package.json +2 -1
|
@@ -3,6 +3,23 @@
|
|
|
3
3
|
*/
|
|
4
4
|
import type { HostBridgeValidationResult } from "./host-bridge-validation.js";
|
|
5
5
|
export declare const HOST_BRIDGE_MESSAGE_VERSION = 1;
|
|
6
|
+
/**
|
|
7
|
+
* Where the gateway is, for a widget whose adapter modules call it: the address a visitor's entries are saved to and
|
|
8
|
+
* the address of the adapter operations (`{url}/{adapterId}/{operation}`). They come from the public lookup of the
|
|
9
|
+
* composition, never from the page, and they are the only two things a snapshot carries that the page did not write.
|
|
10
|
+
*/
|
|
11
|
+
export type WidgeticHostServices = {
|
|
12
|
+
entries?: {
|
|
13
|
+
url: string;
|
|
14
|
+
writeToken?: string;
|
|
15
|
+
};
|
|
16
|
+
adapters?: {
|
|
17
|
+
url: string;
|
|
18
|
+
captcha?: {
|
|
19
|
+
siteKey: string;
|
|
20
|
+
};
|
|
21
|
+
};
|
|
22
|
+
};
|
|
6
23
|
export type WidgeticHostMessage = {
|
|
7
24
|
type: "widgetic:host";
|
|
8
25
|
version: typeof HOST_BRIDGE_MESSAGE_VERSION;
|
|
@@ -10,5 +27,21 @@ export type WidgeticHostMessage = {
|
|
|
10
27
|
context: Record<string, string | number> | null;
|
|
11
28
|
values: Record<string, string | number | boolean> | null;
|
|
12
29
|
mediaResolver: string | null;
|
|
30
|
+
/** Present only when the lookup gave an address; a widget without one reports its saving as unavailable. */
|
|
31
|
+
entries?: {
|
|
32
|
+
url: string;
|
|
33
|
+
writeToken?: string;
|
|
34
|
+
};
|
|
35
|
+
adapters?: {
|
|
36
|
+
url: string;
|
|
37
|
+
captcha?: {
|
|
38
|
+
siteKey: string;
|
|
39
|
+
};
|
|
40
|
+
};
|
|
13
41
|
};
|
|
14
|
-
|
|
42
|
+
/**
|
|
43
|
+
* The addresses of a lookup answer (`entries`, `adapters`) and nothing else from it: the one piece of the answer a
|
|
44
|
+
* snapshot, or a directly mounted widget, is given besides what the page itself wrote.
|
|
45
|
+
*/
|
|
46
|
+
export declare function hostServicesOf(lookup: WidgeticHostServices): WidgeticHostServices;
|
|
47
|
+
export declare function buildWidgeticHostMessage(compositionId: string, fields: HostBridgeValidationResult, services?: WidgeticHostServices): WidgeticHostMessage;
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What the page tells the widget on screen to watch, for a workflow (`widgetic:workflow-watch`, player version 6, and
|
|
3
|
+
* the `workflow` property of a widget mounted directly in the page). See the host bridge contract.
|
|
4
|
+
*
|
|
5
|
+
* Only what a published rule or trigger needs: the tables whose saved entries a trigger waits for, the columns a
|
|
6
|
+
* condition reads, and the actions a trigger waits for. Everything else a visitor does stays inside the widget.
|
|
7
|
+
*
|
|
8
|
+
* Like `workflow-page-events.ts` this file sits outside `src/workflows/` (the folder loaded only for a page with a
|
|
9
|
+
* `workflow-id` tag) because the host bridge uses it for every page; it therefore keeps its own small copy of how an
|
|
10
|
+
* action id is read, and a test pins that it agrees with the engine's.
|
|
11
|
+
*/
|
|
12
|
+
/** The most tables, columns and goals a widget is told to watch (the wrapper keeps no more than these). */
|
|
13
|
+
export declare const MAX_WATCHED_TABLES = 20;
|
|
14
|
+
export declare const MAX_WATCHED_COLUMNS = 50;
|
|
15
|
+
export declare const MAX_WATCHED_GOALS = 20;
|
|
16
|
+
export interface WatchedField {
|
|
17
|
+
table: string;
|
|
18
|
+
column: string;
|
|
19
|
+
}
|
|
20
|
+
/** What a shown composition has to report, in the shape both ways of telling a widget share. */
|
|
21
|
+
export interface WorkflowWatch {
|
|
22
|
+
tables: string[];
|
|
23
|
+
fields: WatchedField[];
|
|
24
|
+
/** Action ids: a goal's metric, or the metric and the element that counts joined by the first `@`. */
|
|
25
|
+
goals: string[];
|
|
26
|
+
}
|
|
27
|
+
/** What the engine's `describeWatch` says a composition needs (only the parts a widget is told about). */
|
|
28
|
+
export interface WatchSource {
|
|
29
|
+
inputTables: string[];
|
|
30
|
+
inputColumns: WatchedField[];
|
|
31
|
+
actionIds: string[];
|
|
32
|
+
}
|
|
33
|
+
export interface ActionIdParts {
|
|
34
|
+
metric: string;
|
|
35
|
+
selector: string | null;
|
|
36
|
+
}
|
|
37
|
+
/** What an action id counts: the goal and, when it is about one element, the element. Null for text that is not an id. */
|
|
38
|
+
export declare function splitActionId(actionId: string): ActionIdParts | null;
|
|
39
|
+
/** The watch of a composition: what a widget is told, with the same limits and filters the wrapper applies. */
|
|
40
|
+
export declare function buildWorkflowWatch(source: WatchSource): WorkflowWatch;
|
|
41
|
+
/** The `widgetic:workflow-watch` message a widget in a frame is sent (the wrapper hands the widget the goals in full). */
|
|
42
|
+
export declare function workflowWatchMessage(compositionId: string, watch: WorkflowWatch): {
|
|
43
|
+
type: "widgetic:workflow-watch";
|
|
44
|
+
version: 1;
|
|
45
|
+
compositionId: string;
|
|
46
|
+
tables: string[];
|
|
47
|
+
fields: WatchedField[];
|
|
48
|
+
goals: string[];
|
|
49
|
+
};
|
|
50
|
+
export interface DirectWorkflowGoal {
|
|
51
|
+
id: string;
|
|
52
|
+
metric: string;
|
|
53
|
+
goalTarget: string | null;
|
|
54
|
+
}
|
|
55
|
+
export interface DirectWorkflowProperty {
|
|
56
|
+
compositionId: string;
|
|
57
|
+
tables: string[];
|
|
58
|
+
fields: WatchedField[];
|
|
59
|
+
goals: DirectWorkflowGoal[];
|
|
60
|
+
}
|
|
61
|
+
/** The `workflow` property of `mount` and `update` for a widget mounted in the page: the goals as the wrapper hands them. */
|
|
62
|
+
export declare function workflowWatchProperty(compositionId: string, watch: WorkflowWatch): DirectWorkflowProperty;
|
|
@@ -9,6 +9,7 @@
|
|
|
9
9
|
*/
|
|
10
10
|
import { REFUSED_HOST_ATTRIBUTE } from "./host-bridge-markers.js";
|
|
11
11
|
export { REFUSED_HOST_ATTRIBUTE };
|
|
12
|
+
export { sendWorkflowEvent } from "./workflow-page-events.js";
|
|
12
13
|
export declare function hydratePublishedHost(host: HTMLElement): boolean;
|
|
13
14
|
export declare function hydratePublishedHosts(root?: ParentNode): number;
|
|
14
15
|
/**
|
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
* The tag has no hyphen, so the shadow root sits on a child.
|
|
4
4
|
*/
|
|
5
5
|
import type { PublicEmbedPayload } from "./public-embed-lookup.js";
|
|
6
|
+
import type { DirectWorkflowProperty } from "./host-workflow-watch.js";
|
|
6
7
|
export declare const DIRECT_CONTRACT_VERSION = 2;
|
|
7
8
|
export type DirectWidgetInstance = {
|
|
8
9
|
update: (next: Record<string, unknown>) => void;
|
|
@@ -12,10 +13,28 @@ export type DirectWidgetModule = {
|
|
|
12
13
|
contractVersion: number;
|
|
13
14
|
getStyles: () => string;
|
|
14
15
|
mount: (target: HTMLElement, props: Record<string, unknown>) => DirectWidgetInstance;
|
|
16
|
+
/**
|
|
17
|
+
* True for a module that reads where the gateway is (`compositionId`, `entries`, `adapters`) from the props of
|
|
18
|
+
* `mount` and `update`. A module without the flag (one built before it did, or one that calls nothing: they cannot
|
|
19
|
+
* be told apart) is taken to listen for a `widgetic:host` message on the page's window instead (the way a widget in
|
|
20
|
+
* the gateway's frame page is told); see `postWindowSnapshots`.
|
|
21
|
+
*/
|
|
22
|
+
acceptsHostProps?: boolean;
|
|
15
23
|
};
|
|
16
24
|
type DirectModuleLoader = (url: string) => Promise<DirectWidgetModule>;
|
|
25
|
+
/**
|
|
26
|
+
* Loads a module ahead of time, so the module is already there when a workflow swaps it in. Resolves to whether it
|
|
27
|
+
* loaded, and never rejects: a module that does not load is found out by the swap that needs it.
|
|
28
|
+
*/
|
|
29
|
+
export declare function warmDirectModule(moduleUrl: string): Promise<boolean>;
|
|
17
30
|
/** Tests replace the network import. Pass null to restore it. */
|
|
18
31
|
export declare function setDirectModuleLoader(loader: DirectModuleLoader | null): void;
|
|
32
|
+
/**
|
|
33
|
+
* Tells a directly mounted widget what its workflow needs it to report: the tables whose saved entries a trigger waits
|
|
34
|
+
* for, the columns a condition reads, and the actions a trigger waits for. Pass null to take it back.
|
|
35
|
+
* It reaches the module as the `workflow` property, in `mount` when set before the mount and in `update` after.
|
|
36
|
+
*/
|
|
37
|
+
export declare function setDirectMountWorkflow(host: HTMLElement, property: DirectWorkflowProperty | null): void;
|
|
19
38
|
/**
|
|
20
39
|
* Updates a live direct-mounted widget in place (e.g. from a WebSocket content/style push)
|
|
21
40
|
* without destroying or reloading the widget.
|
|
@@ -46,6 +46,17 @@ export type PublicEmbedPayload = PublicEmbedOverlay & {
|
|
|
46
46
|
url: string;
|
|
47
47
|
writeToken?: string;
|
|
48
48
|
};
|
|
49
|
+
/**
|
|
50
|
+
* Where the widget's adapter modules call the gateway (`{url}/{adapterId}/{operation}`), and the public key of the
|
|
51
|
+
* CAPTCHA an operation may ask a visitor to solve. The lookup of a gateway from before this field has none: then the
|
|
52
|
+
* address is the sibling of `entries.url`, and a CAPTCHA operation reports itself unavailable.
|
|
53
|
+
*/
|
|
54
|
+
adapters?: {
|
|
55
|
+
url: string;
|
|
56
|
+
captcha?: {
|
|
57
|
+
siteKey: string;
|
|
58
|
+
};
|
|
59
|
+
};
|
|
49
60
|
/** The owner's choice for image delivery, from the lookup answer (see `image-delivery.ts`). */
|
|
50
61
|
media?: PublicEmbedMedia;
|
|
51
62
|
};
|
|
@@ -79,6 +90,11 @@ export type PublishedEmbedLookup = {
|
|
|
79
90
|
} | {
|
|
80
91
|
status: "not-found";
|
|
81
92
|
};
|
|
93
|
+
/**
|
|
94
|
+
* The API hosts a public lookup may ask, in the order they are asked: the ones the page names itself
|
|
95
|
+
* (`data-api-url`, `WIDGETIC_EMBED_API`), then the SDK's own API, then production. Without repeats.
|
|
96
|
+
*/
|
|
97
|
+
export declare function publicEmbedApiOrigins(): string[];
|
|
82
98
|
export declare function publicCompositionLookupUrls(compositionId: string): string[];
|
|
83
99
|
export declare function resolvePublishedEmbed(compositionId: string): Promise<PublishedEmbedLookup>;
|
|
84
100
|
export declare function resolvePublishedEmbedUrl(compositionId: string): Promise<string | null>;
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Relays `widgetic:host` into the gateway frame and wrapper events back to the page.
|
|
3
3
|
*/
|
|
4
|
+
import { type WidgeticHostServices } from "./host-bridge-snapshot.js";
|
|
5
|
+
import { type WorkflowWatch } from "./host-workflow-watch.js";
|
|
4
6
|
/** What the page tells a widget about the A/B test it is part of. */
|
|
5
7
|
export interface AbGoalAssignment {
|
|
6
8
|
/** The goal the test measures (a metric id such as `clicks`). */
|
|
@@ -15,12 +17,14 @@ declare class PublishedHostBridge {
|
|
|
15
17
|
private readonly iframe;
|
|
16
18
|
private readonly gatewayOrigin;
|
|
17
19
|
private readonly compositionId;
|
|
20
|
+
private readonly services?;
|
|
18
21
|
private readyDispatched;
|
|
19
22
|
private latestAbGoal;
|
|
23
|
+
private latestWorkflowWatch;
|
|
20
24
|
private attributeFlushScheduled;
|
|
21
25
|
private attributeObserver;
|
|
22
26
|
private readonly onWindowMessage;
|
|
23
|
-
constructor(host: HTMLElement, iframe: HTMLIFrameElement, gatewayOrigin: string, compositionId: string);
|
|
27
|
+
constructor(host: HTMLElement, iframe: HTMLIFrameElement, gatewayOrigin: string, compositionId: string, services?: WidgeticHostServices);
|
|
24
28
|
private observeHostAttributes;
|
|
25
29
|
private scheduleHostSnapshot;
|
|
26
30
|
postHostSnapshot(): void;
|
|
@@ -30,6 +34,14 @@ declare class PublishedHostBridge {
|
|
|
30
34
|
*/
|
|
31
35
|
sendAbGoal(assignment: AbGoalAssignment): void;
|
|
32
36
|
private postAbGoal;
|
|
37
|
+
/**
|
|
38
|
+
* Tells the widget what the workflow it is part of needs it to report: the tables whose saved entries a trigger
|
|
39
|
+
* waits for, the columns a condition reads, and the actions a trigger waits for (`widgetic:workflow-watch`, host
|
|
40
|
+
* bridge contract, player version 6). Kept, and sent again on every host snapshot. An empty watch is a valid one: it
|
|
41
|
+
* tells the widget to stop reporting.
|
|
42
|
+
*/
|
|
43
|
+
sendWorkflowWatch(watch: WorkflowWatch): void;
|
|
44
|
+
private postWorkflowWatch;
|
|
33
45
|
sendWidgetUpdate(payload: {
|
|
34
46
|
design?: Record<string, string>;
|
|
35
47
|
content?: Record<string, unknown>;
|
|
@@ -39,8 +51,14 @@ declare class PublishedHostBridge {
|
|
|
39
51
|
private dispatchHostEvent;
|
|
40
52
|
destroy(): void;
|
|
41
53
|
}
|
|
42
|
-
/**
|
|
43
|
-
|
|
54
|
+
/**
|
|
55
|
+
* Attaches the host bridge for a published iframe mount.
|
|
56
|
+
*
|
|
57
|
+
* `services` is the gateway's address for entries and adapter operations, from the public lookup: a widget that
|
|
58
|
+
* keeps visitors' answers (or calls an adapter) learns where from the snapshot, and has nowhere to send them
|
|
59
|
+
* without it. It is posted only to the iframe's own origin, like the rest of the snapshot.
|
|
60
|
+
*/
|
|
61
|
+
export declare function attachPublishedHostBridge(host: HTMLElement, iframe: HTMLIFrameElement, embedUrl: string, compositionId: string, services?: WidgeticHostServices): void;
|
|
44
62
|
export declare function getPublishedHostBridge(host: HTMLElement): PublishedHostBridge | undefined;
|
|
45
63
|
export declare function detachPublishedHostBridge(host: HTMLElement): void;
|
|
46
64
|
/** Dispatches a host-level embed error (lookup refusal, not found, device restriction). */
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where the code of a `<widgetic workflow-id>` tag comes from.
|
|
3
|
+
*
|
|
4
|
+
* It is not part of what every page downloads: a page without such a tag never asks for it. Here, in the code-split
|
|
5
|
+
* builds (ESM, which bundlers and `<script type="module">` use), it is a chunk of the same build, loaded with a dynamic
|
|
6
|
+
* import. The single-file (UMD) build, which is what the CDN serves to every embed, cannot split like that, so
|
|
7
|
+
* scripts-sdk/workflow-bundle.js swaps this module for workflow-code-loader.umd.ts there, which loads the code from a
|
|
8
|
+
* second file instead. Whichever one is built in, the caller gets the same thing: a promise of the part of the workflow
|
|
9
|
+
* module that the SDK starts a workflow with.
|
|
10
|
+
*/
|
|
11
|
+
/** The part of the workflow module that the SDK uses. */
|
|
12
|
+
export type WorkflowHostModule = Pick<typeof import("../workflows/workflow-host.js"), "startWorkflowEmbed">;
|
|
13
|
+
/** Loads the workflow code. A rejected promise means it is not there, and the tag is then embedded as a plain one. */
|
|
14
|
+
export declare function importWorkflowHostModule(): Promise<WorkflowHostModule>;
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import type { WorkflowHostModule } from "./workflow-code-loader";
|
|
2
|
+
/** Where the code is when nothing says otherwise: the CDN folder the SDK's own file is served from. */
|
|
3
|
+
export declare const DEFAULT_WORKFLOW_CODE_URL = "https://cdn.widgetic.com/sdks/browser/embed-sdk-workflows.js";
|
|
4
|
+
/**
|
|
5
|
+
* An attribute of the SDK's own script tag, for a page that serves the SDK itself under another name or from another
|
|
6
|
+
* place: `<script src="/vendor/widgetic.js" data-workflows-src="/vendor/widgetic-workflows.js">`.
|
|
7
|
+
*/
|
|
8
|
+
export declare const WORKFLOW_CODE_SOURCE_ATTRIBUTE = "data-workflows-src";
|
|
9
|
+
/** How long the file gets to arrive and run. A slower one leaves the tag as a plain embed. */
|
|
10
|
+
export declare const WORKFLOW_CODE_TIMEOUT_MILLISECONDS = 20000;
|
|
11
|
+
/** After a failure, how long the next tag is refused at once instead of asking the network again. */
|
|
12
|
+
export declare const WORKFLOW_CODE_RETRY_AFTER_MILLISECONDS = 60000;
|
|
13
|
+
/** What is needed of the SDK's own script tag to find the file next to it. */
|
|
14
|
+
export interface SdkScriptFacts {
|
|
15
|
+
/** The address of the script, as the browser resolved it. */
|
|
16
|
+
source: string;
|
|
17
|
+
/** What the script's `data-workflows-src` says, if anything. */
|
|
18
|
+
explicitSource: string | null;
|
|
19
|
+
/** The script's CSP nonce, handed on to the script that is added so that a nonce-based policy lets it run. */
|
|
20
|
+
nonce: string | null;
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Says where the workflow code is: what the SDK's script tag names, or else the file next to the SDK's own (same
|
|
24
|
+
* folder, same query string, so that a page's cache-buster applies to both), or else the CDN's default.
|
|
25
|
+
*/
|
|
26
|
+
export declare function resolveWorkflowCodeUrl(sdkScript: Pick<SdkScriptFacts, "source" | "explicitSource"> | null, documentBaseUrl: string): string;
|
|
27
|
+
/**
|
|
28
|
+
* Loads the workflow code, once for the page: every tag that needs it gets the same promise. After a failure the next
|
|
29
|
+
* tags are refused at once for a minute rather than each asking a network that has just failed, and then it is tried
|
|
30
|
+
* again.
|
|
31
|
+
*/
|
|
32
|
+
export declare function importWorkflowHostModule(): Promise<WorkflowHostModule>;
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which tags run a workflow, so that the page's own teardown of a tag (a reload, a removal) stops the workflow with it.
|
|
3
|
+
*
|
|
4
|
+
* The workflow code is loaded only for a page that has a `workflow-id` tag (see `src/workflows/`). This small file is
|
|
5
|
+
* what the rest of the SDK knows about it, and it is all a page without workflows ever loads.
|
|
6
|
+
*/
|
|
7
|
+
export interface WorkflowEmbedHandle {
|
|
8
|
+
/** Ends the workflow of the tag: timers, listeners and the stages it built. Must be safe to call twice. */
|
|
9
|
+
stop: () => void;
|
|
10
|
+
}
|
|
11
|
+
/** Remembers the workflow a tag runs. A workflow already running on the tag is stopped first. */
|
|
12
|
+
export declare function registerWorkflowEmbed(host: HTMLElement, handle: WorkflowEmbedHandle): void;
|
|
13
|
+
export declare function hasRegisteredWorkflowEmbed(host: HTMLElement): boolean;
|
|
14
|
+
/** Stops the workflow of a tag, if it runs one. Returns whether there was one. */
|
|
15
|
+
export declare function stopRegisteredWorkflowEmbed(host: HTMLElement): boolean;
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a page can tell a workflow: `sendWorkflowEvent(host, name, values)`, or the DOM event it is made of.
|
|
3
|
+
*
|
|
4
|
+
* Lives outside `src/workflows/` on purpose: that folder is the part of the SDK that is only loaded for a page that
|
|
5
|
+
* has a `workflow-id` tag, and `sendWorkflowEvent` is exported for every page. So this file is small and depends on
|
|
6
|
+
* nothing; it keeps its own copy of the engine's limits, and a test pins that they are the same.
|
|
7
|
+
*
|
|
8
|
+
* A page is not trusted. A name or a value that does not fit is dropped here, before the workflow sees it, and what
|
|
9
|
+
* remains is only ever read by a published condition and then forgotten.
|
|
10
|
+
*/
|
|
11
|
+
/** The DOM event a page dispatches on the `<widgetic>` tag to tell its workflow something. */
|
|
12
|
+
export declare const WORKFLOW_EVENT_TYPE = "widgetic:workflow-event";
|
|
13
|
+
/** The DOM event the tag dispatches when a visitor moves to the next composition (`{ workflowId, from, to }`). */
|
|
14
|
+
export declare const WORKFLOW_STEP_EVENT_TYPE = "widgetic:workflow-step";
|
|
15
|
+
/** What a name of an event or of one of its values may look like. The engine's `EVENT_NAME_PATTERN`. */
|
|
16
|
+
export declare const PAGE_EVENT_NAME_PATTERN: RegExp;
|
|
17
|
+
/** How many events a page may send before the workflow is ready; the oldest are dropped past this. */
|
|
18
|
+
export declare const MAX_QUEUED_PAGE_EVENTS = 20;
|
|
19
|
+
export type PageEventValue = string | number | boolean;
|
|
20
|
+
export interface PageEvent {
|
|
21
|
+
name: string;
|
|
22
|
+
values: Record<string, PageEventValue>;
|
|
23
|
+
}
|
|
24
|
+
/** Reads what a page sent: a name that fits, and the values that fit. Null when there is no usable name. */
|
|
25
|
+
export declare function readPageEvent(detail: unknown): PageEvent | null;
|
|
26
|
+
/**
|
|
27
|
+
* Tells the workflow of a `<widgetic workflow-id>` tag that something happened on the page (an Event from your page
|
|
28
|
+
* trigger waits for it by name). Returns false, and does nothing, when the name does not fit.
|
|
29
|
+
*/
|
|
30
|
+
export declare function sendWorkflowEvent(host: HTMLElement, name: string, values?: Record<string, unknown>): boolean;
|
|
31
|
+
/**
|
|
32
|
+
* Events a page sends before its workflow is ready (the graph is still being read, or the next composition is still
|
|
33
|
+
* being shown). They are kept, up to a limit, and handed over in order once the workflow can use them.
|
|
34
|
+
*/
|
|
35
|
+
export declare class PageEventQueue {
|
|
36
|
+
private events;
|
|
37
|
+
add(event: PageEvent): void;
|
|
38
|
+
/** What was kept, oldest first; the queue is empty afterwards. */
|
|
39
|
+
take(): PageEvent[];
|
|
40
|
+
clear(): void;
|
|
41
|
+
}
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What the two files of the single-file (UMD) build agree on: the SDK itself (`embed-sdk.js`, which every page that
|
|
3
|
+
* embeds a widget loads) and the code of a `<widgetic workflow-id>` tag (`embed-sdk-workflows.js`, which only a page
|
|
4
|
+
* with such a tag loads, and which the SDK asks for when it meets one).
|
|
5
|
+
*
|
|
6
|
+
* The code-split builds (ESM, for bundlers) need none of this: there the workflow code is a chunk of the same build and
|
|
7
|
+
* shares the SDK's modules the way every chunk does.
|
|
8
|
+
*
|
|
9
|
+
* The two files are built together and published together, but a visitor's browser can hold one of them from an
|
|
10
|
+
* earlier release for a while. So the pair checks that it is talking to its own kind:
|
|
11
|
+
*
|
|
12
|
+
* 1. The SDK puts the services the workflow code needs under WORKFLOW_SHARED_SERVICES_GLOBAL (see
|
|
13
|
+
* workflow-shared-services.ts) and adds the script of the workflow code to the page.
|
|
14
|
+
* 2. The workflow code (src/workflows/umd-entry.ts) leaves what it offers under WORKFLOW_EXPORTS_GLOBAL, together
|
|
15
|
+
* with the version of this contract it was built against.
|
|
16
|
+
* 3. The SDK takes it only if that version is its own. Otherwise the tag is embedded as a plain one, which is what
|
|
17
|
+
* happens when the code cannot be loaded at all.
|
|
18
|
+
*
|
|
19
|
+
* Both globals are there for the moment of the hand-over and removed straight after it.
|
|
20
|
+
*
|
|
21
|
+
* Raise WORKFLOW_SHARED_CONTRACT_VERSION whenever the shape of the services or of the exports changes.
|
|
22
|
+
*
|
|
23
|
+
* This file is the one module that both files contain a copy of (scripts-sdk/workflow-bundle.js lets it into the
|
|
24
|
+
* workflow code and tests/unit/scripts/umd-layout.test.ts holds the line on everything else), and it must stay free of
|
|
25
|
+
* state for that reason.
|
|
26
|
+
*/
|
|
27
|
+
/** The version of the hand-over described above. */
|
|
28
|
+
export declare const WORKFLOW_SHARED_CONTRACT_VERSION = 1;
|
|
29
|
+
/**
|
|
30
|
+
* Where the SDK leaves the services for the workflow code. scripts-sdk/workflow-shared-modules.js has the same name
|
|
31
|
+
* (the build reads the global from there), and the test next to the layout test holds the two together.
|
|
32
|
+
*/
|
|
33
|
+
export declare const WORKFLOW_SHARED_SERVICES_GLOBAL = "__widgeticEmbedSharedServices";
|
|
34
|
+
/** Where the workflow code leaves what it offers to the SDK. */
|
|
35
|
+
export declare const WORKFLOW_EXPORTS_GLOBAL = "__widgeticEmbedWorkflows";
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
import { elementMatchesGoalTarget, readStoredValue, removeStoredValue, writeStoredValue } from "../abTesting/abVisitor";
|
|
2
|
+
import { readStoredAutoscaleHeight, writeStoredAutoscaleHeight } from "../core/autoscale-manager";
|
|
3
|
+
import { declarativeChildrenOf, isReservedHostAttribute } from "./declarative-embed-parser";
|
|
4
|
+
import { buildWorkflowWatch, splitActionId, workflowWatchProperty } from "./host-workflow-watch";
|
|
5
|
+
import { setDirectMountWorkflow, warmDirectModule } from "./mount-direct-widget";
|
|
6
|
+
import { publicEmbedApiOrigins, resolvePublishedEmbed } from "./public-embed-lookup";
|
|
7
|
+
import { dispatchPublishedHostError, getPublishedHostBridge } from "./published-host-bridge";
|
|
8
|
+
import { registerWorkflowEmbed } from "./workflow-embed-registry";
|
|
9
|
+
import { PageEventQueue, readPageEvent } from "./workflow-page-events";
|
|
10
|
+
/**
|
|
11
|
+
* What the code of a `<widgetic workflow-id>` tag takes from the SDK, in the single-file (UMD) build, where that code
|
|
12
|
+
* is a file of its own (see workflow-shared-contract.ts for the hand-over).
|
|
13
|
+
*
|
|
14
|
+
* The workflow code is built without these modules and reads them from the object below instead, so that there is one
|
|
15
|
+
* of each on the page: the registry of embeds, the bridge to the published hosts, the visitor's stored values and the
|
|
16
|
+
* rest keep their state in these modules, and a second copy of any of them in the workflow code would have a state of
|
|
17
|
+
* its own that the SDK never sees.
|
|
18
|
+
*
|
|
19
|
+
* One entry for each module that src/workflows/ imports (the list is in scripts-sdk/workflow-shared-modules.js, which
|
|
20
|
+
* the build uses to leave them out of the workflow code), and in each entry the names that src/workflows/ takes from
|
|
21
|
+
* it. They are named one by one, not handed over as whole modules, so that the SDK keeps tree-shaking what the
|
|
22
|
+
* workflows do not use. tests/unit/utils/workflow-shared-services.test.ts reads the imports of src/workflows/ and fails
|
|
23
|
+
* the moment one is missing here.
|
|
24
|
+
*/
|
|
25
|
+
export declare function createWorkflowSharedServices(): {
|
|
26
|
+
contractVersion: number;
|
|
27
|
+
abVisitor: {
|
|
28
|
+
elementMatchesGoalTarget: typeof elementMatchesGoalTarget;
|
|
29
|
+
readStoredValue: typeof readStoredValue;
|
|
30
|
+
removeStoredValue: typeof removeStoredValue;
|
|
31
|
+
writeStoredValue: typeof writeStoredValue;
|
|
32
|
+
};
|
|
33
|
+
autoscaleManager: {
|
|
34
|
+
readStoredAutoscaleHeight: typeof readStoredAutoscaleHeight;
|
|
35
|
+
writeStoredAutoscaleHeight: typeof writeStoredAutoscaleHeight;
|
|
36
|
+
};
|
|
37
|
+
declarativeEmbedParser: {
|
|
38
|
+
declarativeChildrenOf: typeof declarativeChildrenOf;
|
|
39
|
+
isReservedHostAttribute: typeof isReservedHostAttribute;
|
|
40
|
+
};
|
|
41
|
+
hostBridgeMarkers: {
|
|
42
|
+
REFUSED_HOST_ATTRIBUTE: string;
|
|
43
|
+
};
|
|
44
|
+
hostWorkflowWatch: {
|
|
45
|
+
buildWorkflowWatch: typeof buildWorkflowWatch;
|
|
46
|
+
splitActionId: typeof splitActionId;
|
|
47
|
+
workflowWatchProperty: typeof workflowWatchProperty;
|
|
48
|
+
};
|
|
49
|
+
logger: {
|
|
50
|
+
log: {
|
|
51
|
+
debug: (message: string, ...args: any[]) => void;
|
|
52
|
+
info: (message: string, ...args: any[]) => void;
|
|
53
|
+
warn: (message: string, ...args: any[]) => void;
|
|
54
|
+
error: (message: string, ...args: any[]) => void;
|
|
55
|
+
setLevel: (level: "info" | "debug" | "warn" | "error") => void;
|
|
56
|
+
};
|
|
57
|
+
};
|
|
58
|
+
mountDirectWidget: {
|
|
59
|
+
setDirectMountWorkflow: typeof setDirectMountWorkflow;
|
|
60
|
+
warmDirectModule: typeof warmDirectModule;
|
|
61
|
+
};
|
|
62
|
+
publicEmbedLookup: {
|
|
63
|
+
publicEmbedApiOrigins: typeof publicEmbedApiOrigins;
|
|
64
|
+
resolvePublishedEmbed: typeof resolvePublishedEmbed;
|
|
65
|
+
};
|
|
66
|
+
publishedHostBridge: {
|
|
67
|
+
dispatchPublishedHostError: typeof dispatchPublishedHostError;
|
|
68
|
+
getPublishedHostBridge: typeof getPublishedHostBridge;
|
|
69
|
+
};
|
|
70
|
+
publishedHostDisplay: {
|
|
71
|
+
OVERLAY_HOST_ATTRIBUTE: string;
|
|
72
|
+
};
|
|
73
|
+
workflowEmbedRegistry: {
|
|
74
|
+
registerWorkflowEmbed: typeof registerWorkflowEmbed;
|
|
75
|
+
};
|
|
76
|
+
workflowPageEvents: {
|
|
77
|
+
PageEventQueue: typeof PageEventQueue;
|
|
78
|
+
readPageEvent: typeof readPageEvent;
|
|
79
|
+
WORKFLOW_EVENT_TYPE: string;
|
|
80
|
+
WORKFLOW_STEP_EVENT_TYPE: string;
|
|
81
|
+
};
|
|
82
|
+
};
|
|
83
|
+
/** The services as the workflow code finds them. */
|
|
84
|
+
export type WorkflowSharedServices = ReturnType<typeof createWorkflowSharedServices>;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where a visitor is in a workflow, kept in the visitor's own browser (localStorage, or memory for a page whose
|
|
3
|
+
* browser refuses storage).
|
|
4
|
+
*
|
|
5
|
+
* Only ids and times are kept: the block and composition the visitor is on, the version of the workflow they started
|
|
6
|
+
* on, when they started and when they reached the block. Never a value a visitor typed, never who they are.
|
|
7
|
+
*
|
|
8
|
+
* The version is what lets a visitor finish on the workflow they started on when a newer one is published in the
|
|
9
|
+
* meantime. After 30 days that no longer holds: the position is forgotten and the visitor is treated as a new one.
|
|
10
|
+
*/
|
|
11
|
+
/** How long a visitor finishes on the version they started on. */
|
|
12
|
+
export declare const POSITION_MAX_AGE_MILLISECONDS: number;
|
|
13
|
+
export interface StoredPosition {
|
|
14
|
+
/** The published version the visitor started on (and finishes on). */
|
|
15
|
+
versionId: string;
|
|
16
|
+
/** The composition block the visitor is on. */
|
|
17
|
+
nodeId: string;
|
|
18
|
+
/** The composition that block shows, so the first paint of a returning visitor needs no graph. */
|
|
19
|
+
compositionId: string;
|
|
20
|
+
/** When the visitor started on this version (milliseconds since the epoch). */
|
|
21
|
+
startedAt: number;
|
|
22
|
+
/** When the visitor reached this block, which is what a wait in a Scheduled trigger counts from. */
|
|
23
|
+
reachedAt: number;
|
|
24
|
+
}
|
|
25
|
+
/** The key one workflow's position is kept under. */
|
|
26
|
+
export declare function positionStorageKey(workflowId: string): string;
|
|
27
|
+
/** Reads what a visitor's browser kept for a workflow; null for none, for one that ran out, and for anything unreadable. */
|
|
28
|
+
export declare function readStoredPosition(workflowId: string, nowMilliseconds?: number): StoredPosition | null;
|
|
29
|
+
/** Keeps where a visitor is. A browser that refuses storage still remembers it for as long as the page lives. */
|
|
30
|
+
export declare function writeStoredPosition(workflowId: string, position: StoredPosition): void;
|
|
31
|
+
/** Forgets where a visitor is (they start again as a new visitor). */
|
|
32
|
+
export declare function clearStoredPosition(workflowId: string): void;
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The rules of the autoscale a workflow embed always has.
|
|
3
|
+
*
|
|
4
|
+
* A workflow swaps one composition for the next in the same place, and the next one is usually a different height.
|
|
5
|
+
* So the embed follows the height of what is shown, whatever `autoscale` or a fixed height on the tag says. The
|
|
6
|
+
* numbers are the ones the other embeds' autoscale reads (`autoscale-min-height`, `-max-height`, `-debounce`,
|
|
7
|
+
* `-threshold`, `-animate`, `-animation-duration`) and have the same defaults.
|
|
8
|
+
*
|
|
9
|
+
* Only decisions live here (which numbers, what a height is held to, whether a change is worth following). Putting a
|
|
10
|
+
* height on the page is the viewport's job (workflow-stage.ts).
|
|
11
|
+
*/
|
|
12
|
+
export interface AutoscaleSettings {
|
|
13
|
+
/** The smallest the embed gets, in pixels. */
|
|
14
|
+
minHeight: number;
|
|
15
|
+
/** The largest the embed gets, in pixels. */
|
|
16
|
+
maxHeight: number;
|
|
17
|
+
/** How long a height has to hold still before the embed follows it, in milliseconds. */
|
|
18
|
+
debounceDelay: number;
|
|
19
|
+
/** The smallest change in height worth following, in pixels. */
|
|
20
|
+
threshold: number;
|
|
21
|
+
/** Whether a change in height is animated. */
|
|
22
|
+
animate: boolean;
|
|
23
|
+
/** How long the animation lasts, in milliseconds. */
|
|
24
|
+
animationDuration: number;
|
|
25
|
+
}
|
|
26
|
+
export declare const AUTOSCALE_DEFAULTS: Readonly<AutoscaleSettings>;
|
|
27
|
+
/**
|
|
28
|
+
* The autoscale settings of a workflow embed, read from its tag. `autoscale="false"` and a fixed height are not
|
|
29
|
+
* read: a workflow embed follows the content.
|
|
30
|
+
*/
|
|
31
|
+
export declare function readAutoscaleSettings(host: Element, options?: {
|
|
32
|
+
prefersReducedMotion?: boolean;
|
|
33
|
+
}): AutoscaleSettings;
|
|
34
|
+
/**
|
|
35
|
+
* A height held between the embed's minimum and maximum, and rounded up to a whole pixel (a half pixel less would cut
|
|
36
|
+
* the last line). `capHeight` is a limit that sits on top of the embed's own, such as the largest height an overlay
|
|
37
|
+
* has on the visitor's screen; when it is smaller than the minimum, the cap decides.
|
|
38
|
+
*/
|
|
39
|
+
export declare function clampHeight(rawHeight: number, settings: Pick<AutoscaleSettings, "minHeight" | "maxHeight">, capHeight?: number | null): number;
|
|
40
|
+
/** Is a new height different enough from the one shown to be worth following? The first height always is. */
|
|
41
|
+
export declare function shouldApplyHeight(currentHeight: number | null, nextHeight: number, threshold: number): boolean;
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a workflow embed reports back to the gateway: how many visitors reached a block (`n`), took a connection (`e`),
|
|
3
|
+
* or could not be moved on to a composition (`f`).
|
|
4
|
+
*
|
|
5
|
+
* Counts are ids and numbers. No visitor, no value a visitor typed and no address is ever in a report; the gateway keeps
|
|
6
|
+
* the same and nothing more. The report carries the token the gateway signed for exactly this workflow and version when
|
|
7
|
+
* it handed out the graph, so a page that never read the workflow cannot raise its numbers.
|
|
8
|
+
*
|
|
9
|
+
* Counts are small and lossy by design: they wait a moment so that what happens together goes in one report, they are
|
|
10
|
+
* sent once and never retried, and a report the gateway refuses or cannot take is simply dropped. A workflow never
|
|
11
|
+
* waits for its numbers and never shows a visitor a thing about them.
|
|
12
|
+
*/
|
|
13
|
+
/** How long a count waits for company before it is reported. */
|
|
14
|
+
export declare const FLUSH_DELAY_MILLISECONDS = 2000;
|
|
15
|
+
/**
|
|
16
|
+
* The most events one report carries (the gateway's limit). At most 90 characters each, so a report of this many is far
|
|
17
|
+
* below the 16 KB the gateway takes, whatever the ids are.
|
|
18
|
+
*/
|
|
19
|
+
export declare const MAX_EVENTS_PER_REPORT = 100;
|
|
20
|
+
export type CountKind = "n" | "e" | "f";
|
|
21
|
+
export interface WorkflowCountsOptions {
|
|
22
|
+
workflowId: string;
|
|
23
|
+
/** The published version the visitor is on. Counts belong to it. */
|
|
24
|
+
versionId: string;
|
|
25
|
+
/** What the gateway signed for this version, or null when it could not (nothing is reported then). */
|
|
26
|
+
token: string | null;
|
|
27
|
+
/** The host that served the workflow; the report goes to the same one. */
|
|
28
|
+
apiOrigin: string;
|
|
29
|
+
/** Whether the embed is still on the page. A report is not worth sending for one that is gone. */
|
|
30
|
+
isActive: () => boolean;
|
|
31
|
+
}
|
|
32
|
+
export declare class WorkflowCounts {
|
|
33
|
+
private readonly options;
|
|
34
|
+
private pending;
|
|
35
|
+
/** The last event of each thing counted, so the same thing counted again is added to it. */
|
|
36
|
+
private lastEventOf;
|
|
37
|
+
private flushTimer;
|
|
38
|
+
private stopped;
|
|
39
|
+
private listening;
|
|
40
|
+
constructor(options: WorkflowCountsOptions);
|
|
41
|
+
/** Whether counting has ended for good (the gateway refused the token, or the embed was disposed). */
|
|
42
|
+
isStopped(): boolean;
|
|
43
|
+
/**
|
|
44
|
+
* Starts reporting what is waiting when the page is hidden or closed, which is the last moment a page can still
|
|
45
|
+
* send anything. Safe to call more than once.
|
|
46
|
+
*/
|
|
47
|
+
start(): void;
|
|
48
|
+
/** Counts that something happened `times` times (once by default). Anything that cannot be an event is ignored. */
|
|
49
|
+
count(kind: CountKind, id: string, times?: number): void;
|
|
50
|
+
/** Reports what is waiting by a beacon, which the browser finishes even when the page is gone. */
|
|
51
|
+
flushBeforeLeaving(): void;
|
|
52
|
+
/** Ends counting: whatever was waiting is forgotten and nothing is sent again. */
|
|
53
|
+
dispose(): void;
|
|
54
|
+
private readonly onPageHide;
|
|
55
|
+
private readonly onVisibilityChange;
|
|
56
|
+
/** Takes the next report's worth off the waiting events. */
|
|
57
|
+
private takeBatch;
|
|
58
|
+
private forgetPending;
|
|
59
|
+
private flush;
|
|
60
|
+
private reportAddress;
|
|
61
|
+
/** The report as text: plain text keeps it a "simple" cross-origin request, which needs no permission round trip. */
|
|
62
|
+
private reportBody;
|
|
63
|
+
private sendWithBeacon;
|
|
64
|
+
private sendWithRequest;
|
|
65
|
+
}
|