README
Segment Wrapper
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 usestrack
but with the correctreferrer
property. - Send
user.id
andanonymousId
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
oruniversalId
config. - Deprecated: Send md5 hashed email with normalizations via
userEmail
orhashedUserEmail
configs.
Adobe Marketing Cloud Visitor Id ☁️
- Load Adobe Visitor API when needed (if flag
importAdobeVisitorId
is set totrue
, otherwise you should loadVisitor API
by your own to get themcvid
). - Fetch
marketingCloudVisitorId
and put in integrations object for every track. - Monkey patch
track
native Segment method to sendmarketingCloudVisitorId
insidecontext.integrations
.
Consent Management Platform 🐾
- Automatic tracking of Consent Management Platform usage.
- Send
gdpr_privacy
oncontext
for for all tracking events. Expect values:unknown
,accepted
anddeclined
.
Developer Experience 👩💻
- Always send
platform
property asweb
. - 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","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...
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.googleAnalyticsMeasurementId
: (optional) If set, this value will be used for the Google Analytics Measurement API. It will load gtag to get the client id.facebookPixelId
: (optional) If set, pixel of Facebook will be synchronized.defaultContext
: (optional) If set, properties will be merged and sent with everytrack
andpage
in the context object. It's the ideal place to put thesite
andvertical
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 everytrack
andpage
.getCustomAdobeVisitorId
: (optional) If set, the output of this function will be used asmarketingCloudVisitorId
in Adobe Analytics' integration. It must return a promise.importAdobeVisitorId
(optional) If set andtrue
, 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 isfalse
but in the next major this configuration will betrue
by default. IfgetCustomAdobeVisitorId
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 eventuniversalId
: (optional) If set this value will be used for the Visitor API and other services.hashedUserEmail
: (optional) If set and notuniversalId
is set this value will be used for the Visitor API and other services.userEmail
: (optional) If set and notuniversalId
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',
googleAnalyticsMeasurementId: 'UA-123456789-1',
facebookPixelId: '448176625351232',
universalId: '7ab9ddf3281d5d5458a29e8b3ae2864',
defaultContext: {
site: 'fotocasa',
vertical: 'realestate'
},
getCustomAdobeVisitorId: () => {
const visitorId = // get your visitorId
return Promise.resolve(visitorId)
},
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
docs
Track -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'
})
docs
Identify -import analytics from '@s-ui/segment-wrapper'
analytics.identify('97980cfea0067', {
name: 'Peter Gibbons',
email: 'peter@initech.com',
plan: 'premium',
logins: 5
})
docs
Reset -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)
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
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
])
})