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

package/src/segmentWrapper.js

@@ -0,0 +1,338 @@
+// @ts-check
+
+import {
+  CONSENT_STATES,
+  getConsentState,
+  getGoogleClientId,
+  getGoogleConsentValue,
+  getGoogleSessionId,
+  sendGoogleConsents,
+  setGoogleUserId
+} from './repositories/googleRepository.js'
+import {getXandrId} from './repositories/xandrRepository.js'
+import {getConfig} from './config.js'
+import {USER_GDPR, CMP_TRACK_EVENT, checkAnalyticsGdprIsAccepted, getGdprPrivacyValue} from './tcf.js'
+import {isGA4DestinationEnabled} from './utils/ga4Detection.js'
+
+/* Default properties to be sent on all trackings */
+const DEFAULT_PROPERTIES = {platform: 'web'}
+
+/* Disabled integrations when no GDPR Privacy Value is true */
+export const INTEGRATIONS_WHEN_NO_CONSENTS = {
+  All: false
+}
+
+export const INTEGRATIONS_WHEN_NO_CONSENTS_CMP_SUBMITTED = {
+  All: true
+}
+
+const getUserId = userId => {
+  const prefix = getConfig('userIdPrefix')
+
+  if (!prefix) {
+    return userId
+  }
+
+  if (typeof userId === 'number' || (typeof userId === 'string' && !userId.startsWith(prefix))) {
+    return `${prefix}${userId}`
+  }
+
+  return userId
+}
+
+/**
+ * Get default properties using the constant and the window.__mpi object if available
+ * @returns {{[key:string]: any}} Default properties to attach to track
+ */
+export const getDefaultProperties = () => ({
+  ...DEFAULT_PROPERTIES,
+  ...getConfig('defaultProperties')
+})
+
+/**
+ * Get all needed integrations depending on the gdprPrivacy value.
+ * @param {object} param - Object with the gdprPrivacyValue and if it's a CMP Submitted event
+ */
+const getTrackIntegrations = async ({gdprPrivacyValue, event}) => {
+  const isGdprAccepted = checkAnalyticsGdprIsAccepted(gdprPrivacyValue)
+  const restOfIntegrations = getRestOfIntegrations({isGdprAccepted, event})
+
+  // Check if we should use manual GA4 (legacy) or Segment destination (new)
+  const useSegmentGA4Destination = isGA4DestinationEnabled()
+
+  if (useSegmentGA4Destination) {
+    // New behavior: let Segment handle GA4
+    return {
+      ...restOfIntegrations,
+      'Google Analytics 4 Web': true
+    }
+  }
+
+  // Legacy behavior: manual GA4 with clientId/sessionId
+  let sessionId
+  let clientId
+
+  try {
+    sessionId = await getGoogleSessionId()
+    clientId = await getGoogleClientId()
+  } catch (error) {
+    console.error(
+      '[segment-wrapper] Failed to retrieve GA4 session/client IDs. Events will be sent without session attribution.',
+      error
+    )
+  }
+
+  return {
+    ...restOfIntegrations,
+    'Google Analytics 4':
+      clientId && sessionId
+        ? {
+            clientId,
+            sessionId
+          }
+        : true
+  }
+}
+
+/**
+ * Get Rest of integrations depending on the gdprPrivacy value and if it's a CMP Submitted event
+ * @param {object} param - Object with the isGdprAccepted and if it's a CMP Submitted event
+ * @returns {object} integrations
+ */
+export const getRestOfIntegrations = ({isGdprAccepted, event}) => {
+  const isCMPSubmittedEvent = event === 'CMP Submitted'
+
+  if (isCMPSubmittedEvent) {
+    return INTEGRATIONS_WHEN_NO_CONSENTS_CMP_SUBMITTED
+  }
+  return isGdprAccepted ? {} : INTEGRATIONS_WHEN_NO_CONSENTS
+}
+
+/**
+ * It returns externalIds to add to context
+ *
+ * @param {Object} param
+ * @param {Object} param.context previous context
+ * @param {String} param.xandrId xandrId to be included
+ * @returns
+ */
+const getExternalIds = ({context, xandrId}) => {
+  const shouldSendXandrId = getConfig('sendXandrId') !== false
+  const isValidXandrId = xandrId && parseInt(xandrId) !== 0
+  if (!shouldSendXandrId || !isValidXandrId) {
+    return {}
+  }
+  const SEGMENT_COLLECTION = 'users'
+  const SEGMENT_ENCODING = 'none'
+  const SEGMENT_TYPE = 'xandr_id'
+  const externalIds = [
+    ...(context?.externalIds || []),
+    {
+      collection: SEGMENT_COLLECTION,
+      encoding: SEGMENT_ENCODING,
+      id: xandrId,
+      type: SEGMENT_TYPE
+    }
+  ]
+
+  const uniqueExternalIds = externalIds.filter(
+    ({id: idFilter, type: typeFilter}, index) =>
+      index === externalIds.findIndex(({id: idFind, type: typeFind}) => idFilter === idFind && typeFilter === typeFind)
+  )
+  return {externalIds: uniqueExternalIds}
+}
+
+/**
+ * Get consent value for Google Consent Mode
+ * @param {string} gdprValue
+ * @returns {string} consent value
+ */
+const getConsentValue = gdprValue => (gdprValue === USER_GDPR.ACCEPTED ? CONSENT_STATES.granted : CONSENT_STATES.denied)
+
+/**
+ * Get data like traits and integrations to be added to the context object
+ * @param {object} context Context object with all the actual info
+ * @returns {Promise<object>} New context with all the previous info and the new one
+ */
+export const decorateContextWithNeededData = async ({event = '', context = {}, properties = {}}) => {
+  const gdprPrivacyValue = await getGdprPrivacyValue()
+  const {analytics: gdprPrivacyValueAnalytics, advertising: gdprPrivacyValueAdvertising} = gdprPrivacyValue || {}
+  const isGdprAccepted = checkAnalyticsGdprIsAccepted(gdprPrivacyValue)
+
+  // Check if we should use Segment destination or legacy mode
+  const useSegmentGA4Destination = isGA4DestinationEnabled()
+
+  const [integrations, xandrId] = await Promise.all([
+    getTrackIntegrations({gdprPrivacyValue, event}),
+    getXandrId({gdprPrivacyValueAdvertising})
+  ])
+
+  // Build integrations without mutating context
+  const contextIntegrations = !isGdprAccepted
+    ? {
+        ...(context.integrations ?? {}),
+        Personas: false,
+        Webhooks: true,
+        Webhook: true
+      }
+    : context.integrations
+
+  // Build Google Consent Mode object
+  const googleConsents = {
+    analytics_storage: useSegmentGA4Destination
+      ? getConsentValue(gdprPrivacyValueAnalytics)
+      : getGoogleConsentValue('analytics_storage') ?? getConsentValue(gdprPrivacyValueAnalytics),
+    ad_storage: useSegmentGA4Destination
+      ? getConsentValue(gdprPrivacyValueAdvertising)
+      : getGoogleConsentValue('ad_storage') ?? getConsentValue(gdprPrivacyValueAdvertising),
+    ad_user_data: useSegmentGA4Destination
+      ? getConsentValue(gdprPrivacyValueAdvertising)
+      : getGoogleConsentValue('ad_user_data') ?? getConsentValue(gdprPrivacyValueAdvertising),
+    ad_personalization: useSegmentGA4Destination
+      ? getConsentValue(gdprPrivacyValueAdvertising)
+      : getGoogleConsentValue('ad_personalization') ?? getConsentValue(gdprPrivacyValueAdvertising)
+  }
+
+  const baseContext = {
+    ...context,
+    ...(!isGdprAccepted && {ip: '0.0.0.0'}),
+    ...getExternalIds({context, xandrId}),
+    clientVersion: `segment-wrapper@${process.env.VERSION ?? '0.0.0'}`,
+    gdpr_privacy: gdprPrivacyValueAnalytics,
+    gdpr_privacy_advertising: gdprPrivacyValueAdvertising,
+    integrations: {
+      ...contextIntegrations,
+      ...integrations
+    }
+  }
+
+  // Legacy behavior: add analytics_storage and google_consents to context
+  if (!useSegmentGA4Destination) {
+    baseContext.analytics_storage = getConsentState()
+    baseContext.google_consents = googleConsents
+  }
+
+  return {
+    context: baseContext,
+    properties: useSegmentGA4Destination
+      ? {
+          ...properties,
+          // New mode: add google_consents to properties
+          google_consents: googleConsents
+        }
+      : properties
+  }
+}
+
+/**
+ * The track method lets you record any actions your users perform.
+ * @param {string} event The name of the event you’re tracking
+ * @param {object} [properties] A dictionary of properties for the event.
+ * @param {object} [context] A dictionary of options.
+ * @param {function} [callback] A function executed after a short timeout, giving the browser time to make outbound requests first.
+ * @returns {Promise}
+ */
+const track = (event, properties, context = {}, callback) =>
+  new Promise(resolve => {
+    const initTrack = async () => {
+      /**
+       * @deprecated Now we use `defaultContextProperties` middleware
+       * and put the info on the context object
+       */
+      const baseProperties = {
+        ...getDefaultProperties(),
+        ...properties
+      }
+
+      const {context: newContext, properties: decoratedProperties} = await decorateContextWithNeededData({
+        context,
+        event,
+        properties: baseProperties
+      })
+
+      const newCallback = async (...args) => {
+        if (callback) callback(...args) // eslint-disable-line n/no-callback-literal
+        const [gdprPrivacyValue] = await Promise.all([getGdprPrivacyValue()])
+
+        if (checkAnalyticsGdprIsAccepted(gdprPrivacyValue)) {
+          resolve(...args)
+        } else {
+          resolve()
+        }
+      }
+
+      const useSegmentGA4Destination = isGA4DestinationEnabled()
+      const needsConsentManagement = getConfig('googleAnalyticsConsentManagement')
+
+      // Legacy behavior: send consents to GTM
+      if (!useSegmentGA4Destination && needsConsentManagement && event === CMP_TRACK_EVENT) {
+        sendGoogleConsents('update', newContext.google_consents)
+      }
+
+      window.analytics.track(
+        event,
+        decoratedProperties,
+        {
+          ...newContext,
+          context: {
+            integrations: {
+              ...newContext.integrations
+            }
+          }
+        },
+        newCallback
+      )
+    }
+
+    initTrack()
+  })
+
+/**
+ * Associate your users and their actions to a recognizable userId and traits.
+ * @param {string} userIdParam Id to identify the user.
+ * @param {object} traits A dictionary of traits you know about the user, like their email or name.
+ * @param {object} [options] A dictionary of options.
+ * @param {function} [callback] A function executed after a short timeout, giving the browser time to make outbound requests first.
+ * @returns {Promise}
+ */
+const identify = async (userIdParam, traits, options, callback) => {
+  const gdprPrivacyValue = await getGdprPrivacyValue()
+
+  const userId = getUserId(userIdParam)
+
+  // Legacy behavior: set user ID in gtag
+  if (!isGA4DestinationEnabled()) {
+    setGoogleUserId(userId)
+  }
+
+  return window.analytics.identify(
+    userId,
+    checkAnalyticsGdprIsAccepted(gdprPrivacyValue) ? traits : {},
+    options,
+    callback
+  )
+}
+
+/**
+ * Record whenever a user sees a page of your website, along with any optional properties about the page.
+ * @param {string} event The name of the event you’re tracking
+ * @param {object=} properties A dictionary of properties for the event.
+ * @param {object} [context] A dictionary of options.
+ * @param {function} [callback] A function executed after a short timeout, giving the browser time to make outbound requests first.
+ * @returns {Promise}
+ */
+const page = (event, properties, context = {}, callback) => {
+  // we put a flag on context to know this track is a page
+  context.isPageTrack = true
+  // just call track again but the with the proper context
+  return track(event, properties, context, callback)
+}
+
+/**
+ * Resets the id, including anonymousId, and clear traits for the currently identified user and group.
+ * NOTE: Only clears the cookies and localStorage set by analytics.
+ * @returns {Promise}
+ */
+const reset = () => Promise.resolve(window.analytics.reset())
+
+export default {page, identify, track, reset}

package/src/tcf.js

@@ -0,0 +1,263 @@
+import {getConfig, isClient, setConfig} from './config.js'
+import analytics from './segmentWrapper.js'
+
+/**
+ * Cookie to extract the already saved consents for the user
+ * @type {string}
+ */
+const TCF_COOKIE_KEY = 'borosTcf'
+/**
+ * TCF Api Version to use
+ * @type {number}
+ */
+const TCF_API_VERSION = 2
+
+/**
+ * Default properties to send with every TCF tracking event
+ */
+const TCF_TRACK_PROPERTIES = {
+  channel: 'GDPR'
+}
+
+/**
+ * List of purpose ids needed to be able to track with all info
+ * @type {Array<number>}
+ */
+const NEEDED_PURPOSES = {
+  analytics: [1, 8, 10],
+  advertising: [3]
+}
+
+/**
+ * TCF events
+ */
+const TCF_EVENTS = {
+  // Event that determines that the tcData has been loaded
+  LOADED: 'tcloaded',
+  // Event that determines that the user has performed an action
+  USER_ACTION_COMPLETE: 'useractioncomplete'
+}
+
+export const CMP_TRACK_EVENT = 'CMP Submitted'
+
+/**
+ * State of user according to GDPR regarding tracking
+ */
+export const USER_GDPR = {
+  ACCEPTED: 'accepted',
+  DECLINED: 'declined',
+  UNKNOWN: 'unknown'
+}
+
+/**
+ * Define the user GDPR consents state. This value will be updated with new values
+ * when the consents of the users changes.
+ */
+const gdprState = {
+  listeners: [],
+  value: undefined,
+  addListener: callback => gdprState.listeners.push(callback),
+  get: () => gdprState.value,
+  set: value => {
+    const {analytics, advertising} = value || {}
+    gdprState.value = {
+      analytics,
+      advertising
+    }
+    gdprState.listeners.forEach(fn => fn(value))
+    gdprState.listeners = []
+  }
+}
+
+/**
+ * Read cookie by using a key
+ * @returns {string}
+ */
+function readCookie(key) {
+  const re = new RegExp(key + '=([^;]+)')
+  const value = re.exec(document.cookie)
+  return value !== null ? unescape(value[1]) : null
+}
+
+/**
+ * Check if we're on client and tcfApi is available on window object
+ * @returns {Boolean}
+ */
+const checkTcfIsAvailable = () => {
+  // if we're on the client, check we haven't already initialized it
+  if (getConfig('initialized')) return false
+
+  // if we're on client, check if we have the tcfapi available
+  const isTcfApiAvailable = !!window.__tcfapi
+  !isTcfApiAvailable &&
+    console.warn("[tcfTracking] window.__tcfapi is not available on client and TCF won't be tracked.")
+  return isTcfApiAvailable
+}
+
+/**
+ * Check from a list of consents if user has accepted being tracked
+ * @param {{[purposeId: string]: boolean}} userConsents
+ * @returns {Boolean}
+ */
+const checkHasUserConsentedAnalytics = userConsents =>
+  NEEDED_PURPOSES.analytics.every(purposeId => userConsents[`${purposeId}`])
+
+const checkHasUserConsentedAdvertising = userConsents =>
+  NEEDED_PURPOSES.advertising.every(purposeId => userConsents[`${purposeId}`])
+
+/**
+ * Track a specific TCF event
+ * @param {object} params
+ * @param {string} params.eventId Event ID to be sent with the TCF Tracking
+ * @param {string} params.gdprPrivacy Send a string telling if the gdpr has been accepted or reject
+ * @return {Promise}
+ */
+const trackTcf = ({eventId, gdprPrivacy}) =>
+  analytics.track(
+    CMP_TRACK_EVENT,
+    {
+      ...TCF_TRACK_PROPERTIES,
+      ...getConfig('tcfTrackDefaultProperties')
+    },
+    {
+      gdpr_privacy: gdprPrivacy.analytics,
+      gdpr_privacy_advertising: gdprPrivacy.advertising
+    }
+  )
+
+/**
+ * Get if we have user consents
+ * @return {Promise<Object>}
+ */
+export const getGdprPrivacyValue = () => {
+  // try to get the actual gdprPrivacyValue and just return it
+  const gdprPrivacyValue = gdprState.get()
+
+  if (gdprPrivacyValue !== undefined) return Promise.resolve(gdprPrivacyValue)
+
+  // // if we don't have a gdprPrivacyValue, then subscribe to it until we have a value
+  return new Promise(resolve => {
+    gdprState.addListener(gdprPrivacyValue => resolve(gdprPrivacyValue))
+  })
+}
+
+/**
+ * Check if gdprPrivacyValue is accepted
+ * @return {boolean}
+ */
+export const checkAnalyticsGdprIsAccepted = gdprPrivacyValue => {
+  return gdprPrivacyValue.analytics === USER_GDPR.ACCEPTED
+}
+
+/**
+ * Set gdprState according to list of purpose consents
+ * @returns {string}
+ */
+const setGdprStateBy = purposeConsents => {
+  const hasAnalyticsConsents = checkHasUserConsentedAnalytics(purposeConsents)
+  const hasAdvertisingConsents = checkHasUserConsentedAdvertising(purposeConsents)
+  // get the state key according to the gdprPrivacyValue
+  const gdprAnalyticsStateKey = hasAnalyticsConsents ? USER_GDPR.ACCEPTED : USER_GDPR.DECLINED
+
+  const gdprAdvertisingStateKey = hasAdvertisingConsents ? USER_GDPR.ACCEPTED : USER_GDPR.DECLINED
+  // update gdprState with the new value for user gdpr
+  gdprState.set({
+    analytics: gdprAnalyticsStateKey,
+    advertising: gdprAdvertisingStateKey
+  })
+  // return the new gdprState
+  return {
+    analytics: gdprAnalyticsStateKey,
+    advertising: gdprAdvertisingStateKey
+  }
+}
+
+/**
+ * Read and decode the tcf cookie
+ */
+const getConsentsFromCookie = () => {
+  const cookieValue = readCookie(TCF_COOKIE_KEY)
+  if (!cookieValue) return
+
+  try {
+    const {purpose} = JSON.parse(window.atob(cookieValue))
+    const {consents} = purpose
+    return consents
+  } catch (e) {
+    console.error(e)
+  }
+}
+
+/**
+ * Set the correct initial gdprState based on the consents cookie string
+ */
+const initializeGdprState = () => {
+  const consents = getConsentsFromCookie()
+  if (consents) setGdprStateBy(consents)
+}
+
+/**
+ * Sets global isFirstVisit flag based on the consents cookie string
+ */
+const initializeIsFirstVisit = () => {
+  const consents = getConsentsFromCookie()
+  setConfig('isFirstVisit', !consents)
+}
+
+/**
+ * Init TCF Tracking User Consents with Segment
+ */
+export default function initTcfTracking() {
+  // first check if we're on server, as this doesn't work on server-side
+  if (!isClient) return
+  // read the cookie and put the correct usergdprValue and isFirstVisit flag before listening events
+  initializeGdprState()
+  initializeIsFirstVisit()
+  // do some checks before initializing tcf tracking as we do that only if available
+  if (!checkTcfIsAvailable()) {
+    // if we don't have a gdpr state and tcf is not available
+    // we should assume we don't known if we have consents
+    const analyticsGdprState = gdprState.get()?.analytics
+    if (analyticsGdprState === undefined)
+      gdprState.set({
+        analytics: USER_GDPR.UNKNOWN,
+        advertising: USER_GDPR.UNKNOWN
+      })
+    // and we stop executing as we can't track tcf
+    return
+  }
+  // add a flag to the segmentWrapper config to know it's already initialized
+  setConfig('initialized', true)
+
+  // listen events from tcf api
+  window.__tcfapi('addEventListener', TCF_API_VERSION, ({eventStatus, purpose}, success) => {
+    if (!success) return Promise.resolve()
+
+    // if we've already user consents or the user is accepting or declining now
+    // we change the state of the GDPR to use in our tracking
+    if (eventStatus === TCF_EVENTS.USER_ACTION_COMPLETE || eventStatus === TCF_EVENTS.LOADED) {
+      const {consents} = purpose
+      const gdprStateKey = setGdprStateBy(consents)
+      // if it's a user action, then we will track it
+      if (eventStatus === TCF_EVENTS.USER_ACTION_COMPLETE) {
+        // extract the eventId and gdprPrivacy string to send with the track
+        const {analytics: analyticsStateKey, advertising: advertisingStateKey} = gdprStateKey
+
+        const gdprPrivacy = {
+          analytics: analyticsStateKey,
+          advertising: advertisingStateKey
+        }
+
+        // temporary during Didomi migration to avoid fake programmatically generated events where the users doesn't really interact
+        const MIGRATION_DIDOMI_SEGMENT_WRAPPER_FLAG = 'didomi-migration'
+        const isDidomiMigration = isClient && window.sessionStorage.getItem(MIGRATION_DIDOMI_SEGMENT_WRAPPER_FLAG)
+        return (
+          !isDidomiMigration &&
+          trackTcf({
+            gdprPrivacy
+          })
+        )
+      }
+    }
+  })
+}

package/src/universalId.js

@@ -0,0 +1,51 @@
+import {dispatchEvent} from '@s-ui/js/lib/events'
+
+import {createUniversalId} from './utils/hashEmail.js'
+import {getConfig, isClient, setConfig} from './config.js'
+
+const USER_DATA_READY_EVENT = 'USER_DATA_READY'
+
+export const getUniversalIdFromConfig = () => getConfig('universalId')
+
+export const getUniversalId = () => {
+  // 1. Try to get universalId from config
+  let universalId = getUniversalIdFromConfig()
+
+  if (universalId) {
+    setUniversalIdInitialized()
+
+    return universalId
+  }
+
+  // 2. If not available, then we use the email and hash it
+  const userEmail = getConfig('userEmail')
+
+  if (userEmail) {
+    universalId = createUniversalId(userEmail)
+    setUniversalId(universalId)
+    setUniversalIdInitialized()
+
+    return universalId
+  }
+
+  // 3. We don't have user email, so we don't have universalId
+  // but we've tried, so we set it as initialized
+  setUniversalIdInitialized()
+}
+
+export const getUserDataAndNotify = () => {
+  if (!isClient) return
+
+  const universalId = getUniversalId()
+  const userEmail = getConfig('userEmail')
+
+  dispatchEvent({eventName: USER_DATA_READY_EVENT, detail: {universalId, userEmail}})
+
+  return {universalId, userEmail}
+}
+
+export const setUniversalIdInitialized = () => {
+  setConfig('universalIdInitialized', true)
+}
+
+export const setUniversalId = universalId => setConfig('universalId', universalId)

package/src/utils/checkAnonymousId.js

@@ -0,0 +1,10 @@
+export const checkAnonymousId = () => {
+  const SEGMENT_ID_USER_WITHOUT_CONSENTS =
+    window.__SEGMENT_WRAPPER?.SEGMENT_ID_USER_WITHOUT_CONSENTS ?? 'anonymous_user'
+
+  const anonymousId = window.analytics.user?.()?.anonymousId()
+
+  if (anonymousId === SEGMENT_ID_USER_WITHOUT_CONSENTS) {
+    window.analytics.setAnonymousId(null)
+  }
+}