Snippet SDK API

1// A wait target: CSS selector, window.x.y global path, or predicate function
2type WaitTarget<T = unknown> = string | (() => T)
3
4interface WaitOptions {
5  timeout?: number  // ms before the wait times out — default 10000
6  all?: boolean     // when true, selector resolves with querySelectorAll array
7}
8
9// Promise-like whose .catch() is OPTIONAL — failures log gracefully
10interface GuardedThenable<T> {
11  then(onFulfilled?, onRejected?): GuardedThenable<...>
12  catch(onRejected?):              GuardedThenable<...>
13  finally(onFinally?):             GuardedThenable<...>
14  stop(): void  // cancel the wait engine
15}
16
17interface IntegrationEvent {
18  experiment_id: string
19  experiment_name: string
20  variation_id: string
21  variation_name: string
22  event_name: string
23  revenue?: number
24}
25
26interface AvsbTrack {
27  event: (shortId: number, properties?: { revenue?: number }) => void
28  segment: (segmentKey: string, segmentValue: string) => void
29}
30
31interface Avsb {
32  init: () => void | Promise<void>
33  disable: () => void
34  track: AvsbTrack
35  getVisitorId: () => string
36  getVariation: (experimentId: string) => string | null
37  getActiveExperiments: () => Array<{ experimentId: string; variationId: string }>
38  forceVariation: (experimentId: string, variationId: string) => boolean
39  // Single target
40  waitUntil<T>(target: WaitTarget<T>, opts?: WaitOptions): GuardedThenable<T>
41  // Multiple targets — resolves with array of results
42  waitUntil<T extends unknown[]>(targets: WaitTarget[], opts?: WaitOptions): GuardedThenable<T>
43  utils: AvsbUtils  // see avsb.utils reference for full shape
44  onEvent?: (event: IntegrationEvent) => void
45}
46
47declare global {
48  interface Window {
49    avsb: Avsb
50  }
51}

1// Context — available in initVariation
2// Note: initVariation runs only after activation — apply changes directly in
3// the function body. onActivation is NOT present; use onRemove for teardown.
4interface VariationOptions {
5  experimentId: string
6  experimentName: string
7  variationId: string
8  variationName: string
9  variationType: 'control' | 'variant'
10
11  // Teardown hook — fires on SPA navigation, experiment end, or avsb.disable()
12  onRemove: (callback: () => void) => void
13
14  // Self-cleaning helpers — all auto-cancelled on variation removal
15  waitUntil(target: WaitTarget | WaitTarget[], opts?: WaitOptions): GuardedThenable<unknown>
16  utils: AvsbUtils  // full toolkit — see Utilities reference
17  setTimeout: (fn: () => void, ms?: number) => { cancel: () => void }
18  setInterval: (fn: () => void, ms?: number) => { cancel: () => void }
19  addEventListener: (target: EventTarget, type: string, handler: EventListenerOrEventListenerObject, opts?: AddEventListenerOptions) => void
20
21  // Tracking
22  track: { event: (shortId: number, properties?: { revenue?: number }) => void; segment: (key: string, value: string) => void }
23  getVisitorId: () => string
24  getVariation: (experimentId: string) => string | null
25  getActiveExperiments: () => Array<{ experimentId: string; variationId: string }>
26  forceVariation: (experimentId: string, variationId: string) => boolean
27}
28
29// Context — available in initProject (subset, no variation fields)
30// Note: initProject runs on every page load and SPA navigation — there is no
31// activation gate. Apply setup directly in the function body. onActivation is
32// NOT present; use onRemove for pre-navigation teardown.
33interface ProjectOptions {
34  projectId: string
35
36  // Teardown hook — fires before each SPA navigation re-run
37  onRemove: (callback: () => void) => void
38
39  waitUntil(target: WaitTarget | WaitTarget[], opts?: WaitOptions): GuardedThenable<unknown>
40  utils: AvsbUtils  // full toolkit — see Utilities reference
41  setTimeout: (fn: () => void, ms?: number) => { cancel: () => void }
42  setInterval: (fn: () => void, ms?: number) => { cancel: () => void }
43  addEventListener: (target: EventTarget, type: string, handler: EventListenerOrEventListenerObject, opts?: AddEventListenerOptions) => void
44
45  track: { event: (shortId: number, properties?: { revenue?: number }) => void; segment: (key: string, value: string) => void }
46  getVisitorId: () => string
47  getVariation: (experimentId: string) => string | null
48  getActiveExperiments: () => Array<{ experimentId: string; variationId: string }>
49  forceVariation: (experimentId: string, variationId: string) => boolean
50}