How to set up visitor stitching for Adobe Analytics (SiteCatalyst)

[#1]

What is visitor stitching?

Adobe's visitor stitching is a method to:

(a) identify the same user across multiple devices

(b) stitch anonymous behaviour from a known customer to identifiable behaviour from a known customer (e.g. if someone browses the site, adds items to their basket and then purchases and logs in we can stitch together their behaviour pre-logging in with behaviour post-logging in)

Here is Adobe's documentation:

http://blogs.adobe.com/digitalmarketing/analytics/15-for-15-a-stitch-in-time-saves-visitors/

http://helpx.adobe.com/analytics/using/cross-device-visitor-identification.html

 

What does this tutorial cover?

This tutorial will explain how to configure Tealium iQ to handle the following situations:

1. Passing in a visitor ID into SiteCatalyst on a web implementation
2. Passing in a visitor ID into SiteCatalyst in a mobile implementation (using our SDK)
3. Stitching together visitor IDs from data from a mobile app to a webview in the same app*

*an example of this could be opening an app you have the Tealium SDK implemented in and then opening a webview via the app which uses a completely different Tealium profile (and therefore visitor ID)

 

Pre-requisites

You need to configure your report suites as per Adobe's guidelines here:

http://helpx.adobe.com/analytics/using/cross-device-visitor-identification.html

 

1. Passing in a visitor ID into SiteCatalyst on a web implementation

Step 1 : Ensure you have a data source which is a unique id

We'll be using 'customer_id' as our unique id. Yours could be called anything but it is typically your unique customer ID that you assign each logged in user on your website.

Step 2 : Map 'customer_id' in your SiteCatalyst tag to the relevant variable

SiteCatalyst Tag

Go to the 'Tags' tab and click on 'edit' in the 'MAPPED DATA SOURCES' box:

Find your data source name and then 'select destination':

Map it to visitorID via the mappings toolbox:

Save and publish and you're done!

SiteCatalyst AppMeasurement for Javascript Tag.

You can map visitorID in the AppMeasurement for JavaScript Tag, just like you did in the SiteCatalyst Tag above.  Click open the Tag's settings and follow the steps #1 and #2 listed above.

Save and publish and you're done!

 

2. Passing in a visitor ID into SiteCatalyst in a mobile implementation (using our SDK)

For the mobile app, we always need to pass in the 'uuid' data source that the mobile SDK generates as the visitorID by default as per the tag guidelines:

Typically, you map 'uuid' (a variable generated by the mobile library) to visitorID in SiteCatalyst to ensure SiteCatalyst can track visitors uniquely. We're going to assume this is what you normally do but in this case we're going to change that. - We will:

(a) Pass in a visitor ID to use for users who don't have your unique identifier (e.g. no 'customer_id')

(b) Pass in your unique identifier (e.g. 'customer_id') for users who do have your unique identifier.

This way you can ensure SiteCatalyst tracks as normal for anonymous users but if they do have a your unique identifier then we'll pass that in instead.

We'll be using 'customer_id' as our unique id. Yours could be called anything but it is typically your unique customer ID that you assign each logged in user on your website.

Step 1 : Add the mobile 'common' data sources via the 'Data Layer' tab

Click here:

Then choose the 'Mobile App Data Sources':

Step 2 : Create your unique identifier and a new 'visitor_id' data source

Use the 'Data Layer' tab to create a UDO data source for your unique identifier (e.g. 'customer_id') and another UDO data source called 'visitor_id':

Step 3 : Create a 'set data values' extension and set it to populate 'visitor_id' with 'customer_id' if 'customer_id' is populated

Create your extension:

Configure it as follows:

Step 4 : Create another 'set data values' extension and set it to populate 'visitor_id' with 'uuid' if 'visitor_id' is not populated

Configure it as follows:

Note : Ensure this runs AFTER the extension you created in step 3

Step 5 : Map 'visitor_id' to 'visitorID' in the 'SiteCatalyst Mobile App' tag

Map it to visitorID via the mappings toolbox:

Step 6 : You're done!

That's it! Now you will be passing in 'uuid' as visitorID for anonymous users and 'customer_id' for known users

 

3. Stitching together visitor IDs from data from a mobile app to a webview in the same app*

*an example of this could be opening an app you have the Tealium SDK implemented in and then opening a webview via the app which uses a completely different Tealium profile (and therefore a different visitorID)

What is this and why is this a problem?

A common problem for analytics on apps is when a user browses through an app natively but then hits a 'web view' to view other content un-natively. The web view content is effectively a web page and we assume you have a standard Tealium web implementation. This means SiteCatalyst will have one visitor ID for the native app and then a different visitor ID for the web view - you will be treated as two different visitors.

You can easily get around this by:

    (i) Passing across the unique ID your Tealium mobile implementation is using as SiteCatalyst's visitorID into the web view

    (ii) Set up the Tealium web implementation to pull this an use it as the visitorID

Prequisites

Read items (1) and (2) above so you understand how to pass in a visitorID in both a mobile and web implementation.

Step 1 : Ensure your mobile implementation is using a unique identifier for 'visitorID'

Ensure that you have mapped some kind of unique identifier to visitorID as per item (2) above in your mobile implementation.

Step 2 : Ask your developers to pass in your unique identifier into the URL when they call the web view

If you're using 'uuid' as your unique identifier then you can use the iOS or Android APIs to request the UUID:

Android APIs (must be using version 2.1  or 2.1c or later)

Run the following code:

context.getSharedPreferences("tealium.sp", 0).getString("uuid", null);

It is advisable to check the library is initialised first to avoid returning a 'null' value:

Tealium.getStatus() == Tealium.Status.INITIALIZED

iOS APIs (link)

You can retrieve the iOS UUID for the app using the following syntax:

NSString *uuid = [[Tealium sharedInstance] retrieveUUID];

Otherwise, just ask your developer to pass in whatever unique identifier you're using (e.g. 'customer_id').

The URL the web view calls might be 'http://www.greatsite.com?vis_id=123123-asdsadSASD-12312

Note

You'll need to choose a query-string parameter ('vis_id' in this example but it could be anything)

Step 3 : Create a new 'query-string' data source in your web profile

The mobile work is done. Now we just need to set up the Tealium web profile that the web view uses to pick up visitor ID you are passing through and to pass that to SiteCatalyst.

Create the data source (learn more)

 

Step 4. Ensure you aren't automatically lower-casing query-string parameters

Note : This is only necessary if you are using an older utag than utag.4.x (how do I upgrade my utag?)

We'll need to add the following javascript extension scoped to 'Pre loader' to ensure that the visitor ID you pass in doesn't get lower-cased - otherwise your visitorIDs won't match in SiteCatalyst:

window.utag_cfg_ovrd = {
  lowerqp : false, // lower query string parameters
};

Notes

- Ensure that by not lower-casing query string parameters you aren't going to affect your current implementation (e.g. if you rely on lower-cased values from another query-string parameter then you may want to use a 'lower casing' extension to do that for you on your specific query string data sources)

- For more information on the above extension please read the utag 4.26 release notes

Step 5. Map the 'vis_id' data source to 'visitorID' in the mappings toolbox

Note

If you really wanted, you could persist the 'vis_id' data source using the 'Persist Data Value' extension and then map that to visitorID to ensure every hit has visitorID set but according to Adobe's documentation this isn't necessary - once you pass in the visitorID for a browser/device once then it will continually associate your activity with that visitorID (whether you set the same visitorID on subsequent hits or not)

Pitfalls

- You need to ensure that your developers use the same logic when passing across your unique identifier in the query-string parameter (e.g. 'vis_id') to the web view as you do when you pass in the unique identifier as visitorID to SiteCatalyst in the mobile app

For example, in the mobile app if you pass in 'customer_id' as visitorID when available but 'uuid' when not you will need to ensure that your developer passes across the same ID you use for visitorID to the web view. If you send across different IDs then they will be treated as two different visitors (instead of one visitor sharing the same visitorID).

Adobe Visitor Stitching Cross-Device Visitor Identification