@widgetic/embed-sdk 2.1.8 → 2.1.10

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.
@@ -0,0 +1,58 @@
1
+ /**
2
+ * Client-side show rules (Gleam-style targeting) evaluated before an overlay opens.
3
+ * No server tracking: localStorage + the current page URL, referrer, and clock.
4
+ */
5
+ export type VisitorTypeRule = "any" | "new" | "returning";
6
+ export interface ShowRulesConfig {
7
+ /** Path or URL substrings; if the current page matches any, the widget is skipped */
8
+ excludeUrlPatterns?: string[];
9
+ /** Do not show again after the visitor closed the overlay */
10
+ excludeAfterDismiss?: boolean;
11
+ /** Do not show after the visitor opened or interacted with the widget */
12
+ excludeAfterInteract?: boolean;
13
+ /** Only new, only returning, or any visitor */
14
+ visitorType?: VisitorTypeRule;
15
+ /** Minimum seconds on this page before the overlay may open */
16
+ minTimeOnPageSeconds?: number;
17
+ /** Minimum site page views (any page with Widgetic on it) before eligible */
18
+ minSitePageViews?: number;
19
+ /** ISO date (YYYY-MM-DD) inclusive start */
20
+ scheduleStartDate?: string;
21
+ /** ISO date (YYYY-MM-DD) inclusive end */
22
+ scheduleEndDate?: string;
23
+ /** Weekday ids: 0=Sun … 6=Sat */
24
+ scheduleDaysOfWeek?: number[];
25
+ /** Local time HH:mm */
26
+ scheduleTimeStart?: string;
27
+ scheduleTimeEnd?: string;
28
+ /** Only when there is no referrer (direct / typed URL) */
29
+ requireDirectTraffic?: boolean;
30
+ /** Referrer host must contain one of these (case-insensitive) */
31
+ referrerInclude?: string[];
32
+ /** Current URL must match one pattern (path substring or glob *) */
33
+ urlIncludePatterns?: string[];
34
+ utmSourceMatch?: string;
35
+ utmMediumMatch?: string;
36
+ utmCampaignMatch?: string;
37
+ }
38
+ export interface ShowRulesContext {
39
+ widgetId: string;
40
+ storageKeySuffix?: string;
41
+ }
42
+ export declare function recordEmbedDismissed(widgetId: string, suffix?: string): void;
43
+ export declare function recordEmbedInteracted(widgetId: string, suffix?: string): void;
44
+ /** Mark that this browser has visited a site running the SDK (first touch). */
45
+ export declare function touchSiteVisitor(): "new" | "returning";
46
+ export declare function incrementSitePageViews(): number;
47
+ export declare function readSitePageViews(): number;
48
+ export declare function incrementWidgetPageViews(widgetId: string, suffix?: string): number;
49
+ export declare function readWidgetPageViews(widgetId: string, suffix?: string): number;
50
+ export declare function parseShowRules(element: HTMLElement): ShowRulesConfig | undefined;
51
+ export interface ShowRulesEvaluation {
52
+ allowed: boolean;
53
+ reason?: string;
54
+ }
55
+ export declare function evaluateShowRules(rules: ShowRulesConfig | undefined, context: ShowRulesContext, pageLoadTimeMs: number): ShowRulesEvaluation;
56
+ export declare function attachShowRulesToTriggerConfig(element: HTMLElement, config: {
57
+ showRules?: ShowRulesConfig;
58
+ }): void;
@@ -23,6 +23,9 @@ export declare const MAX_TRIGGER_DELAY_MS: number;
23
23
  * `ScrollTrigger` has always used as its own default.
24
24
  */
25
25
  export declare const DEFAULT_TRIGGER_SCROLL_DISTANCE_PX = 100;
26
+ /** Default scroll depth when `eventTrigger` is `scrollPercent` and no value is stated (percent of page height). */
27
+ export declare const DEFAULT_TRIGGER_SCROLL_PERCENT = 50;
28
+ export declare const DEFAULT_TRIGGER_TIMES_SHOWN = 3;
26
29
  /**
27
30
  * Stacking order of the overlay layer when the embed does not state one
28
31
  * (`overlay-z-index`). The same value the design system's Portal uses, so an
@@ -42,6 +42,11 @@ export declare class TriggerManager {
42
42
  private delayTimer;
43
43
  private domReadyListener;
44
44
  private fullWidthRestore;
45
+ private readonly pageLoadTimeMs;
46
+ private showRulesGateOpen;
47
+ private showRulesPollTimer;
48
+ private lastShowRulesEvaluation;
49
+ private overlayTriggersArmed;
45
50
  private readonly onTriggerActivated;
46
51
  private readonly onTriggerDeactivated;
47
52
  private readonly onOverlayClose;
@@ -54,6 +59,11 @@ export declare class TriggerManager {
54
59
  * Initialize trigger system based on mode
55
60
  */
56
61
  private initialize;
62
+ /**
63
+ * Whether targeting rules allow showing the overlay right now.
64
+ */
65
+ private passesShowRules;
66
+ private startShowRulesPolling;
57
67
  /**
58
68
  * Arm whatever the embed chose to bring the overlay in.
59
69
  *
@@ -64,6 +74,8 @@ export declare class TriggerManager {
64
74
  * leaves the window.
65
75
  */
66
76
  private armOverlayEventTrigger;
77
+ /** Returns false when the view budget is not met yet (widget stays hidden). */
78
+ private armTimesShownTrigger;
67
79
  /**
68
80
  * Run `callback` once the DOM has finished parsing, or right away if it
69
81
  * already has. The pending listener is kept so destroy() can take it back.
@@ -217,6 +229,10 @@ export declare class TriggerManager {
217
229
  * Force show overlay (for testing/manual trigger)
218
230
  */
219
231
  forceShowOverlay(): void;
232
+ /**
233
+ * Public manual open (same recurrence + dismiss semantics as other triggers).
234
+ */
235
+ showFromManualApi(): void;
220
236
  /**
221
237
  * Force hide overlay (for testing/manual trigger)
222
238
  */
@@ -3,6 +3,7 @@
3
3
  * Simple tag detection + enhancement approach
4
4
  */
5
5
  import type { AutoScaleConfig } from './autoscale-manager.js';
6
+ import type { ShowRulesConfig } from './show-rules.js';
6
7
  /**
7
8
  * Render modes for embedding widgets
8
9
  */
@@ -150,11 +151,17 @@ export interface TriggerConfig {
150
151
  * Only meaningful when `mode` is `'overlay'` — a mixed-mode widget is inline
151
152
  * until it scrolls out of view by design.
152
153
  */
153
- eventTrigger?: 'exitIntent' | 'pageLoad' | 'delay' | 'scroll';
154
+ eventTrigger?: 'exitIntent' | 'pageLoad' | 'delay' | 'scroll' | 'scrollPercent' | 'manual' | 'timesShown';
154
155
  /** Delay trigger configuration, read when `eventTrigger` is `'delay'` */
155
156
  delay?: DelayTriggerConfig;
156
157
  /** Scroll trigger configuration */
157
158
  scroll?: ScrollTriggerConfig;
159
+ /** Percent of page height scrolled (0–100), when `eventTrigger` is `scrollPercent` */
160
+ scrollPercent?: number;
161
+ /** Page views required before showing, when `eventTrigger` is `timesShown` */
162
+ timesShownPageViews?: number;
163
+ /** Targeting rules evaluated before the overlay may open */
164
+ showRules?: ShowRulesConfig;
158
165
  /** Exit intent trigger configuration */
159
166
  exitIntent?: ExitIntentConfig;
160
167
  /** Overlay styling and positioning */
@@ -1 +1 @@
1
- export declare const PACKAGE_VERSION = "2.1.8";
1
+ export declare const PACKAGE_VERSION = "2.1.10";
@@ -28,6 +28,15 @@ export interface PublishedHostDisplayPlan {
28
28
  /** Trigger configuration to arm once the iframe is mounted; absent for a plain inline embed */
29
29
  triggers?: TriggerConfig;
30
30
  }
31
+ /**
32
+ * Open an overlay embed from the host page (manual trigger).
33
+ *
34
+ * `compositionId` matches the `composition-id` on the tag. When several copies
35
+ * exist, each one is shown in document order until one succeeds.
36
+ *
37
+ * Also exposed as `Widgetic.show(compositionId)` once the SDK script runs.
38
+ */
39
+ export declare function showPublishedEmbed(compositionId: string): boolean;
31
40
  /**
32
41
  * Decide, before anything is fetched, what this host is allowed to become on
33
42
  * this device.
@@ -0,0 +1,12 @@
1
+ import type { CompositionNode, WorkflowGraph } from "@widgetic/workflows-engine";
2
+ /**
3
+ * The composition block a new visitor starts on when the tag names `compositionId`.
4
+ *
5
+ * 1. When the workflow start block shows that composition, it wins.
6
+ * 2. Otherwise the matching block nearest to the start along the edges (breadth-first over every edge; ties by
7
+ * `graph.nodes` order).
8
+ * 3. Otherwise (no matching block is reachable from the start) the first matching block in node order (same as
9
+ * `findCompositionNode`).
10
+ * 4. `null` when the workflow has no block for that composition.
11
+ */
12
+ export declare function resolveEntryNode(graph: WorkflowGraph, compositionId: string): CompositionNode | null;