@s-ui/segment-wrapper

Abstraction layer on top of Segment library.

Usage no npm install needed!

<script type="module">
  import sUiSegmentWrapper from 'https://cdn.skypack.dev/@s-ui/segment-wrapper';
</script>

README

Segment Wrapper Build Status

This package adds an abstraction layer on top of segment.com's javascript library with some useful integrations and fixes that could be used across Adevinta Spain:

Data Quality 📈

  • Add page method that internally uses track but with the correct referrer property.
  • Send user.id and anonymousId on every track.
  • Send anonymous data to aws to be able to check data integrity with adobe.

Adobe Audience Manager DMP 🙋

  • Integrates DMP and send ssf correct value depending on user's consents.
  • Sync Facebook and Google pixels (if you provide the needed config).
  • Persist pixels to sync in a stack, to be sure they're sent after navigation.
  • Send SHA256 hashed email with normalizations via userEmail or universalId config.
  • Deprecated: Send md5 hashed email with normalizations via userEmail or hashedUserEmail configs.

Adobe Marketing Cloud Visitor Id ☁️

  • Load Adobe Visitor API when needed (if flag importAdobeVisitorId is set to true, otherwise you should load Visitor API by your own to get the mcvid).
  • Fetch marketingCloudVisitorId and put in integrations object for every track.
  • Monkey patch track native Segment method to send marketingCloudVisitorId inside context.integrations.

Consent Management Platform 🐾

  • Automatic tracking of Consent Management Platform usage.
  • Send gdpr_privacy on context for for all tracking events. Expect values: unknown, accepted and declined.

Developer Experience 👩‍💻

  • Always send platform property as web.
  • Allow to configure window.__mpi.defaultContext to send these properties on all tracks inside the context object.
  • Allow to configure window.__mpi.defaultProperties to send these properties on all tracks.

Segment Middlewares 🖖

  • Optimizely Full Stack middleware to use segment's anonymousId as optimizely's userId, more info here

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

Step 1: Copy the Snippet in your 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"];analytics.factory=function(t){return function(){var e=Array.prototype.slice.call(arguments);e.unshift(t);analytics.push(e);return analytics}};for(var t=0;t<analytics.methods.length;t++){var e=analytics.methods[t];analytics[e]=analytics.factory(e)}analytics.load=function(t,e){var n=document.createElement("script");n.type="text/javascript";n.async=!0;n.src="https://cdn.segment.com/analytics.js/v1/"+t+"/analytics.min.js";var a=document.getElementsByTagName("script")[0];a.parentNode.insertBefore(n,a);analytics._loadOptions=e};analytics.SNIPPET_VERSION="4.1.0";

  analytics.load("YOUR_WRITE_KEY");  // your write key must be set here
  }}();
</script>

Step 2: Use

In your modern and beautiful JavaScript...

import analytics from '@s-ui/segment-wrapper'

In your monolithic JavaScript...

// 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.

  • googleAdsPixelId: (optional) If set, pixel of Google Ads will be synchronized.
  • facebookPixelId: (optional) If set, pixel of Facebook will be synchronized.
  • 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.
  • getCustomAdobeVisitorId: (optional) If set, the output of this function will be used as marketingCloudVisitorId in Adobe Analytics' integration. It must return a promise.
  • importAdobeVisitorId (optional) If set and true, Adobe Visitor API will be fetched from Segment Wrapper instead of relying on being loaded before from Tealium or other services. Right now, by default, this is false but in the next major this configuration will be true by default. If getCustomAdobeVisitorId is being used this will be ignored.
  • 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.

Example:

  window.__mpi = {
    segmentWrapper: {
      googleAdsPixelId: '1054970353',
      facebookPixelId: '448176625351232',
      universalId: '7ab9ddf3281d5d5458a29e8b3ae2864',
      defaultContext: {
        site: 'fotocasa',
        vertical: 'realestate'
      },
      getCustomAdobeVisitorId: () => {
        const visitorId = // get your visitorId
        return Promise.resolve(visitorId)
      },
      tcfTrackDefaultProperties: {
        tcfSpecialProp: 'anyvalue'
      }
    }
  }

Events

Track - docs

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.

import analytics from '@s-ui/segment-wrapper'

analytics.page('Home Viewed')

analytics.page('List Viewed', {
  property: 'HOUSE',
  transaction: 'SELL'
})

Identify - docs

import analytics from '@s-ui/segment-wrapper'

analytics.identify('97980cfea0067', {
  name: 'Peter Gibbons',
  email: 'peter@initech.com',
  plan: 'premium',
  logins: 5
})

Reset - docs

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:

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:

const {universalId} = window.__mpi.segmentWrapper

Or use both systems:

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)

Middlewares

You can find info about segment's middleware here

Optimizely's userId

Will use segment's anonymousId as optimizely's userId

How to

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

import {optimizelySiteAttributeMiddleware} from '@s-ui/segment-wrapper/lib/middlewares/destination/optimizelySiteAttribute'

window.analytics.ready(() => {
  window.analytics.addDestinationMiddleware('Optimizely', [
    optimizelySiteAttributeMiddleware
  ])
})