Back

The purpose of this document is to explain an approach to tracking multiple users on a shared device in AudienceStream. This approach is called visitor switching.

Shared devices

AudienceStream determines the ID of the visitor profile based on the following order:

  • The TAPID cookie, also called tealium_thirdparty_visitor_id
  • The tealium_visitor_id event attribute
  • The utag_main v_id cookie, also called tealium_firstparty_visitor_id

The visitor switching approach changes the value of all three of those identifiers, as sent in the Collect Tag, when a different user is seen on the shared device.

If visitor switching is not used, then AudienceStream will track the Visitor Profile as the first user who logs in on each device.

For an example, see the attached document Visitor Stitching Without Switching.

Visitor switching

Visitor switching uses three new parameters (described below) to track multuple users on shared devices.

The overall approach is as follows:

  1. On the client device, when a user logs in, store the login value. Use a salted SHA256 to encrypt this value.
  2. If a different user logs increate a new ID for a visitor profile and send this in the event to AudienceStream.
  3. AudienceStream will track this new profile as a separate visitor profile, and will stitch this visitor profile to all events seen for this user across all devices and data sources.
  4. Save the link between AudienceStream visitor profiles and login values on the client device.  ID attributes on the client device. If a user who has already logged in does so again, AudienceStream uses their existing visitor profile instead of making a new one.

For an example, see Visitor Stitching With Switching.

There may be complex situations where visitor switching does not resolve your use case. If you have concerns, or if you see anomalous data as a result of visitor switching, contact Tealium Support for additional guidance.

How to implement visitor switching

Add a polling delay to the Tealium Collect tag

The default Tealium Collect tag sends the first data layer enrichment request immediately after the outgoing event. So, you’ll need to edit the u.do_enrichment section of the tag template:

u.do_enrichment = function(server, enrichment_polling, enrichment_polling_delay) {
                            if (typeof utag.ut.loader != "undefined") {
                                for (i = 0; i < enrichment_polling; i++) {
                                    setTimeout(function() {
                                        u.visitor_service_request((new Date).getTime(), server);
                                    }, i * enrichment_polling_delay + (u.enrichment_polling_pre_delay || 1));
                                }
                            }
                        }

For more information about editing the Tealium Collect tag's template, see Managing Templates.

Add a crypto extension to add the SHA256 function

iQ Tag Management only adds the SHA256 function after a crypto extension has been added. We need this function because visitor ID values might contain Personally Identifiable Information (PII), such as email addresses, and need to be encrypted.

Perform the following steps:

  1. In iQ Tag Management > Data Layer, add a UDO variable and name it dummy_sha. Do not set this variable to any value.
  2. In iQ Tag Management > Extensions, add a Crypto Extension.
  3. In the Title box, enter Dummy SHA to make SHA256 function available.
  4. From the Scope dropdown, select Tag Scoped Extensions and then select Tealium Collect tag.
  5. From the Hash Method dropdown, select sha256
  6. Click +Add Variable, and select the UDO variable dummy_sha

You should add this extension even if a Crypto Extension is already scoped to the Tealium Collect tag, because the pre-existing extension could be removed later.

Add a visitor switching extension

Next, add an extension that stores the most recent visitor ID attribute value from the utag_main cookie. This will detect when a different user logs in. It also stores previous visitor ID attribute values in local storage, so it can reuse previous visitor profile ID values to keep AudienceStream working efficiently.

Perform the following steps:

  1. Download the VisitorSwitchingFunction.js file.
  2. In iQ Tag Management > Extensions, add a JavaScript Code Extension.
  3. In the Title box, enter Collect Tag Visitor Switching.
  4. From the Scope dropdown, select Tag Scoped Extensions and then select Tealium Collect tag.
  5. In the Configuration box, paste the contents of the VisitorSwitchingFunction.js file.

You will need to configure the extension, so follow the instructions in the comments at the top of the VisitorSwitchingFunction code, which include:

  1. Enter a name for the switching key. You can use the name of the event attribute if it's read from a single attribute, such as customer_id.
  2. Add logic for how the extension checks that the data layer that populates the visitor ID attribute value in AudienceStream is actually set in a way that causes AS will stitch, and assign the value to stitch on to the variable switchingKeyValue.
    • The example condition in the extension's code will appear on lines 33 and 34 in the Configuration box, where customer_id is present in the data layer. It consists of 6 or more numbers and is accompanied by "is_logged_in" = "true";
if (b.is_logged_in && /^\d{6,}$/.test(b.customer_id)) {
  switchingKeyValue = b.customer_id;
}

About other tags that use TAPID

For other tags that also use a TAPID cookie, you will need to test them, ensure they are working correctly with visitor switching, and adjust them if they are not.

If another tag sends a TAPID cookie response at the same time, a race condition may occur where the response from that other tag overwrites and reverts the changed TAPID from the Collect tag.

For example, the Google Cookie Sync tag (aka Google Cookie Matching Service for Google Ad Manager (DoubleClick)) uses an extension that contains logic to remove the dcsyncran cookie when a switch occurs. In standard Cookie Sync tag setups, the dcsyncran cookie causes the tag to fire at most once per session. This allows the Cookie Sync tag to trigger again on the next page, so that it can enrich the switched visitor profile.

Because the Cookie Sync tag supports EventStream persistence, it will probably not actually run again on the next page. This means that the value for the google GID will already be enriched on to the switched visitor profile without the tag needing to run again. However, if the EventStream persistence cookie has expired, this will be enriched, and the tag will run again. This is the general practice for the Cookie Sync tag, so when a switch occurs, give the tag the opportunity to run again. Be sure to test the tag to confirm it behaves properly.

The switching extension does not change the actual value of the utag_main v_id cookie. Although this is often the visitor profile ID, it is used in many different contexts across multiple tags. Therefore, changing the cookie’s value would risk breaking other uses. Instead, when switching occurs, the switching extension stores an alternate visitor profile ID in the utag_main changed_as_id cookie, and uses it from that point onwards.

For tags that use the utag_main v_id to identify the visitor, you can use a mapping or an extension to make them use utag_main changed_as_id instead, if it exists.

To do this with the Google Cookie Sync tag, scope the following scoped JavaScript Code extension to it:

//the tealium_vid parameter for the cookie sync tag is normally read from cp.utag_main_vid
//however, if the visitor has been switched, then the switching extension will have written cookie cp.utag_main_changed_as_id
//if this is present, then substitute that in the cp.utag_main_vid data layer for just this tag
if (b['cp.utag_main_changed_as_id']){
    b['cp.utag_main_v_id'] = b['cp.utag_main_changed_as_id'];
}

The Google Cookie Sync tag will now use utag_main changed_as_id instead of utag_main v_id without having to change the tag template.

The TAPID cookie

TAPID is an Http-only browser cookie. It was originally designed to facilitate cross-domain identification, and it stores the primary identifiers for Tealium’s server-side products, such as AudienceStream.

When a user fisitrs a website, TAPID is set on the Collect Tag endpoint domain if it is not already present. Its value is set, if it's not already prefent, to the Visitor ID for that user. This value normally comes from the client device. TAPID is usually a third-party cookie, but with first-party domains it can be a first-party cookie.

When the TAPID is a third-party cookie, and the browser does not allow it to be set, Tealium's server-side products use the value of a first-party cookie instead, such asutag_main .

TAPID stores the value in a concatenated list of values for the accounts and profiles that a user's device has visited, using the following format:

account-1/profile-1>visitor_id_value-1|account-2/profile-2>visitor_id_value-2

Once set, the visitor_id_value in the cookie does not usually change. Tealium has added parameters to allow changes, which are described in the Changes to the TAPID cookie section above.

AudienceStream will always use the TAPID identifier as the primary identifier if it is present on an incoming request, in preference to anything else.

Changes to the TAPID cookie

In May 2022, three new optional API request parameters were added that can change the value of the TAPID cookie

As stated before, TAPID uses the following format to store the values of the accounts and profiles that a user's device has visited:

account-1/profile-1>visitor_id_value-1|account-2/profile-2>visitor_id_value-2

The new parameters will only affect the account and profile value in TAPID related to the current incoming API request. It will not change any other account and profile values.

The parameters support the following endpoints:

  • i.gif - Tealium Collect tag
  • /event - HTTP API
  • vdata

Parameter

Type

Actions

Notes

tealium_override_tapid string
    1. Make AudienceStream and server-side use the provided value as the Visitor ID on this event.
    2. For i.gif and vdata, but not /event, change the Set-Cookie response header to use the value you pass to change the TAPID .
This parameter enables visitor switching based on the last known user, while retaining a TAPID for cross-domain tracking.
tealium_delete_3rd_party_vid_cookies boolean
  1. Make AudienceStream and server-side ignore the incoming request value of the TAPID cookie when looking at its order of priority for the visitor profile ID for this event.
  2. For i.gif and vdata, but not /event, change the Set-Cookie response header to remove the TAPID for the current account and profile.
 
tealium_skip_3rd_party_vid_cookies boolean AudienceStream and server side will ignore the TAPID values for this event.  

The parameters only affect the current event. For example, if you pass the skip parameter on one event and not the next, the next event will not skip the TAPID cookie.

However, you can set the override parameter once and the TAPID will change to the value you specify.

Attachments
Public