@ohos-ports/s-ui-segment-wrapper 0.0.0-stage → 5.4.0-beta.0

package/README.md

@@ -1,3 +1,270 @@
-# Temporary Holding Version
+# Segment Wrapper
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This package adds an abstraction layer on top of [segment.com](https://segment.com/)'s [JavaScript library](https://segment.com/docs/sources/website/analytics.js/) with some useful integrations and fixes:
+
+**Data Quality 📈**
+
+- [x] Add `page` method that internally uses `track` but with the correct `referrer` property.
+- [x] Send `user.id` and `anonymousId` on every track.
+
+**Consent Management Platform 🐾**
+
+- [x] Automatic tracking of Consent Management Platform usage.
+- [x] Send `gdpr_privacy` on `context` for for all tracking events. Expect values: `unknown`, `accepted` and `declined`.
+- [x] Send `gdpr_privacy_advertising` on `context` for for all tracking events. Expect values: `unknown`, `accepted` and `declined`.
+- [x] `gdpr_privacy` is accepted when consents [1, 8, 10] are accepted and `gdpr_privacy_advertising` is accepted when consents [3] is accepted.
+- [x] Any track is sent if the user has not accepted/rejected any consent yet.
+
+**Developer Experience 👩‍💻**
+
+- [x] Always send `platform` property as `web`.
+- [x] Allow to configure `window.__mpi.defaultContext` to send these properties on all tracks inside the context object.
+- [x] Allow to configure `window.__mpi.defaultProperties` to send these properties on all tracks.
+
+**Segment Middlewares 🖖**
+
+- [x] Optimizely Full Stack middleware to use Segment's anonymousId as Optimizely's userId, more info [here](#optimizelys-userid).
+
+## Usage
+
+After adding your Segment snippet into your html, you'll need to include this package in order to be able to fire events.
+
+`analytics` will be an object with the methods described [here](#events).
+
+### Step 1: Copy the Snippet in your HTML
+
+```html
+<script>
+  !(function () {
+    var analytics = (window.analytics = window.analytics || [])
+    if (!analytics.initialize)
+      if (analytics.invoked) window.console && console.error && console.error('Segment snippet included twice.')
+      else {
+        analytics.invoked = !0
+        analytics.methods = [
+          'trackSubmit',
+          'trackClick',
+          'trackLink',
+          'trackForm',
+          'pageview',
+          'identify',
+          'reset',
+          'group',
+          'track',
+          'ready',
+          'alias',
+          'debug',
+          'page',
+          'once',
+          'off',
+          'on',
+          'addSourceMiddleware',
+          'addIntegrationMiddleware',
+          'setAnonymousId',
+          'addDestinationMiddleware'
+        ]
+        analytics.factory = function (e) {
+          return function () {
+            var t = Array.prototype.slice.call(arguments)
+            t.unshift(e)
+            analytics.push(t)
+            return analytics
+          }
+        }
+        for (var e = 0; e < analytics.methods.length; e++) {
+          var key = analytics.methods[e]
+          analytics[key] = analytics.factory(key)
+        }
+        analytics.load = function (key, e) {
+          var t = document.createElement('script')
+          t.type = 'text/javascript'
+          t.async = !0
+          t.src = 'https://cdn.segment.com/analytics.js/v1/' + key + '/analytics.min.js'
+          var n = document.getElementsByTagName('script')[0]
+          n.parentNode.insertBefore(t, n)
+          analytics._loadOptions = e
+        }
+        analytics._writeKey = 'YOUR_WRITE_KEY'
+        analytics.SNIPPET_VERSION = '4.13.2'
+
+        analytics.load('YOUR_WRITE_KEY') // your write key must be set here
+      }
+  })()
+</script>
+```
+
+### Step 2: Use
+
+#### In your modern and beautiful JavaScript...
+
+```js
+import analytics from '@s-ui/segment-wrapper'
+```
+
+### In your monolithic JavaScript...
+
+```js
+// First load the UMD module.
+<script src="https://unpkg.com/@s-ui/segment-wrapper/umd/index.js"></script>
+<script>
+  // Then trigger all the events you need referencing the right namespaced
+  // object: `window.sui.analytics`. For more info see the "Events" section below.
+  window.sui.analytics.identify('your user id', {});
+  window.sui.analytics.track('your event', {});
+  window.sui.analytics.reset();
+</script>
+```
+
+### Step 3: Configure Segment Wrapper (optional)
+
+You could put a special config in a the `window.__mpi` to change some behaviour of the wrapper. This config MUST somewhere before using the Segment Wrapper.
+
+- `defaultContext`: _(optional)_ If set, properties will be merged and sent with every `track` and `page` in the **context object**. It's the ideal place to put the `site` and `vertical` info to make sure that static info will be sent along with all the tracking.
+- `defaultProperties`: _(optional)_ If set, properties will be merged and sent with every `track` and `page`.
+- `tcfTrackDefaultProperties` _(optional)_ If set, this property will be merged together with the default properties set to send with every tcf track event
+- `universalId`: _(optional)_ If set this value will be used for the Visitor API and other services.
+- `hashedUserEmail`: _(optional)_ If set and not `universalId` is set this value will be used for the Visitor API and other services.
+- `userEmail`: _(optional)_ If set and not `universalId` is available, this value will be hashed with SHA-256 and used for the Visitor API and other services.
+- `isUserTraitsEnabled`: _(optional)_ If set context traits will be populated with all user traits.
+- `userIdPrefix`: _(optional)_ If set, the user id will be prefixed with this string for identify events.
+
+Example:
+
+```js
+window.__mpi = {
+  segmentWrapper: {
+    universalId: '7ab9ddf3281d5d5458a29e8b3ae2864',
+    defaultContext: {
+      site: 'patinetes',
+      vertical: 'motor'
+    },
+    tcfTrackDefaultProperties: {
+      tcfSpecialProp: 'anyvalue'
+    }
+  }
+}
+```
+
+### It also provides additional information such as:
+
+- window.\_\_mpi.isFirstVisit: boolean - true if the user hasn't interacted with the tcf modal yet
+
+## Events
+
+### Track - [docs](https://segment.com/docs/spec/track/)
+
+```js
+import analytics from '@s-ui/segment-wrapper'
+
+analytics.track('CTA Clicked')
+
+analytics.track('Registered', {
+  plan: 'Pro Annual',
+  accountType: 'Facebook'
+})
+```
+
+### Page
+
+Internally uses `Track` but changes the `referrer` everytime is called.
+
+```js
+import analytics from '@s-ui/segment-wrapper'
+
+analytics.page('Home Viewed')
+
+analytics.page('List Viewed', {
+  property: 'HOUSE',
+  transaction: 'SELL'
+})
+```
+
+### Identify - [docs](https://segment.com/docs/spec/identify/)
+
+```js
+import analytics from '@s-ui/segment-wrapper'
+
+analytics.identify('97980cfea0067', {
+  name: 'Peter Gibbons',
+  email: 'peter@initech.com',
+  plan: 'premium',
+  logins: 5
+})
+```
+
+### Reset - [docs](https://segment.com/docs/sources/website/analytics.js/#reset-logout)
+
+```js
+import analytics from '@s-ui/segment-wrapper'
+
+analytics.reset()
+```
+
+## UniversalID
+
+_Segment Wrapper_ is handling all about the UniversalID, an ID to identify the user across different sites by using a hashed email. If you want, you could subscribe yourself to an event in order to retrieve this info:
+
+```js
+document.addEventListener(USER_DATA_READY_EVENT, e => {
+  const {universalId} = e.detail
+})
+```
+
+Also, you could check directly if the `universalId` is already available on the window:
+
+```js
+const {universalId} = window.__mpi.segmentWrapper
+```
+
+Or use both systems:
+
+```js
+let {universalId, universalIdInitialized} = window.__mpi.segmentWrapper
+
+if (!universalId && !universalIdInitialized) {
+  document.addEventListener(USER_DATA_READY_EVENT, e => {
+    universalId = e.detail.universalId
+    doSomethingWithUniversalId(universalId)
+  })
+}
+
+console.log(universalId)
+```
+
+### Send xandrId as externalIds
+
+To not send the `xandrId` put this flag as configuration: `window.__mpi.segmentWrapper.sendXandrId = false`
+
+By default, all xandrId will be sent.
+
+## Middlewares
+
+You can find info about segment's middleware [here](https://segment.com/docs/connections/sources/catalog/libraries/website/javascript/middleware/)
+
+### Optimizely's userId
+
+Will use segment's anonymousId as optimizely's userId
+
+#### How to
+
+```js
+import {optimizelyUserId} from '@s-ui/segment-wrapper/lib/middlewares/source/optimizelyUserId'
+
+window.analytics.ready(() => {
+  window.analytics.addSourceMiddleware(optimizelyUserId)
+})
+```
+
+### Optimizely's site attribute
+
+Will add the site property as optimizely attribute
+
+#### How to
+
+```js
+import {optimizelySiteAttributeMiddleware} from '@s-ui/segment-wrapper/lib/middlewares/destination/optimizelySiteAttribute'
+
+window.analytics.ready(() => {
+  window.analytics.addDestinationMiddleware('Optimizely', [optimizelySiteAttributeMiddleware])
+})
+```

package/lib/config.js

@@ -0,0 +1,20 @@
+var MPI_CONFIG_KEY = "__mpi";
+export var isClient = typeof window !== "undefined";
+/**
+ * Get the Segment Wrapper config from window
+ * @param {string=} key Key config to extract. If not provided, all the config will be returned
+ * @return {any} Config value or all the config if not key provided
+ */ export var getConfig = function(key) {
+    var ref;
+    var config = (window == null ? void 0 : (ref = window[MPI_CONFIG_KEY]) == null ? void 0 : ref.segmentWrapper) || {};
+    return key ? config[key] : config;
+};
+/**
+ * Set a config value to the Segment Wrapper config
+ * @param {string} key Config key to update
+ * @param {boolean|string|number|object} value Value to set on the config key
+ */ export var setConfig = function(key, value) {
+    window[MPI_CONFIG_KEY] = window[MPI_CONFIG_KEY] || {};
+    window[MPI_CONFIG_KEY].segmentWrapper = window[MPI_CONFIG_KEY].segmentWrapper || {};
+    window[MPI_CONFIG_KEY].segmentWrapper[key] = value;
+};

package/lib/events.js

@@ -0,0 +1,3 @@
+export var EVENTS = {
+    GA4_INIT_EVENT_SENT: "ga4InitEventSent"
+};

package/lib/index.js

@@ -0,0 +1,82 @@
+import _extends from "@swc/helpers/src/_extends.mjs";
+import "./utils/patchAnalytics.js";
+import { campaignContext } from "./middlewares/source/campaignContext.js";
+import { pageData } from "./middlewares/source/pageData.js";
+import { defaultContextProperties } from "./middlewares/source/defaultContextProperties.js";
+import { pageReferrer } from "./middlewares/source/pageReferrer.js";
+import { userScreenInfo } from "./middlewares/source/userScreenInfo.js";
+import { userTraits } from "./middlewares/source/userTraits.js";
+import { DEFAULT_DATA_LAYER_NAME, getCampaignDetails, loadGoogleAnalytics, sendGoogleConsents } from "./repositories/googleRepository.js";
+import { checkAnonymousId } from "./utils/checkAnonymousId.js";
+import { isGA4DestinationEnabled } from "./utils/ga4Detection.js";
+import { getConfig, isClient } from "./config.js";
+import analytics from "./segmentWrapper.js";
+import initTcfTracking from "./tcf.js";
+import { getUserDataAndNotify } from "./universalId.js";
+// Initialize TCF Tracking with Segment
+initTcfTracking();
+// Generate UniversalId if available
+try {
+    getUserDataAndNotify();
+} catch (e) {
+    console.error("[segment-wrapper] UniversalID couldn't be initialized") // eslint-disable-line
+    ;
+}
+// Initialize middlewares
+var addMiddlewares = function() {
+    var experimentalPageDataMiddleware = getConfig("experimentalPageDataMiddleware");
+    window.analytics.addSourceMiddleware(userTraits);
+    window.analytics.addSourceMiddleware(defaultContextProperties);
+    window.analytics.addSourceMiddleware(campaignContext);
+    window.analytics.addSourceMiddleware(userScreenInfo);
+    window.analytics.addSourceMiddleware(pageReferrer);
+    if (experimentalPageDataMiddleware) {
+        window.analytics.addSourceMiddleware(pageData);
+    }
+};
+if (isClient && window.analytics) {
+    // Check GA4 mode synchronously to avoid delaying initialization
+    var useSegmentGA4Destination = isGA4DestinationEnabled();
+    // Only initialize manual GA4 if destination is not enabled (legacy mode)
+    // This runs synchronously to ensure GA4 is ready for first events
+    if (!useSegmentGA4Destination) {
+        // Legacy behavior: Initialize Google Analytics manually
+        var googleAnalyticsMeasurementId = getConfig("googleAnalyticsMeasurementId");
+        var dataLayerName = getConfig("googleAnalyticsDataLayer") || DEFAULT_DATA_LAYER_NAME;
+        var needsConsentManagement = getConfig("googleAnalyticsConsentManagement");
+        if (googleAnalyticsMeasurementId) {
+            var googleAnalyticsConfig = getConfig("googleAnalyticsConfig");
+            window[dataLayerName] = window[dataLayerName] || [];
+            window.gtag = window.gtag || function gtag() {
+                window[dataLayerName].push(arguments);
+            };
+            window.gtag("js", new Date());
+            if (needsConsentManagement) sendGoogleConsents();
+            window.gtag("config", googleAnalyticsMeasurementId, _extends({
+                cookie_prefix: "segment",
+                send_page_view: false
+            }, googleAnalyticsConfig, getCampaignDetails()));
+            loadGoogleAnalytics().catch(function(error) {
+                console.error(error);
+            });
+        }
+    }
+    window.analytics.ready(checkAnonymousId);
+    window.analytics.addSourceMiddleware ? addMiddlewares() : window.analytics.ready(addMiddlewares);
+}
+export default analytics;
+export { getGoogleClientId, getGoogleSessionId } from "./repositories/googleRepository.js";
+export { getUniversalId } from "./universalId.js";
+export { EVENTS } from "./events.js";
+// Deprecated Adobe Analytics functions - kept for backwards compatibility
+// @deprecated Adobe Analytics integration has been removed
+export var getAdobeVisitorData = function() {
+    return Promise.resolve({
+        trackingServer: "",
+        version: ""
+    });
+};
+// @deprecated Adobe Analytics integration has been removed
+export var getAdobeMCVisitorID = function() {
+    return Promise.resolve("");
+};

package/lib/middlewares/destination/optimizelySiteAttribute.js

@@ -0,0 +1,17 @@
+import _extends from "@swc/helpers/src/_extends.mjs";
+export var optimizelySiteAttributeMiddleware = function(param) {
+    var payload = param.payload, next = param.next;
+    var ref;
+    var _obj = payload.obj, integrations = _obj.integrations, context = _obj.context;
+    if (!context.site) {
+        return next(payload);
+    }
+    payload.obj.integrations = _extends({}, integrations, {
+        Optimizely: _extends({}, integrations.Optimizely, {
+            attributes: _extends({
+                site: context.site
+            }, (ref = integrations.Optimizely) == null ? void 0 : ref.attributes)
+        })
+    });
+    next(payload);
+};

package/lib/middlewares/source/campaignContext.js

@@ -0,0 +1,10 @@
+import _extends from "@swc/helpers/src/_extends.mjs";
+import { getCampaignDetails } from "../../repositories/googleRepository.js";
+export var campaignContext = function(param) {
+    var payload = param.payload, next = param.next;
+    var campaignDetails = getCampaignDetails({
+        needsTransformation: false
+    });
+    payload.obj.context = _extends({}, payload.obj.context, campaignDetails);
+    next(payload);
+};

package/lib/middlewares/source/defaultContextProperties.js

@@ -0,0 +1,11 @@
+import _extends from "@swc/helpers/src/_extends.mjs";
+import { getConfig } from "../../config.js";
+var DEFAULT_CONTEXT = {
+    platform: "web"
+};
+export var defaultContextProperties = function(param) {
+    var payload = param.payload, next = param.next;
+    var defaultContext = getConfig("defaultContext") || {};
+    payload.obj.context = _extends({}, DEFAULT_CONTEXT, defaultContext, payload.obj.context);
+    next(payload);
+};

package/lib/middlewares/source/optimizelyUserId.js

@@ -0,0 +1,15 @@
+import _extends from "@swc/helpers/src/_extends.mjs";
+export var optimizelyUserId = function(param) {
+    var payload = param.payload, next = param.next;
+    var integrations = payload.obj.integrations;
+    // when integrations.All equals false, destinations are deactivated
+    if (integrations.All === false) {
+        return next(payload);
+    }
+    payload.obj.integrations = _extends({}, integrations, {
+        Optimizely: _extends({
+            userId: window.analytics.user().anonymousId()
+        }, integrations.Optimizely)
+    });
+    next(payload);
+};

package/lib/middlewares/source/pageData.js

@@ -0,0 +1,42 @@
+import _extends from "@swc/helpers/src/_extends.mjs";
+export var createPageDataMiddleware = function() {
+    var last = null;
+    return function(param) {
+        var payload = param.payload, next = param.next;
+        try {
+            var ref;
+            var obj = payload.obj;
+            var event = obj.event, type = obj.type;
+            if (type !== "track") {
+                next(payload);
+                return;
+            }
+            if (typeof event === "string" && event.endsWith("Viewed")) {
+                var ref1 = obj.properties || {}, name = ref1.page_name, type1 = ref1.page_type;
+                last = {
+                    name: name,
+                    type: type1
+                };
+                next(payload);
+                return;
+            }
+            if (!last) {
+                next(payload);
+                return;
+            }
+            next(_extends({}, payload, {
+                obj: _extends({}, obj, {
+                    properties: _extends({}, obj.properties, {
+                        page_name_origin: last.name,
+                        page_type: ((ref = obj.properties) == null ? void 0 : ref.page_type) || last.type
+                    })
+                })
+            }));
+        } catch (error) {
+            console.error(error) // eslint-disable-line
+            ;
+            next(payload);
+        }
+    };
+};
+export var pageData = createPageDataMiddleware();

package/lib/middlewares/source/pageReferrer.js

@@ -0,0 +1,102 @@
+import _extends from "@swc/helpers/src/_extends.mjs";
+import { isGA4DestinationEnabled } from "../../utils/ga4Detection.js";
+/**
+ * Capture document.referrer at module load time, before Safari ITP can clear it.
+ * This ensures the first page event has the real referrer from the external source.
+ */ export var INITIAL_DOCUMENT_REFERRER = typeof document !== "undefined" ? document.referrer : "";
+/**
+ * Capture window.location.search at module load time, before Safari ITP can
+ * strip tracking parameters via redirects.
+ */ export var INITIAL_SEARCH_STRING = typeof window !== "undefined" ? window.location.search : "";
+/**
+ * Capture initial URL at module load time
+ */ var INITIAL_URL = typeof window !== "undefined" ? window.location.href : "";
+export var referrerState = {
+    spaReferrer: "",
+    referrer: INITIAL_DOCUMENT_REFERRER,
+    isFirstPageViewSent: false
+};
+/**
+ * Useful wrapper around document and window objects
+ */ export var utils = {
+    /**
+   * @returns {string} The referrer of the document
+   */ getDocumentReferrer: function() {
+        return document.referrer;
+    },
+    /**
+   * @returns {string} The actual location with protocol, domain and pathname
+   */ getActualLocation: function() {
+        var _location = window.location, origin = _location.origin, pathname = _location.pathname;
+        return "" + origin + pathname;
+    },
+    /**
+   * @returns {string} The actual query string captured at module load (protected from Safari ITP)
+   */ getActualQueryString: function() {
+        // In tests using window.history.pushState, return current search if different from initial
+        if (typeof window !== "undefined" && window.location.search && window.location.search !== INITIAL_SEARCH_STRING) {
+            return window.location.search;
+        }
+        return INITIAL_SEARCH_STRING;
+    }
+};
+/**
+ * Get the correct page referrer for SPA navigations
+ * @returns {string}  referrer
+ */ export var getPageReferrer = function(param) {
+    var ref = param === void 0 ? {} : param, _isPageTrack = ref.isPageTrack, isPageTrack = _isPageTrack === void 0 ? false : _isPageTrack;
+    var referrer = referrerState.referrer, spaReferrer = referrerState.spaReferrer;
+    if (isPageTrack) {
+        // For page events, use referrer (initially from INITIAL_DOCUMENT_REFERRER, then from previous page location)
+        return referrer;
+    } else {
+        // For track events, use spaReferrer if available, otherwise fall back to referrer
+        // This handles the case where a track happens before the first page event
+        return spaReferrer || referrer;
+    }
+};
+/**
+ * Update page referrer for SPA navigations
+ */ export var updatePageReferrer = function() {
+    referrerState.spaReferrer = getPageReferrer({
+        isPageTrack: true
+    });
+    // mutate actualReferrer with what will be the new referrer
+    referrerState.referrer = utils.getActualLocation();
+};
+/**
+ * @param {object} params
+ * @param {{obj: {context: object }}} params.payload
+ * @param {function} params.next
+ * @returns {void}
+ */ export var pageReferrer = function(param) {
+    var payload = param.payload, next = param.next;
+    var context = payload.obj.context;
+    var isPageTrack = context.isPageTrack;
+    var referrer = getPageReferrer({
+        isPageTrack: isPageTrack
+    });
+    var props = {};
+    if (isPageTrack && !referrerState.isFirstPageViewSent) {
+        referrerState.isFirstPageViewSent = true;
+        props = {
+            url: INITIAL_URL,
+            search: INITIAL_SEARCH_STRING
+        };
+    }
+    payload.obj.context = _extends({}, context, {
+        page: _extends({}, context.page, props, {
+            referrer: referrer
+        })
+    });
+    // In NEW mode (client-side destination), also add referrer to properties
+    // GA4 Web destination uses properties.page_referrer for attribution
+    if (referrer && isGA4DestinationEnabled()) {
+        payload.obj.properties = _extends({}, payload.obj.properties, {
+            page_referrer: referrer
+        });
+    }
+    // update page referrer only if it's a page event
+    isPageTrack && updatePageReferrer();
+    next(payload);
+};

package/lib/middlewares/source/userScreenInfo.js

@@ -0,0 +1,12 @@
+import _extends from "@swc/helpers/src/_extends.mjs";
+export var userScreenInfo = function(param) {
+    var payload = param.payload, next = param.next;
+    payload.obj.context = _extends({}, payload.obj.context, {
+        screen: {
+            height: window.innerHeight,
+            width: window.innerWidth,
+            density: window.devicePixelRatio
+        }
+    });
+    next(payload);
+};

package/lib/middlewares/source/userTraits.js

@@ -0,0 +1,48 @@
+import _async_to_generator from "@swc/helpers/src/_async_to_generator.mjs";
+import _extends from "@swc/helpers/src/_extends.mjs";
+import _ts_generator from "@swc/helpers/src/_ts_generator.mjs";
+import { getConfig } from "../../config.js";
+import { checkAnalyticsGdprIsAccepted, getGdprPrivacyValue } from "../../tcf.js";
+/**
+ * Get user traits from global analytics object and put in the object
+ * @param {string} gdprPrivacyValue Determine if we have user consents
+ * @returns {object} User traits with to add
+ */ var getUserTraits = function(gdprPrivacyValue) {
+    var isUserTraitsEnabled = getConfig("isUserTraitsEnabled");
+    var user = window.analytics.user();
+    var isGdprAccepted = checkAnalyticsGdprIsAccepted(gdprPrivacyValue);
+    var userId = user.id();
+    return _extends({
+        anonymousId: user.anonymousId()
+    }, userId && {
+        userId: userId
+    }, isGdprAccepted && isUserTraitsEnabled && user.traits());
+};
+export var userTraits = /*#__PURE__*/ _async_to_generator(function(param) {
+    var payload, next, gdprPrivacyValue, userTraits;
+    return _ts_generator(this, function(_state) {
+        switch(_state.label){
+            case 0:
+                payload = param.payload, next = param.next;
+                return [
+                    4,
+                    getGdprPrivacyValue()
+                ];
+            case 1:
+                gdprPrivacyValue = _state.sent();
+                try {
+                    userTraits = getUserTraits(gdprPrivacyValue);
+                } catch (error) {
+                    console.error(error) // eslint-disable-line
+                    ;
+                }
+                payload.obj.context = _extends({}, payload.obj.context, {
+                    traits: _extends({}, payload.obj.context.traits, userTraits)
+                });
+                next(payload);
+                return [
+                    2
+                ];
+        }
+    });
+});