feat(tracker): add currency context, add transactionTotal to order tr…

docs/INTEGRATION_CONTEXT.md

@@ -10,16 +10,17 @@ There are a few core context variables utilized by Snap, `shopper`, `merchandisi
 |---|---|:---:|---|
 | shopper.id | logged in user unique identifier | all | required for personalization functionallity |
 | shopper.cart | array of cart objects, each object in the array can contain `sku` and/or `childSku` | all | current cart contents, required if checkout process does not contain a dedicated cart page (ie. slideout cart) |
+| currency.code | currency code string, ie. 'EUR' (ISO 4217) | all | currency code of the shopper's cart contents or order confirmation. Used for beacon events containing pricing data |
 | merchandising.segments | array of strings used for merchandising | any | segmented merchandising allows for custom control over products returned on search requests and must also be setup within the Searchspring Management Console (SMC) |
 | config | object containing Snap configurations | any | advanced usage of Snap (not recommended for standard integrations) |
 
 ## Examples
 
-The custom variable example below shows a custom context being added for 'region'. The value would typically be assigned server side using template logic. This would be used to possibly toggle the siteId utilized by the client (to fetch different catalog data) or to modify text or currency displays.
+The custom variable example below shows a custom context being added for 'page'. The value would typically be assigned server side using template logic. This would be used to possibly toggle the siteId utilized by the client (to fetch different catalog data) or to modify text or currency displays.
 
 ```html
 <script src="https://snapui.searchspring.io/[your_site_id]/bundle.js">
-	region = "US";
+	page = "404";
 </script>
 ```
 
@@ -36,6 +37,9 @@ When used, shopper context should always include at least an `id`; the `cart` co
 			}
 		]
 	};
+	currency = {
+		code: 'EUR'
+	};
 </script>
 ```
 
@@ -53,12 +57,15 @@ Example using multiple context variables together.
 
 ```html
 <script src="https://snapui.searchspring.io/[your_site_id]/bundle.js">
-	region = "CAD";
+	page = "404";
 	shopper = {
 		id: '[email protected]'
 	};
 	merchandising = {
 		segments: ['country:canada']
 	};
+	currency = {
+		code: 'EUR'
+	};
 </script>
 ```

docs/INTEGRATION_TRACKING.md

@@ -93,7 +93,9 @@ Tracks order transaction. Should be invoked from an order confirmation page. Exp
 
 `order.id` - (optional) order id
 
-`order.otal` - (optional) sub total of all items
+`order.total` - (optional) transaction total of all items after tax and shipping
+
+`order.transactionTotal` - (optional) transaction total of all items before tax and shipping
 
 `order.city` - (optional) city name
 
@@ -107,7 +109,8 @@ Tracks order transaction. Should be invoked from an order confirmation page. Exp
 <script type="searchspring/track/order/transaction">
 	order = {
 		id: '123456',
-		total: '31.97',
+		total: '34.29',
+		transactionTotal: '31.97',
 		city: 'Los Angeles',
 		state: 'CA',
 		country: 'US',
@@ -135,7 +138,8 @@ Alternatively, this can also be integrated using the `searchspring.tracker.track
 searchspring.tracker.track.order.transaction({
 	order: {
 		id: '123456',
-		total: '31.97',
+		total: '34.29',
+		transactionTotal: '31.97',
 		city: 'Los Angeles',
 		state: 'CA',
 		country: 'US',

packages/snap-preact/src/Snap.tsx

@@ -308,7 +308,7 @@ export class Snap {
 		let globalContext: ContextVariables = {};
 		try {
 			// get global context
-			globalContext = getContext(['shopper', 'config', 'merchandising', 'siteId']);
+			globalContext = getContext(['shopper', 'config', 'merchandising', 'siteId', 'currency']);
 		} catch (err) {
 			console.error('Snap failed to find global context');
 		}
@@ -394,7 +394,14 @@ export class Snap {
 			this.logger = services?.logger || new Logger({ prefix: 'Snap Preact ', mode: this.mode });
 
 			// create tracker
-			const trackerGlobals = this.config.tracker?.globals || (this.config.client!.globals as ClientGlobals);
+			let trackerGlobals = this.config.tracker?.globals || (this.config.client!.globals as ClientGlobals);
+
+			if (this.context.currency?.code) {
+				trackerGlobals = deepmerge(trackerGlobals || {}, {
+					currency: this.context.currency,
+				});
+			}
+
 			const trackerConfig = deepmerge(this.config.tracker?.config || {}, { framework: 'preact', mode: this.mode });
 			this.tracker = services?.tracker || new Tracker(trackerGlobals, trackerConfig);
 

packages/snap-tracker/README.md

@@ -116,7 +116,8 @@ This method will call the `retarget` method on all `DomTargeters` set in the Tra
 <script type="searchspring/track/order/transaction">
     order = {
         id: '123456',
-        total: '31.97',
+        total: '34.29',
+		transactionTotal: '31.97',
         city: 'Los Angeles',
         state: 'CA',
         country: 'US',
@@ -192,6 +193,8 @@ A beacon event payload object provided to the `track.event` method may contain t
 
 `context.website.trackingCode` - optional `context` object that will be merged with constructed context object. Can be used to specify a different `siteId` value.
 
+`context.currency.code` - optional `context` object that will be merged with constructed context object. Can be used to specify a different `currency` value.
+
 ```typescript
 const payload = {
     type: BeaconType.CLICK,
@@ -205,6 +208,9 @@ const payload = {
         website: {
             trackingCode: 'abc123',
         },
+        currency: {
+            code: 'USD',
+        },
     },
 };
 
@@ -311,7 +317,9 @@ Tracks order transaction. Should be invoked from an order confirmation page. Exp
 
 `order.id` - (optional) order id
 
-`order.otal` - (optional) sub total of all items
+`order.total` - (optional) transaction total of all items after tax and shipping
+
+`order.transactionTotal` - (optional) transaction total of all items before tax and shipping
 
 `order.city` - (optional) city name
 
@@ -325,7 +333,8 @@ Tracks order transaction. Should be invoked from an order confirmation page. Exp
 tracker.track.order.transaction({
     order: {
         id: '123456',
-        total: '31.97',
+        total: '34.29',
+        transactionTotal: '31.97',
         city: 'Los Angeles',
         state: 'CA',
         country: 'US',
@@ -350,10 +359,10 @@ tracker.track.order.transaction({
 ## Tracker properties
 
 ### `globals` property
-When constructing an instance of `Tracker`, a globals object is required to be constructed. This object contains a `siteId` key and value. 
+When constructing an instance of `Tracker`, a globals object is required to be constructed. This object contains a `siteId` key and value. An optional `currency` object with a `code` property containing a string can be provided. 
 
 ```typescript
-const globals = { siteId: 'abc123' };
+const globals = { siteId: 'abc123', currency: { code: 'EUR' } };
 const tracker = new Tracker(globals);
 console.log(tracker.globals === globals) // true
 ```
@@ -381,6 +390,8 @@ The `context` property is generated at the time of instantiating Tracker. It is
 
 `website.trackingCode` - the `siteId` specified in the globals object
 
+`currency.code` - the optional `currency` specified in the globals object
+
 ```typescript
 context: {
     userId: '0560d7e7-148a-4b1d-b12c-924f164d3d00',
@@ -390,6 +401,9 @@ context: {
     website: {
         trackingCode: 'abc123',
     },
+    currency: {
+        code: 'USD',
+    },
 }
 ```
 
@@ -402,6 +416,16 @@ The `namespace` property contains the Tracker namespace. Invoking this method is
 ### `track` property
 The `track` property contains various tracking events. See `track` methods section above.
 
+### `setCurrency` method
+Sets the currency code on the tracker context.
+
+```typescript
+const tracker = new Tracker();
+
+tracker.setCurrency({ code: 'EUR' })
+```
+
+
 ### `getUserId` method
 Returns an object containing the `userId` stored in the `ssUserId` cookie (with a fallback to localstorage.) If key doesn't exist, a new ID will be generated, saved to cookie/localstorage, and returned. 
 

packages/snap-tracker/src/BeaconEvent.test.ts

@@ -73,6 +73,9 @@ describe('BeaconEvent', () => {
 				website: {
 					trackingCode: '8uyt2m',
 				},
+				currency: {
+					code: 'USD',
+				},
 			},
 			event: [
 				{
@@ -109,10 +112,14 @@ describe('BeaconEvent', () => {
 				website: {
 					trackingCode: '8uyt2m',
 				},
+				currency: {
+					code: 'USD',
+				},
 			},
 			event: {
 				orderId: '123456',
-				total: '42.96',
+				total: '34.29',
+				transactionTotal: '31.97',
 				city: 'Los Angeles',
 				state: 'CA',
 				country: 'US',

packages/snap-tracker/src/PixelEvent.test.ts

@@ -42,6 +42,9 @@ describe('PixelEvent', () => {
 				website: {
 					trackingCode: '8uyt2m',
 				},
+				currency: {
+					code: 'USD',
+				},
 			},
 			event: {
 				items: [
@@ -64,6 +67,7 @@ describe('PixelEvent', () => {
 
 		expect(event.event).toStrictEqual(data.event);
 		expect(event.src).toContain('&a=basket');
+		expect(event.src).toContain(`&currencyCode=${encodeURIComponent(data.context.currency.code)}`);
 		expect(event.src).toContain(event.endpoint);
 
 		data.event.items.forEach((cartItem) => {
@@ -87,10 +91,14 @@ describe('PixelEvent', () => {
 				website: {
 					trackingCode: '8uyt2m',
 				},
+				currency: {
+					code: 'USD',
+				},
 			},
 			event: {
 				orderId: '123456',
-				total: '42.96',
+				total: '34.29',
+				transactionTotal: '31.97',
 				city: 'Los Angeles',
 				state: 'CA',
 				country: 'US',
@@ -114,6 +122,7 @@ describe('PixelEvent', () => {
 
 		expect(event.event).toStrictEqual(data.event);
 		expect(event.src).toContain('&a=sale');
+		expect(event.src).toContain(`&currencyCode=${encodeURIComponent(data.context.currency.code)}`);
 		expect(event.src).toContain(event.endpoint);
 		expect(event.src.split('&item=')).toHaveLength(data.event.items.length + 1);
 
@@ -125,6 +134,7 @@ describe('PixelEvent', () => {
 
 		expect(event.src).toContain(`&orderId=${encodeURIComponent(data.event.orderId)}`);
 		expect(event.src).toContain(`&total=${encodeURIComponent(data.event.total)}`);
+		expect(event.src).toContain(`&transactionTotal=${encodeURIComponent(data.event.transactionTotal)}`);
 		expect(event.src).toContain(`&city=${encodeURIComponent(data.event.city)}`);
 		expect(event.src).toContain(`&state=${encodeURIComponent(data.event.state)}`);
 		expect(event.src).toContain(`&country=${encodeURIComponent(data.event.country)}`);

packages/snap-tracker/src/PixelEvent.ts

@@ -20,6 +20,10 @@ export class PixelEvent {
 			`&x=${Math.floor(Math.random() * 2147483647)}` +
 			`${window.document.referrer ? `&r=${encodeURIComponent(window.document.referrer)}` : ''}`;
 
+		if (payload?.context?.currency?.code) {
+			this.src += `&currencyCode=${encodeURIComponent(payload?.context?.currency?.code)}`;
+		}
+
 		switch (payload.category) {
 			case BeaconCategory.PAGEVIEW:
 				this.event = payload.event as ProductViewEvent;
@@ -38,10 +42,11 @@ export class PixelEvent {
 				});
 				break;
 			case BeaconCategory.ORDERVIEW:
-				const { orderId, total, city, state, country, items } = (this.event = payload.event as OrderTransactionEvent);
+				const { orderId, total, transactionTotal, city, state, country, items } = (this.event = payload.event as OrderTransactionEvent);
 				this.src += `&a=sale`;
 				if (orderId) this.src += `&orderId=${encodeURIComponent(orderId)}`;
 				if (total) this.src += `&total=${encodeURIComponent(total)}`;
+				if (transactionTotal) this.src += `&transactionTotal=${encodeURIComponent(transactionTotal)}`;
 				if (city) this.src += `&city=${encodeURIComponent(city)}`;
 				if (state) this.src += `&state=${encodeURIComponent(state)}`;
 				if (country) this.src += `&country=${encodeURIComponent(country)}`;