@veroxm/sdk 1.3.0 → 1.4.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/CHANGELOG.md CHANGED
@@ -1,5 +1,11 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.4.0
4
+
5
+ - Campaign targeting (public API 2.6): in a browser, `getExperience` and `getFlag` send the page the visit started on
6
+ and its referrer, so experiences can target `campaign.*` (utm tags, ad click ids, the referring site) on the landing
7
+ page itself. `tracker.setLandingPage(url, referrer?)` sets it for an app opened by a link, or a server.
8
+
3
9
  ## 1.3.0
4
10
 
5
11
  - Two-step sign-in (public API 2.5). A sign-in throws `VeroXMTwoStepRequiredError` (a `VeroXMApiError`, code
package/README.md CHANGED
@@ -291,7 +291,13 @@ const stop = tracker.subscribe(() => rerenderExperiences());
291
291
  - **Consent:** before analytics consent it resolves to `'none'` with
292
292
  `waitingForConsent: true` and makes no request (a sticky assignment needs
293
293
  a stored visitor id, and the server records an exposure). Segment
294
- targeting additionally needs personalization consent.
294
+ targeting additionally needs personalization consent, except rules on
295
+ the visit's own campaign (`campaign.*`).
296
+ - **Campaigns:** in a browser the tracker sends the page the visit started
297
+ on and its referrer, so a variant can target `campaign.source`,
298
+ `campaign.channel`, a link tag like `campaign.param.tf_campaign`, and so
299
+ on, on the landing page itself. In an app opened by a link, call
300
+ `tracker.setLandingPage(url)` first (and `page({ url })` to record it).
295
301
  - **Journey messages:** a journey's in-app step can leave a message for
296
302
  this person on a placement. Then `d.reason === 'journey'` and the
297
303
  message fields are in `d.config` (e.g. `title`, `text`, `ctaLabel`,
@@ -3576,6 +3576,10 @@ export interface operations {
3576
3576
  userId?: string;
3577
3577
  /** @description Server keys: the person agreed to personalised content. */
3578
3578
  consent?: "personalization";
3579
+ /** @description The page the visit started on: campaign.* rules read its campaign (utm tags, ad click ids). The SDK sends it. */
3580
+ url?: string;
3581
+ /** @description The page that linked to it. */
3582
+ referrer?: string;
3579
3583
  };
3580
3584
  header?: never;
3581
3585
  path: {
package/dist/tracker.d.ts CHANGED
@@ -84,6 +84,8 @@ export declare class VeroxmTracker {
84
84
  private backoffMs;
85
85
  private retryAt;
86
86
  private decisions;
87
+ /** The page this visit started on, and what linked to it: /decide reads its campaign (campaign.* rules). */
88
+ private landing;
87
89
  private readonly listeners;
88
90
  constructor(options: TrackerOptions);
89
91
  /** The anonymous id for this browser/app install. */
@@ -107,6 +109,13 @@ export declare class VeroxmTracker {
107
109
  identifyAccount(accessToken: string, traits?: Record<string, unknown>): Promise<void>;
108
110
  /** Call on sign-out: starts a new anonymous visitor on this device. Consent answers are kept. */
109
111
  reset(): void;
112
+ /**
113
+ * The address the visit started from, for campaign targeting (campaign.* rules) when it isn't the browser's own
114
+ * page: an app opened by a link (a deep link or universal link with utm tags), or a server rendering for a visitor.
115
+ * Call it before getExperience; decisions already made are asked again. Record the visit itself with
116
+ * `page({ url })`, so the visitor's profile keeps the campaign too.
117
+ */
118
+ setLandingPage(url: string, referrer?: string): void;
110
119
  /**
111
120
  * Which variant of a placement this visitor sees, e.g.
112
121
  * `const d = await tracker.getExperience('home.hero')` -- then render
package/dist/tracker.js CHANGED
@@ -112,6 +112,8 @@ export class VeroxmTracker {
112
112
  this.backoffMs = 0;
113
113
  this.retryAt = 0;
114
114
  this.decisions = new Map();
115
+ /** The page this visit started on, and what linked to it: /decide reads its campaign (campaign.* rules). */
116
+ this.landing = null;
115
117
  this.listeners = new Set();
116
118
  this.apiBase = `${options.baseUrl.replace(/\/$/, '')}/public/v2/projects/${options.projectId}`;
117
119
  this.key = options.eventsKey;
@@ -125,6 +127,11 @@ export class VeroxmTracker {
125
127
  };
126
128
  this.consentState = this.readConsent();
127
129
  this.visitorId = this.store().get(this.keys.visitor) ?? uuid();
130
+ // Campaign attribution: in a browser, the page the visitor arrived on (with its utm tags and ad click ids) and the
131
+ // page that linked to it. Kept in memory for this page load only; a single-page app keeps it as people move around.
132
+ if (typeof window !== 'undefined' && window.location) {
133
+ this.landing = { url: window.location.href, referrer: typeof document !== 'undefined' ? document.referrer : '' };
134
+ }
128
135
  if (this.canPersist()) {
129
136
  this.store().set(this.keys.visitor, this.visitorId);
130
137
  setVisitorCookie(this.visitorId);
@@ -241,6 +248,16 @@ export class VeroxmTracker {
241
248
  }
242
249
  this.changed();
243
250
  }
251
+ /**
252
+ * The address the visit started from, for campaign targeting (campaign.* rules) when it isn't the browser's own
253
+ * page: an app opened by a link (a deep link or universal link with utm tags), or a server rendering for a visitor.
254
+ * Call it before getExperience; decisions already made are asked again. Record the visit itself with
255
+ * `page({ url })`, so the visitor's profile keeps the campaign too.
256
+ */
257
+ setLandingPage(url, referrer) {
258
+ this.landing = { url, referrer: referrer ?? '' };
259
+ this.decisions.clear();
260
+ }
244
261
  /**
245
262
  * Which variant of a placement this visitor sees, e.g.
246
263
  * `const d = await tracker.getExperience('home.hero')` -- then render
@@ -266,7 +283,11 @@ export class VeroxmTracker {
266
283
  const timeoutMs = options.timeoutMs ?? 1500;
267
284
  const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
268
285
  const timer = setTimeout(() => controller?.abort(), timeoutMs);
269
- const qs = `placement=${encodeURIComponent(placement)}&visitorId=${encodeURIComponent(this.visitorId)}`;
286
+ let qs = `placement=${encodeURIComponent(placement)}&visitorId=${encodeURIComponent(this.visitorId)}`;
287
+ if (this.landing?.url)
288
+ qs += `&url=${encodeURIComponent(this.landing.url.slice(0, 2000))}`;
289
+ if (this.landing?.referrer)
290
+ qs += `&referrer=${encodeURIComponent(this.landing.referrer.slice(0, 2000))}`;
270
291
  const request = fetch(`${this.apiBase}/decide?${qs}`, {
271
292
  headers: { Authorization: `Bearer ${this.key}` },
272
293
  ...(controller ? { signal: controller.signal } : {}),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@veroxm/sdk",
3
- "version": "1.3.0",
3
+ "version": "1.4.0",
4
4
  "description": "VeroXM client for JavaScript and TypeScript: content, media, experiences, events and the visitor tracker.",
5
5
  "keywords": [
6
6
  "veroxm",