Adobe® Marketing Cloud
Marketing Cloud Visitor ID Service
Contents
Marketing Cloud Visitor ID Service.................................................................................4
How the Visitor ID Service Works....................................................................................5
Using the Visitor ID Service with Analytics...............................................................................................................8
Using the Visitor ID with Target....................................................................................................................................9
Using the Visitor ID with Video Heartbeat................................................................................................................9
Visitor ID Service Requirements....................................................................................10
Migrating Analytics to use the Visitor ID Service.........................................................12
Visitor ID Service Migration Decision Points................................................................14
Visitor ID Service Migration Scenarios..........................................................................16
Visitor ID Service Implementation................................................................................17
Verify Visitor ID Service Implementation.....................................................................20
Customer IDs...................................................................................................................22
Data Collection CNAMEs and Cross-Domain Tracking................................................23
Visitor ID Grace Period...................................................................................................25
Server-side Implementation Mixed with JavaScript...................................................26
Library Reference...........................................................................................................27
FAQ..................................................................................................................................30
Last updated 2/5/2015
Marketing Cloud Visitor ID Service
Contents
Release History...............................................................................................................31
Last updated 2/5/2015
Marketing Cloud Visitor ID Service
Marketing Cloud Visitor ID Service
4
Marketing Cloud Visitor ID Service
The Marketing Cloud visitor ID service provides a universal visitor ID across Marketing Cloud solutions. The visitor ID service
replaces the legacy Analytics visitor ID mechanism, and is required by Analytics for Target, video heartbeat, and future Marketing
Cloud integrations.
The visitor ID service provides the following benefits:
• The same visitor ID is used across Marketing Cloud solutions, enabling the master marketing profile and visitor integration
across solutions.
• A CNAME for your Analytics server and the associated SSL certificates are no longer used to set first party cookies. The visitor
ID services sets a first party cookie using JavaScript.
• Current Analytics visitors are migrated automatically. The visitor ID service checks for an existing s_vi cookie, and if found,
copies the value to the new visitor ID cookie.
Date
Update
August 7, 2014
Added support to deploy the Marketing Cloud ID service using Dynamic Tag Management.
June 19, 2014
Added support for data collection server CNAME records.
Added the Visitor ID Grace Period
May 22, 2014
Added support for the visitor ID service to H.27.
How the Visitor ID Service Works
5
How the Visitor ID Service Works
Describes the process used by the visitor ID service to request an ID.
The visitor ID service uses JavaScript to store a unique visitor ID in an AMCV_###@AdobeOrg cookie on the domain of the
current website, where ### represents a random string of characters. For example,
AMCV_1FD6776A524453CC0A490D44%40AdobeOrg.
This cookie is set with a 2-year expiration and is refreshed on each visit.
The following sections describe the visitor ID request process based on your configuration:
• Visitor ID Request Process
• Visitor ID Request Process using a Data Collection CNAME
Visitor ID Request Process
When a customer visits your site, the visitor ID service first checks for an existing AMCV_###@AdobeOrg visitor ID cookie. If
present, the ID from the cookie is used. If the cookie is not present, the visitor ID service makes a request to Marketing Cloud
servers to receive an ID. The ID is stored and used going forward for that visitor, and is included in hits in the 'mid' query
string parameter.
Next, the cookie is checked for an Analytics ID. If present, the ID from the cookie is used. If the Analytics ID is not present, the
visitor ID service makes a request to your data collection server to check for a legacy Analytics visitor ID (s_vi cookie). If an
s_vi cookie is set for the visitor, that value is stored as the Analytics ID, and is included in hits in the 'aid' query string
parameter. If the s_vi cookie is not set, the analytics ID is set to an empty string. When the Analytics ID is empty, the Marketing
Cloud ID is used by Analytics and the 'aid' query string parameter is not set on the hit.
How the Visitor ID Service Works
6
Note that there are no charges for the calls to retrieve a visitor ID.
Visitor ID Request Process using a Data Collection CNAME
When a customer visits your site, the visitor ID service first checks for an existing AMCV_###@AdobeOrg visitor ID cookie. If
present, the ID from the cookie is used. If the cookie is not present, the visitor ID service makes a request to Marketing Cloud
servers to receive an ID. When a data collection CNAME is configured (the visitor.marketingCloudServer and
visitor.marketingCloudServerSecure variables are set), the server first checks to see if a demdex.net cookie can be set
to determine browser support for third-party cookies. If the browser accepts the third-party cookie, a Marketing Cloud ID is
returned and the demdex.net cookie is used for cross-domain tracking. If the browser does not accept third-party cookies and
the demdex.net cookie cannot be set, a Marketing Cloud ID is not returned. If the Visitor API does not receive a Marketing
Cloud ID in the first request, a request is sent to the data collection CNAME for a visitor ID. The data collection server sets an
AMCV cookie with the Marketing Cloud ID in the response header. This cookie is set in a first-party context, so it can be used
for cross-domain tracking.
This ID is stored and used going forward for that visitor, and is included in hits in the 'mid' query string parameter.
How the Visitor ID Service Works
7
The AMCV cookie is then checked for an Analytics ID. If present, the ID from the cookie is used. If the Analytics ID is not present,
the previous request to your data collection server is checked for a legacy Analytics visitor ID (s_vi cookie), or if a request
wasn't made in the previous step, a new request is sent. If an s_vi cookie is set for the visitor, that value is stored as the Analytics
ID, and is included in hits in the 'aid' query string parameter. If the s_vi cookie is not set, the analytics ID is set to an empty
string. When the Analytics ID is empty, the Marketing Cloud ID is used by Analytics and the 'aid' query string parameter is
not set on the hit.
Note that there are no charges for the calls to retrieve a visitor ID.
How the Visitor ID Service Works
8
Using the Visitor ID Service with Analytics
The Marketing Cloud visitor ID service replaces the legacy Analytics visitor ID methods.
After the visitor ID service is implemented, the visitor ID service code executes before AppMeasurement. The visitor ID service
retrieves the Marketing Cloud and Analytics visitor IDs so these values are ready when AppMeasurement is loaded.
When AppMeasurement loads, the Marketing Cloud and Analytics visitor IDs values are requested from the visitor ID service
and are sent to data collection with each server call. Since the visitor ID service determines the visitor ID and simply passes it
to AppMeasurement, the visitor ID service must be included and implemented on each page before your AppMeasurement
JavaScript file.
Changes to the Analytics Visitor ID process
The primary change when migrating to the visitor ID service is that the visitor ID cookie is now set using JavaScript, instead of
in the HTTP header that is returned from the data collection web server. To understand this change, the following sections
describe how cookies are set using these two methods.
HTTP Header
Cookies are set by a web server by including them in the HTTP response, which is how the s_vi cookie that is used to identify
Analytics visitors is set. After a cookie is set, it is sent with all subsequent HTTP requests to that server.
When a request is sent to the Adobe data collection server, the header is checked for the s_vi cookie. If this cookie is in the
request, it is used to identify the visitor. If the cookie is not in the request, the server generates a unique visitor ID, sets it as a
cookie in the HTTP response header, and sends it back with the request. The cookie is stored in the browser and is sent back to
the data collection server during subsequent visits the site, which enables the visitor to be identified across visits.
However, some browsers, such as Apple Safari, no longer store cookies that are set in the HTTP header from domains that do
not match the domain of the current website. For example, if you are on mysite.com and your data collection server is
mysite.omtrdc.net, the cookie that is returned in the HTTP header from mysite.omtrdc.net might be rejected by the
browser.
To avoid this, many customers have implemented CNAME records for their data collection servers as part of a first-party cookie
implementation. If a CNAME record is configured to map a hostname on the customer's domain to the data collection server
(for example, mapping metrics.mysite.com to mysite.omtrdc.net), the visitor ID cookie is stored since the data collection
domain now matches the domain of the website. This increases the likelihood that the visitor ID cookie will be stored, but it
introduces some overhead as you need to configure CNAME records and maintain SSL certificates for data collection servers.
JavaScript
JavaScript can read and write cookies on the domain of the current website. The visitor ID service uses this method to set the
AMCV_###@AdobeOrg cookie that contains all of the visitor IDs, so the domain of the tracking server no longer needs to match
the domain of the website in order for the visitor ID cookie to be stored. In most circumstances this is the preferred way to set
the visitor ID cookie since it eliminates the overhead of CNAME records and SSL certificates.
However, there are a few situations where setting the cookie in the HTTP header is beneficial for cross-domain tracking, which
is described in Data Collection CNAMEs and Cross-Domain Tracking.
Custom Visitor IDs
Setting a customer visitor ID using s.visitorID continues to be supported by the visitor ID service.
How the Visitor ID Service Works
9
There is a small risk when using s.visitorID with the Analytics for Target integration. If Target receives data for a hit and Analytics
does not, the Target data sent server-side will not be tied to any Analytics data, and will be assigned a different visitor ID. Visitor
counts could be inflated when this occurs. Moving your Analytics code to the top of the page when setting s.visitorID
minimizes this risk.
We recommend also setting the custom visitor ID as a customer ID.
For new implementations we recommend setting Customer IDs instead.
Analytics Visitor ID Order
After you deploy the visitor ID service, there are five ways a visitor can be identified in Analytics (listed in the following table
in order of preference):
Order Query Parameter (collection method)
Used
Present When
vid (s.visitorID)
s.visitorID is set
aid (s_vi cookie)
Visitor had an existing s_vi cookie before you deployed the visitor
ID service, or you have a Visitor ID Grace Period configured.
mid (AMCV_ cookie set by Marketing Cloud
visitor ID service)
Visitor's browser accepts cookies (first-party)
fid (fallback cookie on H.25.3 or newer, or
AppMeasurement for JavaScript)
Visitor's browser accepts cookies (first-party)
IP Address, User Agent, Gateway IP Address
Visitor's browser does not accept cookies.
In many scenarios you might see 2 or 3 different IDs on a call, but Analytics will use the first ID present from that list as the
official visitor ID. For example, if you are setting a custom visitor ID (included in the "vid" query parameter), that ID will be
used before other IDs that might be present on that same hit.
Using the Visitor ID with Target
Adobe Target can be integrated with Adobe Analytics and the visitor ID service using an integration. When this integration is
enabled, Target and Analytics data are combined on the same server call during processing so that visitors are connected between
the two solutions.
See Adobe Analytics as the Reporting Source for Adobe Target.
Using the Visitor ID with Video Heartbeat
Video heartbeat requires the visitor ID service. When measuring video on JavaScript or Flash, implementing the visitor ID
service on your site pages and in video playback ensures that visitors are not counted separately when viewing video.
See Measuring Video in Adobe Analytics using Video Heartbeat.
Visitor ID Service Requirements
10
Visitor ID Service Requirements
This section lists the specific code versions and other visitor ID service requirements.
Marketing Cloud Enabled
Before you implement the visitor ID service, your company must be enabled for the Marketing Cloud and you must have your
Marketing Cloud Organization ID.
If you are already enabled but do not know your Marketing Cloud Organization ID, you can view it in the Marketing Cloud.
See Marketing Cloud Administration.
If you aren't sure if you are enabled or not, ask an Administrator if members of your company can log in at marketing.adobe.com
using an Adobe ID. If so, then you are already enabled and an Administrator can view your Marketing Cloud Organization ID.
If your company is not yet enabled for Marketing Cloud, see Marketing Cloud Getting Started for Administrators to find out
how to get enabled.
Visitor ID Service Enabled
Contact your Adobe Account Manager and request that your company be enabled for the visitor ID service.
Analytics Regional Data Collection (RDC)
Your Analytics implementation must be using RDC in order to implement the Marketing Cloud visitor ID service. RDC provides
increased data collection performance in Analytics, and ensures that your implementation is ready for Marketing Cloud
integrations.
Complete the steps in Visitor ID Service Migration Decision Points to find out how to start using RDC.
Supported Code Versions
The following library versions are required to support the visitor ID service.
JavaScript
Library
Marketing Cloud
Solution
Library Filename
Required Version
Marketing Cloud visitor ID All Solutions
service for JavaScript
VisitorAPI.js
1.2.1 or later*
AppMeasurement for
JavaScript
Analytics
AppMeasurement.js
1.3 or later
s_code
Analytics
s_code.js
H.27 or later
Mbox Code
Target
mbox.js
48 or later
Data Integration Library
(DIL)
Audience
management
dil.js
4.9 or later
Video heartbeat
Analytics
VideoHeartbeat.js
1.2.0 or later
*1.3 or later is required to use a data collection CNAME in Analytics by specifying the marketingCloudServer variable.
Flash, Flex, and Air
Visitor ID Service Requirements
Library
11
Marketing Cloud
Solution
Library Filename
Required Version
Marketing Cloud visitor ID All Solutions
service for ActionScript
VisitorAPI.swc
3.8
Platform Requirements
N/A
All Solutions
The visitor ID service for Flash requires the
following software versions based on your
target platform:
• AIR 3.0+
• Flex SDK 4.6+
• Flash Player 11+
AppMeasurement for Flash Analytics
AppMeasurement.swc
3.8 or later
Video heartbeat
VideoHeartbeat.swc
1.2.0 or later
Analytics
Migrating Analytics to use the Visitor ID Service
12
Migrating Analytics to use the Visitor ID Service
This section provides an overview of the steps required to migrate your Analytics JavaScript data collection code to use the
visitor ID service. At each step, links are provided to more detailed steps to help you perform the upgrade task.
You should be familiar with the following terms before you start:
• Analytics JavaScript code - This refers to the JavaScript code that defines the objects and functions used to measure your
website. It is usually contained in a file called s_code.js or AppMeasurement.js depending on the code version, but this
file is often renamed, and sometimes combined with other JavaScript files. For Adobe Dynamic Tag Manager customers, this
is the code that is pasted into the core AppMeasurement Code section.
• Data collection CNAME - Sometimes just CNAME or abstracted as 'first-party cookies', this is a process where a customer
configures a DNS entry on their hostname that points to their Adobe data collection server (for example,
metrics.example.com). This configuration sets the Analytics visitor ID cookie as a 'first-party cookie' (since the domain
of the Adobe data collection server now matches your website), which is much more likely to be accepted by all browsers. The
visitor ID makes this process unnecessary for many customers, so this guide also addresses migrating away from a data collection
CNAME.
Step Task
Get enabled for Adobe
Marketing Cloud
Create a migration plan
Description
All customers need to be enabled for the Adobe Marketing
Cloud to implement the visitor ID service. Make sure you
know your Marketing Cloud Org ID before you proceed.
To create a migration plan, you need to following
information:
Details
Visitor ID Service Requirements
Visitor ID Service Migration
Decision Points
• List of all data collection code used on your site, including Visitor ID Service Migration
JavaScript, Flash, Silverlight, and hard-coded image tags. Scenarios
• Your secure and non-secure data collection server
hostnames (trackingServer and trackingServerSecure).
Use the links in the details column to answer the following
questions before you proceed:
• Do I need to configure a grace period?
• Do I need to migrate visitors to a new data collection
hostname?
• Do I need to upgrade any data collection methods that are
not supported?
Configure visitor
migration from your data
collection CNAME or
2o7.net to *.sc.omtrdc.net
If you determined that you need to migrate from your
current data collection hostname, you should configure
visitor migration. When this is configured, the Analytics
JavaScript code makes a quick hop back to your old domain
to see if new visitors already have a visitor ID cookie. If so,
that cookie is moved over and historical data is preserved.
Configure a visitor ID
grace period
If you determined that you need to configure a visitor ID
grace period, you should configure that next. During the
grace period, new visitors continue to receive a legacy
Visitor Migration
Visitor ID Grace Period
Migrating Analytics to use the Visitor ID Service
Step Task
Description
13
Details
Analytics ID (an s_vi cookie) so that you have time to update
code across your site.
Update your Analytics
JavaScript code
The visitor ID service requires the latest Analytics JavaScript
code. Test and deploy the latest version of H code or
AppMeasurement for JavaScript using your standard
process.
Analytics Implementation Guide
If you are migrating from your current data collection
hostname, make sure you update s.trackingServer with
your new data collection hostname.
Implement and deploy
the visitor ID service
Visitor ID Service
The code implementation requires that you include the
Implementation
VisitorAPI.js code on all site pages, and then add a few
lines of configuration code.
Test and verify your
implementation
Verify Visitor ID Service
After you've completed the migration steps, make sure data Implementation
is being sent correctly.
Visitor ID Service Migration Decision Points
14
Visitor ID Service Migration Decision Points
The code changes required to deploy the visitor ID service are straightforward. However, it is important that you understand
how switching to the visitor ID service impacts the way visitors might be tracked on multiple domains, and potential issues if
you are using multiple data collection methods or JavaScript files to collect data.
Answer the question in this section to determine any additional migration steps you should take.
• Do you have a data collection CNAME?
• If you have a data collection CNAME, do you have multiple domains?
• If you do not have a data collection CNAME, is your data collection server *.2o7.net or *.sc.omtrdc.net?
• Do you have multiple Analytics JavaScript files, or are you tracking Flash applications or videos?
• Are you using data collection methods that are unsupported?
Do you have a data collection CNAME?
Many customers can migrate away from a data collection CNAME as part of the visitor ID service migration.
I am using a data collection See the next question to decide if you should migrate away from a data collection CNAME.
CNAME
I am not using a data
collection CNAME
Skip to If you do not have a data collection CNAME, is your data collection server *.2o7.net or
*.sc.omtrdc.net?.
If you have a data collection CNAME, do you have multiple domains?
If you have multiple domains that send data to the same report suite, you might benefit from a data collection CNAME to track
visitors across domains. If you are collecting data on a single domain, there is no advantage to maintaining a data collection
CNAME.
I am collecting data from
multiple domains
I am collecting data from a
single domain
If you are tracking visitors across multiple domains, and you also have a main entry site where
customers can be identified before they visit other domains, then you should continue to use
your data collection CNAME. See Data Collection CNAMEs and Cross-Domain Tracking for a
detailed explanation. Note that you need to specify two additional parameters,
visitor.marketingCloudServer and visitor.marketingCloudServerSecure, to
configure a CNAME with the visitor ID service (details are provided in the implementation
steps as part of the migration process).
You should migrate away from your data collection CNAME back to your default data collection
hostname (either omtrdc.net or 2o7.net).
To make this migration, configure visitor migration from your CNAME to *.sc.omtrdc.net, and
then update s.trackingServer to [namespace].sc.omtrdc.net when you update your
Analytics JavaScript code later as part of the migration process. If you have any questions at all
about the hostname of your tracking server, have a supported user in your organization contact
Customer Care.
If you are keeping your data collection CNAME, is it mapped to omtrdc.net?
If you decided to keep your CNAME, open a command prompt and ping your CNAME:
$: ping metrics.example.com
PING example.com.d1.sc.omtrdc.net (66.235.139.256)
Visitor ID Service Migration Decision Points
My CNAME resolves to
*.omtrdc.net
Your CNAME is configured correctly, no additional action is necessary.
My CNAME resolves
somewhere else
You need to update the CNAME record to point to your RDC hostname.
15
If you do not have a data collection CNAME, is your data collection server *.2o7.net or *.sc.omtrdc.net?
My server is *.2o7.net
If you are using *.2o7.net, you need to migrate to the RDC data collection domain,
*.sc.omtrdc.net.
To make this migration, configure visitor migration from *.2o7.net to *.sc.omtrdc.net,
and then update s.trackingServer to [namespace].sc.omtrdc.net when you update
your Analytics JavaScript code later as part of the migration process. If you have any questions
at all about the hostname of your tracking server, have a supported user in your organization
contact Customer Care.
My server is *.sc.omtrdc.net You can continue to use your current data collection server, and you can skip the visitor
migration step in Migrating Analytics to use the Visitor ID Service.
Do you have multiple Analytics JavaScript files, or are you tracking Flash applications or videos?
If you have multiple Analytics JavaScript files or Flash applications or videos across your site that send data to the same report
suite, You should configure a grace period so that visitors continue to be identified by an Analytics ID while you roll out the
visitor ID service.
I have multiple Analytics
JavaScript files, or I am using You should configure a visitor ID service grace period so that you can roll out the visitor ID
service to each JavaScript file and other data collection libraries. See Visitor ID Grace Period.
other data collection
methods in addition to
JavaScript
I have a single Analytics
JavaScript file
You can update your single JavaScript file to use the visitor ID service without a grace period.
Are you using data collection methods that are unsupported?
You might need to update the way you track links or migrate away from Sliverlight.
My site uses JavaScript
and/or Flash only
My site uses Silverlight
My site uses hard-coded
image tags
The visitor ID service is supported by these data collection methods.
If visitors can access Silverlight content in addition to other sections of your site that use the
visitor ID service, you need to migrate away from Silverlight since it is not supported by the
visitor ID service. If you are tracking a Silverlight-based video player, the vendor likely provides
JavaScript APIs that you can use instead.
You should update these links to use JavaScript instead.
Visitor ID Service Migration Scenarios
16
Visitor ID Service Migration Scenarios
Contains server example configurations and the required migration steps.
• Single Web Property
• Multiple JavaScript Files, hard-coded image tags
• Multiple Web Properties, Multiple JavaScript Files and a Flash-based Video Player
Single Web Property
• Customer: Example Company Inc.
• Marketing Cloud enabled: No
• Web Properties: example.com
• Data collection servers: metrics.example.com, smetrics.example.com
• Analytics JavaScript file: A single file for all site pages
First, this customer should get enabled for the Marketing Cloud (see Visitor ID Service Requirements). Since they have a single
JavaScript file, they do not need to configure a grace period. This customer will also set up visitor migration and then migrate
away from their data collection CNAME as it is no longer necessary.
Multiple JavaScript Files, hard-coded image tags
• Customer: Another Example Company Inc.
• Marketing Cloud enabled: Yes
• Web Properties: anotherexample.com
• Data collection servers: anotherexampleco.112.2o7.net
• Analytics JavaScript file: Multiple JavaScript files. One file for their main site, another file for their support section that is
maintained in a separate CMS.
• Other data collection methods: Hard-coded image tags on one site section
First, this customer should find their Adobe Marketing Cloud Organization ID (see Visitor ID Service Requirements). Next,
since they are using multiple JavaScript files, they should configure a migration grace period. This customer will also set up
visitor migration and then migrate from *.2o7.net to *.sc.omtrdc.net.
When this customer updates to the latest Analytics JavaScript code in preparation for the visitor ID service rollout, they will
also update all hard-coded image tags to use JavaScript instead.
Multiple Web Properties, Multiple JavaScript Files and a Flash-based Video Player
• Customer: A Good Customer LLC
• Marketing Cloud enabled: Yes
• Web Properties: mymainsite.com, myothersiteA.com, myothersiteB.com
• Data collection servers: metrics.mymainsite.com, smetrics.mymainsite.com
• Analytics JavaScript file: Multiple JavaScript files. One file for each web property.
• Other data collection methods: A Flash-based video player
First, this customer should find their Adobe Marketing Cloud Organization ID (see Visitor ID Service Requirements). Next,
since they are using multiple JavaScript files, they should configure a migration grace period. This customer tracks visitors
between their primary domain and their sub-domains, so they will continue to use their data collection CNAME with the visitor
ID service.
When this customer updates to the latest Analytics JavaScript code in preparation for the visitor ID service rollout, they will
also update their Flash-based video player to the latest version of AppMeasurement for Flash.
Visitor ID Service Implementation
17
Visitor ID Service Implementation
This section contains instructions to deploy the Marketing Cloud visitor ID service.
This section lists the steps required to deploy the visitor ID service code and configure your Analytics JavaScript file to use the
visitor ID service.
Before you implement, make sure you have reviewed the requirements and have requested that your company be enabled for
the visitor ID service.
Important: If you need to configure a grace period, it must be configured before you complete these steps.
Complete one of the following tasks based on your chosen deployment method:
• Dynamic Tag Management
• JavaScript Deployment (VisitorAPI.js)
• Other Deployment Tools
Dynamic Tag Management
See Marketing Cloud ID Service in the Dynamic Tag Management help.
JavaScript Deployment (VisitorAPI.js)
Use these steps to deploy the visitor ID service by including VisitorAPI.js on site pages.
Step
Task
Download the visitor ID library
Configure the visitor ID service
Description
The visitor ID library is distributed with AppMeasurement in Code Manager.
In VisitorAPI.js, add the following visitor ID initialization code at the
beginning of the file:
var visitor = new Visitor("INSERT-MCORG-ID-HERE");
visitor.trackingServer = "INSERT-TRACKING-SERVER-HERE"; //
same as s.trackingServer
visitor.trackingServerSecure =
"INSERT-SECURE-TRACKING-SERVER-HERE"; //same as
s.trackingServerSecure
// To enable CNAME support, add the following configuration
variables
// If you are not using CNAME, DO NOT include these variables
visitor.marketingCloudServer = "INSERT-TRACKING-SERVER-HERE";
visitor.marketingCloudServerSecure =
"INSERT-SECURE-TRACKING-SERVER-HERE"; //same as
s.trackingServerSecure
/*
============== DO NOT ALTER ANYTHING BELOW THIS LINE !
============
• "INSERT-MCORG-ID-HERE" - (Required) Your Adobe Marketing Cloud
Organization ID, including @AdobeOrg. See Marketing Cloud Enabled.
• "INSERT-TRACKING-SERVER-HERE" - (Required) Your Analytics tracking
server. See Correctly populate the trackingServer and trackingServerSecure
variable.
Visitor ID Service Implementation
Step
Task
18
Description
• "INSERT-SECURE-TRACKING-SERVER-HERE" - (Required if SSL is enabled
on your site) Your Analytics secure tracking server. See Correctly populate the
trackingServer and trackingServerSecure variable.
Note: If you have a 2-part top-level domain (such as .com.uk), review the
cookieDomain configuration variable reference to determine if the
cookieDomain variable must be set.
Distribute VisitorAPI.js
This file should be deployed to your site and then referenced in the <head> or
<body> tag on each page. VisitorAPI.js must execute before appMeasurement
for JavaScript and other Adobe Marketing Cloud libraries and page code, so place
it higher on the page.
If you are deploying a tag that must appear in the <head> tag, you must also
deploy VisitorAPI.js in the <head> tag so that it appears before other solution
tags.
Can I add the code in VisitorAPI.js to my Analytics JavaScript File?
Set a custom prop in
AppMeasurement.js or
s_code.js to measure
coverage
(Recommended) Add the following to a custom prop in your implementation:
s.prop1 = (typeof(Visitor) != "undefined" ? "VisitorAPI
Present" : "VisitorAPI Missing");
You can then view the prop report to see what percentage of your pages are
referencing VisitorAPI.js.
If the visitor API is not present on all pages, you should enable a grace period to
provide time to deploy updated code to production.
After you have the correct coverage, continue to the next step.
Activate the visitor ID service in
Deploying the VisitorAPI.js file and activating the service in Analytics are
AppMeasurement
separate steps. You should make sure you have complete coverage on all site pages
using the process in the previous step before you active the visitor ID service in
Analytics.
In AppMeasurement.js or s_code.js, add the following code to start using
the new visitor ID service:
s.visitor = Visitor.getInstance("INSERT-MCORG-ID-HERE");
This line can be inserted anywhere above the core AppMeasurement code before
any tracking calls are made.
Test the visitor ID service
You can verify that the visitor ID service is in use by checking for the mid
parameter using Adobe Debugger (previously DigitalPulse Debugger).
You can also check that the AMCV_###@AdobeOrg cookie is set on the domain
where your page is hosted.
Visitor ID Service Implementation
Other Deployment Tools
Use the following guidelines to select the correct deployment configuration when using other deployment tools.
The visitor ID service should:
• Be loaded before all other Marketing Cloud tags (Analytics, Target, Audience Manager, and so on).
• Run synchronously
• Execute globally
If deploying with Analytics, you can add the contents of Visitor API to the beginning of your Analytics JavaScript code.
19
Verify Visitor ID Service Implementation
20
Verify Visitor ID Service Implementation
Use the following process to make sure the visitor ID service is implemented correctly on your site.
1. Clear cookies for your site so you can see the request to the visitor ID service (the request happens on the first visit, then
approximately once per visitor per week).
2. Using a packet analyzer or the network panel in a web browser debugger, look for a request going to dpm.demdex.net.
3. Verify that the response contains d_mid and a value, for example:_setMarketingCloudFields({"d_mid":"4235....
If there is no d_mid value, you will see an error message saying the org ID has not been provisioned. If this is the case, you'll
need to contact Customer Care to verify that your company is correctly provisioned.
Correctly provisioned:
Incorrectly provisioned:
4. Verify that the Analytics request contains an mid parameter (the Marketing Cloud visitor ID). During the grace period, you
should also see an aid parameter (the Analytics visitor ID). Note that your Analytics request will still contain the mid that
was generated using the JavaScript fallback even if the org ID has not been provisioned (this was tested in the previous step).
For existing visitors, or when you have a visitor ID grace period configured, aid will also be present in the server call.
Verify Visitor ID Service Implementation
21
Validating Customer IDs
Customer IDs are sent in calls to dpm.demdex.net in query-string variables named "d_cid_ic", with values formatted according
to "[CIDTYPE]%01[CID]". For example, in the following call in the Visitor API:
visitor.setCustomerIDs({
"loginid":"EA12345"
});
The resulting dpm.demdex.net image request contains the following:
&d_cid_ic=loginid%01EA12345
Customer IDs
22
Customer IDs
Along with the Marketing Cloud visitor ID, you can set additional customer IDs to associate with each visitor. The Visitor API
accepts multiple Customer IDs for the same visitor, along with a customer type identifier to separate the scope of the different
Customer IDs.
Note: Customer IDs are not currently used to identify visitors, but should be set in preparation for future functionality.
// Single
visitor.setCustomerIDs({
"crm_id":"67312378756723456"
});
// Multiple
visitor.setCustomerIDs({
"crm_id":"67312378756723456",
"support_chat_id":"550e8400-e29b-41d4-a716-446655440000"
});
You should not include any Personally Identifiable Information (PII) in the customer IDs. If you are using PII to identify a
visitor (such as an email address), we recommending storing a hashed or encrypted version of the information instead.
Customer IDs are not stored in the visitor ID cookie, so they must be set for every page or application context.
See Validating Customer IDs for details on how customer IDs are sent.
Customer IDs and Analytics Custom Visitor IDs
See Custom Visitor IDs.
Data Collection CNAMEs and Cross-Domain Tracking
23
Data Collection CNAMEs and Cross-Domain Tracking
If you have a main entry site where customers can be identified before they visit other domains, then a CNAME can enable
cross-domain tracking in browsers that do not accept third-party cookies (such as Safari).
In browsers that accept third-party cookies, a cookie is set by the demdex.net server during the request to retrieve a visitor ID.
This cookie allows the visitor ID service to return the same Marketing Cloud visitor ID on all domains that are configured using
the same Marketing Cloud Org ID.
In browsers that reject third-party cookies, a new Marketing Cloud visitor ID is assigned for each domain.
The demdex.net cookie enables the visitor ID service to provide the same level of cross-domain tracking as the s_vi cookie in
Analytics, where the cookie is accepted in some browsers and used across domains, but rejected by other browsers.
Data Collection CNAMEs
When the Analytics cookie was set by the data collection server, many customers have configured data collection server CNAME
records as part of a first-party cookie implementation to avoid issues with browsers that reject third-party cookies. This process
configures your data collection server domain to match your website domain so the visitor ID cookie is set as a first-party cookie.
Since the visitor ID service sets the visitor cookie directly on the domain of the current website using JavaScript, this configuration
is no longer needed to set first-party cookies.
Customers that have a single web property (a single domain) can migrate away from data collection CNAMEs and use their
default data collection hostname instead (either omtrdc.net or 2o7.net).
However, there is an additional benefit to using a CNAME for data collection which allows you to track visitors between a main
landing domain and other domains in browsers that do not accept third-party cookies. Customers that have multiple web
properties (multiple domains) might benefit from maintaining a data collection CNAME. The following section explains how
cross-domain visitor tracking works in detail so you can decide if you might benefit.
How CNAMEs enable cross-domain tracking
Due to the way first-party cookies can be used in a third-party context in Apple Safari and some other browsers, a CNAME let
you track customers between a primary domain and additional domains that used the same tracking server.
For example, you have a primary site at mymainsite.com. You configured the following two CNAME records to point to your
non-secure and secure data collection servers:
• metrics.mymainsite.com
• smetrics.mymainsite.com
When a user visits mymainsite.com, the visitor ID cookie is set by the data collection server. This is allowed since the domain
of the data collection server matches the domain of the website, and is what is known as using a cookie in a "first-party context",
or just a "first-party cookie".
If you are also using these same data collection servers on other sites (for example, myothersiteA.com, and
myothersiteB.com), if a visitor later visits these sites, the cookie that was set during the visit to mymainsite.com is sent in
the HTTP request to the data collection server (remember that browsers send all cookies for a domain with all HTTP requests
to that domain, even if the domain doesn't match the domain of the current website). This is what is known as using a cookie
in a "third-party context, or just a "third-party cookie", and it enables the same visitor ID to be used on these other domains.
Note that this functionality may be seen in all major browsers, even those such as Safari that block third party cookies by default.
If a cookie has been used in a first-party context during the visit to mymainsite.com, Safari continues to use it in a third-party
Data Collection CNAMEs and Cross-Domain Tracking
24
context (during the visit to the other domains). Be aware that if a visitor visits myothersiteA.com before visiting
mymainsite.com, Safari will block the mymainsite.com cookie because it hasn't ever been used in a first-party context.
As a result, your collection domain should be a domain that people commonly visit in order for a visitor to be identified across
domains. If there is no “common” domain to use for the data collection domain, there is no cross-domain benefit to maintaining
a CNAME for the data collection domain. If the main entry site is not visited first, visitors are identified differently on the
secondary site and main site.
Enable CNAME support with the Visitor ID Service
Data collection server CNAME support is enabled by setting the visitor.marketingCloudServer and
visitor.marketingCloudServerSecure variables. Instructions are provided as part of the Visitor ID Service Implementation.
Visitor ID Grace Period
25
Visitor ID Grace Period
If you have multiple JavaScript files that are sending data to the same report suite, or if you are using other technologies on your
site such as Flash video measurement, we recommend configuring a grace period.
After you deploy the visitor ID service, new visitors no longer receive an Analytics visitor ID from your data collection server.
If sections of your site have not yet implemented the visitor ID service, when visitors browse to these sections, the Marketing
Cloud ID is not recognized and visitors are assigned a legacy Analytics visitor ID. This can cause a number of issues including
duplicate visits and incorrect attribution.
For example, if the support section of your site is managed in a separate CMS, you might have a different Analytics JavaScript
file for this section. If you deploy the visitor ID on your main site before you deploy the visitor ID service to the support site,
new visitors will receive a legacy Analytics ID when they visit the support section, and visits that span both site sections will be
reported as different visits.
Deploying the visitor ID service on sites that are using multiple JavaScript files or other technologies (such as Flash) can cause
coordination issues since you need to enable the visitor ID service on all portions of your site at the same time. By configuring
a grace period, new visitors to continue to receive an Analytics visitor ID from the visitor ID service, so visitors can be consistently
identified on sections of your site that have not been upgraded to use the visitor ID service.
Note: Grace Period support requires version 1.3 or later of the visitor ID service.
Do I need a grace period?
If you have a single Analytics JavaScript file and are not using any other AppMeasurement libraries, then you likely do not need
a grace period. You can make the update in the single JavaScript file and new visitors will be consistently identified using the
marketing cloud ID during the visit.
If you have multiple JavaScript files that are sending data to the same report suite, or if you are using other technologies on your
site such as Flash video measurement, we recommend configuring a grace period.
The Visitor ID Service Implementation process contains a step to test coverage before it is enabled so you can determine coverage
before the visitor ID service is activated in Analytics.
How can I enable a grace period?
A supported user in your organization can Contact Customer Care.
Server-side Implementation Mixed with JavaScript
26
Server-side Implementation Mixed with JavaScript
In some implementations, visitor IDs are passed from JavaScript to a server so that additional Analytics events (such as a
purchase) can be sent by the server.
The Visitor API provides methods, getMarketingCloudVisitorID and getAnalyticsVisitorID, to retrieve the visitor ID values that
can then be passed to the server.
Make sure you check for both the Marketing Cloud visitor ID and the Analytics visitor ID, and send both IDs (if present) to
make sure any data sent is associated with the existing Analytics visitor profile.
Important: AppMeasurement for Java does not currently support the Marketing Cloud visitor ID service.
Data Insertion API
Include the Analytics visitor ID (if set) in the <visitorID> element.
Include the Marketing Cloud visitor ID in the <marketingCloudVisitorID> element.
See Supported XML Tags.
AppMeasurement for Java
The Marketing Cloud visitor ID is not currently supported by AppMeasurement for Java.
Library Reference
27
Library Reference
The following functions and values are provided by the visitor ID service library.
Visitor ID Service Functions
Method
getInstance
Description
Creates or returns an existing a visitor ID object for the specified Adobe Marketing Cloud
Organization ID. This is required to initialize the visitor ID object that is provided to
AppMeasurement using s.visitor.
JavaScript
var visitor = Visitor.getInstance("016D5C175213CCA80A490D13@AdobeOrg")
ActionScript/Flash
import com.adobe.mc.Visitor;
...
var visitor:Visitor =
Visitor.getInstance("016D5C175213CCA80A490D13@AdobeOrg")
If getInstance doesn't find an existing instance, an new instance is created and returned
(similar to s_gi if you are familiar with AppMeasurement).
The Visitor API maintains a list of all instances created for each Adobe Marketing Cloud
Organization ID, so if the application using the Visitor API isn't passing around a reference
to the instance it can find that instance by calling getInstance instead of creating a new
one. This also provides support for multiple instances for different organizations in the same
web page/application.
This is useful for applications that don't have a clear "init" phase but need to call into the
Visitor API in multiple places. You can call getInstance in all of those places and the first
to execute will be the one that creates the instance, and the existing instance will be returned
by subsequent calls.
getMarketingCloudVisitorID
Returns the Marketing Cloud visitor ID.
var mcID = visitor.getMarketingCloudVisitorID()
This method is typically used by custom solutions that require reading the visitor ID. It is not
used by a standard implementation.
Make sure you check for both the Marketing Cloud visitor ID and the Analytics visitor ID,
and send both IDs (if present) to make sure any data sent is associated with the existing
Analytics visitor profile. For example, if you are passing the visitor ID in a hidden form
element to a server-side application that uses the data insertion API, both the Marketing
Cloud and Analytics visitor IDs should be collected and sent.
getAnalyticsVisitorID
Returns the legacy Analytics ID (if any) that was stored in the s_vi cookie before the visitor
ID service was implemented. If a visitor was not previously assigned an Analytics ID, this
returns is an empty string.
var analyticsID = visitor.getAnalyticsVisitorID()
Library Reference
Method
28
Description
This method is typically used by custom solutions that require reading the visitor ID. It is not
used by a standard implementation.
Make sure you check for both the Marketing Cloud visitor ID and the Analytics visitor ID,
and send both IDs (if present) to make sure any data sent is associated with the existing
Analytics visitor profile. For example, if you are passing the visitor ID in a hidden form
element to a server-side application that uses the data insertion API, both the Marketing
Cloud and Analytics visitor IDs should be collected and sent.
setCustomerIDs
Sets one or more key value pairs as customer IDs.
// Single
visitor.setCustomerIDs({
"crm_id":"67312378756723456"
});
// Multiple
visitor.setCustomerIDs({
"crm_id":"67312378756723456",
"support_chat_id":"550e8400-e29b-41d4-a716-446655440000"
});
getCustomerIDs
Returns any customer IDs that were set.
var mcID = visitor.getCustomerIDs();
alert(mcID.crm_id);
Visitor ID Service Configuration Variables
Variable
cookieLifetime
Description
Cookie lifetime in seconds, used to override the default 2-year cookie expiration.
visitor.cookieLifetime = 33696000
loadTimeout
Sets the amount of time the visitor ID services spends waiting for a response from the visitor
ID service, in milliseconds:
visitor.loadTimeout = 750
The default load timeout is 500 milliseconds.
Adobe recommends leaving the timeout at the default value to avoid slowing page load time
in the extremely rare case of an Adobe outage. However, if more than 5% of visitors do not
have a marketing cloud visitor ID (you can run a data warehouse report with the marketing
cloud visitor ID), raising the timeout could help. This is most likely to happen for users with
very slow network connections.
cookieDomain
This variable must be set for 2-part top-level domains where the 2 parts are not two characters.
For example:
• www.example.com - Not required because the top-level domain only has one part, "com"
• www.example.co.uk - Not required because both parts of the 2-part top-level domain are 2
characters
Library Reference
29
Variable
Description
• www.example.com.uk - Required because the second part of the 2-part top-level domain is
not 2 characters, so cookieDomain must be set to "example.com.uk". Without this setting,
the cookieDomain would default to "com.uk" which is invalid.
Visitor ID Values
Value
Variable
Query String
Parameter
Marketing Cloud
organization ID
marketingCloudOrgID
N/A
Description
Marketing Cloud organization IDs uniquely identify
the client company in the Adobe Marketing Cloud.
For example:
016D5C175213CCA80A490D05@AdobeOrg
This value is provided to your Administrator after your
company is enabled for the Adobe Marketing Cloud.
Marketing Cloud
visitor ID
returned by
mid
getMarketingCloudVisitorID
Analytics visitor ID returned by
getAnalyticsVisitorID
aid
Universal ID across Marketing Cloud solutions.
Legacy Analytics visitor ID. Contains the Analytics
visitor ID if an ID was assigned before the visitor ID
service was implemented (s_vi cookie). This is sent
along with the Marketing Cloud visitor ID with each
server call to make sure historical data is preserved.
This is empty for new visitors.
FAQ
30
FAQ
A list of common questions asked about the visitor ID service.
Can I add the code in VisitorAPI.js to my Analytics JavaScript File?
Yes, as long as your AppMeasurement.js or s_code.js file is loaded before all other Marketing Cloud JavaScript tags (such
as mbox.js). If so, you can paste the contents of the VisitorAPI.js file, including the configuration you added in step 1
"Configure the visitor ID service", and paste it at the beginning of your AppMeasurement.js or s_code.js file. Make sure
you also enable the service by completing step 4 "Enable the visitor ID service in AppMeasurement".
Note that AppMeasurement.js can be deployed in the <head> or <body> tag on each page, where s_code.js must be
deployed in the <body>.
Do I have to set up a CNAME to track visitors across domains?
If you have a main entry site where customers can be identified before they visit other domains, then a CNAME can enable
cross-domain tracking in browsers that do not accept third-party cookies (such as Safari).
In browsers that accept third-party cookies, a cookie is set by the demdex.net server during the request to retrieve a visitor ID.
This cookie allows the visitor ID service to return the same Marketing Cloud visitor ID on all domains that are configured using
the same Marketing Cloud Org ID. In browsers that reject third-party cookies, a new Marketing Cloud visitor ID is assigned
for each domain.
Even when a CNAME is configured, if the main entry site is not visited first, visitors are identified differently on the secondary
site and main site in browsers that do not accept third-party cookies.
Why is the 'mid' parameter not in the Analytics request?
If the visitor ID service is returning information correctly but you do not see the mid parameter, make sure that you've upgraded
to a supported version of AppMeasurement.
Can my site use H code and AppMeasurement for JavaScript with the visitor ID service?
Yes. As long as both files refer to the same VisitorAPI.js file, you can use a mix of H code and AppMeasurement for JavaScript
across your site.
Why do I need to migrate to RDC?
In addition to the global performance benefits, RDC migration is required to make sure your implementation is ready for
upcoming features that leverage Adobe's global network of edge notes.
Can I use Dynamic Tag Management to deploy the visitor ID service?
Yes, see Marketing Cloud ID Service in the Dynamic Tag Management help.
Release History
31
Release History
Release date and changes for each version of VisitorAPI.js.
1.3.4
Release date: January 15, 2015
• AN-93555 Reworked <head>/<body> tag finding for JSONP request <script> tag container, as well as the creation of the
<script> tag to account for different DOM implementations (HTML vs XHTML) with possibly different case sensitivity
settings.
1.3.3
Release date: November 20, 2014
• Fixed handling of forced field expiration reset when that field is received which lead to multiple, identical requests to
dpm.demdex.net.
1.3.2
Release date: September 18, 2014
• Fixed an issue that might cause an invalid Marketing Cloud visitor IDs to be generated by the fallback mechanism when
handling timeouts.
1.3.1
Release date: August 21, 2014
• Added a cookieDomain configuration variable to let you specify the domain on which the AMCV_ cookie is set for some
domains that can't be determined automatically.
1.3
Release date: June 19, 2014
• Support for using existing Analytics first-party data collection hostname (cname) with Marketing Cloud visitor ID service.
1.2.2
Release date: May 22, 2014
• Fixed handling of 2 character top-level domains such as ".no" and ".us" when writing cookies.
1.2.1
Release date: April 17, 2014
• Support for Marketing Cloud ID
• Updated to use Marketing Cloud Organization ID instead of Analytics namespace
• Support for Audience Manager location hint and blob for supplemental data support.
1.0
Release date:
• Initial Release supporting Analytics visitor ID.