close

Вход

Log in using OpenID

Audience Management Help

embedDownload
Adobe® Marketing Cloud
Audience Management Help
Contents
Audience Management Product Documentation..........................................................8
Release Notes....................................................................................................................9
Overview.........................................................................................................................10
History and Background...............................................................................................................................................10
Types of Data Collected................................................................................................................................................11
First-Party Data Collection.....................................................................................................................................................................11
Second-Party Data Collection..............................................................................................................................................................12
Third-Party Data Collection...................................................................................................................................................................12
Custom Segment Generation.....................................................................................................................................13
Performance Reporting.................................................................................................................................................14
Ad Server Integration.....................................................................................................................................................14
Destination Publishing..................................................................................................................................................15
Tag Management............................................................................................................................................................15
Data Security and Privacy.............................................................................................................................................15
Data Security..............................................................................................................................................................................................15
Data Privacy................................................................................................................................................................................................17
Privacy Capabilities Summary..............................................................................................................................................................19
System Components......................................................................................................20
Key Components in the Audience Management System.................................................................................20
Platform Architecture: Data Flow Diagram............................................................................................................20
Functional Architectural Diagrams....................................................................................................................................................22
Tag Management Components.................................................................................................................................24
Data Collection Components......................................................................................................................................25
Data Processing Components....................................................................................................................................26
Data Actionability Components................................................................................................................................27
Understanding the Edge Data Center.....................................................................................................................28
Last updated 12/16/2014
Audience Management Help
Contents
User Interface..................................................................................................................30
Reports................................................................................................................................................................................30
General Reports.........................................................................................................................................................................................30
Trend Reports.............................................................................................................................................................................................32
Onboarding Status Report....................................................................................................................................................................34
Outbound History Report......................................................................................................................................................................36
Custom Reports.........................................................................................................................................................................................38
Interactive Reports...................................................................................................................................................................................38
Counting Unique Users in Overlap and General Reports...........................................................................................................50
Reports and Data Sampling Methodologies...................................................................................................................................50
Data Sources.....................................................................................................................................................................51
Data Sources List View............................................................................................................................................................................51
Create a Data Source...............................................................................................................................................................................52
Edit a Data Source.....................................................................................................................................................................................54
Delete Data Sources.................................................................................................................................................................................56
Traits.....................................................................................................................................................................................56
Trait List View.............................................................................................................................................................................................57
Trait Summary View.................................................................................................................................................................................57
Trait Builder.................................................................................................................................................................................................58
Trait Storage...............................................................................................................................................................................................64
Trait Builder Reference............................................................................................................................................................................65
Segments............................................................................................................................................................................73
Segments: Purpose, Composition, and Rules.................................................................................................................................73
Segments List View..................................................................................................................................................................................74
Segment Summary View........................................................................................................................................................................74
Segment Builder........................................................................................................................................................................................74
Destinations......................................................................................................................................................................81
Working with Destinations....................................................................................................................................................................81
Destination Builder...................................................................................................................................................................................81
Data Delivery Methods in Destination Builder...............................................................................................................................82
How to Choose a Data Delivery Method..........................................................................................................................................82
How to Create URL, Cookie, or Server-to-Server Destinations.................................................................................................83
Destinations Reference...........................................................................................................................................................................88
Last updated 12/16/2014
Audience Management Help
Derived Signals.................................................................................................................................................................91
Create a Derived Signal..........................................................................................................................................................................91
Edit a Derived Signal................................................................................................................................................................................91
Delete a Derived Signal..........................................................................................................................................................................92
Models.................................................................................................................................................................................92
Models..........................................................................................................................................................................................................92
TraitWeight.................................................................................................................................................................................................93
Update Schedule for Algorithmic Models and Traits...................................................................................................................94
Models List View........................................................................................................................................................................................94
Models Summary View...........................................................................................................................................................................95
Model Builder.............................................................................................................................................................................................95
Tags......................................................................................................................................................................................96
The TIM Container....................................................................................................................................................................................97
Scheduled Tags.........................................................................................................................................................................................98
Visitor Profile Viewer....................................................................................................................................................100
User Management........................................................................................................................................................101
Create Users..............................................................................................................................................................................................102
Create Groups..........................................................................................................................................................................................102
Edit Your Account Settings.................................................................................................................................................................103
API..................................................................................................................................105
REST APIs..........................................................................................................................................................................105
Getting Started........................................................................................................................................................................................105
Algorithmic API Methods....................................................................................................................................................................110
Data Integration Library API Methods............................................................................................................................................117
Data Source API Methods....................................................................................................................................................................124
Derived Signals API Methods.............................................................................................................................................................130
Destination API Methods.....................................................................................................................................................................133
Domain Management API Methods................................................................................................................................................151
Segment API Methods..........................................................................................................................................................................152
Taxonomic API Methods......................................................................................................................................................................159
Trait API Methods...................................................................................................................................................................................161
Trait Types.................................................................................................................................................................................................171
User, Group, and Permissions Management API Methods.....................................................................................................173
Last updated 12/16/2014
Audience Management Help
Contents
DCS Region API Methods....................................................................................................................................................................184
Data Integration Library (DIL) API...........................................................................................................................185
Class-level DIL Methods.......................................................................................................................................................................185
Instance-level DIL Methods................................................................................................................................................................189
DIL Modules..............................................................................................................................................................................................196
DIL Tools....................................................................................................................................................................................................200
DIL Use Cases and Code Samples.....................................................................................................................................................202
Flash DIL.....................................................................................................................................................................................................205
Tag Manager Integration.....................................................................................................................................................................207
Implementing Audience Management.......................................................................209
Implementation Overview........................................................................................................................................209
Define Phase............................................................................................................................................................................................209
Discovery Phase......................................................................................................................................................................................210
Build, Test, and Train Phase................................................................................................................................................................210
Launch, Support, and Optimize Phase...........................................................................................................................................211
Code Implementation..........................................................................................................................................................................211
Post-Implementation Support.................................................................................................................................212
Integration Guides.......................................................................................................213
Data Integration Methods.........................................................................................................................................213
Data Integration Methods...................................................................................................................................................................213
Data Translation File..............................................................................................................................................................................215
Real-Time Data Transfer Process.......................................................................................................................................................216
Batch Data Transfer Process...............................................................................................................................................................217
Customer Data Feeds..................................................................................................................................................218
Customer Data Feed Overview.........................................................................................................................................................218
Customer Data Feeds Implementation..........................................................................................................................................222
Customer Data Feeds Getting Started............................................................................................................................................222
Sending Audience Data..............................................................................................................................................228
Real-Time Inbound Data Integration..............................................................................................................................................228
Batch Data Transfer Process Described..........................................................................................................................................231
Receiving Audience Data...........................................................................................................................................244
ID Synchronization for Outbound Data Transfers......................................................................................................................244
Last updated 12/16/2014
Audience Management Help
Real-Time Outbound Data Transfers...............................................................................................................................................244
Batch Outbound Data Transfers.......................................................................................................................................................246
DCS Integration.............................................................................................................................................................248
Variable Prefix Requirements.............................................................................................................................................................248
Supported Variables..............................................................................................................................................................................249
URL Format for Passing in Data to the DCS..................................................................................................................................250
DCS Appendix..........................................................................................................................................................................................252
Ad Server Integration..................................................................................................................................................260
DART Enterprise as an Audience Management Destination..................................................................................................261
GPT as an Audience Management Destination...........................................................................................................................263
DFP as an Audience Management Destination...........................................................................................................................266
OAS as an Audience Management Destination..........................................................................................................................267
OpenX as an Audience Management Destination.....................................................................................................................269
Share Data between Marketing Cloud Solutions..............................................................................................271
Analytics Data Integration..................................................................................................................................................................271
Auditude Data Integration..................................................................................................................................................................276
Experience Manager Integration......................................................................................................................................................279
Target Data Integration........................................................................................................................................................................279
Reference......................................................................................................................284
FAQ.....................................................................................................................................................................................284
API FAQ......................................................................................................................................................................................................284
Data Collection and Product Integration FAQ.............................................................................................................................284
Inbound CRM Data Ingestion.............................................................................................................................................................286
Privacy FAQ...............................................................................................................................................................................................289
Product Features and Functions FAQ.............................................................................................................................................290
Reporting FAQ.........................................................................................................................................................................................290
Targeting FAQ.........................................................................................................................................................................................291
Campaign Data Integration......................................................................................................................................292
Capturing Campaign Data Via Pixel Calls to Audience Managment...................................................................................292
Delivery Performance Report: Log File Recommendations....................................................................................................295
Pre-Submission Data Integration Checklist..................................................................................................................................303
Reporting and File Transfer Time-Frame Guidelines.......................................................................................304
About Amazon S3.........................................................................................................................................................305
Last updated 12/16/2014
Audience Management Help
Contents
Use Cases for Advertisers and Publishers.............................................................................................................306
Advertiser Use Cases.............................................................................................................................................................................306
Publisher Use Cases...............................................................................................................................................................................308
Advertiser and Publisher Use Cases.......................................................................................................................310
Profile Merge..................................................................................................................................................................310
Profile Merge Terminology.................................................................................................................................................................311
Profile Merge Architecture..................................................................................................................................................................311
Profile Merge Customer Enablement..............................................................................................................................................312
Profile Merge Implications and Limitations..................................................................................................................................313
Declared IDs....................................................................................................................................................................314
Declared ID Targeting...........................................................................................................................................................................314
URL Variables and Syntax for Declared IDs...................................................................................................................................316
Declared ID Variables............................................................................................................................................................................317
Signals, Traits, and Segments...................................................................................................................................318
Boolean Expressions in Trait and Segment Builder..........................................................................................319
Key-Value Pairs Explained..........................................................................................................................................320
Password Requirements, Locked Accounts, and Forgotten Passwords...................................................321
Supported Browsers....................................................................................................................................................322
Sandbox (Beta) Environment....................................................................................................................................322
Documentation Updates..............................................................................................324
Data Privacy..................................................................................................................335
If There's a Problem......................................................................................................337
Contact and Legal Information...................................................................................339
Last updated 12/16/2014
Audience Management Help
Audience Management Product Documentation
8
Audience Management Product Documentation
Audience Management provides industry-leading services for online audience data management. Our product and services give
digital advertisers and publishers the tools they need to control and leverage their data assets to help drive sales success.
Popular Resources
Marketing Cloud Resources
Last update: 12/11/2014
• Adobe Social Community
• Release Notes
• Marketing Cloud Release Notes
• Documentation Updates
• Product Documentation Home
• Overview
• Developer
• Implementing Audience Management
• Idea Exchange
• System Components
• Adobe Training and Tutorials
Data Integration
• Data Integration Methods
• Auditude Data Integration
• DCS Integration
• Real-Time Inbound Data Integration
• Batch Data Integration
• Analytics Data Integration
• Target Data Integration
• Experience Manager Integration
• Featured Solutions Center
Release Notes
9
Release Notes
Information about new features, enhancements, and fixes in Adobe Audience Management.
The Adobe Marketing Cloud solutions have been updated with many new features, enhancements, and fixes. For more information,
see the Adobe Marketing Cloud Release Notes.
For detailed information about updates to this guide that might not be included in these release notes, see Documentation
Updates.
Audience Management (12/11/2014) Update:
This release includes the following updates:
DIL v5.5: Fixed an issue where specifying a partner name with certain characters caused the event call to not function. The
characters belonged to the set that cannot be used in JavaScript variable names, such as a hyphen.
Audience Management (12/03/2014) Update:
This release includes the following updates:
DIL v5.4: Fixed an issue with large datasets where the event call request size exceeded the limit accepted by the DCS. With
browsers that support CORS, DIL now makes a cross-domain POST to send the full dataset. Supported browsers include Chrome,
Firefox, Opera, and IE 10+. Safari is supported only in a declared ID context. With browsers that do not support CORS, the
standard JSON-P event call is used with the URL truncated to a maximum of 2048 characters.
Audience Management (11/21/2014) Update:
This release includes the following updates:
Adobe Media Optimizer Search and Delivery Report: The Adobe Media Optimizer (AMO) Search Delivery and Performance
Report lets a customer see how segments are responding to AMO search campaigns. For more information, see Adobe Media
Optimizer Search and Delivery Report.
DIL v5.3: Fixed an issue with the SiteCatalyst module where event call key-value pairs for evars and props were being included
with "undefined" for a value when no value existed. Key-value pairs with no value are not supposed to be included in the event
call.
Audience Management (10/31/2014) Update:
Includes enhancements to the General and Trend reports for Role Based Access Control (RBAC) and new functionality. For
more information, see General Reports and Trend Reports.
Overview
10
Overview
Information about the history of Adobe Audience Management, the types of data collected, segmentation, reporting, and more.
Audience Management helps you bring your audience data assets together, making it easy to collect commercially relevant
information about site visitors, create marketable segments, and serve targeted advertising and content to the right audience.
Furthermore, Audience Management offers easy tag deployment and management with robust data collection, control, and
protection.
With Audience Management, you’re not tied to a data seller, exchange, or demand-side platform. Additionally, Audience
Management is completely agnostic when it comes to our partners’ data assets. With access to multiple data sources, Audience
Management offers digital publishers the ability to use a wide variety of third-party data as well as our private data co-op. Talk
to our Partner Solutions team about help with making smart and accurate decisions about your target audience.
History and Background
Audience Management started as Demdex in 2008. It was acquired by Adobe Systems in 2011 and subsequently rebranded as
Audience Management.
History
Since 2008, Audience Management (formerly, Demdex) has been a pioneer in the on-line audience management market.
Audience Management services power dynamic, multi-channel online data strategies. Our platform and services are used by an
array of diverse industries from automobiles (AutoTrader), to airlines (American Airlines), and financial services companies
(American Express). Audience Management uses enterprise-level technology to provide the scale, reliability, analytics, and
performance to help your business succeed online. Audience Management integrates with the Adobe Marketing Cloud to help
you centralize, manage, and take action on your data assets across a growing number of digitally addressable channels.
Audience Management and its Data Management Platform (DMP)
Audience Management helps you manage your data pipeline. Our service is a catalyst that transforms generic users and raw
data signals into actual audience segments used for multi-channel marketing efforts. Additionally, Audience Management
provides tools for tag management and audience analytics while simultaneously meeting the privacy and data security needs of
clients and consumers.
Overview
11
Types of Data Collected
Audience Management helps you collect and manage first-party, second-party, and third-party data.
Unlocking customer information assets stored in multiple silos is one of the biggest data challenges faced by companies today.
From CRM databases, to registration systems, to ad servers, and so forth, companies require tools that help centralize valuable
data and manage customer/audience information as a single strategic data asset. Audience Management helps you unlock isolated
customer information and manage data collection from multiple sources. Collected data can be managed based on data element
time-to-live (TTL) values, which helps the publisher control data expiration across all sources. Audience Management is designed
to help you manage the following types of data:
Data Type
Where Data Comes From
First-party
Customers. Data is collected online (from consumer interactions on your websites) or offline.
Second-party
Strategic partners and advertisers.
Third-party
Data providers and/or exchanges. Data can include information such as intent, demography,
social/lifestyle, psychographic, and more.
First-Party Data Collection
First-party data collection is a main Audience Management feature. This core competency addresses the needs of our customers
(publishers or advertisers) who want to use proprietary data as the cornerstone of their marketing programs or for targeting
and modeling against other data sources.
Audience Management works with clients to understand their data strategy and then maps that strategy back to a custom
data-collection plan. Our Partner Solutions team works with you to evaluate sites, raw data signals, and other user interactions
on your websites. With this information, we’ll help you create a tailored data-collection strategy that captures user-level data
signals from various pages in your inventory. Captured data is stored and mapped back to a predefined taxonomy, which can
be updated at any time, as your business needs change.
The following example illustrates how potential data elements can be captured from a sample shopping page.
Overview
12
After the raw data is collected, it gets mapped back to customer-defined traits within the Audience Management platform. Both
the taxonomy and data mappings can be adjusted at any time without making changes to the data collection code.
Second-Party Data Collection
Second-party data comes from a strategic business partner (it's not publisher data). This information is collected and managed
just like first-party data.
In a second-party-data scenario, advertisers send their own data assets to publishers so they can combine that information with
the publisher’s data and then execute a more targeted advertising program. Furthermore, publishers can extend their audience
pool by partnering with their advertisers. In most cases, these arrangements involve contractual relationships limited to putting
the Audience Management container tag on the partner site to facilitate data collection and sharing.
An example of second-party-data collection and remarketing could involve an automobile manufacturer collecting data on its
car configuration pages and then sharing this information with key partners. In this case, the car manufacturer could serve
different ads across an Audience Management partner site for consumers who configured different types of vehicle options (e.g.,
color, model, etc.).
Third-Party Data Collection
Third-party data is information collected and shared by vendors outside of Audience Management.
Third-party data can be used to qualify existing data segments (for example, age, household income, and so forth), provide data
that is in demand but not otherwise available, or be used in lookalike modeling against a known user base from first-party and
second-party data. Audience Management works with many third-party data providers and will help you understand the type
of data these data providers collect so you can make the right strategic deals with each provider.
Note: For a full list of third-party data providers supported by Audience Management, see the Adobe Exchange Marketplace
(https://marketing.adobe.com/resources/content/resources/en/exchange/marketplace/audience.html).
Audience Management integrates with other data providers based on their available APIs and data sets. Data collection works
in real-time, as a user browses your site, or via out-of-band methodologies where IDs are synchronized between partners and
data is transferred between servers after a user has left your site. In either case, Audience Management clients get the benefit of
having third-party data synchronized on our platform, which means each client, or domain, does not have to perform its own
synchronization. This helps increase reach and reduces server calls from the page.
The following sections describe third-party data collection sources:
Overview
13
• Offlline Data Matching
• Match Partners
Offlline Data Matching
As part of their digital targeting efforts, many clients want to leverage their offline data assets, such as customer marketing or
registration. Audience Management works with its customers to take databases that include Personally Identifiable Information
(PII) such as name, address, and email and migrate them to a non-PII digital data store that is fully privacy compliant.
Data-match partners and email are the main mechanisms for bringing this data into a digitally addressable environment. This
combination gives publishers the ability to maximize reach while minimizing costs associated with external partners.
Match Partners
Many clients choose to work with third-party data-match partners. These entities have relationships with sites that have
registration requirements and can process customer data files by matching them (in real-time) based on their registration
network.
Custom Segment Generation
Data sources are represented in a client-specific trait taxonomy. Publishers can customize and modify this taxonomy based on
their data source and business use cases. Within the Audience Management interface, publisher team members can browse traits
and segments to combine them into new marketing segments.
You can report on historical trait and segment size as segments are created. This helps publisher team members understand
potential inventory and lets them adjust segment composition based on reporting data.
Note: Historic segment size reporting shows actual numbers, not estimates.
Qualification begins after a segment is saved in the Audience Management interface. Our system uses two complimentary
methodologies that help ensure full segment coverage across a publisher’s entire user base:
• Instant Segment Qualification: Qualifies users based on real-time data collection processes.
• Processed Segments: Back-end processing of users not yet seen again who qualify based on new segment rules criteria.
Overview
14
Performance Reporting
Audience Management offers standard reporting interfaces for all data stored on user traits and segments, including segment
sizes, segment composition, targeting platform mappings (destinations), and custom reports.
This section contains the following information:
• Overlap Analysis and Lookalike Modeling
• Inventory and Audience Insight
• Audience Overlap Against Sites and/or Domains
Overlap Analysis and Lookalike Modeling
In addition to custom segment generation and standard reporting, publishers are interested in understanding data relationships
between all of their data elements and segments. This is easily accomplished based on reports that run on our Netezza database.
Audience Management can create data overlay reports based on a publisher’s specific needs. Some examples might include:
• Third-party data overlaid against first-party data
• Third-party to third-party overlap for data analysis and scoring (e.g. gender across four providers)
• First-party data relationships
• Segment-to-segment overlap and analysis for additional lookalike modeling
The Partner Solutions and Analytics teams can work with you to understand your data/reporting needs, create report templates,
create custom reports, and schedule delivery of all overlap and lookalike reports.
Inventory and Audience Insight
Inventory and audience insight is closely tied to segment generation and overlay reporting. Inventory and audience insight
reports help you understand:
• How audiences overlap or trend against individual sites and domains
• Potential ad inventory based on unique users within audience segments
Audience Overlap Against Sites and/or Domains
As part of a data-collection strategy, publishers can capture site, domain, and site groupings, etc. in the standard data. This gives
publishers full visibility into overlap across sites, by data segment across sites, or overlap of any data combination of trait,
segment, site, domain, or site grouping. Data is available in a number of areas depending on the specific use case:
• Standard reporting based on overlap segments generated
• Custom overlay report templates as defined above
• Segment creation wizard available via the user interface
Ad Server Integration
Helping you take action on data is a core feature of the Audience Management platform. Our platform lets customers manage
a single digital data repository and then leverage that data across all their channels. This can include ad servers, content
optimization, creative optimization, video delivery, search, and so forth.
Audience Management has developed a central interface for managing new targeting destinations that provides multiple
integration points (depending on the use case and technical implementation of the external system).
Overview
15
Destination Publishing
In Audience Management, a destination is any third-party system (ad server, DSP, ad network, etc.) that you want to share data
with. Destination Builder helps you manage URL, cookie-based, or server-to-server destinations.
As a data management platform, it is important to standardize the data transfer mechanisms so they can be easily configured
and managed by our systems. Audience Management allows publishers to easily set up new targeting partners (destinations) in
the interface.
Audience Management DIL code includes an asynchronous iframe that can be configured to perform ID syncs with third-party
vendors, such as demand-side platforms and data providers. By default, no ID syncs are initiated from the iframe. Your Audience
Management consultant can enable them on your request. The purpose of an ID sync is to reconcile unique-visitor identifiers
between Audience Management and third-party vendors you might be working with.
This asynchronous iframe is called within the Analytics code, which typically loads at the bottom of the page after your site
content is loaded. The asynchronous nature of the iframe allows the rest of the page to load while ID syncs are being made.
When enabled, most ID syncs are configured to occur once per unique visitor per 14 days.
Supported Destination Types
You can send information to a destination by passing it in through a URL string; by writing to a browser cookie; or through
offline, server-to-server data transfers. URL and cookie-based destinations transmit data synchronously, as a user takes action
on a page. Server-to-server data transmission is asynchronous and can occur long after a user has left the page. The delivery
type you select depends on your business requirements and how a particular data partner wants to, or can, receive data. See
Destinations for more information.
For each method, a publisher selects the appropriate data traits/segments to pass to each system. Publishers can pass the same
segment to multiple platforms/channels simultaneously.
Tag Management
Tag management is a key feature of the Audience Management platform. Tag management consists of two core components:
JavaScript container code and a graphical user interface that helps you manage tags for deployment and data collection on your
website.
Enterprise-level tag management is integral to Audience Management. Furthermore, Audience Management is tag agnostic.
The system lets customers create, schedule, deploy, and manage their own tags. Additionally, the intuitive management interface
uses conditional logic that provides flexibility when managing tags across a complex site environment. Adobe is committed to
developing this platform and supporting our clients and partners. We are also working to integrate our platform into the Adobe
Marketing Cloud. See Tags for more information.
Data Security and Privacy
Data security is an important part of data management. Audience Management has controls and systems designed to improve
data security and prevent data leakage.
Data Security
Audience Management takes data security and privacy very seriously. We work to keep our systems secure and protect your
valuable data.
Overview
16
Audience Management security practices include external and internal audits, activity logging, training, and other procedures
designed to help protect our systems and your valuable data. We believe a secure product helps build and maintain the trust
customers place in us.
In Audience Management, we think about security in three main categories:
Security Type
Provides Support For
Information security
Enterprise-level authentication, encryption, and data storage practices
Data leakage/transparency
Deep and actionable insight into on-site activities that constitute or contribute to data
leakage
Process/policy enhancements
Clients, by working with industry best practices for privacy and data security
This topic contains the following information:
• Systems, Training, and Access
• Privacy and Personally Identifiable Information (PII)
• Data Partitioning
• Inbound Server-to-Server (S2S) Transfers
• Protecting Data by Escaping
Systems, Training, and Access
Processes that help keep our system and your data secure.
External Security Validation: Audience Management tests security on an annual and quarterly basis.
• Yearly: Once a year, Audience Management undergoes a full penetration test conducted by an independent third-party company.
The test is designed to identify security vulnerabilities in the application. The tests include scanning for cross-site scripting,
SQL injections, form parameter manipulation, and other application-level vulnerabilities.
• Quarterly: Once each quarter, internal teams check for security vulnerabilities. These tests include network scans for open
ports and service vulnerabilities.
Systems Security: To help keep data safe and private, Audience Management:
• Blocks requests from unauthorized IP addresses.
• Protects data behind firewalls, VPNs, and with Virtual Private Cloud storage.
• Tracks changes in the customer and control-information databases with trigger-based audit logging. These logs track all changes
at the database level, including the user ID and IP address from which changes are made.
Security Assets: Audience Management has a dedicated network operations team that monitors firewalls and intrusion-detection
devices. Only key personnel have access to our security technology and data.
Security Training: Internally, our commitment to security extends to developers who work on our product. Adobe provides
formal training to developers on how to build secure applications and services.
Secure Access: Audience Management requires strong passwords to log on to the system. See password requirements.
Privacy and Personally Identifiable Information (PII)
Processes that help keep personal information safe. For additional privacy information, see the Adobe Privacy Center.
PII Data: Audience Management contractually enjoins customers and data partners from sending PII information into our
system. Additionally, the Unique User ID (UUID) does not contain or use PII data as part of the ID-generation algorithm.
Overview
17
IP Addresses: Audience Management does collect IP addresses. IP addresses are used in data-processing and log-aggregation
processes. They are also required for geographic/location look-ups and targeting. Additionally, all IP addresses within retained
log files are obfuscated within 90 days.
Data Partitioning
Processes that help protect data owned by individual clients.
Trait Data Partitioning: Your data (traits, IDs, etc.) is partitioned by client. This helps prevent accidental information exposure
between different clients. For example, trait data in cookies is partitioned by customer and stored in a client-specific sub-domain.
It cannot be read or used accidentally by another Audience Management client. Furthermore, trait data stored in the Profile
Cache Servers (PCS) is also partitioned by customer. This prevents other clients from accidentally using your data in an event
call or other request.
Data Partitioning in Reports: Client IDs are part of the identifying key in all reporting tables and report queries are filtered
by ID. This helps prevent your data from appearing in the reports of another Audience Management customer.
Inbound Server-to-Server (S2S) Transfers
Adobe Audience Management supports two main methods of transferring S2S on-boarded data files to our systems:
Both methods are designed with the security of our customer and partner data in mind while data is in flight between their
systems and our system.
SFTP: For the SFTP option, most customers choose to deliver files via the Secure FTP (SFTP) protocol, which uses the Secure
Shell (SSH) protocol. This method ensures that files are encrypted while in flight between the customer's systems and Adobe's
system. For each customer, we create a jailed drop-box location on our SFTP servers, which is tied to a user account on that
system. Only the customer's credentialed and privileged internal system users can access this jailed drop-box location. This jail
is never accessible to other customers.
Amazon Web Services S3 via HTTPS: For the S3 delivery option, we recommend that all customers configure their S3 clients
to use the HTTPS encryption method for file transfers (this is not the default, so it must be explicitly configured). The HTTPS
option is supported both by the s3cmd command line tool as well as the S3 libraries available in every major programming
language. With this HTTPS option enabled, customer's data is encrypted while in flight to our systems. For each customer, we
create a separate S3 bucket sub-directory that can be accessed only by that customer's credentials and those of our internal
system users. If desired, we can create a separate S3 bucket (instead of just a separate directory) for customers who are especially
security-minded.
Protecting Data by Escaping
Note that Audience Management does not escape outgoing data to secure it against possible cross-site scripting (XSS), etc. It is
the responsibility of the client to escape incoming data.
Data Privacy
Describes Audience Management integration and compliance with generally accepted best practices related to consumer privacy
and opt-out procedures.
This section contains the following information:
• Consumer Privacy Protection
• DoNotTarget and Partner Opt-outs
• Privacy Integrations
• Collection of IP Addresses
Overview
18
Consumer Privacy Protection
Audience Management recognizes the implicit pact between consumers and the online brands with which they interact. Both
parties benefit from the transparent exchange of anonymous data elements. Consumers receive personalized content, discounted
product offers, and streamlined user experiences. Similarly, brands receive vital revenue streams supporting multiple online
business models. In our continuing support of this model, Audience Management remains committed to providing transparency
and control to consumers, and meeting or exceeding the Online Behavioral Advertising (OBA) Self-Regulatory Principles.
DoNotTarget and Partner Opt-outs
Audience Management owns and operates the portal DoNotTarget.com, which provides opt-out access to all consumers.
Consumers will not be tracked across the Audience Management network when they opt-out via DoNotTarget.com.
Privacy Integrations
Audience Management provides the following privacy integrations:
Do Not Track: Audience Management processes recognize and take action on “Do Not Track” HTTP headers.
Evidon: Audience Management works with Evidon, a leading privacy compliance vendor, to enhance our commitment to data
privacy. Current efforts include:
• Enabling Audience Management and partner-level opt out capabilities within the Evidon "Ad Choices" interface.
• Working as a partner in the Open Data Partnership, which provides segment-level transparency across multiple data companies
to all consumers.
• Improved workflow for ad notice tag trafficking.
Other Industry Affiliations: Audience Management understands the benefit of industry standards and their ability to build
scale in emerging sectors of the economy. As a result, we constantly engage with industry certification providers such as the
Network Advertising Initiative, the Digital Advertising Alliance, and TRUSTe.
Collection of IP Addresses
Adobe has enabled processes and offers settings that allow customers to use Audience Management in compliance with applicable
data privacy laws.
The IP address of a visitor to a customer’s website is transmitted to an Adobe Data Processing Center (DPC) where the IP address
may be stored. Depending on the network configuration for the visitor, the IP address does not necessarily represent the IP
address of the visitor’s computer. For example, the IP address could be the external IP address of a Network Address Translation
(NAT) firewall, HTTP proxy, or Internet gateway.
Replacement of Last Octet of the IP Address: Adobe has developed a new “privacy by design” setting that can be enabled by
Audience Management Consulting. When this setting is enabled, the last octet (the last portion) of the IP address is immediately
hidden when the IP address is collected by Adobe. This anonymization is performed prior to any processing of the IP address,
including before an optional geo-lookup of the IP address.
For example:
123.45.67.89
is changed to
123.45.67.0
When this feature is enabled, the IP address is made sufficiently anonymous so it is no longer identifiable as personal information.
As a result, Adobe Audience Management can be used in compliance with data privacy laws in countries that do not permit the
Overview
19
collection of personal information. Obtaining city-level information will likely be significantly impacted by the obfuscation of
the IP address. Obtaining region- and country-level information should only be slightly impacted.
Note: Contact your Audience Management Consulting representative to enable the IP obfuscation feature.
GeoSegmentation: If customers enable the replacement of the last octet of the IP address, the remaining values of the IP address
can still be utilized for geo-segmentation and reporting in Audience Management. If the last octet of the IP address has not been
obfuscated, the full IP address is used. Customers can use the GeoSegmentation feature that allows the customer to map out
visitor location by geographic area in either case, but with some slight loss of precision when IP obfuscation is being used.
GeoSegmentation data is granular only to the city level or zip code level, and not to the individual level.
Privacy Capabilities Summary
An overview of the Audience Management position related to data privacy.
System Components
20
System Components
A brief technical overview of the major system components and their function/role within Audience Management.
Key Components in the Audience Management System
Audience Management groups its systems and processes into four main categories: tag management, data collection, data
organization, and data actionability.
The following illustration shows the main components and the underlying technology (hardware and software) that power
Audience Management. Although some processes perform specific functions and others have multi-purpose roles, all systems
work together to help you manage tags, collect data, analyze performance, synchronize information with other systems, and
take action on that information.
Platform Architecture: Data Flow Diagram
Understand the major components within Audience Management and understand how site visitor data (green), client data
(blue), and reporting data (orange) flow into and through different parts of our system.
System Components
21
System Components
22
Functional Architectural Diagrams
Detailed, functional architectural diagrams that illustrate the major components within Audience Management and the data
flow into and through different parts of our system.
System Components
23
System Components
24
Tag Management Components
Audience Management tag management components include the client portal, Adobe Tag Manager, DIL, Akamai, and the
control database.
Audience Management contains the following components:
• Client Portal
• Adobe Tag Manager (ATM)
• Data Information Library (DIL)
• Akamai
• Control Database
Client Portal
The client portal is the primary user interface (UI) for tag and data management. Customers use the portal to work with tags,
build traits and segments, set up destinations, and monitor campaign performance with reports.
System Components
25
Adobe Tag Manager (ATM)
Tag Manager helps deploy Audience Management data collection code to your website. You use ATM to configure and generate
container code that you place on pages in your inventory. The ATM container works with the Data Information Library (DIL)
to collect data from your site and send it to Audience Management. See the Dynamic Tag Management documentation for more
information.
Data Information Library (DIL)
The Data Information Library (DIL) is a self-contained API module that collects data from your website. DIL helps eliminate
the need to write special code for data collection, integration, reading cookie values, and recovering page data. DIL performs
these actions automatically. Additionally, DIL is compact. It is a self-contained code library that helps reduce the amount of
code required to collect data from websites. Finally, DIL helps you integrate Audience Management with other products in the
Adobe Marketing Cloud.
Akamai
Audience Management uses Akamai to host and deliver container code from our own tag management platform known as TIM
(Tag Insertion Manager). However, code deployment with TIM is being phased out in favor of Adobe Tag Management.
Control Database
The control database:
• Processes client input from the portal (for example, setting up or changing scheduled tags, creating traits and destinations,
and more
• Transmits data to Akamai, which includes data used to build the container template and destination publishing iFrame
• Returns data for UI reporting systems
Data Collection Components
The main data-collection components consist of the Data Collection Server along with systems that manage log files and privacy
opt-out processes.
Audience Management contains the following data-collection components:
• Java Data Collection Servers (DCS)
• Log Files
• Other DCS Processes: Privacy Opt-outs and Log Files
Java Data Collection Servers (DCS)
The Java Data Collection Servers (DCS) are key components in the edge data center. At its core, the DCS collects and works
with user data to make it actionable by Audience Management clients and partners.
DCS Process
Explanation
Example
Collect
The DCS receives raw user information and signals Data received by a user browsing an automotive
returned from your website.
website and selecting options for a potential
purchase.
Translate
Turns raw data into human-readable information. Transform captured data into a SKU or product
name.
System Components
26
DCS Process
Explanation
Example
Interpret
Understanding translated data and segmenting
users based on that information. Includes:
The user looked at minivans and expensive consumer
electronics. Evaluate those signals to qualify the user
for “automobiles” and “high-income” traits.
• Cookie management (create, set, and modify).
• Combining new information with stored data
and adding users to other related segments.
Use
Make translated/interpreted data actionable.
Show targeted ads (based on segment membership)
and share data with third-party providers to build a
detailed picture about the user.
Log Files
The DCS creates log files. Log files contain non-personally identifiable (PII) user data (IDs and associated qualified traits). Log
data is sent to Hadoop for additional trait matching and reporting.
Other DCS Processes: Privacy Opt-outs and Log Files
The DCS generates user-data log files and sends them to Hadoop to build processed segments and for reporting. Also, these
server systems handle privacy and user opt-out requests. User cookie information is not collected in the log file if a user has
opted out of data collection.
Data Processing Components
Descriptions of the components Audience Management uses to process and manage customer data.
Audience Management uses the following components to process data:
• Hadoop
• Elastic MapReduce (EMR)
• Talend
• Netezza
• SOLR
• Tableau
Hadoop
In the Audience Management ecosystem, Hadoop is the master database that contains everything Audience Management knows
about a user. Hadoop is used for batch segmentation and synchronization of collected user data. Other important Hadoop
elements include:
• Hive: A data warehouse for Hadoop. Hive manages ad hoc queries to the data stored in Hadoop.
• HBase: A very large Hadoop database.
Elastic MapReduce (EMR)
Amazon's Elastic Map Reduce (EMR) service lets Audience Management rapidly increase or reduce the amount of computational
power needed to process and manage data. This technology helps Audience Management operate efficiently at scale and quickly
manipulate the tremendous volume of information that flows through our system.
System Components
27
Talend
Talend is a data transformation service that receives data from Netezza and makes it available via customer reports in the user
interface.
Netezza
Netezza is used for ad hoc business intelligence and custom analytics queries run against the large data sets pushed to Hadoop.
SOLR
SOLR is an open-source search platform. It helps optimize report performance by quickly finding and returning data.
Tableau
Audience Management uses Tableau to display data in the interactive reports. The interactive reports display performance and
overlap data for traits and segments. Instead of using numbers arranged in columns and rows, they return data using different
shapes, colors, and sizes. Additionally, you can choose individual or groups of data points and drill down into the report results
for more details. These visualization techniques and report interactivity help make large amounts of numeric data easier to
understand.
Data Actionability Components
The main data-action components consist of the Profile Cache Server and data feed converters/submitters.
Audience Management uses the following data-action components:
• Profile Cache Server (PCS)
• Feed Converters/Submitters
Profile Cache Server (PCS)
The Profile Cache Server (PCS) is a server-side, memory-based data store (basically, a huge server-side cookie) that stores user
IDs and traits. Audience Management runs the PCS on Apache Cassandra. Cassandra helps Audience Management scale to
meet high demand and maintain system performance.
The PCS helps overcome the built-in space and storage limits of browser cookies, including situations when cookies are not
available, such as from mobile applications. Additionally, the PCS receives data from Hadoop, which extends the number and
types of traits to which a user can belong. In addition to traits based on a user's activity on the edge (in the browser), the PCS
stores traits sent by data providers and traits added via algorithmic modeling.
For each active user, the PCS stores traits that are used in segments. Traits that are not used in segments are not actionable and,
thus, not needed in the PCS. If a trait is later added to a segment, the user's traits are added to the PCS without waiting for the
user to visit any page or application.
An active user is any user who has been seen on the edge (DCS) recently, currently, or during the last fourteen days. The user
does not need to be seen on any particular domain. This user's data (traits) are pushed out to the PCS as long as the user visits
from a device that has his or her ID in a cookie or passes that ID in an event call to DCS.
Specifically, seeing the user at least once, for any partner, during the last 14 days on the edge using the following methods keeps
a user active in PCS:
• /event calls
• /ibs calls (ID syncs)
• /dpm calls (third-party data-provider traits passed in during user visit)
System Components
28
After 17 days of inactivity, the traits are flushed from the PCS, but remain in Hadoop. If the user is later seen again, all of his or
her traits are pushed from Hadoop to the PCS, typically within 12 hours.
Because Adobe has multiple regions across the globe from which we serve DCS requests, and because DCS event calls are always
routed to the closest DCS location, we ensure that the latest data for each user is pushed out to the edge cache in each location
where we have seen activity for this user. A user can often be seen in more than one location, for example, when a user connects
to the internet via a corporate vpn and shows activity.
Activity does not include:
• Trait qualification that came through Inbound Server-to-Server file ingestion (includes first-party and third-party data)
• Algorithmic trait qualification
• Segment qualification based on previously acquired traits
• Sending user data to a partner via a Server-to-Server Outbound transfer
In the future, seeing the user in log ingestion data from a targeting/delivery partner can mark them as active.
The User's Traits Might Not Always be Available in the PCS
There is one scenario in which a user's traits might be unavailable. If the user visits infrequently, for example once a month to
view a monthly statement or to pay a bill, and the user visits from a device/browser that is used only for visiting your site, then
the user's activity will not be updated by visiting other domains. This user's traits will expire from the PCS and will not be
refreshed on the PCS until it's too late. If the device/browser does not support our cookies, we will not have any trait history on
the edge for this visit. One example of this scenario is if the user visits via a mobile application that sends an authenticated ID
as the user ID.
Feed Converters/Submitters
The feed converters/submitters receive and send data from internal and external data sources. These processes can use HTTP,
HTTPS, or FTP/SFTP communication protocols. The feed systems take data and process it into a useable format for external
customers (for example, real-time or server-to-server data integrations) or other internal processes.
Understanding the Edge Data Center
Audience Management uses distributed, edge-computing topologies to meet the demands placed on our systems by external
sources.
Edge computing provides improved performance in response to diffuse, Internet-wide demand because the “edge” itself is a
global boundary. This means Audience Management dynamically places processing closest to the sources of demand and returns
data by the shortest possible path. Edge computing helps maintain site performance, which, in turn, preserves the user experience
on your website. The edge data center is a key gateway for moving data in and out of Audience Management.
The Audience Management edge data center includes:
• Core Servers: These are the main Audience Management systems. They update and provide data to the edge servers.
• Edge Servers: Typically, these are application and/or web servers. They sit at the boundary between Audience Management
and the Internet. Edge servers, such as the DCS or Akamai systems, typically handle data and requests flowing into and out of
Audience Management.
• Load Balancers: Manage uneven computing/processing demands inherent in Internet applications. These balancers prevent
clusters of servers from being overloaded while others remain idle.
The following diagram illustrates the Audience Management edge data center environment.
System Components
29
User Interface
30
User Interface
Use the Audience Management user interface rather than using APIs to work with Audience Management.
Reports
Describes available reports, their purposes, and typical uses. All reports are available from the Analytics dashboard.
For information describing the time frames when Audience Management receives information to populate reports, see Reporting
and File Transfer Time-Frame Guidelines.
General Reports
A General report returns performance data on traits, segments, and destinations.
Audience Management uses Role Based Access Control (RBAC) to extend user-group permissions to the General reports. Users
can see only those traits and segments in reporting that they have permissions to view. RBAC functionality lets you control what
reporting data internal teams are able to view. For example, an agency that manages different advertiser accounts can configure
user-group permissions so that a team that manages Advertiser A's account cannot see Advertiser B's reporting data.
Run a General report when you need to:
• Review performance by trait, segment, or destination.
• Track impressions (total and unique) at 7, 14, 30, and 60-day intervals.
• Review total and unique load counts.
• Compare trait and segment performance.
• Identify strong or poor performance traits and segments, analyze demand, or compare load/fire data with third-party reports.
• Export data (.csv format) for further analysis and sharing.
The following illustration provides a high-level overview of key elements in the General report.
User Interface
31
1. Configure the following options:
Report Type: Select the desired report type (Trait, Segment, or Destination).
For Dates Through: Specify the date range for the report.
Include Client Level Activity for Third Party: Select this option to display the number of 3rd-party users who were active
or visited a client’s properties during the specified time range.
2. Search for a trait, segment, or destination by name or ID.
3. From the folder list, drag and drop the traits, segments, or destinations you want to report to the Selections panel on the
right side.
4. Generate the report to display in an exportable table.
Run a General Report
This procedure describes how to run a General report and set time and other performance options.
1. In the Analytics dashboard, click General Reports.
2. From the Report Type drop-down list, select the desired type:
• Trait
• Segment
User Interface
32
• Destination
3. (Conditional) Click the date box to display a calendar, then select the ending date for your report if you want to specify a
date other than today.
4. (Conditional) Select the Include Client Level Activity for Third Party check box.
Select this option to display the number of 3rd-party users who were active or visited a client’s properties during the specified
time range. For example, assume that a 3rd-party segment contains 100 people and the specified time range in 30 days.
Assume further that 50 of these people visited client A's website in the last 30 days. Without this option selected, the report
displays 100 visits. With this option selected, the report displays 50 visits.
5. Search for a trait, segment, or destination by name or ID.
6. From the folder list, drag and drop the traits, segments, or destinations you want to report to the Selections panel on the
right side.
7. Click Run Report.
Results display in an exportable table. Click the column headers to sort the results in ascending or descending order.
8. Select the desired check boxes at the top of the report to return data by performance (total fires and unique impressions) or
by time (7, 14, 30, or 60-day range).
9. (Optional) Click Export to CSV.
Trend Reports
A Trend report returns trend data on traits and segments.
Audience Management uses Role Based Access Control (RBAC) to extend user-group permissions to the Trend reports. Users
can see only those traits and segments in reporting that they have permissions to view. RBAC functionality lets you control what
reporting data internal teams are able to view. For example, an agency that manages different advertiser accounts can configure
user-group permissions so that a team that manages Advertiser A's account cannot see Advertiser B's reporting data.
Run a Trend report when you need to:
• Review trend data by traits and segments.
• Track trends by day, 7-day, 14-day, 30-day, or 60-day intervals.
• Compare trait and segment trends over time.
• Identify strong or poor performance traits and segments.
• Export data (.csv format) for further analysis and sharing.
The following illustration provides a high-level overview of key elements in the Trend report.
User Interface
33
1. Configure the following options:
Report Type: Select the desired report type (Trait or Segment).
Dates Range: Specify the date range for the report (start date and end date).
Display Interval: Specify the display interval (by day, 7-day, 14-day, 30-day, or 60-day).
Include Client Level Activity for Third Party: Select this option to display the number of 3rd-party users who were active
or visited a client’s properties during the specified time range.
2. Search for a trait or segment by name or ID.
3. From the folder list, drag and drop the traits or segments you want to report to the Selections panel on the right side.
4. Generate the report to display in data in graphical format or export the report to CSV format.
Run a Trend Report
This procedure describes how to run a Trend report.
1. In the Analytics dashboard, click Trend Reports.
2. From the Report Type drop-down list, select the desired type: Trait or Segment.
3. Click the date boxes to display a calendar, then select the starting and ending dates for your report.
User Interface
34
4. Specify the display interval: by day, 7-day, 14-day, 30-day, or 60-day.
5. (Conditional) Select the Include Client Level Activity for Third Party check box.
Select this option to display the number of 3rd-party users who were active or visited a client’s properties during the specified
time range. For example, assume that a 3rd-party segment contains 100 people and the specified time range in 30 days.
Assume further that 50 of these people visited client A's website in the last 30 days. Without this option selected, the report
displays 100 visits. With this option selected, the report displays 50 visits.
6. Search for a trait or segment by name or ID.
7. From the folder list, drag and drop the traits or segments you want to report to the Selections panel on the right side.
For best performance, run a Trend report on fewer than 20 traits or segments at a time.
8. Click Graph Traits or Graph Segments, depending on which type of report you are viewing (Traits or Segments).
These options ignore all folders and graphs only individually selected traits or segments.
Or
Click Export to CSV to export the trait or segment data and all folders in CSV format for further analysis and sharing.
9. (Optional) Mouse over individual traits or segments to display the number of visits and the date for each data point.
You can click the column headers in the table to sort the results in ascending or descending order.
For Trended Trait reports, zeroes indicate that Audience Management did not collect data for that day. Blank entries indicate
that the trait didn't exist. The following example shows examples of both types of entries:
Onboarding Status Report
View onboarding file status (inbound data) for a specified data source. You can select a date range for the report and also manage
email notifications.
1. Click Reports > Onboarding Status.
User Interface
35
2. In the Search for a Data Source box, start typing and select the desired data source.
3. In the Select a Date Range box, specify the start and end dates for your report, then click Apply Date Filter.
The following table contains information corresponding to columns in the report:
Line
Data Sync File Name
Successful
Description
List of all inbound files that Adobe received for this data source that were processed together.
Number of records resulting in data to be loaded into the system--records with realized data
that could be stored.
User Interface
Line
Failed Parse Check
Failed UUID Lookup:
Failed Invalid AAM UUIDs
Records Received
Percent Success
Total Unused Signals
Total Realized Traits
36
Description
Number of lines that did not match the expected format. These lines were not recognizable
by the inbound job.
Total number of users for whom audience management failed to find a matching UUID. These
files have not been ID synced, so Audience Management cannot look up the UUID.
Number of Audience Management UUIDs that did not match the expected 38-digit format.
Or the Audience Management UUIDs are not numbers.
Total number of records Adobe received across all files. In most cases, this should be the total
number of lines in inbound files.
Percent of files that were successfully stored.
Total number of unused signal for all users across all inbound files (key/value pairs that did
not map to Audience Management traits). In most cases, this means that Audience Management
does not have rules defined for the signal.
Number of Audience Management traits for all users across all inbound files based on the
signals.
4. In the Manage Email Notification box, specify an email address, then click Add.
Add additional email addresses, as necessary.
Email notifications are sent whenever inboarding is processed. Audience Management checks for inbound files twice a day,
every 12 hours.
The email report contains additional information that is not displayed in this report. See Sample Message to Partners after
Inbound Processing.
To remove an email address, click X in the Remove column.
Outbound History Report
View outbound batch job history information for a specified destination and time period.
1. Click Reports > Outbound History.
2. In the Search for a Destination box, start typing and select the desired destination.
User Interface
37
3. In the Select a Date Range box, specify the start and end dates for your report, then click Apply Date Filter.
The following table contains information corresponding to columns in the report:
Line
Data Sync File Name
Successful
Failed
Records Received
Description
List of all outbound files that Adobe generated for this destination that were processed together.
Number of records that were successfully sent from Audience Management to the destination.
Number of records that could not be sent to the destination.
Total number of records Adobe generated in the files and attempted to send to the destination.
In most cases, this should be the total number of successful files and failed files.
User Interface
38
Custom Reports
Used for data sets that are too large to display in the browser or unavailable in the current reporting suite.
Your Partner Solutions manager runs a custom report and uploads data to Audience Management. When a report is ready,
you'll receive an automated email notification and see a link to the report under the Custom Reports section under the Analytics
dashboard. Click the link to download the report.
Interactive Reports
Interactive reports display performance and overlap data for traits and segments. Instead of using numbers arranged in columns
and rows, these reports return data using different shapes, colors, and sizes. Additionally, you can choose individual or groups
of data points and drill down into the report results for more details. These visualization techniques and report interactivity
help make large amounts of numeric data easier to understand.
Delivery and Performance Report
Returns segment-level data on impressions and click-through rates.
The Delivery and Performance report lets you evaluate how segments perform on different advertiser sites. As an optimization
tool, this report helps you:
• Identify high-performance segments for re-use in other campaigns or on other sites.
• Find and remove segments from underperforming sites.
• Visually analyze segment impression size and click-through rates.
Note: 1-day views are updated daily. 7-day and 30-day look-back periods are updated weekly.
The following illustration provides a high-level overview of elements in the Delivery and Performance report.
Select an individual point to view data details in a pop up window. Also, you can click and drag the cursor over a group of points
to return data about those data elements only. These actions automatically update the report results.
Delivery and Performance Data Pop Fields Defined
Describes the metrics displayed in the popup window when you click an individual data point.
The popup for the Delivery and Performance Report report contains the following metrics:
Metric
Description
Date Range Start
Start date used by the report.
Date Range End
End date used by the report.
Segment ID
Unique numeric ID for that segment.
User Interface
39
Metric
Description
Segment Name
Name of the segment.
Clicks
Number of clicks recorded for that segment.
Impressions
Number of impressions recorded for that segment.
Reach
Number of unique visitors.
Click Through
Number of times a visitor clicked on an ad.
Adobe Media Optimizer Search and Delivery Report
The Adobe Media Optimizer (AMO) Search Delivery and Performance Report lets a customer see how segments are responding
to AMO search campaigns.
This report helps you do the following:
• Identify top-performing segments and keywords that are resonating with those segments. With that knowledge, a Google
RLSA campaign can be launched targeting that segment to hit more users in that audience.
• Drive creative development by seeing which themes are resonating with each audience.
• Analyze average conversion value per user to identify high value segments.
These reports provide three different views that are filterable by network and account:
• AMO campaign-level reporting
• AMO ad-level reporting
• AAM segment-level reporting
The reports have the list of AMO tracked conversions that can be used in each report to see segment performance based on that
metric.
Metrics include the following:
Metric
Description
Clicks
Number of clicks recorded for that segment.
Click Reach
Number of unique users for whom a click was recorded in that segment.
Conversion Value
The aggregate value of AMO-tracked conversion recorded for that segment.
Conversion Reach
Number of unique users for whom a conversion was recorded in that segment.
Average Conversion Per Unique
The average conversion value per unique user in that segment.
Frequently Asked Questions
What does the "null" conversion mean?
This value shows all users who did not register a conversion.
User Interface
40
Why don't the numbers match up between Adobe Audience Management and Adobe Media Optimizer?
Reasons for number discrepancies include the following:
• Each system uses a different attribution mechanism. AMO allows for multi-event attribution. AAM applies the conversion to
the last click.
• AAM reporting operates in UTC. The AMO reporting time zone is configurable per client.
• AAM shows data for the users it has seen. There could be users targeted in an AMO campaign that do not qualify for an AAM
segment. Those users won't be reported in the AAM reports.
• Currently the AAM reports report only on AMO-tracked conversion events.
• AAM reporting aggregates the AMO metrics across all of the segments the user has qualified for. Taking the simple example
of one campaign and a user who has generated one AMO conversion who is qualified for five segments in AAM. The AMO
report shows one conversion, but the AAM report would attribute that one conversion to all the user's segments. So in the
AAM report, if you sum the conversion count across this user's segmentation, the aggregate number would be five conversions
(one per each of five segments). The purpose of this logic is to show the value of each segment that user qualifies for.
Trait-to-Trait Overlap Report
Returns data on the number of unique users shared among all your first and third-party traits.
Overview
The Trait-to-Trait Overlap report returns data on the % of unique users shared between all your own traits and your third-party
traits. As an optimization tool, this report helps you:
• Create segments with high or low overlap, depending on your needs. Traits with high overlap give you a targeted audience,
but fewer unique visitors. Traits with low overlap can be useful to reach a larger, unique visitor set.
• Validate third-party trait data: Strong overlap between similar first and third-party traits suggests that the trait from your data
partner is accurate and trustworthy. Conversely, low overlap can indicate that a third-party trait may not actually contain the
same information as your own, similar first-party trait.
• Find unexpected overlap between traits and use that information to build innovative segments.
Sample Report
The following illustration provides a high-level overview of elements in the Trait-to-Trait Overlap report.
Note: The Trait-to-Trait Overlap report returns an empty field when it compares the same trait to itself.
User Interface
41
Drill Down on Individual Data Points
Select an individual point to view data details in a pop up window. Your click actions automatically update data displayed in
the report.
Trait-to-Trait Overlap Data Pop Fields Defined
Describes the metrics displayed in the popup window when you click an individual data point.
The popup for the Trait-to-Trait Overlap report contains the following metrics:
Metric
Description
Data Provider Name
Name of the trait's owner.
Data Provider Type
Defines the type of provider a trait belongs to. Can be either:
• First-party (your own trait).
• Third-party (from an outside data partner/vendor).
Trait ID
Unique numeric ID for that trait.
Trait Name
Name of the trait.
Overlap %
Shows the % of unique overlap between compared traits (overlap uniques/trait
uniques).
User Interface
42
Metric
Description
Overlap Uniques
The number of unique visitors shared between the compared traits.
Trait Uniques
The number of unique visitors in the trait.
Segment-to-Trait Overlap Report
Returns data on the number of unique users shared between a particular trait and an entire segment.
Overview
As an optimization tool, the Segment to Trait Overlap reports helps you build highly focused segments or expand segment reach.
For example, you can create focused segments and traits with high overlap to reach a particular audience. However, a lot of
overlap may mean fewer unique users (less reach). Running this report to help expand reach by removing traits with a lot of
segment overlap and replacing them with traits that have less overlap.
Sample Report
The following illustration provides a high-level overview of the Segment-to-Trait Overlap report.
Drill Down on Individual Data Points
Select an individual point to view data details in a pop up window. Your click actions automatically update data displayed in
the report.
Comparing Segments to Traits
Describes how you can compare segments and traits to derive meaningful information from the results.
Comparing Trait and Segment Uniques: An Example
At first glance, it may seem illogical to compare segments to traits and attempt to draw conclusions from the results. After all,
segments and traits are different, so how can data derived from disparate items have meaning? However, in this case, we're not
comparing traits and segments, but the number of unique visitors shared between them. The shared unique visitor count provides
the common value that makes a segment to trait comparison possible.
The following diagram illustrates the relationship between a trait and the segment it belongs to. In this case, we have a trait with
10 visitors and a segment with 1,000 visitors. They share 3 unique visitors in common.
User Interface
43
The unique visitor count is the common, constant value shared between these different classes of objects. As a result, you can
determine the unique visitor relationship between them as follows:
• The trait shares 30% of its unique visitors with the segment (3/10 = 0.30).
• The segment shares 0.3% of its unique visitors with the trait (3/1,000 = 0.003)
Find Value in Segment to Trait Comparisons
Looking at the overlap between traits and segments can help you estimate the total available visitor pool (forecasting) or find
inefficient segments with too much overlap.
Use Case
Forecasting
Description
To determine the available visitor pool, sum the difference between the trait total (less overlap)
and the segment total (less overlap).
This segment-trait combination could reach up to 1004 new users.
Find Inefficient Segments
If a trait is part of an AND group in a segment definition, the unique visitors who have that
trait are already in the segment and not available for adding to the segment. You can use this
report to find relevant traits with low overlap and add them to the segment definition, therefore
increasing the reach of that segment audience pool.
Understanding the Data Filters in the Segment-to-Trait Overlap Report
Describes how the trait and segment unique overlap % sliders work.
The Segment-to-Trait overlap report lets you use two sliders to filter data by the overlap % by trait or segment.
• Filter Trait Uniques %: Filters data by the % of unique visitors shared between the trait and the segment.
• Filter Segment Uniques Overlap %: Filters data by the % of unique visitors share between the segment and the trait.
Example
The following diagram illustrates the difference between the trait uniques % and the segment uniques %. In this case, the trait
and segment share 3 unique visitors. As proportions:
• The trait shares 30% of its unique visitors with the segment (3/10 = 0.30).
User Interface
44
• The segment shares 0.3% of its unique visitors with the trait (3/1,000 = 0.003)
Segment-to-Trait Data Pop Fields Defined
Describes the metrics displayed in the popup window when you click an individual data point.
The popup for the Segment-to-Trait Overlap report contains the following metrics:
Metric
Description
Segment ID
Unique numeric ID for the segment.
Data Provider Name
Name of the segment owner.
Data Provider Type
Defines the type of provider a trait belongs to. Can be either:
• First-party (your own trait).
• Third-party (from an outside data partner/vendor).
SID
Unique numeric ID for the segment.
SID Name
Name of the segment.
Trait Uniques Overlap %
% of unique visitors a trait shares with the segment.
Segment Uniques Overlap %
% of unique visitors a segment shares with a trait.
Overlap Uniques
Number of unique visitors shared between the segment and the trait.
Segment Uniques
Number of unique visitors in the segment.
Trait Uniques
Number of unique visitors in the trait.
Segment-to-Segment Overlap Report
Returns data on how many unique users are shared between your segments.
Overview
The Segment-to-Segment Overlap report can help you:
User Interface
45
• Identify segments with high or low overlap, depending on your needs. Traits with high overlap give you a targeted audience,
but fewer unique visitors. Traits with low overlap can be useful to reach a larger, unique visitor set.
• Find unexpected overlap and use that information to build new, high-performance segments.
Sample Report
The following illustration provides a high-level overview of the Segment-to-Segment Overlap report.
Note: The Segment-to-Segment Overlap report returns an empty field when it compares the same segment to itself.
Drill Down on Individual Data Points
Select an individual point to view data details in a pop up window. Your click actions automatically update data displayed in
the report.
Segment-to-Segment Overlap Data Pop Fields Defined
The popup for the Segment-to-Segment Overlap report contains the following metrics:
Metric
Description
Segment ID1
Unique numeric ID for the segment that appears in the report results. Appears as the
row ID for the segment.
Segment ID2
Unique numeric ID for the segment you select when running the report. Appears as the
column ID for the segment.
Segment Name1
Name of the segment that appears in the report results row.
Segment Name2
Name of the segment you select when running the report. Appears in the report results
column.
Overlap %
Shows the % of unique overlap between compared segments (overlap uniques/segment
uniques 1).
Overlap Uniques
The number of unique visitors shared between compared segments.
Segment Uniques1
The number of unique visitors in segment 1.
Segment Uniques2
The number of unique visitors in segment 2.
Unused Signals Report
This report returns a frequency count of all the unused information collected on your inventory and sent to Audience Management.
Unused Signals Report
A signal is information from your website passed in to Audience Management in the form of key-value pairs (e.g., color=blue,
price>100, gender=female, etc.). Unused signals consist of data that you collect but have not been mapped to a trait. The
User Interface
46
Unused Signals report shows data in a table by date, key, value, and frequency count. Review this report to help identify orphaned
signals that can be mapped to new or existing traits.
Note: Specify a key or value name in the search fields to limit results to specific records.
Use Cases
Examples
Description
Ensure Trait Uniformity or Add
Related Values to a Single Key
Review the report to account for different value variations for a particular signal.
For example, say you have a trait for the state "North Carolina" defined in a key-value
pair as c_state = North Carolina. The report can help you find name variants and
add those to the trait (e.g., c_state = North Carolina, NC, N.C., NCarolina).
Alternatively, you could spot name variants with the report and replaces those with a
uniform value across all sites.
Create New Traits
Review the report to see what new values get passed in on a particular key. You may want
to create new key-value pairs based on these new values.
Note: Check the report bi-weekly for values that change frequently (e.g., shows,
campaigns, celebrities, etc.).
Find Unmapped Values
Review the report for the number 1. The number 1 in an Unused Signals report represents
a null value. This is not necessarily bad. It simply means that a particular key does not
have an associated value mapping. When you see a lot of 1 values for an important
variable, check with your site team to make sure all your pages are tagged correctly.
Best Practices
Run and check the Unused Signals report:
• After you create a trait or update trait rules. This helps ensure your traits and rules are set up properly. The number 1 in results
indicates a new trait may not be configured correctly.
• Bi-weekly or monthly. Scheduled reviews help ensure trait mappings are up-to-date.
Bulk Trait Creation
Contact your Partner Solutions representative if you need to bulk create a lot of traits based on data obtained from the Unused
Signals report.
Improve Log File Processing Times with Lookup Tables
Put data in Delivery Performance report log files into tables that contain IDs only. Put non-ID metadata in separate lookup
tables to help reduce file size and processing times.
Log File Metadata Increases File Size and Processing Time
A typical log file used by the Delivery Performance report usually contains thousands of rows and dozens of columns. It consists
of numeric IDs and human-readable information such as names for creatives, advertisers, insertion orders, etc. This non-ID
information is referred to as metadata (i.e., information about other information) and gets written in each row of the log file.
However, the Delivery Performance report mainly works with the IDs in the log file. The metadata is useful, but repetitious. It
increases file size and data ingestion times.
User Interface
47
Reduce File Size and Shorten Processing Time With Index Tables
To help improve performance, your main data file should contain IDs only. Put metadata in a separate lookup (or index) table
and link those records to the main file with a key variable common to both.
How Lookup Tables Reduce File Size
Let's say you have a data file that looks similar to the one below.
User ID
Ad ID
Ad Name
Order ID
Order Name
Advertiser ID
Advertiser Name
1
111
Shoe A
456
Sneakers
27
Company A
2
111
Shoe A
456
Sneakers
27
Company A
3
111
Shoe A
456
Sneakers
27
Company A
4
222
Shoe B
789
Hiking
14
Company B
5
222
Shoe B
789
Hiking
14
Company B
Here's the same log file with the metadata removed. The file is smaller and easier to process when it consists of IDs only.
User ID
Ad ID
Order ID
Advertiser ID
1
111
456
27
2
111
456
27
3
111
456
27
4
222
789
14
5
222
789
14
The lookup file below holds the metadata and can be linked back to the main file with the Ad ID. Note the size as well. Instead
of repeating each advertiser several times, you only need one reference for each.
Ad ID
Ad Name
Order Name
Advertiser Name
111
Shoe A
Sneakers
Company A
222
Shoe B
Hiking
Company B
APIs Can Eliminate the Need for Lookup Tables
If your ad serving system has an API, you might not need to send metadata in a lookup file. We may be able to get that information
through the API. When this is the case, your log files should contain IDs only. We'll work with you to determine if metadata
can be obtained through an API.
Filter Report Results With the Data Sliders
Use the various report sliders to show only the data that falls above, below, or within your specified range.
Set a Lower/Upper Range for Report Results With the Data Sliders
The report sliders let you set limits on the data returned by an interactive report. Move the left slider to exclude data below a
specific value. Move the right slider to exclude data above a specific value. The report updates and returns data that falls within
the desired range. Use the sliders to:
User Interface
48
• Reduce the overall amount of data returned by the reports.
• Focus on traits or segments that fall within a particular size range.
Overlap Reports
Describes the segment size and creation time requirements required by the Overlap report update process.
Overlap Report Update Schedule and Requirements
Overlap reports update weekly on Sunday. Additional report pre-processing begins on Saturday. This affects how new or existing
segments appear in an overlap report on Monday. To be included in an overlap report, a segment must:
• Contain a minimum of 70,000 total users during the last 14 days.
• Have been created on, or prior to, Thursday (2 full days before the weekly overlap report update process begins).
Why Segments May Not Appear in an Overlap Report
If you do not see a segment in one of the Overlap reports, it may be because the segment does not meet these minimum
requirements. See the examples below for more detail.
Example 1: Segment Size Too Small
Let's say you create a segment on (or before) Thursday, but it contains less than 70,000 total users. This segment won't appear
in an overlap report until it meets the user threshold requirements. Note, also, the segment must meet the required user count
on, or prior to, the Thursday cutoff period. If it does not meet the weekly deadline, the segment will appear in the overlap reports
for the week after the upcoming Sunday data run.
Example 2: Segment Created Too Late
Let's say you create a segment on Friday and it contains more than 70,000 total users. This segment won't appear in the overlap
reports for the next week because it was created less than 2 days prior to the report update period. However, the segment will
appear in an overlap report after the next weekly update.
Shapes, Colors, and Sizes Used in Interactive Reports
Most of the interactive reports display results using shapes of different sizes and colors. This display format is designed to help
you make sense of the data visually, without having to wade through rows and columns of numbers.
Report Legend
The following table defines the shapes, sizes, and colors used in the dynamic reports.
Data Element
Description
Shapes
• Circles indicate your own first-party traits.
• Squares indicate third-party traits.
Colors
• Red shades indicate low overlap.
• Green shades indicate high overlap.
Size
Size increases or decreases in direct proportion to reach (the number or % of clicks or
unique users in a trait or segment).
Report Icons and Tools Explained
Describes how to search and use the various icon-tools used in the dynamic reports.
User Interface
49
Data Icons and Tools
The following icons-tools are available at the bottom of each dynamic report window. The following illustration provides more
information about these tools.
Export Data
This tools lets you export data from the report in 4 different formats.
Export Option
Exports Data
Image
As an image (.png) file. Useful when you want to download and share report data in
its original, graphical format.
PDF
As a PDF file.
Data
In a new browser window as numeric data in columns and rows.
Crosstab
As a .csv file.
Revert Changes
Select this tool to undo any interactive click changes you may have performed on the report.
Automatic Updates
The Delivery-Performance and Trait-to-Trait Overlap reports are dynamic reports that respond and change based on user
click actions. For example, say you want to select several advertisers in the Overlap report. When enabled, automatic updates
will start to return data as soon as you select a checkbox. This dynamic behavior can interrupt your workflow because you have
to wait until the report finishes processing before selecting another advertiser. Use this tool to turn that feature off (and on
again) as required.
Refresh Data
Click the refresh icon to run a report or reload your data set. When automatic updates are off, click refresh to run or update the
report.
Search
Search is represented by a generic magnifying glass icon (not shown). The search field is hidden until you click on the selection
labels on the left side of the screen. The table below describes the location of the search tool for each report.
User Interface
50
Report
To find search, hover over
Delivery and Performance report
The "Advertiser Name" label.
Overlap reports
The "SID Name" label.
Report Technology
Describes the underlying software that powers the interactive reports and the data update schedule.
Interactive Reports Use Tableau Technology
Audience Management uses Tableau software to display data in the interactive reports. With Tableau, the Delivery and Overlap
reports use visual cues and symbols that help you:
• Find high and low performance traits.
• Spot traits and segments with low and high unique visitor overlap.
• Use overlap data to build targeted segments.
• Expand reach by identifying related traits with low overlap.
Data Update Schedule
Report data is updated weekly each Sunday. The update processes data from Saturday (the day before) back to the previous
Sunday.
Counting Unique Users in Overlap and General Reports
Describes the variation in unique user totals between reports for the same trait and time period.
Overlap Report: Unique User Count
The overlap reports count users as unique when they qualify for a trait:
• During the selected time interval for the report.
• That has a time-to-live value longer than the selected time interval for the report.
• If they're seen as active in our system (i.e, qualified for any other trait, had an ID sync, etc.) within the past 60 days.
General Report: Unique User Count
The General report counts site visitors as unique if they qualified for the trait during the selected time period.
Reports and Data Sampling Methodologies
Lists reports that use sampled and total data to generate results.
Reports That Use Sampled Data
Report Type
Methodology
• General reports for traits
Data in these reports consists of a statistically significant
random sample of all available data.
• Trend reports for traits
• Trait Builder Trend report
• Segment Builder trend report
• Segment Builder - Total Segment Population
User Interface
51
Report Type
Methodology
Overlap Reports
Overlap report data consists of a statistically significant random
sample of all available data.
• Trait - Trait
• Segment - Trait
• Segment - Segment
Additionally, these reports exclude traits and segments when
they do not meet the minimum unique visitor requirements.
The minimum unique visitor requirements are:
• Traits: 28,000 or more over a 14-day period.
• Segments: 70,000 or more over a 14-day period.
Reports That Use All Data
The Delivery and Unused Signals report return results based on all available data. These reports do not use sampled data.
Data Sources
View a list of your currently configured data sources, add new data sources, and edit existing sources.
You can also manage data sources using API methods. For more information, see Data Source API Methods.
Data Sources List View
The Data Sources dashboard is a centralized workspace for managing data sources.
The Data Sources dashboard (Manage Data > Data Sources) contains features and tools that help you:
• See all your existing data sources, including each data source's description, status, and whether it is Inbound, Outbound, both,
or a Share Provider.
• Search for data sources by name.
• Create, edit, and delete data sources.
User Interface
52
Create a Data Source
Create and configure a new data source, including specifying its name, integration code, description, and data source settings
(Inbound, Outbound, and Share Provider).
1. Click Manage Data > Data Sources.
2. Click
to display the Data Sources Details page.
User Interface
53
3. Fill in the fields:
Name: Specify a descriptive, unique name for this data source.
A descriptive name becomes very useful if you create numerous data sources. The name will help you locate an individual
data source faster, in the event you need to edit it. You can use the Search box to locate the desired data source if you have
a long list.
Integration Code: Specify an optional integration code. The integration code is an alternate ID that you can use instead of
the Audience Management ID. For example, you can specify an ID from a client-specific internal system, such as a CRM.
User Interface
54
Marketing Cloud Visitor ID Version: Select your Marketing Cloud Visitor ID version from the drop-down list. For more
information about the Master Marketing Profile and the Marketing Cloud Visitor ID service, see Audience Services - Master
Marketing Profile.
ID Type: Specify the desired type.
• Cookie: ID used in a cookie for identifying a device.
• Mobile: Mobile ID, such as Apple iOS IDFA IDs or Google Android IDs.
• Cross Device: A customer-provided authenticated ID, which is the same across devices.
Use this option for Profile Merge functionality that combines profiles from authenticated accounts and anonymous devices
into a single profile to deepen segmentation and targeting. Audience Management distinguishes between authenticated
(known) and anonymous (device) profiles and provides the ability to merge those data sets as needed.
Note: Ensure that you do one-way hashing of any PII IDs before sending them to Audience Management.
Description: Specify a description for the data source. The description, like the name, helps you identify and differentiate
data sources in your system.
Data Source Settings: Select one or more options:
• Inbound: Specifies that this data source will be used to receive inbound data. If you select this option, specify which visitor
ID will be used in the file:
• Customer Visitor ID: Identify the inbound data with the Customer Visitor ID.
• Audience Management Visitor ID: Identify the inbound data with the Audience Management Visitor ID.
• Outbound: Specifies that this data source will be used to send outbound data.
• Share Enabled: Specifies that data in this data source can be shared with other partners.
• Unique Trait Integration Code: Specifies that the trait integration code for this data source must be unique. If the code
is not unique, an error is returned.
• Unique Segment Integration Code: Specifies that the segment integration code for this data source must be unique. If the
code is not unique, an error is returned.
• Share Associated Visitor or Device IDs with All Platform Customers: Specifies that the visitor or device IDs can be
shared across Adobe Marketing Cloud solutions. For more information, see Marketing Cloud Visitor ID Service.
4. Click Save.
Edit a Data Source
Edit an existing data source to reconfigure its settings, including specifying its name, integration code, description, and data
source settings (Inbound, Outbound, and Share Provider).
1. Click Manage Data > Data Sources.
2. Select the check box next to the desired data source.
You can use the Search box to locate the desired data source if you have a long list.
3. Click
to display the Data Sources Details page.
User Interface
55
4. Edit the fields, as necessary:
Name: Specify a descriptive, unique name for this data source.
A descriptive name becomes very useful if you create numerous data sources. The name will help you locate an individual
data source faster, in the event you need to edit it. You can use the Search box to locate the desired data source if you have
a long list.
Integration Code: Specify an optional integration code. The integration code is an alternate ID that you can use instead of
the Audience Management ID. For example, you can specify an ID from a client-specific internal system, such as a CRM.
User Interface
56
Description: Specify a description for the data source. The description, like the name, helps you identify and differentiate
data sources in your system.
Marketing Cloud Visitor ID Version: Select your Marketing Cloud Visitor ID version from the drop-down list. For more
information about the Master Marketing Profile and the Marketing Cloud Visitor ID service, see Audience Services - Master
Marketing Profile.
ID Type: Specify the desired type.
• Cookie: ID used in a cookie for identifying a device.
• Mobile: Mobile ID, such as Apple iOS IDFA IDs or Google Android IDs.
• Cross Device: A customer-provided authenticated ID, which is the same across devices.
Use this option for Profile Merge functionality that combines profiles from authenticated accounts and anonymous devices
into a single profile to deepen segmentation and targeting. Audience Management distinguishes between authenticated
(known) and anonymous (device) profiles and provides the ability to merge those data sets as needed.
Note: Ensure that you do one-way hashing of any PII IDs before sending them to Audience Management.
Data Source Settings: Select one or more options:
• Inbound: Specifies that this data source will be used to receive inbound data. If you select this option, specify which visitor
ID will be used in the file:
• Customer Visitor ID: Identify the inbound data with the Customer Visitor ID.
• Audience Management Visitor ID: Identify the inbound data with the Audience Management Visitor ID.
• Outbound: Specifies that this data source will be used to send outbound data.
• Share Enabled: Specifies that data in this data source can be shared with other partners.
• Unique Trait Integration Code: Specifies that the trait integration code for this data source must be unique. If the code
is not unique, an error is returned.
• Unique Segment Integration Code: Specifies that the segment integration code for this data source must be unique. If the
code is not unique, an error is returned.
• Share Associated Visitor or Device IDs with All Platform Customers: Specifies that the visitor or device IDs can be
shared across Adobe Marketing Cloud solutions. For more information, see Marketing Cloud Visitor ID Service.
5. Click Save.
Delete Data Sources
Delete a data source that you no longer need.
1. Click Manage Data > Data Sources.
2. Select the check box next to one or more data sources.
You can use the Search box to locate the desired data sources if you have a long list.
3.
Click , then confirm the deletion.
Traits
Manage data collection and audience creation with rules-based or algorithmic traits.
User Interface
57
Trait List View
The Trait Builder dashboard is a centralized workspace for managing traits.
The Trait Builder dashboard contains features and tools that help you:
1. See all your traits and related details in a table with sortable columns.
2. Create, edit, and delete traits.
3. View and manage trait storage folders.
4. Search for traits by name, ID, or other associated elements.
Trait Summary View
The trait summary page gives you a detailed overview of useful trait information.
Click on a trait name from the main dashboard to access its summary page. The trait summary page contains details about:
1. Basic Information: Shows required and optional details specified when the trait was created.
2. Performance: Graphs trait performance for the last 30-days.
3. Signal Rules: Shows the various rules for the trait. Clicking "Edit Signal Rules" lets you manage the various rules that the trait
consists of.
4. Associated Segments: Shows you what segments the trait belongs to and lets you add the trait to an existing segment or add
it to a new segment.
User Interface
58
Trait Builder
Describes how to create rules-based and algorithmic traits with Trait Builder.
About Trait Builder
TraitBuilder is a feature that improves upon traditional pixel-based data collection and audience creation/segmentation processes.
It works by processing page data with server-side rules you create in the user interface.
Compared to pixels, which fire in response to simple "yes" or "true" conditions, TraitBuilder lets you:
User Interface
59
• Collect all page data so you can use it later to build relevant, useful traits.
• Build traits based on key-value pairs passed in during data collection.
• Evaluate complex data conditions with server-side rules that work with Boolean expressions and comparison operators.
• Reduce or eliminate the need to maintain data collection pixels on your inventory.
• Monitor performance with AudienceManager reports.
Create Rules-Based or Algorithmic Traits
Contains information about set up steps, features, or tools unique to each trait type.
Basic Information for Traits
In TraitBuilder, the Basic Information settings let you create new, or edit existing traits. To create a new trait, provide a name,
data source, and select a storage folder. Other Basic Information fields are optional.
Basic Information Fields Defined
Interface Element
Explanation
Required/Optional
Name
The trait name.
Required
Description
A few words to help describe the trait's purpose or function.
Optional
Type
Assigns the trait to a type or category, usually according to
function (e.g., site visitor, partner, page view, etc.).
Optional
Data Source
Associates the trait with a specific data provider.
Required
Integration Code
A field for an ID, SKU, or other value used by your internal
business processes.
Optional
Comments
General notes about a trait.
Optional
Stored In
Determines which storage folder the trait belongs to.
Required
Data Category
Classifies traits according to commonly understood categories. Optional
Note: Traits belong to a single category only.
Create Rules-Based Traits
Describes set up steps and features unique to the rules-based trait creation process.
Managing Trait Rules
In TraitBuilder, the Expression Builder lets you create and test rules that establish audience qualification requirements. Rules
consist of key-value pairs such as "color == blue" or "price > 100". Comparison operators establish the relationship between keys
and values. Boolean expressions determine the relationship between rule groups.
Main Signal Rules Features Described
User Interface
60
1. The Expression Builder or Code View tabs provide an overview of the rules in your trait. The Expression Builder tab lets
you create rules with fields and dropdown menus. The Code View lets you create rules by manually writing those expressions
as code. The illustration above shows a simple trait composed of a signal that evaluates data for a qualifying condition where
a product key equals a specific value, in this case color == "blue".
2. The fields and controls in this section let you create signals from key-value pairs and set the relationship between them with
a comparison operator. A key, operator, and value are required. A meta-tag is similar to an informal nickname for the signal
and is not required.
3. The test fields let you validate combinations of signal rules or the URLs that you want to use when sending data to Audience
Management.
Create a Trait Rule
Rules (or expressions) consist of individual or groups of key-value pairs. Comparison operators set the relationship between
key-value pairs. To create a rule, provide a key, a value, select an operator, and click "Add Rule."
Complete the required fields in the Basic Information section before creating trait rules.
To create a rule
1. Expand the Signal Rules section and enter a key and value name.
This creates a signal.
Note: Include the c_ prefix (or any other naming convention) for key variable if your event calls send data to Audience
Management using that syntax.
2. Select a comparison operator from the Operator dropdown.
The comparison operator evaluates the relationship between the elements in a signal.
User Interface
Note: The Boolean OR operator establishes the relationship between multiple signals within a group and cannot be
changed.
3. (Optional) Assign a meta-tag your key-value signal.
4. Click Add Rule.
The saved rule appears in the traits workspace above the data entry fields.
Example
In the example below, a user has created a new trait rule based on the product ID for a camera. To build this rule, the user
provided:
• An optional meta-tag (used to help build additional rules).
• The key productkey linked with an equals operator (==) to the value 2093.
Clicking Add Rule saves and moves the trait into the Expression Builder workspace.
61
User Interface
62
Create a New Rule Group
This procedure describes how to create a new rule group from.
Your trait must contain at least two rules before you can create a new rule group.
To create a new rule group
1. Move your cursor over the rule you want to move to highlight it.
2. Hover over the highlighted rule border.
This automatically separates the rule from its current group and moves it into a new group.
Note: Drag a rule back to its original group if you move it unintentionally.
3. Select a Boolean operator (AND, OR, AND NOT) from the dropdown menu to set the relationship between the rule groups.
Move Rules Between Groups
To move a rule, click and drag it to another group.
Edit a Trait
This procedure describes how to edit a trait.
To edit a trait
1. In the Traits dashboard, hover over the Actions column for the trait you want to delete.
This brings up the trait management icons.
2. Click the pencil to edit the trait.
User Interface
63
Delete a Trait Rule
This procedure describes how to delete a trait rule.
To delete a rule
1. In the Traits dashboard, hover over the Actions columns for the trait you want to edit and click the pencil icon.
This brings up the trait management icons.
2. Expand the Trait Expression section.
3. Hover over the rule you want to delete and click the X icon.
Clicking X deletes the rule immediately.
Set a Trait Expiration Interval
In TraitBuilder, the Advanced Option sets a time-to-live (TTL) interval for a trait. TTL defines how many days a qualified visitor
remains in a trait. When set to 0 (default), trait membership never expires.
To set the TTL for a trait
1. Expand the Advanced Options section and enter a number to set a TTL value for the trait.
2. Click Save.
Create Algorithmic Traits
Describes set up steps and features unique to the algorithmic trait creation process.
Create an Algorithmic Trait
Describes the required and optional steps that let you create an algorithmic trait.
To create an algorithmic trait, go to Traits and follow the steps below:
1. Click Create New Trait and select Algorithmic from the drop down menu.
2. In the Basic Information section
•
•
•
Name the trait.
Select a data source.
Choose a storage folder.
3. Expand the Configuration pane and click Browse All Models.
This opens a new window that lets you select the model you want to use with the trait.
4. Select a model and click Add Selected Model to Trait.
Adding the model exposes the reach and accuracy settings.
5. Select reach or accuracy as your goal and choose a value from the respective drop down menus. Click Save when done.
Configuration Settings for Algorithmic Traits
In Trait Builder, the Configuration section lets you associate an algorithmic model to a trait. To complete the algorithmic trait
creation process, select a model and choose a reach or accuracy goal.
Prerequisites:
User Interface
64
• Create an algorithmic model.
• Wait for the notification email that lets you know the model data run has finished.
• Complete the required fields in the Basic Information section.
Configuration Fields and Settings
Interface Element
Explanation
Select Model for Algorithmic Trait
Click the Update button to open the models window. From
the window, select the algorithmic model that you want to use
to create the trait.
Select Goal Accuracy
Select this option to create a trait based on accuracy. Accuracy
is a scored value that indicates how close potential users are to
your baseline. The accuracy scale ranges from 0 (least accurate)
to 1 (most accurate).
Reach and Accuracy Data Columns
Located on the right, this section displays up to 21 rows of
numeric data that displays the accuracy and reach values for
your model.
Reach and Accuracy Slider
Located at the bottom of the graph, the slider lets you set a
numeric value for your reach or accuracy goals. You can set
the slider and then choose the reach or accuracy goal button
to create a trait.
Trait Storage
Trait storage folders store and help you organize traits.
Purpose of Trait Storage Folders
In TraitBuilder, trait storage folders are directories that hold and organize traits into logical groups that you create. Trait storage
folders replace the folders Data Storage section in the user interface. All the information in your existing data storage folders
(such as folder hierarchy, names, and traits) gets converted and moved in to corresponding trait storage folders. Access the
storage folders from the Traits dashboard or when creating a new trait. Remember, you cannot create a new trait without
assigning it to a storage folder.
User Interface
65
Create a Trait Storage Folder
This procedure describes how to create a storage folder for your traits.
You can create a new storage folder in the Basic Information section when setting up a new trait. Also, folders can be created
in Trait Storage section of the main Traits list dashboard.
To create a new storage folder
1. In the Trait Storage window, hover over:
• "All Traits" text to add a new root level folder.
• An existing parent folder to add a new subordinate folder.
2. Click the + icon to create the trait.
3. Name the trait and click Save.
Rename or Delete a Trait Storage Folder
This procedure describes how to rename or delete a storage folder.
You can rename or delete storage folders from the Trait Storage section of the main Traits list dashboard.
•
•
Rename a folder by hovering over it and clicking the pencil icon.
Delete a folder by hovering over it and clicking the X icon.
Trait Builder Reference
Concepts and other material related to traits.
Accuracy and Reach
Describes the relationship between accuracy and reach in algorithmic traits.
User Interface
66
Accuracy vs Reach: About
It's important to understand the relationship between accuracy and reach when working with algorithmic traits. Accuracy is
represented by a scored value that reflects how similar users are to your baseline. The accuracy scale ranges from 0 (least accurate)
to 1 (most accurate). Reach is simply a value that represents the number of unique users you would like to include in a trait.
Reach and accuracy are inversely related. Accurate traits reach fewer users and traits with greater reach are less accurate. The
following image illustrates this concept.
Accuracy and Reach Affect Audience Size
Your business goals should help you make the right decisions about accuracy and reach when working with algorithmic traits.
If accuracy is your goal, note that a trait's population can increase or decrease across model runs. Population changes are the
results of the algorithm making decisions during each evaluation period. Sometimes, the algorithm finds more qualified users
during a processing cycle and, during others, it may find fewer. Results are determined by the baseline data used to create the
model and new visitors and trait qualifications that have come since the previous model run. By contrast, when working with
reach, the user population count remains constant. For example, if you want to reach 10,000 users, the algorithm will make sure
it always hits that number for each model run.
General Use Cases for Accuracy vs Reach
The focus on accuracy or reach depends on what you want to achieve with a particular segment. The following table may help
you evaluate accuracy vs reach when creating a trait.
Trait Decision Favors
Helps Find
Accuracy
Users similar to baseline customers in your model. Useful for targeted campaigns when
you want to reach a specific audience.
User Interface
67
Trait Decision Favors
Helps Find
Reach
A specific number of users for each data run. Useful for brand campaigns when you're
interested in reaching an audience of a specific size.
Working with Comparison Operators in TraitBuilder
This article describes the comparison operators used by TraitBuilder.
Purpose of Comparison Operators
Comparison operators (or relational operators) are used to compare, test, or evaluate the relationship between different values.
In TraitBuilder, when building signal rules, comparison operators let you test the relationship between different key-value pairs.
For example, you could create a signal rule to define an audience for expensive camera shoppers. In this case, you could create
a camera/price key-value pair and qualify a user if they've looked for a camera with a price equal to or greater than a set amount.
Advantages of Comparison Operators
Comparison operators are useful when you need to evaluate and create traits based on multiple values. Looking at prices on
goods and services can illustrate this condition. For example, your business may want to identify visitors based on the prices of
the products they view. However, it can be administratively inefficient to define individual segments based on specific values.
Comparison operators help overcome this hurdle by establishing segmentation triggers based on price thresholds or ranges.
Comparison Operators
You can build rules with the following comparison operators:
Operator
Definition
==
Equal to
!=
Not equal to
>
Greater than
<
Less than
=>
Greater than/equal to
<=
Less than/equal to
Named Operators
You can build rules with the following named operators:
Operator
Evaluates to True When
Contains
The value in a key-value pair contain characters specified in a
regular expression.
Matchesregex
The values in a key-value pair match the pattern specified by
a regular expression.
Startswith
The value in a key-value pair starts with characters specified
by a regular expression.
User Interface
68
Operator
Evaluates to True When
Endswith
The value in a key-value pair ends with the characters specified
by a regular expression.
Classifying Traits with a Common Taxonomy
This article provides general overview about classifying traits (pixels) with a common taxonomy.
The Audience Management Taxonomy
The Audience Management taxonomy is an optional feature that classifies traits (pixels) using uniform, logical, and commonly
understood naming conventions. It operates at the platform level to help ensure naming consistency throughout the Audience
Management ecosystem. Ultimately, the common taxonomy is designed to bring our product into greater alignment with
industry standards regarding consumer privacy and opt-out processes.
Advantages of Trait Classification
Enabling our customers to build custom segments and data models is core to the Audience Management model and to your
ability to capture value from our platform. What is also required, however, is a robust and scalable means to communicate
information about segments to your customers and partners. Furthermore, this communication requires that segment information
is shared in an easy-to-understand and universally understood language while protecting your proprietary trait and segment
names. The Audience Management common taxonomy provides this language and capability.
The Taxonomy Uses Industry Standard Classification Categories
The common taxonomy is based on the classifications created by the Interactive Advertising Bureau (IAB). Refer to the IAB's
website for more information about quality assurance guidelines for networks and exchanges.
Taxonomic Organization
The Audience Management taxonomy organizes data into nested categories called tiers. Each category can contain up to 3
separate tiers for data classification. At the highest level, a Tier 1 category groups data into its most general form (e.g., geography).
Subsequent tiers provide greater specificity to the higher level, general category (e.g., geography --> United States --> New York).
However, not every category has 3 tiers, some use just 2.
Classify Traits in the Pixel Wizard
You assign taxonomic classifications when creating or editing traits in the pixel wizard (located in Manage Data > Pixels). Refer
to the documentation on creating pixels for more information.
Working With the Taxonomy: Additional Considerations
If you decide to classify traits according to our common taxonomy, it's important to remember:
• Classification is optional.
• Traits are not assigned to a taxonomic category by default (i.e., traits are not classified as "unknown" or "uncategorized" etc.).
• Traits can belong to one taxonomic category only (multiple and cross-category classifications are not allowed).
Order of Operations in TraitBuilder Expressions
Reading from left to right, TraitBuilder looks at rules in parenthesis first and evaluates expressions according to a standard order
of operations.
The following table ranks the TraitBuilder operators according to precedence, from high to low.
User Interface
69
Operator precedence
Symbol
Comments
Parenthesis
()
Expressions in parenthesis are always evaluated first and follow precedence
order.
Comparison operators
< > <= >=
Less than, greater than, less than/equal to, greater than/equal to
Equality operators
== !=
Equal to, not equal to
Boolean AND
AND
n/a
Boolean OR
OR
Name Requirements for Key Variables
This article describes the naming conventions used by the key variable in a key-value pair
Naming Requirements for Keys
In Expression Builder, the name of a key variable in a key-value pair can consist of any number of digits followed by 1 (or more)
letters, a dash, an underscore, and additional digits.
• Valid key names: price123, 123price, price-123, c_price123.
• Invalid key names: 123, price!123.
Prefixing Key Variables with c_
The c_ prefix is always required if the parameters that send in data on an event call URL use that syntax.
Time to Live Explained
This article describes how trait time-to-live interval affects segment membership.
Time to Live
Time-to-live (TTL) defines how long a site visitor remains in a segment after the last trait qualification event. TTL is set on traits
and not on segments. Visitors fall out of a segment if they do not see a qualifying trait before the end of the TTL interval. The
TTL for new traits is set to never expire by default. Set the TTL value when you create or edit a trait in the Advanced Options
section of TraitBuilder.
TTL and Dropping Out of a Segment
A user falls out of a segment if they do not see any of its traits within the TTL interval. For example, if you have a 1-trait segment
with a 30-day TTL, the user will drop out of that segment if they do not see the trait again within the 30 days.
TTL and Segment Renewal
The TTL resets, and the user remains in a segment, if they see that segment’s trait within the TTL period. Also, because most
segments contain multiple traits with their own TTL periods, a user can remain in a segment (and reset the TTL interval) as
User Interface
70
long as they keep seeing any traits associated with a segment. For example, say you have Segment 1 composed of Trait A (30-day
TTL) and Trait B (15-day TTL). Assuming the user sees each trait only once, the illustration below outlines the TTL renewal
process and total in-segment duration.
Audience Management TTLs are Independent of Third-Party TTL Settings
Remember, the TTL set on your Audience Management pixel operates independently from the TTL set on other pixels used by
third parties (DSPs, ad networks, etc.).
Prefix Requirements for Key Variables
This article describes the prefixes you must attach to key variables when creating trait rules.
Purpose of Key Variable Prefixes
When you create Trait Builder rules, it is important to preface the key variable with a recommended prefix. These prefixes
identify the type of data passed in and help avoid namespace conflicts within Audience Management. Generally, you can give
a variable any name, but data for a rule will not process if the key variable name does not match the variable name in an event
call.
Prefixes for Key Variables
The following table defines the common prefixes used by Trait Builder.
Key variable prefix
Identifies the variable
c_
As customer specific. This is key data sent in from your own properties.
d_
At the Audience Management level. This data is uniform across the Audience Management
ecosystem. See Supported Variables for a more complete list.
h_
That contains HTTP header information. Includes header parameters such as referer, IP,
accept-language, etc.
p_
As personally identifiable information (PII data) from site visitors.
Note: TraitBuilder uses personal information for trait qualification purposes only. It does
not record or store PII data.
User Interface
71
Geotargeting With Platform-level Keys
Describes the common platform-level key-value pairs you can use to target users with geographic variables across all properties
in your Audience Management account.
This topic contains the following sections:
• Purpose of Platform-level Variables
• Adding Values to Platform Level Keys
• User Defined Platform-Level Keys
• Platform Level Keys Defined by IP Address
Purpose of Platform-level Variables
Platform-level variables let you take data passed in from a particular site and make it available for targeting across all the properties
in your Audience Management account. These variables are formed by key-value pairs with the key prefixed by d_ as shown
below.
Adding Values to Platform Level Keys
For some platform-level keys, you can specify the value yourself. With others, the keys are associated with corresponding IP
addresses passed in on an event call. In either case, you still need to specify the value when building traits in Trait Builder.
User Defined Platform-Level Keys
You specify the value when building traits with these key-value pairs:
Key
For Targeting
d_zx
ZIP code (e.g., d_zx=10022).
Platform Level Keys Defined by IP Address
The values for these keys are determined by matching IP addresses to corresponding geographic and demographic data. However,
you'll still have to enter the value parameter when creating the key-value pair in Trait Builder.
Key
For Targeting
d_area_code
Area codes. For a full list of codes, see the AreaCode.org website.
For example,
Trait: d_area_code=801
Trait Name: Utah
d_city
Cities and towns. Download the City List.
For example,
Trait: d_city=bonn
Trait Name: Bonn
d_country
Area codes. For a full list of codes, see ISO 3166-1.
For example,
Trait: d_country=CZ
User Interface
Key
72
For Targeting
Trait Name: Czech Republic
d_dma_code
Metropolitan areas, or metro codes. Download the Metro Code List.
For example,
Trait: d_dma_code=807
Trait Name: San Francisco
d_lat
Latitude (e.g. d_lat=40.75).
d_long
Longitude (e.g. d_long=73.98).
d_postal_code
ZIP codes (exclude the extended +4 code). Download the Postal Code List.
For example,
Trait: d_postal_code=84004
Trait Name: Alpine
d_state
States. Download the State List.
d_region
Regions. Download the Region List.
d_isp
ISP/organization. Download the ISP List.
Sample Expressions With Boolean and Comparison Operators
Examples you can refer to for creating expressions in the Expression Builder code editor.
Code Samples Overview
Create your own trait rules with the Expression Builder code editor. The following examples can help you get started. Some of
the examples preface the key variable with c_ to identify it as a user-defined variable. Include the c_ prefix (or any other naming
convention) for key variable if your event calls send data to Audience Management using that syntax.
Boolean Expressions
AND Example
The rule establishes trait qualification requirements using Boolean AND operators.
Sample code
To qualify, a visitor must
(c_make==“A”) AND (c_model==“B”) AND
(c_search==“1”)
• Look for a specific make and model.
• Find the product from a search results page (search = "1" or
"true).
OR Example
User Interface
73
This rule establishes trait qualification requirements using Boolean OR and AND operators.
Sample code
To qualify, a visitor must
(a== “1” OR b==“1”) AND (c== “new”)
Meet the conditions set by variables a or b and c.
Range Example with Greater Than, Less Than, Equal To
This rule establishes trait qualification requirements using a range.
Sample code
To qualify, a visitor must
(price>== “1.00” OR price<== “100.00”)
Meet any price condition between 1.00 and 100.00.
Comparison Operators
Segments
API methods for working with individual segments.
Segments: Purpose, Composition, and Rules
Describes segments, their constituent parts, and rule creation with Segment Builder.
Purpose of Segments
A segment (or audience)is a set of users who share common attributes. In Audience Management, you create segments with
server-side rules. These rules let you build audience groups based on site visitor attributes such as:
• Behavior.
• Demographics (age, gender, income, etc.).
• Other characteristics you can define in the user interface.
Segment Composition
An Audience Management segment is a server-side rule that consists of individual or groups of traits. Traits are composed of
data elements called key-value pairs. Along with rules you set at the segment level, these key-value pairs contain the criteria that
qualify visitors for trait and segment membership.
Create Rules-based Segments With Segment Builder
Unlike traditional pixels that fire in response to simple yes/no conditions, Segment Builder lets you create complex segment
requirements. Like traits, segments evaluate data using Boolean expressions (AND, OR, NOT), comparison operators (greater
than, less than, equal to, etc.), and recency/frequency criteria. These features help create focused audience segments relevant to
your business needs.
Benefits
Segments improve upon standard pixel-based audience creation/segmentation processes because they let you:
• Build relevant, useful segments with first and third-party traits.
• Create sophisticated and complex segmentation rules with Boolean operators, comparison expressions, and recency/frequency
criteria.
• Send segment data to a destination partner.
User Interface
74
• Monitor performance with Audience Management reports.
Segments List View
The Segments dashboard is a centralized workspace for managing destinations.
The main Segments page contains features and tools that help you:
• Create new segments.
• Edit and delete segments.
• Clone (duplicate) existing segments.
• See all your segments in a table with sortable columns.
• Manage segment storage.
• Search for segments by name.
Segment Summary View
The segment summary page displays details such as name, traits in the segment, rules, performance data, and destination mapping
information.
Click a segment name from the main dashboard to access its summary page. Summary sections include:
1. Basic Information: Shows required and optional details specified when the segment was created.
2. Performance: Displays performance data graphically and for fixed 7, 30, and 60-day intervals.
3. Segment Traits: Lists traits in the segment along with qualification rules.
4. Destination Mappings: Lists destination mappings for the segment.
5. Management Tools: Controls that let you create, edit, clone, and delete segments.
Segment Builder
Describes how to create segments with Segment Builder.
Create a Segment
Describes the required and optional steps that create a segment in Segment Builder.
Segment Builder Section
Segment Builder consists of 3 separate sections: Basic Information, Traits, and Destinations Mapping. To create a segment,
complete the required fields in the Basic Information and Traits sections. Destinations Mapping settings are optional. See the
instructions below for additional help.
1. In the Basic Information section
• Name the segment.
• Set the segment status (active is default).
• Choose a data source.
• Assign the segment to a storage folder.
2. In the Traits section
• Search for the trait you want to add to a segment and click Add Trait. Add another trait to create a trait group.
• Click and drag traits to create separate groups.
• Hover between groups to set relationships with Boolean AND, OR, and not values.
User Interface
75
• Hover over the clock icon to add recency and frequency rules to the trait.
• Click Save when done.
3. (Optional) Map a segment to a destination in the Destination Mapping section
• Search for the destination and click Add Destination. Note, the destination must already exist before you can add it to a
segment.
• Click Save when done.
Basic Information
In Segment Builder, the Basic Information settings let you create new, or edit existing traits. To create a new segment, provide
a name, a data source, and select a storage folder. All other fields are optional. Move on to the Traits section when done.
Field
Description
Name
Give the segment a short, logical name that describes its function or purpose. Avoid
abbreviations and special characters.
Description
A field for additional descriptive information about the segment.
Integration Code
A field for a user-defined ID or other company-specific information.
Data Source
Associates the segment with a specific data provider.
Status
Activates or deactivates the segment (active by default).
Folder Storage
Determines which storage folder the segment belongs to.
Traits
In Segment Builder, the Traits section lets you manage traits in a segment, create trait groups, and set qualification criteria. To
add a trait to a segment, type the trait name in the search field and click Add Trait. Save the trait (if finished) or move on to
Destinations Mapping.
Prerequisites: Complete the required fields in the Basic Information section.
Field
Segment Traits
Description
This section provides visual controls that let you:
• Build new and manage existing segments.
• Add up to 50 (maximum) traits to a segment.
• Drag and drop traits to create new groups.
• View traits and trait groups in a segment.
• Set qualification criteria with Boolean expressions, comparison operators, and
recency/frequency settings.
Segment Expression (Code View)
Opens a development environment that lets you create and manage traits, groups,
and qualification requirements with code instead of the visual interface. The code
view is useful if your segments:
• Contain more than 50 traits in an individual segment.
Note: Segments are limited to 5000 traits (maximum).
User Interface
Field
76
Description
• Contain many trait groups.
• Have complex qualification requirements.
Search
Finds traits to add to a segment.
Estimated Historic Segment Size
See the segment performance documentation.
Total Segment Population
Destinations Mappings
In Segment Builder, the optional Destinations Mapping section lets you send segment data to a third-party cookie, URL, or
server-to-server destination. To add a destination, search (or browse) for a destination, provide destination specific information,
and click Add Destination.
Prerequisites: Complete the required fields in the Basic Information and Traits sections. Also, the destination must already
exist.
Destination Mappings Search Tools
The Destination Mappings panel contains search tools as described in the table below.
Search Type
Description
Search by Destination Name
Lets you search for a specific destination by name. To search, start typing.
The field will auto-complete based on your search terms. Click Add
Destination when done.
Browse All Destinations
Browse a list of all destinations available to you. Select and add destinations
to your segment from the popup list.
Fields in the Destination Mappings Pop-up Windows
In Segment Builder, the Add Destination pop appears after you select a destination. This window displays static information
about the destination and fields that vary depending on the destination type. Provide the required information in the empty
fields to set up a destination mapping.
Note: Publication dates are optional. When blank, the destination becomes active and never expires.
Cookie Destination Fields
In the Destination Mapping fields, specify the key-value pairs used to send data to the destination. Enter the key in the first field
and the values in the second. Your cookie destination pop could look similar to this:
URL Destination Fields
In the URL and Secure URL fields, specify the complete standard or secure address used to send data to the destination.
User Interface
77
Server-to-Server Destination Fields
In the Destination Value field specify the value (part of a key-value pair) used to send data to the destination.
Code Syntax Used in the Segment Expression Editor
Segment Builder lets you build trait rules for a segment using a code editor. Click the Segment Expressions (Code View) tab in
the Traits panel to access this feature.
Expression Builder Code Syntax
You can add trait rules to a segment with code instead of using drag and drop features. When coding, replace italicized elements
in the example with an actual expression or value. The base code uses following syntax:
FREQUENCY([<traitID1>T,<traitID2>T]<Recency Operator><Numeric Value>D)
<Frequency Operator><Numeric Value>
Note: By default, Boolean OR conditions apply to multiple traits within an expression.
Join Segments with Boolean Operators
To build groups of segments, wrap the frequency function in parenthesis and set the relationship between each expression with
a Boolean operator (AND, OR, and NOT).
Parameters
Note: All parameters are required unless noted otherwise.
Name or Variable
Description
FREQUENCY
A literal that must precede the expression.
[<traitID>T]
An array of trait IDs followed by the letter T. Separate multiple traits with
a comma. For example, [123T, 456T].
<Recency Operator><Numeric Value>D
(Optional) Sets recency rules on traits in the segment. The letter D indicates
recency in days.
<Frequency Operator><Numeric Value>
Sets frequency rules on traits in the segment.
User Interface
78
Allowed Recency and Frequency Operators
Set recency and frequency intervals with a comparison operator and an integer. Segment Builder uses standard expressions like
< (less than), > (greater than), == (equal), etc. However, the types of allowed operators vary when you set recency or frequency.
The table below lists the allowed recency/frequency operators.
Recency Operators
Frequency Operators
• >= (greater than/equal to)
• >= (greater than/equal to)
• <= (less than/equal to)
• <= (less than/equal to)
• == (equal to)
Recency and Frequency
In Segment Builder, recency and frequency let you segment visitors based on actions that occur or repeat over a set daily interval.
Recency and Frequency: About
Audience Management defines recency and frequency as follows:
• Recency: The number of days during which a user viewed or qualified for one (or more) traits.
• Frequency: The rate at which a user viewed or qualified for one (or more) traits.
Recency and frequency settings help you segment visitors based on their real (or perceived) level of interest in a site, section, or
particular creative. For example, users who qualify for a segment with high recency/frequency requirements may be more
interested in a site or product than users who visit less often or less frequently.
Limitations and Rules
When working with recency and frequency, remember:
• You cannot set recency/frequency rules on individual third-party traits, or trait groups that contain third-party traits.
Recency/frequency applies to your own traits only.
• Recency must be greater than 0.
• By default, recency/frequency is set to >= 1 time in the last 30 days.
• When you need recency/frequency requirements to be less than a specific number of times or days, you must join that trait to
another with an AND operator.
• Frequency is unlimited, but our system records only a maximum of 255 frequency events per day. For example, if a visitor
returned to your site 256 times in a day, Audience Management records the frequency value as 255. If this same visitor returns
256 times the next day, the frequency count total would be 510 (255 + 255 = 510).
Location of Recency and Frequency Controls
Recency and frequency settings are located in the Traits panel. Hover over a trait and select the clock icon to expose the
recency/frequency controls.
User Interface
79
Segment Performance Data: Composition and Location
Describes the data displayed in the Segment Builder traits panel and the segment summary page.
Data Shown in the Segment Builder Traits Panel
In Segment Builder, the Traits Panel displays performance data described in the table below.
Report Name
Estimated Historic Segment Size
Results Composed Of
The estimated number of visitors that qualified for a trait based on its
recency/frequency settings.
Results include visitors regardless of their trait time-to-live (TTL) settings.
For example, say you have a trait with a 5-day TTL. A visitor does not qualify
after that interval and falls out of the segment. However, because they were
in the segment for the 7, 30, or 60-day interval, this visitor will still be counted
in the total.
Total Segment Size
The number of all unique users in the segment for 7, 30, and 60 day intervals.
The report uses processed and instant segment data. Data is updated nightly.
Total segment size results for a new segment shows a dash because data is
not available until after the nightly update.
On a daily basis, these number may not vary much. Stable totals suggest the
segment:
• Contains traits with a high TTL or no TTL (visitors expire slowly or not at
all).
• Is already very large. As a result, it contains most of the potentially available
audience members. Growth is incremental.
30 Days
Totals
The number of users who qualified for the trait over the last 30-days. Results
should match the 30-day number in the Instant Segment Population data.
Total number of unique users for a trait group. Results update automatically
when you add new traits or change qualification rules.
User Interface
Report Name
80
Results Composed Of
Totals returns estimated numbers when you either:
• Add another trait to the group.
• Apply recency and frequency rules to the trait.
Data Shown in the Segment Summary View Page
A segment's summary page displays performance data described in the table below.
Report Name
Total Segment Population
Results Composed Of
Data for 7, 30, 60 day intervals and in the performance graph.
Total segment population is all visitors in the back-end store who are currently
qualified for the segment or have been qualified within the specified time
range. These are visitors we can deliver to Server-to-Server destinations
(assuming we also have an ID sync with the partner in question for the user).
See Total Segment Size above.
Instant Segment Population
The number of active users in a segment.
Instant segment population is a count of unique visitors we have seen in
real-time via the DCS over the specified time range who were qualified for
the segment at the moment we saw them. Basically, these are visitors we could
have delivered to Cookie/URL destinations or targeted on-site.
Paused and Deleted Segments (Using UI)
Describes the effects on segmented users, data, and destinations when you pause or delete an active segment using the Segment
Builder.
Access to the Pause and Delete Controls
Hover over a segment name in the segments list to expose the pause and delete icons (in the Actions column). These features
affect segments as described below.
Paused Segment Functionality
A paused (deactivated) segment:
• Stops segmenting new, qualified users.
• Retains a user's segmentation status/membership (does not remove a user from the segment).
• Remains in the segment list and can be reactivated.
• Does not send data to associated destinations.
• Returns data in the available reports (up to the deactivation date).
Deleted Segment Functionality
A deleted segment:
• Stops segmenting new, qualified users.
User Interface
81
• Removes qualified users from segment membership .
• Is removed from the segment list.
• Cannot be undeleted.
• Does not send data to associated destinations.
• Does not return data in the available reports.
Note: You can also pause and delete segments using an API method. For more information, see REST APIs.
Destinations
Manage URL, cookie-based, or server-to-server destinations with Destination Builder. In Audience Management, a destination
is any third-party system (ad server, DSP, ad network, etc.) that you want to share data with.
Working with Destinations
The Audience Management Destination Builder lets you create destinations and send information about segmented users to
your data partner.
Creating destinations and sending data with Destination Builder helps you:
• Protect data value: Rather than send all user data to a destination, Destination Builder let you share specific information
about qualified users only.
• Take action on your data: Sending data to a destination partner helps them quickly develop and target qualified audience
segments.
• Reduce technical overhead: Business users can set up destinations safely in the Destination Builder interface. This helps
reduce the time required for pre-deployment testing. With Destination Builder, you create, manage, and delete destinations
as your business needs change, all without working through a long development cycle.
Destination Builder
Destination Builder lets you set up and manage data delivery to your third-party data partner.
Purpose of Destination Builder
Destination Builder provides the tools you need to set up and manage URL or cookie-based destinations. You cannot create a
server-to-server (S2S) destination, but you can manage S2S segment mappings. Contact your Partner Solutions manager to set
up a S2S destination.
Destination Builder consists of the following sections:
Destination Builder Section
Purpose
Basic Information
Used to name the destination, describe it, and select destination type (URL or cookie).
Configuration
For serialized URL destinations:
• Contains base URL, secure URL, and delimiter that separates segments in the URL
string.
For non-serial URL destinations:
User Interface
Destination Builder Section
82
Purpose
• Not used. You provide URL details to individual segments in the Segment Mappings
section.
For cookie-based destinations:
• Contains cookie name, domain, size, expiration interval, data format, etc.
Segment Mappings
Lets you:
• Search for, add, and manage segments associated with all destination types.
• Set delivery priorities on individual segments (for cookie-based segments only).
Data Delivery Methods
You can send information to a destination by passing it in through a URL string, by writing to a browser cookie, or through
offline server-to-server data transfers. URL and cookie-based destinations transmit data synchronously, as a user takes action
on a page. Server-to-server data transmission is asynchronous and can occur long after a user has left the page. The delivery
type you select depends on your business requirements and how a particular data partner wants to, or can, receive data.
Data Delivery Methods in Destination Builder
Audience Management sends data to destinations in real time or by offline, asynchronous delivery methodologies.
Data Delivery Methods
You can send information to a destination by passing it in through a URL string, by writing to a browser cookie, or through
offline server-to-server data transfers. URL and cookie-based destinations transmit data synchronously, as a user takes action
on a page. Server-to-server data transmission is asynchronous and can occur long after a user has left the page. The delivery
type you select depends on your business requirements and how a particular data partner wants to, or can, receive data.
How to Choose a Data Delivery Method
Describes technical and business reasons for choosing a URL, cookie, or server-to-server destination.
Selecting a Data Delivery Type
Technical Considerations
Data delivery depends on how your data partner wants to, or can, receive destination information. Technical or engineering
constraints may prevent a destination from receiving data via URL, cookie, or server-to-server processes. Work with your
third-party partner to determine which method they can use.
Business Considerations
Business decisions for selecting one delivery method over another depend on the technical capabilities of your destination
partner and what you want to do with qualified user information. For example, technical constraints can limit your options if
a destination cannot receive data by a particular delivery method. However, if there are no technical issues, you can send
information based on how you want to take action on that data. URLs and cookie-based destinations work almost synchronously
with user actions on a page while server-to-server methods are good for building deep audience segments over time.
User Interface
83
Destination Types and Typical Uses
The examples in the following table can help you understand when to use a particular destination and the differences between
each type.
Destination Type
Typically Used When
Example
URL
You need to transfer data
immediately so a destination
can take action on a qualified
user right away.
Sending data from a ticket
• Transfers data about new
purchasing site. Use a URL or visitors only.
cookie destination to qualify
• Visitors must be seen again
user and immediately retarget.
to qualify for the segment.
• Immediate data transfer is
not required.
• Collecting data to build a
large audience pool of
qualified users.
Collecting data over time
• Transfers data about new and
(hours or days) to use it in a
previous site visitors.
campaign set to run at a later
• Visitors don't have to be seen
date.
again to qualify for other
segments.
Cookie
Server-to-server
Considerations
How to Create URL, Cookie, or Server-to-Server Destinations
Contains documentation that describes how to properly create a URL, cookie, or server-to-server destination in Destination
Builder.
Destination Builder Sections
When creating a destination, the Basic Information settings remain the same regardless of the destination type (URL or cookie).
However, features in the Configuration and Segment accordion panels contain different options for each destination type. The
following table lists the documents that explain how to set up the different destinations and describes these different features.
Setting Up Different Destination Types: A Guide to Task Documents
Destination Type
Refer To
• Basic Information Section Described
URL
• URL Configuration Settings Described
• Map Segments to a Serialized URL
• Map Segments to a Non-Serial URL
• Basic Information Section Described
Cookie
• Cookie Configuration Settings Described
• Add Segment Mappings to a Cookie-based Destination
Contact your Partner Solutions manager to set up a server-to-server destination.
Server-to-server
Note: Although you cannot create a server-to-server destination, you can manage
the segment mappings associated with this destination type.
User Interface
84
Provide Basic Information
Describes the required fields or steps in the Basic Information section you must complete to set up Auditude as a cookie-based
destination.
To complete the Basic Information section:
Basic Information Fields Defined
Field
Description
Name
Give the destination short, logical name that describes its
function or purpose. Avoid abbreviations and special characters.
Description
An optional field you can use for additional descriptive
information about the destination.
Type
Lets you create a URL or cookie-based destinations.
URL Configuration Settings Described
For a serialized URL, select the serialize checkbox, provide a base URL, a secure URL, and specify the location of the %ALIAS%
placeholder macro within the URL string. There are no configurable settings for a non-serial URL destination (click Save and
continue). After you complete this section, save and move on to the Segment Mappings sections.
Serial URL Configuration Settings Defined
Field
Description
Serialize checkbox
Lets you sends segment data (in a URL string) sequentially to a destination rather than
making multiple, separate calls. It is a more efficient way to transmit information to
your destination partner.
Base URL
Defines the foundation of a standard HTTP destination URL. This part of the destination
URL does not change.
Also, you need to place the %ALIAS%placeholder macro in the base URL.
Example: http://www.myCompany.com/?%ALIAS%...
Secure URL
Defines the foundation of a secure HTTPS destination URL. This part of the destination
URL does not change.
Also, you need to place the %ALIAS%placeholder macro in the base URL.
Example: https://www.myCompany.com/?%ALIAS%...
Delimiter
The symbol (usually a comma or semi-colon) that separates the segment variables in
the URL string. Get this information from your destination partner.
User Interface
85
Add Segment Mappings to a Serialized URL Destination
To add a segment to a serialized destination, locate it with the available search features in the segment mappings section. Click
Add and enter the mapping variable and optional flight dates. Click Add Mapping when done.
Field
Description
Search and Add Segments
A search feature that lets you find segments you want to add to a destination.
After finding a segment, click Add to open the Edit Mapping pop and complete
the mapping process.
Note: The search field auto-completes entries when it starts to recognize
key words in your segment name.
Mapping
A field in the Edit Mapping pop that holds an ID used by your destination
partner.
Publish from
Lets you set optional flight dates for the segment. When blank, the segment is
active immediately and does not expire.
Add Segment Mappings to a Non-serialized URL Destination
To add a segment to a non-serialized destination, locate it with the available search features in the segment mappings section.
Click Add and provide the destination URL (standard and secure) and optional flight dates. Click Add Mapping when done.
Field
Description
Search and Add Segments
A search feature that lets you find segments you want to add to a destination. After
finding a segment, click Add to open the Edit Mapping pop and complete the
mapping process.
Note: The search field auto-completes entries when it starts to recognize key
words in your segment name.
URL
A field in the Edit Mapping pop where you enter the destination's full HTTP URL.
Secure URL
A field in the Edit Mapping pop where you enter the destination's full HTTPS URL.
Publish from
Lets you set optional flight dates for the segment. When blank, the segment is active
immediately and does not expire.
Provide Cookie Details
Describes the required fields or steps in the Configuration section you must complete to set up Auditude as a cookie-based
destination.
User Interface
86
Note: AudienceManager writes encoded data to a destination cookie. For example, spaces are encoded as %20 and semicolons
as %3B.
To complete the Configuration section:
• Name the cookie aud.
• Name the key segs.
• Choose the Single Key option in the Data Format section.
• Select the Serialize checkbox and use a comma for the serial delimiter.
Cookie Configuration Settings Defined
Interface Element
Cookie Name
Cookie Domain
Max Size
Expire After
Publish Data To
Single-key
Multi-key
Description
Give the cookie short, logical name that describes its function or purpose. Avoid
abbreviations and special characters.
The domain the cookie belongs to.
Amount of data (in bytes) that the cookie can hold before the system applies segment
priorities to your data. Maximum size is 2048 bytes.
Defines how many days segment values are stored in the cookie. If the cookie expiration
value is set to 0, the cookie is immediately deleted. The 0 value should never be used
as a setting. If you leave this field empty in the UI, this setting allows the cookie to
persist forever or until someone deletes his or her cookies.
Lets you determine where you want to publish data to. This can be useful if your
company manages multiple domains. You can push data to all domains (default) or
include/exclude specific domains.
Select this data format option when your key-value data uses the same key to define
a different value (e.g., x=1&x=2).
Select this data format option when your key-value data uses different keys in the
key-value pair (e.g., x=1&y=2&z=3).
If you choose Multi-key, you must configure the following separator/delimiters:
• Key Value Separator
• Key Value Delimiter
Key Value Separator
Key Value Delimiter
Serialize
A symbol that separates keys and values in the key-value pair.
Select to pass in multiple values on a single key (e.g., x=1;2;3).
If you choose Serialize, you must configure the following delimiter:
User Interface
Interface Element
87
Description
• Serial Delimiter
Serial Delimter
Add Segment Mappings
Describes the required fields or steps in the Configuration section you must complete to set up Auditude as a cookie-based
destination.
To add a segment to a cookie destination, locate it with the available search features in the segment mappings section. Click
Add and provide the mapping values and optional flight dates. Click Add Mapping when done.
After a segment mapping is added to a destination, the change is pushed to our edge servers within 30 minutes to allow for user
targeting.
Segment Mappings Settings Defined
Field
Description
Search and Add Segments
A search feature that lets you find segments you want to add to a destination.
After finding a segment, click Add to open the Edit Mapping pop and complete
the mapping process.
Note: The search field auto-completes entries when it starts to recognize key
words in your segment name.
Mapping
Publish from
A field in the Edit Mapping pop where you enter the key-value pairs used by the
segment.
Lets you set optional flight dates for the segment. When blank, the segment is
active immediately and does not expire.
Add Segment Mappings to a Server-to-Server Destination
To add a segment to a server-to-server destination, locate it with the available search features in the segment mappings section.
Click Add and provide the mapping values and optional flight dates. Click Add Mapping when done.
Note: You can only manage server-to-server segment mappings. You cannot create a new server-to-server destination.
Contact Partner Solutions if you need to create a server-to-server destination.
Field
Description
Search and Add Segments
A search feature that lets you find segments you want to add to a destination.
After finding a segment, click Add to open the Edit Mapping pop and complete
the mapping process.
Note: The search field auto-completes entries when it starts to recognize
key words in your segment name.
User Interface
88
Field
Description
Mapping
A field in the Edit Mapping pop where you enter the key-value pairs used by the
segment.
Publish from
Lets you set optional flight dates for the segment. When blank, the segment is
active immediately and does not expire.
Destinations Reference
Concepts and other material related to destinations (macros, cache busting, serialization, key-value pairs, etc.).
Destinations Main Dashboard
The Destinations dashboard is a centralized workspace for managing destinations.
The Destinations main dashboard contains features and tools that help you:
• Create URL, Cookie, or Server-to-Server Destinations..
• Add existing destinations to a segment.
• Edit and delete destinations.
• See all your destinations in a table with sortable columns.
• Search for destinations by name.
Destination Serialization
A serialized destination combines multiple traits into a single string and sends that information to a destination.
Serialized data transmission helps improve efficiency because multiple traits fire sequentially, rather than in parallel. This
provides the destination server with enough time to receive, process, and return data before responding to additional requests.
Serialization helps maintain efficient data collection through reduced data calls.
Supported Destinations
In Audience Management, you can serialize and send data to just about any destination you want to work with. However, before
using this feature, you will need to know the destination URL and where to place some required or optional macros. Obtain this
information from your destination partner.
Destination Macros Defined
Describes the required and optional macros you can add to a destination URL. Destination macros define the location of traits
in a URL string and help prevent browsers from serving cached content.
When creating a URL destination, insert the following macros into the URL string:
Note: Check with your data/destination partner about proper macro placement within the destination URL.
Macro
Required
Explanation
%alias%
Yes
Defines the location of traits in a destination URL.
User Interface
89
Macro
Required
Explanation
%rnd%
No
Inserts a random number into the destination URL to prevent browsers from
serving cached content.
%timestamp%
No
Inserts a UNIX timestamp into the destination URL to prevent browsers from
serving cached content.
Cache Busting with Destination Macros
The %rnd% and %timestamp% macros insert unique values into a URL string to prevent browser caching.
Browsers cache (save) save frequently requested content in memory. When a page loads, saved content serves from the cache
rather than from a remote server. This process helps maintain efficient download times because data serves locally rather than
from another location. However, because caching does not require a server call, it can skew reporting by artificially lowering
the number of unique requests.
Cache Busting with %rnd% and %timestamp%
Cache busting prevents browsers from saving and reusing content. This technique uses code that inserts a random number or
time stamp into a URL string, which makes it look unique to the browser. As a result, each HTTP call is counted as a separate
request to the server. Forcing a new server call for each request helps maintain reporting accuracy and reduce discrepancies.
Audience Management provides two macros for cache busting:
• %rnd%: Inserts a random number into a URL.
• %timestamp%: Inserts the Unix date/time into a URL.
Comparing %rnd% and %timestamp%
Both macros prevent caching, but %rnd% may be more efficient. For example, with%timestamp%, if several users view a page
simultaneously they'll get the same date/time value. As a result, the URL is not unique and multiple calls are counted only once.
However, %rnd% generates a unique numeric value for each call (even when users see the same page simultaneously). This means
the URL string contains different values and is counted as unique.
Key-Value Pairs Explained
Defines and describes standard and serialized key-value pairs.
A key-value pair consists of two related data elements: A key, which is a constant that defines the data set (e.g., gender, color,
price), and a value, which is a variable that belongs to the set (e.g., male/female, green, 100). Fully formed, a key-value pair could
look like these:
• gender = male
• color = green
• price > 100
The following sections contain more information:
• Standard and Serialized Key-Value Pairs
• Keys, Delimiters, and Separators
• Standard and Serialized Key-Value Elements
Standard and Serialized Key-Value Pairs
Destinations accept key-value data in standard or serialized format. Standard formatting organizes data into separate key-value
pairs. Each key is stated explicitly, even when used again to define a different value. By contrast, serialized formatting condenses
User Interface
90
multiple values into one set defined by a single key. Also, in a serialized pair, a special indicator is used to separate the values
within the key-value set. Finally, standard and serialized key-values can contain single or multiple values. The following table
provides examples of standard and serial key-value formats.
Formatting
Single Key
Key-Value Pairs
Standard
x=1&x=2
x=1&x=2&y=3&y=4
Serialized
x=1;2
x=1;2&y=3;4
Keys, Delimiters, and Separators
When working with serialized data, you must specify the characters that separate values within and between the key-value pairs.
Elements in key-value pairs are defined as follows:
• Key: A unique identifier in the key-value pair.
• Value delimiter: Separates individual key-value pairs.
• Key-value separator: Separates a key from the values within a key-value pair.
• Serial separator: Separates individual values within serialized key-value pairs.
Standard and Serialized Key-Value Elements
Type
Example
Key
Key-Value
Separator
Key-Value
Delimiter
Serial Separator
Single key
x=1&x=2
x
=
&
n/a
;
(standard)
Key-value pairs
x=1&x=2&y=3&y=4 x, y
(standard)
Single key
x=1;2;3
x
n/a
x=1;2&y=3;4
x, y
&
(serial)
Key-value pairs
(serial)
get_aamCookie Code
Code required by DART Enterprise (and other destination types) to capture the Audience Management UUID value.
Define this function at the top of the page, ideally within the <head> codeblock.
<script type="text/javascript">
function get_aamCookie (c_name)
{
var i,x,y,ARRcookies=document.cookie.split(";");
for (i=0;i<ARRcookies.length;i++)
{
x=ARRcookies[i].substr(0,ARRcookies[i].indexOf("="));
y=ARRcookies[i].substr(ARRcookies[i].indexOf("=")+1);
x=x.replace(/^\s+|\s+$/g,"");
if (x==c_name)
{
return unescape(y);
}
}
User Interface
91
}
</script>
Derived Signals
A derived signal qualifies site visitors for additional traits based on a trait they've already seen. In other words, additional trait
qualification can be derived from a currently exhibited trait even if a user has never seen the new trait before.
Purpose of Derived Signals
In Audience Management, you can create a relationship between signals (or trait rules) passed in during an event call to other,
specified signals or traits. For example, assume an event call passes in a signal composed of the key-value "product = new_car"
(http://<domain alias>/event?product=new_car). Audience Management would connect that signal to any others
created with the derived signals tool. Although the associated signals can be any key-values you specify, they are most useful
when linked to existing signals already set up as TraitBuilder rules. For example, in the illustration below, when a user action
fires the signal "product = new car" that user can also qualify for traits defined by the target key and value signals.
Location of Derived Signals
Create and manage derived signals in Manage Data > Derived Signals from the sidebar navigation.
Create a Derived Signal
Information about creating a derived signal.
To create a derived signal
1. Select Derived Signals from the Manage Data menu.
2. Provide a:
• (Optional) Integration Code
• Source Key
• Source Value
• Target Key
• Target Value
3. Click Add Signal.
Edit a Derived Signal
Information about editing a derived signal.
To edit a derived signal
User Interface
92
1. Hover over the signal, then click Edit.
2. Make the required code, key, or value changes, then click Save.
Delete a Derived Signal
Information about deleting a derived signal.
To delete a derived signal
•
Hover over the signal, then click Delete.
Models
Build and manage the traits or segments used in algorithmic modeling. Model features are located in Manage Data > Models.
Models
A summary of algorithmic modeling in Audience Management. Describes how modeling works, benefits, and workflow.
Finding New Users With Algorithmic Modeling
Algorithmic modeling helps you discover new, unique audiences through automated data analysis. The process starts when you
select a trait or segment, a time interval, and first and third-party data sources. Your choices provide the inputs for the algorithmic
model. When the analytics process runs, it looks for eligible users based on shared characteristics from the selected population.
Upon completion, this data is available in Trait Builder where you can use it to create traits based on accuracy and reach.
Additionally, you can build segments that combine algorithmic traits with rules-based traits and add other qualification
requirements with Boolean expressions and comparison operators. Algorithmic modeling gives you a dynamic way to extract
value from all your available trait data.
Advantages
Some benefits of using Audience Management modeling include:
• Data accuracy: The algorithm runs regularly, which helps keep results current and relevant.
• Automation: You don't have to manage a large set of static rules. The algorithm will find audiences for you.
• Save time and reduce effort: With our modeling process you don't have to guess at what traits/segments may work or spend
time resources on campaigns to discover new audiences. The model can do this for you.
• Reliability: Modeling works with server-side discovery and qualification processes that evaluate your own data and selected
third-party data that you have access to. This means you don't have to see the visitors on your site to qualify them for a trait.
Workflow
Work in the Model and Traits section of the Audience Management user interface to build algorithmic models and traits. At
a high level, the workflow process involves the following:
• Select the baseline data you want the algorithm to evaluate. This includes a trait or segment, time range, and data sources (your
own data and third-party data you already have access to through Audience Management).
• Save your model. Once saved, algorithmic evaluation process runs automatically. Note, however, it can take up to 24 hours
for this process to complete. Audience Management sends you an email when the algorithm has finished and results are
available for trait creation.
• Build algorithmic traits in Trait Builder.
• Combine traits into segments in Segment Builder.
• Create and send segment data to a destination.
User Interface
93
TraitWeight
Describes the TraitWeight algorithmic discovery process.
TraitWeight Process Described
TraitWeight is a proprietary algorithm designed to help you discover new audience members automatically. It compares trait
data from your current traits and segments against all other first and third-party data that you have access to through Audience
Management.
Step 1: Build a Baseline for Trait Comparison
To build a baseline, TraitWeight measures at all the traits associated with an audience for a 30, 60, or 90 day interval. Next, it
ranks traits according to their frequency. The frequency count measures commonality. Traits that appear often are said to exhibit
high commonality, an important characteristic used to set a weighted score when combined with traits discovered in your
selected data sources.
Step 2: Find the Same Traits in the Data Source
After it builds a baseline for comparison, the algorithm looks for identical traits in your selected data sources. In this step,
TraitWeight performs a frequency count of all discovered traits and compares them to the baseline. However, unlike the baseline,
uncommon traits are ranked higher than those that appear more often. Rare traits are said to exhibit a high degree of specificity.
TraitWeight assesses combinations of common baseline traits and uncommon (highly specific) data source traits as more
influential or desirable than traits common to both data sets. Rare traits are more likely to represent new, unique users than
traits with high commonality across the board.
Step 3: Assign Weight
In this step, TraitWeight assigns a weight the results. Weight numerically ranks newly discovered traits in order of influence or
desirability. The weight scale runs from 0 to 1. Traits with weights close to 1 means they're more like the audience in your baseline
User Interface
94
population. Also, heavily weighted traits are valuable because they represent new, unique users who may behave similarly to
your established, baseline audience. Remember, TraitWeight considers traits with high commonality in the baseline and high
specificity in the compared data sources to be more valuable than traits common in each data set.
Step 4: Display and Work With Results
Audience Management displays your weighted model results in Trait Builder. When you want to build an algorithmic trait,
Trait Builder lets you create traits based on the weighted score generated by the algorithm during a data run. You can use these
results to build accurate traits, or compromise accuracy for reach to help expand audience size.
Update Schedule for Algorithmic Models and Traits
Creation and update schedules for new or existing algorithmic models and traits.
Algorithmic Model Creation and Update Schedule
Activity Type
Create or Clone a Model
Description
For new or cloned algorithmic models, the creation process runs once per day at:
• 10 am EST (November - March)
• 11 am EDT (March - November)
Models built or cloned after the creation deadline are processed the following day.
Update a Model
Existing models rerun at eight-day intervals from the creation day. For example, if
you create a model (by the deadline) on Monday, it updates the following Tuesday.
After the update on Tuesday, the model will update the following Wednesday, and
so on.
A model will rerun if it meets any of the following conditions:
• Its last run was not successful.
• It has run successfully before AND it has been at least eight days since its last run
AND the model has at least one active trait attached to it.
• Its last run produced no data AND it has been at least eight days since its last run.
Algorithmic Trait Creation and Update Schedule
Activity Type
Create a Trait
Update a Trait
Description
The trait creation process runs 3 times each day. Generally, new algorithmic traits
appear in the UI within 24 hours.
Existing traits are updated at 8 day intervals and follow the schedule for model
updates.
Models List View
The list view is a central workspace that helps you to create, review, and manage models.
The Models list page contains features and tools that help you:
User Interface
95
• Create new models.
• Manage existing models (edit, pause, delete, or clone).
• Search for models by name.
Models Summary View
The summary page displays model details such as name, reach/accuracy, processing history, and traits created from the model.
Click a model name from the list view to access its summary page. Summary sections include:
• Basic Information: Shows required and optional details specified when you created the model.
• Reach and Accuracy: Shows reach and accuracy data.
Model Builder
How to create an algorithmic model with Model Builder.
Build a Model
Describes the required and optional steps that let you create an algorithmic model in Model Builder.
Model Builder Section
Model Builder consists of the Basic Information and Configuration sections. To create a model, complete the required fields
in these two sections. Save your model to start the algorithm. Audience Management sends you an automated notification after
the first data run completes. After you receive the email, you can go to Trait Builder and create algorithmic traits.
Note:
• The modeling process runs only once if you create a model and do not build any traits with it.
• Build models from data sources that contain a meaningful amount of information. Models with insufficient data will run,
but they will not return results.
• Do not create models with other algorithmic traits or segments.
• The automated email notification is sent one time only (after the first data run).
Build a Model
To build a model, go to the Models section and click Create New Model and follow the steps below:
1. In the Basic Information section
• Name the model.
• (Optional) Provide a brief description about the model.
2. In the Configuration section:
• Click Browse All Traits or Browse All Segments to select a trait or segment you want to model against.
• Choose a 30, 60, or 90-day look-back period. This sets a time range for the model.
• The Trait Weight algorithm is selected by default.
• Select a data source from the Available Data list.
• Click Save when done.
Basic Information for Algorithmic Models
In Model Builder, the Basic Information settings let you create new or edit existing models. To create a new model, provide a
name and move on to the Configuration settings. The description field is optional.
User Interface
96
Field
Description
Name
Give your model a short, logical name that describes its function or purpose. Avoid
abbreviations, special characters, and accent marks.
Description
A field for additional descriptive information about the model.
Status
Activates or deactivates the model (active by default).
Configuration
In Model Builder, the Configuration section lets you add traits or segments to the model. In this section, select a baseline trait
or segment, a look-back period, and data from your first and third-party data sources.
Prerequisites: Complete the required fields in the Basic Information section first.
Field
Description
Select a Baseline Trait or Segment
Click the trait or segment button to see a list of all your traits or segments. Your
selected segment or trait becomes the baseline that the system algorithms use for
modeling.
Note: Do not create models with other algorithmic traits or segments.
Select Look Back Period
Sets a time range for the model. Based on your selection, the algorithm includes and
evaluates data from the previous 30, 60, or 90 days.
Select Algorithm
A this time, Model Builder works with our proprietary Trait Weight algorithm only.
Audience Management may add other algorithmic functions in subsequent releases.
Select Available Data
Lets you select the first and third-party data sources you want to use in the model.
Tags
Manage containers and scheduled tags with the Tag Insertion Manager (TIM).
Note: Tag Insertion Manager is a deprecated product. All new Audience Management users should be using Adobe Dynamic
Tag Manager.
Purpose of the Tag Insertion Manager
TIM helps manage data collection on your website. It is a key feature of Audience Management and consists of two core
components: JavaScript container code and a graphical user interface that helps you schedule third-party tags for deployment
on your website. TIM is used to:
• Create and manage containers in a secure user interface.
• Generate container code.
• Set up, run, and edit scheduled tags.
Where to Find TIM
TIM is located in Manage Data > Tags.
User Interface
97
The TIM Container
The Tag Insertion Manager (TIM) container is a mechanism for managing the code, pixels, and scripts that run and collect data
on your inventory.
Purpose of the TIM Container
The TIM container (also referred to as the container, or master tag) consists of a JavaScript code block that downloads TIM
code when your web page loads. Serving tags and scripts through the container lets your business teams manage data collection
and audience segmentation processes without involving your IT staff or web developers. Simply place the container code on
your website and manage data collection processes by adding/removing tags, traits, and scripts in TIM.
Container Hosting and Delivery
Audience Management uses Akamai technology to host and delivery the JavaScript container. Upon download, the container
inserts scheduled tags onto the page based on choices made previously when scheduling tags in TIM. The container can load
tags used for:
• Analytics
• Data acquisition
• Affiliate program tracking
• Counting/tracking site visitors
• Audience segmentation
Creating a TIM Container
This procedure describes how to create a new TIM container.
1. Go to Manage Data and click Tags.
User Interface
98
2. Click Add New Container. Name the container (required) and give it a useful description (optional).
Note: Avoid special characters (e.g., @, #, $, ~, etc.) when naming or describing the container.
3. Click Create Container
Editing a TIM container
This procedure describes how to edit an existing container. Editing a container lets you modify the container name and description.
1.
2.
3.
4.
From the Manage Data tab, click Tags.
Scroll through the container list or use the search feature to find your container.
Click Edit Container.
Change the container name or description and click Save Changes.
Generating TIM Container Code
This procedure describes how to generate TIM container code.
To create container code:
1. From the Manage Data tab, click Tags.
2. Search for the container you want to work with and click Get Code.
Note: Place the code adjacent to (or near) the closing </body> tag on your page. You can put the container on a
single page, or on all of the pages on your site.
Sample Container Code
Your container code could look similar to this:
<!-- Demdex Tag Insertion Manager -->
<script type="text/javascript">
var dexBaseURL=(("https:"==document.location.protocol) ?
"https://a248.e.akamai.net/demdex.download.akamai.com/<sampleDomainNameHere>/<ID>/"
:
"http://cdn.demdex.net/<sampleDomainNameHere>/<ID>/");
document.write(unescape("%3Cscript src='"+ dexBaseURL +
"demdex.js' type='text/javascript' %3E%3C/script%3E"));
</script>
<!-- End Demdex Tag Insertion Manager -->
Scheduled Tags
Scheduled tags are the actual pixels and data collection code that run on your inventory.
Purpose of Scheduled Tags
Scheduled tags perform various tasks from simple search term frequency counts to complex audience segmentation and data
collection/synchronization activities. You set up and manage scheduled tags in the Tag Insertion Manager (TIM).
Scheduled Tag Hosting and Delivery
Even though you traffic and manage data collection scripts in the Audience Management user interface, the tag provider hosts
and serves all your pixels or code. For example, ad tags are served by Audience Management and hosted by Akamai. Other tags,
such Analytics tags or third-party code, are hosted and served by Adobe or your third-party partner.
User Interface
99
Scheduling Tags with TIM
This procedure describes how to schedule tags. A scheduled tag is the actual code (traits, scripts, data collection code, etc.) served
by the container when your page loads.
You set up and mange scheduled tags in the Tag Insertion Manager (TIM). New tags, or changes to existing tags, start serving
in approximately 30 minutes. To schedule a new tag:
1. From the Manage Data tab click:
• Tags and find the container you want to add a scheduled tag to.
• Scheduled Tags (edit) for the selected container.
• Add a new one now or the Add new tag button.
2. Configure the tag:
• Provide a name (required) and a useful description (optional).
• Select pixels from the pixel list or enter your own code (JavaScript, IMG, or IFRAME only).
• To help reduce page load problems, select a page position for the tag.
Note: You can load pixels in the page <head>, but it is not recommended. Select Before close of bodyOn Load instead.
For more information, refer to the article on positioning scheduled tags the related concepts section below.
3. In the Set Tag Destination section, choose an option to determine where you want the tag to collect data on your site. The
table below describes the available destination options.
Select
To collect data
All available destinations
On all of your inventory, run-of-site.
(e.g., my_business.com)
Entire domain or section
On site-sections below the main page.
(e.g., my_business.com/section1.html)
Individual page
At the product page level only.
(e.g., my_business.com/section1/product1.html)
Match regular expression
By customizing tag placement with regular expressions.
(e.g., /cart/ inserts the tag anywhere your URL string contains that term.)
4. Schedule the tag.
Select start and end dates and click Save.
Scheduled Tag Positioning Explained
The Tag Insertion Manager lets you load tags in the page head or body. The following table explains these options.
Tag Execution Options Explained
User Interface
Tag execution option
Head
100
Loads tags
Simultaneously with all other page elements.
Note: Selecting this option may affect page load times.
Before close of body </body>
After most page elements finish loading. May execute tags while style sheets,
images, or frames are still loading. This is the default (recommended) option.
On load
After all page elements finish loading.
Tag Rules Options Explained
Tag rule
Tag rule loads scheduled tags on
All pages
All pages that have a container in the source code. This is the default, run-of-site
option.
Specific pages
Pages that contain, equal, or match all, or part, of a specified URL string. For
example, selecting match and the URL string
my_company.com/section1.html loads tags on the section1 page and
all subordinate pages only.
Editing Scheduled Tags
This procedure describes how to edit a scheduled tag.
To edit an existing scheduled tag:
1.
2.
3.
4.
From the Manage Data tab, click Tags.
Search for the container holding the scheduled tags you want to work with.
In the container's Scheduled Tag column, click Edit.
Click Edit again on the scheduled tag you want to change.
Visitor Profile Viewer
Use the Visitor Profile Viewer to display the current state of a user profile for the current browser, including its traits and
segments. You can also view the visitor profile for another Audience Management profile ID (UUID). The Visitor Profile Viewer
is helpful for troubleshooting purposes.
For each trait, you can view its SID, name, details about how visitor traits were realized (1st-party or 3rd party), the realization
date, and the frequency of realizations.
For each segment, you can view its SID, name, and the segment membership date. Note that there is a 12-hour delay before
segment-realization information displays in the user interface.
1. Click Tools > Visitor Profile Viewer.
User Interface
101
2. (Optional) Click the trait name to display that trait in the Trait Builder.
For more information, see Traits.
3. (Optional) Click the segment name to display that segment in the Segment Builder.
For more information, see Segments.
4. (Conditional) In the UUID box, specify another Audience Management profile ID, then click Refresh to view the traits and
segments for that user.
User Management
Create Audience Management users and assign them to groups.
Enterprise customers using Audience Management need one data management platform for all of their data, but must be able
to control the visibility of the different data elements to specific business units. You can accomplish this using group permissions
User Interface
102
Audience Management uses groups to assign permissions. Permissions are not assigned at the user level. Group permissions
are tied to objects (traits, segments, etc.) and to actions you can perform on those objects (edit, view, etc.).
Create Users
Create users in Audience Manager and specify user details, login status, and assign users to groups.
1. Click User Management > Users.
2. Click
to display the User Add page.
3. Under User Details, fill in the fields:
Username: Specify a unique username for Audience Management.
First Name: Specify the user's first name.
Last Name: Specify the user's last name.
Email Address: Specify the user's email address. Audience Management does not send regular notification to users. Audience
Manager administrators have access to users' email addresses and can manually email users as needed. For example, if a user
forgets his or her password, the email address specified in this field is used to send a temporary password and instructions
to reset the password.
Phone Number: Specify the user's phone number.
Is Admin: Specify if this user is an Audience Management administrator. Admin users can manage users (create, edit, etc.)
and groups (create, assign permissions, etc.). Non-admin users can control only their own user profiles, including editing
their email addresses and resetting their own passwords. For more information, see Edit Your Account Settings.
4. Under Login, select the desired status:
Active: Active users can access Audience Manager and have the permissions granted by group membership.
Deactivated: Deactivated users cannot access Audience Manager and do not have any permissions. If you deactivate users,
their user information remains in Audience Management and you can simple reactivate them, if necessary. If you remove
users, you must re-create them if they need to use Audience Management again in the future.
5. Under Assigned Groups, from the drop-down list, select the desired groups to which you want to assign this user.
For more information about groups and permissions, see Create Groups.
6. Click Save.
Create Groups
Create a new group. A group is a collection of users that you want to give a common set of Audience Management access rights
and permissions.
1. Click User Management > Groups.
2. Click
to display the Group Settings page.
3. Under Group Details, fill in the fields:
Name: Specify a descriptive name for the group. If you have many groups, a descriptive name helps you quickly locate groups.
Description: Specify the group's description. A good practice is to describe the group's purpose, such as the type of access
and permissions the group grants.
4. Under Group Members, from the Add Users drop-down list, select the desired users that you want to add to the group.
User Interface
103
Audience Management uses groups to assign permissions. When you create a group, you assign permissions to individual
objects by adding those objects to the group and then by specifying individual permissions for selected data sources, as
explained in Step 5 below.
You can also use Wild Card Permissions to grant access to all elements of a specific object type. Wild Card Permissions
give you greater flexibility. For example, if you add individual data source destinations (as explained in Step 5 below), you
explicitly set permissions for each existing source. If new destination data sources are added in the future, you must explicitly
configure permissions for those new sources. However, if you use Wild Card Permissions (as explained in Step 6 below),
as new destination data sources are added to Audience Management, users in the group automatically inherit permissions
for the newly added sources.
You can use a mix of both methods to assign permissions to objects. If you use both methods for the same object, the Wild
Card Permission settings take precedent.
5. (Conditional) Under Group Permissions, from the Add Object drop-down list, select the objects for which you want to
grant permissions.
Destination: In Audience Management, a destination is any third-party system (ad server, DSP, ad network, etc.) that you
want to share data with.
Select the desired destination data sources, then specify the access permissions that you want to grant for each data source:
Read, Write, Create, and Delete.
Segment: In Audience Management, a segment (or audience) is a set of users who share a set of common attributes and
qualify for related traits.
Select the desired destination data sources, then specify the access permissions that you want to grant for each data source:
Read, Write, Create, Delete, Map_To_Destinations, and Map_To_Models.
Trait: In Audience Management, a trait is a combination of one or more signals. A signal is the smallest data units in Audience
Management and are expressed a key-value pairs.
Select the desired trait data sources, then specify the access permissions that you want to grant for each data source: Read,
Write, Create, Delete, Map_To_Segments, Map_To_Models and Create_ALGO_Traits.
6. (Conditional) Select Wild Card Permissions to specify wild card permissions for Reports, Destinations, Segments, Tags,
Derived Signals, and Traits.
Click the desired tabs, then specify the desired permissions, which vary, depending on the selected tab.
7. Click Save Group.
Edit Your Account Settings
Non-admin users can edit their own profiles, including changing their email addresses and resetting their passwords.
Admin users can create users and add them to groups for permission purposes, as explained in Create Users and Create Groups
1.
In the Audience Management header, click .
2. Click Account Settings, then click Edit to display the My Account page.
3. In the Email Address field, specify your new email address, if necessary.
Audience Management does not send regular notification to users. Audience Manager administrators have access to users'
email addresses and can manually email users as needed. For example, if a user forgets his or her password, the email address
specified in this field is used to send a temporary password and instructions to reset the password.
4. To reset your password, specify your current password, specify the new password, then confirm the new password.
User Interface
Passwords must be:
• At least eight characters in length
• Contain at lease one uppercase character
• Contain at least one lowercase character
• Contain at least one number
• Contain at least one special character
• Begin and end with an alpha-numeric character
• Be different from your previous 12 passwords
5. Click Save.
For more information about passwords, see Password Requirements, Locked Accounts, and Forgotten Passwords.
104
API
105
API
APIs let you work programmatically with Audience Management.
Currently, these features are not supported by our APIs:
• General, Trend, and Interactive reports.
• Legacy Tag Insertion Manager (TIM) functionality.
REST APIs
RESTful APIs let you work programmatically with Audience Management.
The Audience Management REST API follows JavaScript Object Notation (JSON) standards for formatting sent and received
data. A principal advantage of JSON is that it helps make API queries easy to write, read, and parse by developers and machines.
Review the Getting Started material before working with these API methods.
Getting Started
Information about general requirements, authentication, optional query parameters, request URLs, and other references.
Requirements
Requirements and best practices for making requests with the Audience Management APIs.
Note the following when working with the API:
• All request parameters are required unless specified otherwise.
• Expect to send requests and receive responses as JSON objects.
• Specify content-type: application/jsonandaccept: application/json in your code.
• Server responses can contain requested data, a status code, or both.
• Replace italicized text in API documentation with a value, ID, or other variable data as required by the method you're working
with.
OAuth Authentication
The Audience Management REST API follows OAuth 2.0 standards for token authentication and renewal.
This section contains the following information:
• Password Authentication Workflow
• Refresh Token
• Authorization Code and Implicit Authentication
Password Authentication Workflow
Password Authentication is an easy and secure way to access the REST API. The following table outlines the workflow for
password authentication from a JSON client in your browser.
Note: As best practice, we recommend that you encrypt access and refresh tokens if you store them in a database.
API
Process Step
Request API Access
106
Description
Contact your Partner Solutions manager. The manager will provide you with an API client ID and
secret. The ID and secret authenticate you to the API.
Note: If you'd like to receive a refresh token, specify that when you request API access.
Request the Token
Pass in a token request with your preferred JSON client. When you build the request:
• Use a POST method to call https://api.demdex.com/oauth/token.
• Convert your client ID and secret to a base-64 encoded string. Separate the ID and secret with a
colon during the conversion process. For example, the credentials testId:testSecret convert
to dGVzdElkOnRlc3RTZWNyZXQ=.
• Pass in the HTTP headers Authorization:Basic <base-64 clientID:clientSecret>
and Content-Type: application/x-www-form-urlencoded. For example, your header
could look like this:
Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
Content-Type: application/x-www-form-urlencoded
• Set up the request body as follows:
grant_type=password&username=<your AudienceManager user name>&
password=<your AudienceManager password>
Receive the Token
The JSON response contains your access token. The response should look like this:
{
"access_token": "28fed402-eafd-456c-9341-ac753f25bbbc",
"token_type": "bearer",
"refresh_token": "b27122c0-b0c7-4b39-a71b-1547a3b3b88e",
"expires_in": 21922,
"scope": "read write"
}
The "expires_in" property represents the number of seconds until the access token expires. As
best practice, use short expiration times to limit exposure if the token is ever leaked.
Refresh Token
Refresh tokens renew API access after the original token expires. If requested, the response JSON in the password workflow
includes a refresh token. If you don't receive a refresh token, create a new one through the password authentication process.
You can also use a refresh token to generate a new token before the existing access token expires.
If your access token has expired, you receive a 401 Status Code and the following header in the response:
WWW-Authenticate: Bearer realm="oauth", error="invalid_token", error_description="Access token
expired: <token>"
The following table outlines the workflow for using a refresh token to create a new access token from a JSON client in your
browser.
API
Process Step
Request the New Token
107
Description
Pass in a refresh token request with your preferred JSON client. When you build the request:
• Use a POST method to call https://api.demdex.com/oauth/token.
• Convert your client ID and secret to a base-64 encoded string. Separate the ID and secret
with a colon during the conversion process. For example, the credentials
testId:testSecret convert to dGVzdElkOnRlc3RTZWNyZXQ=.
• Pass in the HTTP headers Authorization:Basic <base-64
clientID:clientSecret> and Content-Type:
application/x-www-form-urlencoded. For example, your header could look like
this:
Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
Content-Type: application/x-www-form-urlencoded
• In the request body, specify the grant_type:refresh_token and pass in the refresh
token you received in your previous access request. The request should look like this:
grant_type=refresh_token&refresh_token=b27122c0-b0c7-4b39-a71b-1547a3b3b88e
Receive the New Token
The JSON response contains your new access token. The response should look like this:
{
"access_token": "4fdfc261-2ffc-4fb7-8dbd-64221714c45f",
"token_type": "bearer",
"refresh_token": "295fa487-1825-4caa-a715-80b81ac17dae",
"expires_in": 21922,
"scope": "read write"
}
Authorization Code and Implicit Authentication
The Audience Management REST API supports other access methods such as authorization code and implicit authentication.
See the OAuth 2.0 Authorization Framework (RFC 6749) for additional details about these authentication models.
Make Authenticated API Requests
Requirements for calling API methods after you receive an authentication token.
To make calls against the available API methods:
• In the HTTP header, set Authorization: Bearer <token>.
• Call the required API method.
Optional Query Parameters
Set the optional parameters available to methods that return all properties for an object.
You can use these optional parameters with API methods that return all properties for an object. Set these options in the request
string when passing that query in to the API.
Parameter
Description
page
Returns results by page number. Numbering starts at 0.
pageSize
Sets the number of response results returned by the request (10 is default).
API
108
Parameter
Description
sortBy
Sorts and returns results according to the specified JSON property.
descending
Sorts and returns results in descending order. Ascending is default.
search
Returns results based on the specified string you want to use as a search parameter. For
example, let's say you want to find results for all models that have the word "Test" in
any of the value fields for that item. Your sample request could look like this:
GET https://api.demdex.com/v1/models/?search=Test.
You can search on any value returned by a "get all" method.
folderId
Returns all the IDs for traits inside the specified folder. Not available to all methods.
permissions
Returns a list of segments based on the specified permission. READ is default. Permissions
include:
• READ: Return and view information about a segment.
• WRITE: Use PUT to update a segment.
• CREATE: Use POST to create a segment.
• DELETE: Delete a segment. Requires access to underlying traits, if any. For example,
you'll need rights to delete the traits that belong to a segment if you want to remove
it.
Specify multiple permissions with separate key-value pairs. For example, to return a list
of segments with READ and WRITE permissions only, pass in "permissions":"READ",
"permissions":"WRITE".
includePermissions
(Boolean) Set to true to return your permissions for the segment. Default is false.
A Note About Page Options
When page information is not specified, the request returns plain JSON results in an array. If page information is specified, then
the returned list is wrapped in a JSON object that contains information about the total result and current page. Your sample
request using page options could look similar to this:
GET https://api.demdex.com/v1/models/?page=1&pageSize=2&search=Test
API URLs
URLs for requests, staging and production environments, and versions.
This section contains the following information:
• Request URLS
• Environments
• Versions
Request URLS
The following table lists the request URLs used to pass in API requests, by method.
API
109
API Methods
Request URL
Algorithmic Modeling
https://api.demdex.com/v1/models/
Data Source
https://api.demdex.com/v1/datasources/
Derived Signals
https://api.demdex.com/v1/signals/derived/
Destinations
https://api.demdex.com/v1/destinations/
Domains
https://api.demdex.com/v1/partner-sites/
Folders
• Traits: https://api.demdex.com/v1/folders/traits/
• Segments: https://api.demdex.com/v1/folders/segments/
Schema
https://api.demdex.com/v1/schemas/
Segments
https://api.demdex.com/v1/segments/
Traits
https://api.demdex.com/v1/traits/
Trait Types
https://api.demdex.com/v1/customer-trait-types
Taxonomy
https://api.demdex.com/v1/taxonomies/0/
Environments
The Audience Management APIs provide access to different working environments. These environments help you test code
against separate databases without affecting live, production data. The following table lists the available API environments and
corresponding resource hostnames.
Environment
Hostname
Production
https://api.demdex.com/...
Sandbox
https://sandbox-api.demdex.com/...
Note: We refresh the sandbox environment every weekend with the production data set. You should be able to use your
production account credentials to log in based on your account a week prior.
Versions
New versions of these APIs are released on a regular schedule. A new release increments the API version number. The version
number is referenced in the request URL as v<version number> as shown in the following example:
https://<host>/v1/...
Response Codes Defined
HTTP status codes and response text returned by the Audience Management REST API.
Response code ID
Response text
Definition
200
OK
The request processed successfully. Will return expected content or data
if required.
201
Created
The resource was created. Returns for PUT and POST requests.
API
110
Response code ID
Response text
Definition
204
No Content
The resource has been deleted. The response body will be blank.
400
Bad Request
The server did not understand the request. Usually due to malformed
syntax. Check your request and try again.
403
Forbidden
You do not have access to the resource.
404
Not Found
The resource could not be found for the specified path.
409
Conflict
The request could not be completed due to a conflict with the state of
the resource.
500
Server Error
The server encountered an unexpected error that prevented it from
fulfilling the request.
Algorithmic API Methods
Methods that let you work programmatically with algorithmic modeling features.
Create a New Model
A POST method that lets you create a new algorithmic model.
Request
POST https://api.demdex.com/v1/models/
Sample Request
All request values are required unless otherwise indicated.
{
"name" : "New model",
"description" : "Test Model",
"dataSources" : [<data_provider_id_1>, <data_provider_id_2>],
"sid" : 8,
"algoTypeId" : <Algorithm ID. Currently, only ID 1 is available>,
"lookBackPeriod" : <Specify 30, 60, or 90 days>
}
Sample Response
{
"algoModelId": 1394,
"pid": 1099,
"name": "New model",
"description": "Test Model",
"algoTypeId": 1,
"intervalSeconds": 86400,
"lookBackPeriod": 30,
"crUID": 3,
"upUID": 3,
"status": 1,
"processingStatus": 0,
"createTime": 1346092322000,
"algoModelVersion": 0,
"dataSources": [size(2)
3,
4
],
"sid": 8,
"latestRunTS": 10000,
API
111
"baselineTraitType": 3,
"updateTime": 1346092322000
}
Update a Model
A PUT method that lets you revise the model's name, description, and status.
Request
PUT https://api.demdex.com/v1/models/<model-id>/
Sample Request
All request values are required unless otherwise indicated. Model status settings include active and inactive only.
{
"name" : "New name",
"description" : "Revised description",
"status" : "active",
"algoTypeId":1,
"dataSources":[3,4},
"sid":8
"lookBackPeriod":90
}
Sample Response
{
"algoModelId": 1394,
"pid": 1,
"name": "New name",
"description": "Revised description",
"algoTypeId": 1,
"intervalSeconds": 86400,
"lookBackPeriod": 30,
"crUID": 3,
"upUID": 3,
"status": 1,
"processingStatus": 0,
"createTime": 1346092322000,
"algoModelVersion": 0,
"dataSources": [size(2)
3,
4
],
"sid": 8,
"latestRunTS": 10000,
"baselineTraitType": 3,
"updateTime": 1346092322000
}
Delete a Model
A DELETE method that removes a model from your collection.
Request
DELETE https://api.demdex.com/v1/models/<model-id>
Sample Response
Returns response code 204 No Content if successful. Returns 400 Bad Request if there are any active traits created with
this model and returns those trait IDs in an array. Remove traits from the model (or delete them) before you delete a model.
API
112
Delete Models
A POST method that lets you bulk delete multiple models.
Request
POST https://api.demdex.com/v1/models/bulk-delete/
Sample Request
In the request body, pass in a JSON array that includes the model IDs you want to delete.
[
111,
222
]
Sample Response
Returns 204 No Content.
Return Properties for an Algorithm
A GET method that returns ID, name, and description for the available algorithms. Currently, TraitWeight (ID 1) is the only
available algorithm.
Request
GET https://api.demdex.com/v1/algorithms/
Sample Response
A successful response returns response code 200 OK and the list of algorithm IDs, name, and a brief description.
[
{
"algoTypeId": 1,
"name": "Trait Weight",
"description": "Trait Weight"
}
]
Return Properties for an Algorithm by ID
A GET method that returns algorithm details (ID, name, and description) based on the passed in algorithm ID. Currently,
TraitWeight (ID 1) is the only available algorithm.
Request
GET https://api.demdex.com/v1/algorithms/<algotype-id>/
Sample Response
A successful response returns response code 200 OK and the algorithm ID, name, and a brief description.
{
"algoTypeId": 1,
"name": "TF-IDF",
"description": "TF-IDF"
}
Return Properties for all Models
A GET method that returns details about all your models.
API
113
Request
GET https://api.demdex.com/v1/models/
Optional Query Parameters
You can use these optional parameters with API methods that return all properties for an object. Set these options in the request
string when passing that query in to the API. See Optional Parameters.
Parameter
Description
page
Returns results by page number. Numbering starts at 0.
pageSize
Sets the number of response results returned by the request (10 is default).
sortBy
Sorts and returns results according to the specified JSON property.
descending
Sorts and returns results in descending order. Ascending is default.
search
Returns results based on the specified string you want to use as a search parameter. For
example, let's say you want to find results for all models that have the word "Test" in any of
the value fields for that item. Your sample request could look like this:
GET https://api.demdex.com/v1/models/?search=Test.
You can search on any value returned by a "get all" method.
Sample Request
GET https://api.demdex.com/v1/models/?page=1&pageSize=2&search=Test
Sample Response
["total": 43,
"page": 1,
"pageSize": 2,
"list": [
{
"algoModelId": 698,
"pid": 1099,
"name": "abcd",
"description": "Test Model description 1345087373",
"algoTypeId": 1,
"intervalSeconds": 86400,
"lookBackPeriod": 30,
"crUID": 3,
"upUID": 3,
"status": 1,
"processingStatus": 0,
"createTime": 1345661622000,
"algoModelVersion": 0,
"dataSources": [
3,
4
],
"sid": 8,
"latestRunTS": 10000,
"baselineTraitType": 3,
"updateTime": 1345661622000
},
{
"algoModelId": 738,
"pid": 1,
"name": "abcd upda2ted trait",
"description": "Test description",
API
114
"algoTypeId": 1,
"intervalSeconds": 86400,
"lookBackPeriod": 30,
"crUID": 3,
"upUID": 3,
"status": 1,
"processingStatus": 0,
"createTime": 1345669555000,
"algoModelVersion": 0,
"dataSources": [
3,
4
],
"sid": 8,
"latestRunTS": 10000,
"baselineTraitType": 3,
"updateTime": 1345669555000
}
]
Return Properties for a Model by ID
A GET method that returns algorithmic model details based on the passed in model ID.
Request
GET https://api.demdex.com/v1/models/<model-id>
Sample Response
A successful request returns details for the model. An unsuccessful request throws an exception and related error code.
{
"algoModelId": 16,
"pid": 1099,
"name": "newmodel78",
"description": "descriptions is in the name",
"algoTypeId": 1,
"intervalSeconds": 864000,
"lookBackPeriod": 30,
"crUID": 3,
"upUID": 3,
"status": 1,
"processingStatus": 0,
"createTime": 1344969143000,
"algoModelVersion": 0,
"dataSources": [
4
],
"sid": 8,
"latestRunTS": 10000,
"baselineTraitType": 3,
"updateTime": 1344969143000
}
Return Properties for Your Most Accurate Traits
A GET method that returns a list of your most influential (accurate) traits.
Request
GET https://api.demdex.com/v1/models/<model-id>/runs/latest/traits/
Optional Query Parameters
API
115
You can use these optional parameters with API methods that return all properties for an object. Set these options in the request
string when passing that query in to the API. See also Optional Parameters.
Parameter
Description
page
Returns results by page number. Numbering starts at 0.
pageSize
Sets the number of response results returned by the request (10 is default).
sortBy
Sorts and returns results according to the specified JSON property.
descending
Sorts and returns results in descending order. Ascending is default.
search
Returns results based on the specified string you want to use as a search parameter. For
example, let's say you want to find results for all models that have the word "Test" in any of
the value fields for that item. Your sample request could look like this:
GET https://api.demdex.com/v1/models/?search=Test.
You can search on any value returned by a "get all" method.
folderId
Returns all the IDs for traits inside the specified folder. Not available to all methods.
Sample Response
{
"total": 2,
"page": 0,
"pageSize": 10,
"list": [
{
"sid": 914,
"pid": 1,
"name": "sample rule",
"description": "hello world, i am your rule.. err",
"traitRuleVersion": 0,
"ttl": 0,
"crUID": 3,
"upUID": 3,
"createTime": 1346790825000,
"updateTime": 1346790825000,
"dataSourceId": 3,
"folderId": 10,
"traitType": "RULE_BASED_TRAIT",
"uniques7Day": 213930,
"uniques14Day": 415599,
"uniques30Day": 770717,
"uniques60Day": 9,
"count7Day": 657,
"count14Day": 626,
"count30Day": 5201,
"count60Day": 149,
"weight": 67,
"rank": 1
},
{
"sid": 9,
"pid": 1,
"name": "trait2",
"description": "new trait 2",
"comments": "",
"integrationCode": "",
"traitRule": "",
"traitRuleVersion": 0,
"ttl": 0,
API
116
"crUID": 3,
"upUID": 3,
"createTime": 1344277873000,
"updateTime": 1344277873000,
"type": 1,
"dataSourceId": 1,
"folderId": 10,
"traitType": 3,
"uniques7Day": 113632,
"uniques14Day": 210777,
"uniques30Day": 393718,
"uniques60Day": 77,
"count7Day": 85502,
"count14Day": 977684,
"count30Day": 3755,
"count60Day": 18517223,
"weight": 37,
"rank": 2
}
]
}
Return Accuracy and Reach Values for a Model
A GET method that returns accuracy and reach values for your algorithmic model.
Request
GET https://api.demdex.com/v1/models/<model-id>/runs/latest/stats/
Sample Response
[
{
"AccuracyValue": 0.12,
"ReachValue": 0
},
{
"AccuracyValue": 0.18,
"ReachValue": 0
},
{
"AccuracyValue": 0.19,
"ReachValue": 23232
},
{
"AccuracyValue": 0.28,
"ReachValue": 33432
}
]
Return Processing Timestamp
A GET method that returns an array of UNIX time stamps (UTC) of successful data runs for your model.
Request
GET https://api.demdex.com/v1/models/<model-id>/processing-history/
Sample Response
[
102032939, 1223030409, 1346236373
]
API
117
Data Integration Library API Methods
Methods that let you work programmatically with the Data Integration Library (DIL).
Return Versions for DIL
A GET method that returns a list of versions ordered from oldest to newest.
Request
GET https://api.demdex.com/v1/dil/
Sample Response
A successful request returns response code ["4.0", "4.1"] as shown below.
["4.0", "4.1"]
Return JSON Schema for Version
A GET method that returns the JSON schema for the version. Supports using alias LATEST for version to get the latest version
of DIL.
Request
GET https://api.demdex.com/v1/dil/<version>
Sample Response
A successful request returns response code ["4.0", "4.1"] and data as shown below.
{
"type": "object",
"$schema": "http://json-schema.org/draft-03/schema",
"required": true,
"additionalProperties": false,
"properties": {
"core": {
"id": "core",
"required": true,
"type": "object",
"properties": {
"code": {
"type": "boolean",
"required": true,
"id": "code"
},
"instanceVariable": {
"type": "string",
"id": "instanceVariable",
"required": false
},
"create": {
"type": "object",
"id": "create",
"required": false,
"properties": {
"initConfig": {
"additionalProperties": false,
"type": "object",
"id": "initConfig",
"required": true,
"properties": {
"declaredId": {
"id": "declaredId",
"required": false,
API
118
"type": "object",
"additionalProperties": false,
"properties": {
"dpid": {
"id": "dpid",
"required": true,
"type": "string"
},
"dpuuid": {
"id": "dpuuid",
"required": true,
"type": "string"
}
}
},
"containerNSID": {
"type": "number",
"id": "containerNSID",
"required": false
},
"disableDestinationPublishingIframe": {
"type": "boolean",
"id": "disableDestinationPublishingIframe",
"required": false
},
"enableErrorReporting": {
"type": "boolean",
"id": "enableErrorReporting",
"required": false
},
"iframeAkamaiHTTPS": {
"type": "boolean",
"id": "iframeAkamaiHTTPS",
"required": false
},
"iframeAttachmentDelay": {
"type": "number",
"id": "iframeAttachmentDelay",
"required": false
},
"mappings": {
"type": "object",
"id": "mappings",
"required": false,
"additionalProperties": {
"type": "string"
}
},
"removeFinishedScriptsAndCallbacks": {
"type": "boolean",
"id": "removeFinishedScriptsAndCallbacks",
"required": false
},
"uuidCookie": {
"type": "object",
"id": "uuidCookie",
"additionalProperties": false,
"required": false,
"properties": {
"days": {
"type": "number",
"id": "days",
"required": false
},
"domain": {
"type": "string",
"id": "domain",
"required": false
},
API
119
"name": {
"type": "string",
"id": "name",
"required": true
},
"path": {
"type": "string",
"id": "path",
"required": false
},
"secure": {
"type": "boolean",
"id": "secure",
"required": false
}
}
},
"visitorService": {
"type": "object",
"id": "visitorService",
"required": false,
"properties": {
"namespace": {
"type": "string",
"id": "namespace",
"required": true
}
}
}
}
}
}
}
}
},
"options": {
"id": "options",
"type": "object",
"required": false,
"properties": {
"minify": {
"id": "minify",
"required": false,
"type": "boolean"
}
}
},
"include": {
"type": "object",
"id": "include",
"required": false,
"properties": {
"modules": {
"type": "object",
"id": "modules",
"required": false,
"additionalProperties": false,
"properties": {
"GoogleAnalytics": {
"type": "object",
"id": "GoogleAnalytics",
"required": false,
"properties": {
"code": {
"id": "code",
"type": "boolean",
"required": true
}
}
API
120
},
"Peer39": {
"type": "object",
"id": "Peer39",
"required": false,
"properties": {
"code": {
"id": "code",
"type": "boolean",
"required": true
}
}
},
"SiteCatalyst": {
"type": "object",
"id": "SiteCatalyst",
"required": false,
"additionalProperties": false,
"properties": {
"code": {
"type": "boolean",
"id": "code",
"required": true
},
"init": {
"type": "object",
"id": "init",
"required": false,
"additionalProperties": false,
"properties": {
"siteCatalystInstance": {
"type": "string",
"id": "siteCatalystInstance",
"required": true
},
"dilInstance": {
"type": "string",
"id": "dilInstance",
"required": true
},
"trackedVariables": {
"id": "trackedVariables",
"required": false,
"type": "object",
"properties": {
"iteratedNames": {
"type": "array",
"id": "iteratedNames",
"required": false,
"items": {
"type": "object",
"id": "0",
"required": true,
"properties": {
"maxIndex": {
"type": "number",
"id": "maxIndex",
"required": true
},
"name": {
"type": "string",
"id": "name",
"required": true
}
}
}
},
"names": {
"type": "array",
API
121
"additionalItems": false,
"id": "names",
"required": false,
"items": [
{
"type": "string",
"required": true
},
{
"type": "string",
"required": false
},
{
"type": "string",
"required": false
},
{
"type": "string",
"required": false
},
{
"type": "string",
"required": false
},
{
"type": "string",
"required": false
},
{
"type": "string",
"required": false
},
{
"type": "string",
"required": false
},
{
"type": "string",
"required": false
}
]
}
}
}
}
}
}
}
}
},
"tools": {
"type": "object",
"id": "tools",
"required": false,
"additionalProperties": false,
"properties": {
"getMetaTags": {
"type": "boolean",
"id": "getMetaTags",
"required": false
},
"getSearchReferrer": {
"type": "boolean",
"id": "getSearchReferrer",
"required": false
},
"decomposeURI": {
"type": "boolean",
"id": "decomposeURI",
API
122
"required": false
}
}
}
}
}
}
}
Generate DIL
A GET method that generates DIL based on passed in request body using the specified version of DIL. If the alias LATEST is
used for version in the URL, the latest version of DIL is generated.
Request
POST https://api.demdex.com/v1/dil/<version>/generate
Sample Request
{
core: {
code: true,
instanceVariable: 'dil_instance',
create: {
initConfig: {
declaredId: {
dpid: '159',
dpuuid: '456'
},
containerNSID: 81,
disableDestinationPublishingIframe: false,
enableErrorReporting: false,
iframeAkamaiHTTPS: false,
iframeAttachmentDelay: 575,
mappings: {
c_k1: 'd_k1',
c_k2: 'd_k2'
},
removeFinishedScriptsAndCallbacks: false,
uuidCookie: {
days: 12,
domain: 'adobe.com',
name: 'adobe_did',
path: '/',
secure: false
},
visitorService: {
namespace: 'demofirst'
}
}
}
},
options: {
minify: true
},
include: {
modules: {
GoogleAnalytics: {
code: true
},
Peer39: {
code: true
},
SiteCatalyst: {
code: true,
init: {
siteCatalystInstance: 'sc_instance',
API
123
dilInstance: 'dil_instance',
trackedVariables: {
iteratedNames: [{
name: 'prop',
maxIndex: 5
}, {
name: 'pev',
maxIndex: 3
}],
names: ['pageName', 'channel', 'campaign', 'products', 'events', 'spe',
'spev1', 'spev2', 'spev3']
}
}
}
},
tools: {
getMetaTags: true,
getSearchReferrer: true,
decomposeURI: true
}
}
}
initConfig can consist of the following:
Name
Type
Description
partner
String
Required. Partner name as provided by Audience
Management.
visitorService
Object
containerNSID
Integer
Optional. Customer NSID. Default is 0.
disableDeclaredUUIDCookie
Boolean
Optional. False by default, which means Audience
Management sets a cookie in the partner's domain (sets
a first party cookie).
disableDestinationPublishingIframe
Boolean
Optional. If true, will not attach the destination
publishing IFRAME to the DOM or fire destinations.
Default is false.
iframeAkamaiHTTPS
Boolean
Optional. Specifies if the destination publishing template
should use Akamai for HTTPS connections. Enabled
on a per-partner basis.
iframeAttachmentDelay
Integer
Optional. Specifies the delay interval (in milliseconds)
before attaching the destination publishing IFRAME to
the DOM.
Required if Visitor ID functionality is present on the
page. See visitorService Properties. Released with v2.9.
Default delay interval is 500 milliseconds.
When disableDestinationPublishingIframe
is true, then:
• The IFRAME is not attached to the DOM.
• This parameter does not apply.
uuidCookie
Object
Sets a cookie with the unique user ID returned from
Audience Management. See uuidCookie Properties.
Released with v2.6.
API
124
Name
Type
Description
enableErrorReporting
Boolean
Optional. Set to true to enable error reporting for all
DIL instances on the page. Works with Boolean true
only.
removeFinishedScriptsAndCallbacks
Boolean
Optional. Removes scripts and callbacks. Default is
False. Applies to the current DIL instance only.
Released with v3.3.
mappings
Object
Associates the value from one key-value pair to another.
See Map Key Values to Other Keys. Released with v2.4.
declaredId
Object
Optional. Sends Declared ID variables on every event
call to Audience Management.
delayAllUntilWindowLoad
Boolean
Optional. If true, defers all requests (IFRAME, event
calls, ID sync, and destinationing) from executing until
the Page Load event fires. Default is false.
Sample Response
A successful update returns response code 201 created along with the DIL JavaScript code.
Data Source API Methods
API methods that let you manage data sources associated with your account.
Create a New Data Source
A POST method that lets you create a new data source in your account with the structure specified by the request body. The data
source will be associated with the authenticated user's pid.
Request
POST https://api.demdex.com/v1/datasources/
Sample Request
The name and status values are required. The other values are optional.
{
"name": "TARGUSInfo 3rd Party",
"defaultDataSyncType": "FTP",
"status": "ACTIVE",
"outboundS2S": false,
"containerIDs": [],
"description": "TARGUSInfo 3rd Party Data (TARGUSInfo Owned)",
"inboundS2S": true,
"allowDataSharing" : true,
"useAudienceManagerVisitorID" : true,
"marketingCloudVisitorIdVersion" : 0,
"uniqueSegmentIntegrationCodes : true,
"uniqueTraitIntegrationCodes" : true,
"idType" : "COOKIE" | "MOBILE" | "CROSS_DEVICE"
}
Sample Response
A successful response returns 201 Created.
{
"name": "TARGUSInfo 3rd Party",
"defaultDataSyncType": "FTP",
API
125
"status": "ACTIVE",
"pid": 343,
"pcsWrite": true,
"outboundS2S": false,
"containerIDs": [],
"description": "TARGUSInfo 3rd Party Data (TARGUSInfo Owned)",
"inboundS2S": true,
"integrationCode" : "",
"dataSourceId": 343
"allowDataSharing" : true,
"useAudienceManagerVisitorID" : true,
"marketingCloudVisitorIdVersion" : 0,
"uniqueSegmentIntegrationCodes" : true,
"uniqueTraitIntegrationCodes" : true,
"idType" : "COOKIE" | "MOBILE" | "CROSS_DEVICE"
}
Note that you cannot edit the "uniqueTraitIntegrationCodes" and "uniqueSegmentIntegrationCodes" parameters
after creating a new data source. The default values for both of these parameters is "false." If you specify an "integrationCode",
it must be unique across all data sources for the partner.
Acceptable Values for Enumeration Properties
status: The only currently supported status is active.
defaultDataSyncType: FTP or HTTP.
Update a Data Source
A PUT method that lets you update a data source with the structure specified by the request body.
Request
PUT https://api.demdex.com/v1/datasources/<dataSourceId>/
Sample Request
{
"name": "TARGUSInfo 3rd Party",
"defaultDataSyncType": "FTP",
"status": "ACTIVE",
"outboundS2S": false,
"containerIDs": [],
"description": "TARGUSInfo 3rd Party Data (TARGUSInfo Owned)",
"inboundS2S": true,
"dataSourceId": 342
"allowDataSharing" : true,
"useAudienceManagerVisitorID" : true
"marketingCloudVisitorIdVersion" : 0,
"idType" : "COOKIE" | "MOBILE" | "CROSS_DEVICE"
}
Sample Response
A successful response returns 200 OK.
{
"name": "TARGUSInfo 3rd Party",
"defaultDataSyncType": "FTP",
"status": "ACTIVE",
"pid": 343,
"pcsWrite": true,
"outboundS2S": false,
"integrationCode" : "",
"containerIDs": [],
"description": "TARGUSInfo 3rd Party Data (TARGUSInfo Owned)",
"inboundS2S": true,
API
126
"dataSourceId": 342
"allowDataSharing" : true,
"useAudienceManagerVisitorID" : true
"marketingCloudVisitorIdVersion" : 0,
"idType" : "COOKIE" | "MOBILE" | "CROSS_DEVICE"
}
Acceptable Values for Enumeration Properties
status: The only currently supported status is active.
defaultDataSyncType: FTP or HTTP.
idType is a read-only parameter. You can not update it.
Delete a Data Source
A DELETE method that lets you delete a data source.
Request
DELETE https://api.demdex.com/v1/datasources/<dataSourceId>
Sample Response
Returns response code 204 No Content if successful, otherwise returns 409 Conflict.
Delete Multiple Data Sources in Bulk
A POST method that lets you bulk delete multiple data sources.
Request
POST https://api.demdex.com/v1/datasources/bulk-delete/
Sample Response
In the request body, pass in a JSON array that includes the data source IDs you want to delete.
[
111,
222
]
Returns 204 No Content if successful.
Return Properties for a Data Source
A GET method that returns details about a specific data source.
Request
GET https://api.demdex.com/v1/datasources/<dataSourceId>
Sample Response
A successful response returns and data as shown in the sample below. Returns 200 OK or 404 Not found if the data provider
ID is not found.
{
"name": "TARGUSInfo 3rd Party",
"defaultDataSyncType": "FTP",
"status": "ACTIVE",
"pid": 343,
"pcsWrite": true,
"outboundS2S": false,
API
127
"containerIDs": [],
"description": "TARGUSInfo 3rd Party Data (TARGUSInfo Owned)",
"integrationCode" : "",
"inboundS2S": true,
"dataSourceId": 342
"allowDataSharing" : true,
"useAudienceManagerVisitorID" : true,
"marketingCloudVisitorIdVersion" : 0,
"idType" : "COOKIE" | "MOBILE" | "CROSS_DEVICE"
}
Acceptable Values for Enumeration Properties
status: The only currently supported status is active.
defaultDataSyncType: FTP or HTTP.
Return Properties for All Data Sources
A GET method that returns details about all your data sources.
Request
GET https://api.demdex.com/v1/datasources/
Optional Query Parameters
The following parameters can be used in combination with each other, with the exception of objectType. You can combine
objectType only with includePermissions.
Parameter
Description
search
String. Search for value in name, description, integrationCode, and
dataSourceId properties.
sortBy
String. Property by which to sort.
descending
Boolean. True if results are in descending order.
page
Integer. Page to view.
pageSize
Integer. Size of page.
modelingEnabled
Boolean. Return only data sources with modeling enabled.
firstPartyOnly
Boolean. Return only data that belong to the logged-in partner.
inboundOnly
Boolean. Filter data sources with Inbound = true.
outboundOnly
Boolean. Filter data sources with Outbound = true.
integrationCode
String. Filter on input integration code.
API
128
Parameter
Description
objectType
String. Lists the data providers with permissions for RBAC. Acceptable values:
"segment" and "trait."
includePermissions
Boolean. If True, returns the data providers with available permissions on them.
Sample Request
GET https://api.demdex.com/v1/datasources/?firstPartyOnly=true&modelingEnabled=true
Sample Response
The response returns 200 OK and data in an array as shown below.
[
{
"name": "33Across",
"defaultDataSyncType": "FTP",
"status": "ACTIVE",
"pid": 343,
"pcsWrite": false,
"outboundS2S": false,
"containerIDs": [],
"description": "33Across",
"inboundS2S": false,
"dataSourceId": 2,
"integrationCode" : "",
"allowDataSharing" : true,
"useAudienceManagerVisitorID" : true,
"marketingCloudVisitorIdVersion" : 0,
"idType" : "COOKIE" | "MOBILE" | "CROSS_DEVICE"
},
{
"name": "Acxiom",
"defaultDataSyncType": "FTP,
"status": "ACTIVE",
"pid": 343,
"pcsWrite": false,
"outboundS2S": false,
"containerIDs": [],
"description": "Acxiom",
"inboundS2S": false,
"integrationCode" : "",
"dataSourceId": 60
"allowDataSharing" : false,
"useAudienceManagerVisitorID" : true,
"marketingCloudVisitorIdVersion" : 0,
"idType" : "COOKIE" | "MOBILE" | "CROSS_DEVICE"
},
{
"name": "AlmondNet",
"defaultDataSyncType": "FTP",
"status": "ACTIVE",
"pid": 343,
"pcsWrite": false,
"outboundS2S": false,
"containerIDs": [],
"integrationCode" : "",
"description": "AlmondNet",
"inboundS2S": false,
"dataSourceId": 12
"allowDataSharing" : false,
"useAudienceManagerVisitorID" : false,
"marketingCloudVisitorIdVersion" : 0,
"idType" : "COOKIE" | "MOBILE" | "CROSS_DEVICE"
API
129
}
]
Acceptable Values for Enumeration Properties
status: The only currently supported status is active.
defaultDataSyncType: FTP or HTTP.
Return Available Data Source ID Types
A GET method that returns all available data source ID types.
Request
GET /datasources/configurations/available-id-types/
Sample Response
[
COOKIE, MOBILE, CROSS_DEVICE
]
Return All Active Marketing Cloud Visitor ID Versions
A GET method that returns a list of all active Marketing Cloud visitor ID versions.
Request
GET datasources/configurations/marketing-cloud-visitorid-versions/
Sample Response
[
0
1
2
]
Return Data Onboarding File Status
A GET method that returns data onboarding (inbound) file status.
Request
GET
https://api.demdex.com/v1/datasources/325/history/inbound?startDate=1000000000&endDate=1403034473000
Query parameters are optional.
Sample Response
[
{
"dataFileName":"ftp_dpm_325_1311024211.sync",
"idSyncDpid":0,
"recordsReceived":null,
"recordsSuccess":null,
"percentageSuccess":0,
"failedParseCheck":0,
"failedPCSTimeoutUUIDLookup":null,
"failedPCSTimeoutTraitsLookup":null,
"failedUUIDLookup":117377,
"failedInvalidDemdexUUID":null,
"failedNoRealizedTrait":null,
API
130
"totalSignals":null,
"totalUnusedSignals":null,
"totalrealizedtraits":null,
"totalRemovedTraits":null,
"totalNewTraits":null,
"percentageUsedSignals":0,
"startTime":1314130955000,
"endTime":1314131435000
},
{
"dataFileName":"ftp_dpm_325_1311024211.sync",
"idSyncDpid":0,
"recordsReceived":null,
"recordsSuccess":null,
"percentageSuccess":0,
"failedParseCheck":0,
"failedPCSTimeoutUUIDLookup":null,
"failedPCSTimeoutTraitsLookup":null,
"failedUUIDLookup":117346,
"failedInvalidDemdexUUID":null,
"failedNoRealizedTrait":null,
"totalSignals":null,
"totalUnusedSignals":null,
"totalrealizedtraits":null,
"totalRemovedTraits":null,
"totalNewTraits":null,
"percentageUsedSignals":0,
"startTime":1314132390000,
"endTime":1314132757000
},
{
"dataFileName":"ftp_dpm_325_1311024211.sync",
"idSyncDpid":0,
"recordsReceived":null,
"recordsSuccess":null,
"percentageSuccess":0,
"failedParseCheck":0,
"failedPCSTimeoutUUIDLookup":null,
"failedPCSTimeoutTraitsLookup":null,
"failedUUIDLookup":116949,
"failedInvalidDemdexUUID":null,
"failedNoRealizedTrait":null,
"totalSignals":null,
"totalUnusedSignals":null,
"totalrealizedtraits":null,
"totalRemovedTraits":null,
"totalNewTraits":null,
"percentageUsedSignals":0,
"startTime":1314184814000,
"endTime":1314185179000
}
]
Derived Signals API Methods
API methods that let you work with derived signals. A derived signal qualifies site visitors for additional traits based on a trait
they've already seen.
For more information about derived signals, see Derived Signals.
Create a New Derived Signal
A POST method that lets you create a new derived signal.
Request
API
131
POST https://api.demdex.com/v1/signals/derived/
Sample Request Body
The JSON request body contains a source key and source value. These parameters are used to associate the source key-value
pair with other traits that are associated (derived) from those values. For example, in this request the key-value pair product
SKU=1234 are also associated with a related target key-value pair. Note, source key and value variables must be unique. All
request values are required unless otherwise indicated.
{
"sourceKey": "product SKU",
"sourceValue": "1234",
"targetKey": "camera",
"targetValue": "brand x"
}
Sample Response
A successful update returns response code 201 Created and data as shown below. An unsuccessful attempt returns response
code 409 Conflict if the source/target mapping already exists.
{
"derivedSignalId": 2,
"targetKey": "camera",
"sourceKey": "product SKU",
"integrationCode": null,
"targetValue": "brand x",
"pid": 1099,
"updateTime": 1319752831000,
"version": 0,
"upUID": 507,
"crUID": 507,
"sourceValue": "1234",
"createTime": 1319752831000
}
Delete a Derived Signal
A DELETE method that lets you remove a derived signal from your collection.
Request
DELETE https://api.demdex.com/v1/signals/derived/<derivedSignalId>
Sample Response
Returns response code 204 No Content if successful.
Return Properties for a Derived Signal
A GET method that returns details for an individual derived signal.
Request
GET https://api.demdex.com/v1/signals/derived/<derivedSignalId>
Sample Response
A successful request returns response code 200 OK and data as shown below.
{
"derivedSignalId": 2,
"targetKey": "targetKey",
"sourceKey": "sourceKey",
"integrationCode": null,
"targetValue": "targetValue",
API
132
"pid": 1099,
"updateTime": 1319752928000,
"version": 1,
"upUID": 507,
"crUID": 507,
"sourceValue": "sourceValue",
"createTime": 1319752831000
}
Return Properties for all Derived Signals
A GET method that returns details for all your derived signals.
Request
GET https://api.demdex.com/v1/signals/derived/
Optional Query Parameters
You can use these optional parameters with API methods that return all properties for an object. Set these options in the request
string when passing that query in to the API. See Optional Parameters.
Parameter
Description
page
Returns results by page number. Numbering starts at 0.
pageSize
Sets the number of response results returned by the request (10 is default).
sortBy
Sorts and returns results according to the specified JSON property.
descending
Sorts and returns results in descending order. Ascending is default.
search
Returns results based on the specified string you want to use as a search parameter. For example,
let's say you want to find results for all models that have the word "Test" in any of the value fields
for that item. Your sample request could look like this:
GET https://api.demdex.com/v1/models/?search=Test.
You can search on any value returned by a "get all" method.
Sample Response
A successful update returns response code 200 OK and data (in an array) as shown below. All request values are required unless
otherwise indicated.
[
{
"derivedSignalId": 1,
"targetKey": "targetKey",
"sourceKey": "sourceKey",
"integrationCode": null,
"targetValue": "targetValue",
"pid": 1099,
"updateTime": 1319746748000,
"version": 0,
"upUID": 507,
"crUID": 507,
"sourceValue": "sourceValue",
"createTime": 1319746748000
},
{
"DerivedSignalId": 2,
"targetKey": "targetKey",
"sourceKey": "sourceKey",
API
133
"integrationCode": null,
"targetValue": "targetValue",
"pid": 1099,
"updateTime": 1319752831000,
"version": 0,
"upUID": 507,
"crUID": 507,
"sourceValue": "sourceValue2",
"createTime": 1319752831000
}
]
Destination API Methods
Methods that let you work programmatically with destination features.
In Audience Management, a destination is any other system (ad server, DSP, ad network, exchange, your own first-party cookie,
etc.) that you want to share data with.
Destination Types: URL and Cookie
Lists the variables used by the destinationType parameter. Specify push or ADS to work with a URL or cookie destination.
You cannot create server-to-server destinations with the available destination API methods.
API Destination Type
UI Destination Type
PUSH
URL
ADS
Cookie
Create Destinations
Create destinations with these RESTful API methods.
Supported Destination Types: URL and Cookie Only
The available POST methods let you create URL and cookie destinations only. Currently, you cannot create server-to-server
destinations with these REST API methods. However, the related destination GET methods let you retrieve information about
server-to-server destinations created in the user interface.
Create a Non-Serial URL Destination
A POST method that lets you create a destination that accepts segments composed of single key-value pairs (e.g., gender=male
or gender=female).
Request
POST https://api.demdex.com/v1/destinations/
Sample Request
This request creates a single destination. All request values are required unless otherwise indicated.
{
"name":"Sample URL Destination (not serialized)",
"description":"",
"destinationType":"PUSH",
"serializationEnabled":false
}
Sample Response
API
134
A successful request returns 201 created and the destination.
{
"destinationType":"PUSH",
"destinationId":4033,
"dataSourceId":null,
"pid":1099,
"name":"Sample URL Destination (not serialized)",
"description":"",
"startDate":null,
"endDate":null,
"status":"ACTIVE",
"destinationType":"PUSH",
"createTime":1338937116000,
"updateTime":1338937116000,
"crUID":694,
"upUID":694,
"domainRestrictions":"all_domains",
"tagType":0,
"serializationEnabled":false,
"urlFormatString":"http://www.adobe.com/send?%ALIAS%",
"secureUrlFormatString":"https://www.adobe.com/send?%ALIAS%",
"delimiter":null,
"mappings":null
}
Create a Serialized URL Destination
A POST method that lets you create a destination that accepts multiple values associated with a single key (e.g., color=blue,
red, green).
Request
POST https://api.demdex.com/v1/destinations/
Sample Request
Specify the secure URL and delimiter for the key-value pair passed in to the destination. All request values are required unless
otherwise indicated.
{
"name":"Sample URL Destination (Serialized)",
"description":"",
"destinationType":"PUSH",
"serializationEnabled":true,
"urlFormatString":"http://www.adobe.com/send?data=%ALIAS%",
"secureUrlFormatString":"https://www.adobe.com/%ALIAS%",
"delimiter":","
}
Sample Response
A successful update returns response code 201 created and the destination.
{
"destinationType":"PUSH",
"destinationId":4034,
"dataSourceId":null,
"pid":1099,
"name":"Sample URL Destination (Serialized)",
"description":"",
"startDate":null,
"endDate":null,
"status":"active",
"destinationType":"PUSH",
"createTime":1338937420000,
"updateTime":1338937420000,
"crUID":694,
"upUID":694,
API
135
"domainRestrictions":"all_domains",
"tagType":0,
"serializationEnabled":true,
"urlFormatString":"http://www.adobe.com/send?%ALIAS%",
"secureUrlFormatString":"https://www.adobe.com/%ALIAS%",
"delimiter":"-",
"mappings":null
}
Create a Cookie Destination: Single-Key, Non-Serialized
A POST method that lets you create a cookie destination that accepts segments composed of single key-value pairs (e.g.,
gender=male or gender=female).
Request
POST https://api.demdex.com/v1/destinations/
Sample Request
All request values are required unless otherwise indicated.
{
"name":"Cookie Destination Single Key Not Serialized",
"destinationType":"ADS",
"adServerTypeID":1,
"cookieName":"adobe",
"cnameDomain":"adobe.com",
"maxSize":"2048",
"ttl":"0",
"domainRestrictions":"inclusion",
"siteIDs":[
312
],
"formatType":"single_key",
"singleKey":"key",
"keySeparator":"=",
"valueSeparator":",",
"serializationEnabled":false
}
Sample Response
A successful update returns response code 201 created and the destination.
{
"destinationType":"ADS",
"destinationId":4035,
"pid":1099,
"name":"Cookie Destination Single Key Not Serialized",
"status":"active",
"destinationType":"ADS",
"createTime":1338937984000,
"updateTime":1338937984000,
"crUID":694,
"upUID":694,
"domainRestrictions":"inclusion",
"cnameDomain":"adobe.com",
"cookieName":"adobe",
"singleKey":"key",
"keySeparator":"=",
"valueSeparator":",",
"formatType":"single_key",
"transferMethod":0,
"serializationEnabled":false,
"maxSize":2048,
"ttl":0,
"siteIDs":[
312
API
136
],
"uparamEnabled":false
}
Create a Cookie Destination: Single Key, Serialized
A POST method that lets you create a destination that accepts multiple values associated with a single key (e.g., color=blue,
red, green).
Request
POST https://api.demdex.com/v1/destinations/
Sample Request
All request values are required unless otherwise indicated.
{
"name":"Cookie Destination Single Key Serialized",
"destinationType":"ADS",
"adServerTypeID":1,
"cookieName":"adobe",
"cnameDomain":"adobe.com",
"maxSize":"2048",
"ttl":"0",
"domainRestrictions":"all_domains",
"siteIDs":[
],
"formatType":"single_key",
"singleKey":"k",
"keySeparator":"=",
"valueSeparator":",",
"serializationEnabled":true,
"serializationSeparator":"#"
}
Sample Response
A successful update returns response code 201 created and the destination.
{
"destinationType":"ADS",
"destinationId":4036,
"pid":1099,
"name":"Cookie Destination Single Key Serialized",
"status":"active",
"destinationType":"ADS",
"createTime":1338938329000,
"updateTime":1338938329000,
"crUID":694,
"upUID":694,
"domainRestrictions":"all_domains",
"cnameDomain":"adobe.com",
"cookieName":"adobe",
"singleKey":"k",
"keySeparator":"=",
"valueSeparator":",",
"formatType":"single_key",
"transferMethod":0,
"serializationEnabled":true,
"serializationSeparator":"#",
"maxSize":2048,
"ttl":0,
"siteIDs":[
],
"uparamEnabled":false
}
API
137
Create a Cookie Destination: Multi-Key, Non-Serialized
A POST method that lets you create a destination that accepts segments that contain multiple keys with different values (e.g.,
gender=male; gender=female; color=blue; color=red).
Request
POST https://api.demdex.com/v1/destinations/
Sample Request
All request values are required unless otherwise indicated.
{
"name":"Ad Server Multi-Key Not Serialized",
"destinationType":"ADS",
"adServerTypeID":1,
"cookieName":"adobe",
"cnameDomain":"adobe.com",
"maxSize":"2048",
"ttl":"0",
"domainRestrictions":"all_domains",
"siteIDs":[
],
"formatType":"key_value",
"keySeparator":"=",
"valueSeparator":",",
"serializationEnabled":false
}
Sample Response
A successful update returns response code 201 created and the destination.
{
"destinationType":"ADS",
"destinationId":4037,
"pid":1099,
"name":"Ad Server Multi-Key Not Serialized",
"status":1,
"destinationType":"ADS",
"createTime":1338938666000,
"updateTime":1338938666000,
"crUID":694,
"upUID":694,
"domainRestrictions":"all_domains",
"cnameDomain":"adobe.com",
"cookieName":"adobe",
"keySeparator":"=",
"valueSeparator":",",
"formatType":"key_value",
"transferMethod":0,
"serializationEnabled":false,
"maxSize":2048,
"ttl":0,
"siteIDs":[
],
"uparamEnabled":false
}
Create a Cookie Destination: Multi-Key, Serialized
A POST method that lets you create a destination that accepts segments that contain multiple keys and values (e.g., gender=male,
female; color=blue, red, green).
Request
API
138
POST https://api.demdex.com/v1/destinations/
Sample Request
All request values are required unless otherwise indicated.
{
"name":"Cookie Destination Multi-Key Serialized",
"destinationType":"ADS",
"adServerTypeID":1,
"cookieName":"adobe",
"cnameDomain":"adobe.com",
"maxSize":"2048",
"ttl":"0",
"domainRestrictions":"all_domains",
"siteIDs":[
],
"formatType":"key_value",
"keySeparator":"=",
"valueSeparator":",",
"serializationEnabled":true,
"serializationSeparator":"#"
}
Sample Response
A successful update returns response code 201 created and the destination.
{
"destinationType":"ADS",
"destinationId":4038,
"pid":1099,
"name":"Ad Server Multi-Key Serialized",
"status":"active",
"destinationType":"ADS",
"createTime":1338938872000,
"updateTime":1338938872000,
"crUID":694,
"upUID":694,
"domainRestrictions":"all_domains",
"cnameDomain":"adobe.com",
"cookieName":"adobe",
"keySeparator":"=",
"valueSeparator":",",
"formatType":"key_value",
"transferMethod":0,
"serializationEnabled":true,
"serializationSeparator":"#",
"maxSize":2048,
"ttl":0,
"siteIDs":[
],
"uparamEnabled":false
}
Map Segments to a Destination
Map segments to destinations with these RESTful API methods.
Supported Destination Types: URL and Cookie Only
The available POST methods let you map segments to URL and cookie destinations only. Currently, you cannot map segments
to server-to-server destinations with these REST API methods. Use the user interface instead. However, the related destination
GET methods let you retrieve information about server-to-server destinations created in the user interface.
API
139
Map a Segment to a Non-Serialized URL Destination
A POST method that lets you map a segment to a non-serial URL destination.
Request
POST https://api.demdex.com/v1/destinations/<destinationId>/mappings/
Sample Request
All request values are required unless otherwise indicated.
{
"sid":87723,
"traitType":"SEGMENT",
"url":"http://adobe.com",
"startDate":"2012-07-04"
}
Sample Response
{
"mappingId":65334,
"traitType":"SEGMENT",
"traitValue":0,
"destinationId":4033,
"elementName":"Sample games",
"elementDescription":"Sample games pixel",
"elementStatus":"active",
"createTime":1338940094000,
"updateTime":1338940094000,
"crUID":694,
"upUID":694,
"sid":87723,
"startDate":"2012-07-03",
"endDate":null,
"priority":null,
"url":"http://adobe.com",
"secureUrl":null,
"tagCode":null,
"secureTagCode":null,
"traitAlias":null
}
Map a Segment to a Serialized URL Destination
A POST method that lets you map a segment to a serialized URL destination.
Request
POST https://api.demdex.com/v1/destinations/<dataOrderId>/traits/
Sample Request
In the request, the traitAlias corresponds to the key in a key-value pair. All request values are required unless otherwise
indicated.
{
"sid":87723,
"traitType":"SEGMENT",
"startDate":"2012-07-04",
"traitAlias":"123"
}
Sample Response
{
"mappingId":65335,
"traitType":"SEGMENT",
"traitValue":0,
API
140
"destinationId":4034,
"elementName":"Sample Games",
"elementDescription":"Migration of Sample Games Pixel",
"elementStatus":"active",
"createTime":1338940401000,
"updateTime":1338940401000,
"crUID":694,
"upUID":694,
"sid":87723,
"startDate":"2012-07-03",
"endDate":null,
"priority":null,
"url":"123",
"secureUrl":"123",
"tagCode":null,
"secureTagCode":null,
"traitAlias":"123"
}
Map a Segment to a Cookie Destination: Single-Key, Non-Serialized
A POST method that lets you map a segment to single-key, non-serialized cookie destination.
Request
POST https://api.demdex.com/v1/destinations/<destinationId>/mappings/
Sample Request
In the request, the valueAlias corresponds to the value in a key-value pair. All request values are required unless otherwise
indicated.
{
"sid":87723,
"traitType":"SEGMENT",
"startDate":"2012-07-04",
"valueAlias":"123"
}
Sample Response
{
"destinationMappingId":65336,
"traitType":"SEGMENT",
"traitValue":0,
"destinationId":4035,
"elementName":"Sample Games",
"elementDescription":"Migration of Sample Games Pixel",
"elementStatus":"active",
"createTime":1338940704000,
"updateTime":1338940704000,
"crUID":694,
"upUID":694,
"sid":87723,
"startDate":"2012-07-03",
"endDate":null,
"priority":1,
"traitAlias":null,
"valueAlias":"123"
}
Map a Segment to a Cookie Destination: Multi-Key, Non-Serialized
A POST method that lets you map a segment to multi-key, non-serialized cookie destination.
Request
POST https://api.demdex.com/v1/destinations/<destinationId>/mappings/
API
141
Sample Request
In the request, the traitAlias and valueAlias set the key and the value respectively in a key-value pair. All request values
are required unless otherwise indicated.
{
"sid":87723,
"traitType":"SEGMENT",
"startDate":"2012-07-04",
"traitAlias":"type",
"valueAlias":"123"
}
Sample Response
{
"mappingId":65338,
"traitType":"SEGMENT",
"traitValue":0,
"destinationId":4037,
"elementName":"Sample Games",
"elementDescription":"Migration of Sample Games Pixel",
"elementStatus":"active",
"createTime":1338941092000,
"updateTime":1338941092000,
"crUID":694,
"upUID":694,
"sid":87723,
"startDate":"2012-07-03",
"endDate":null,
"priority":1,
"traitAlias":"type",
"valueAlias":"123"
}
Map a Segment to a Cookie Destination: Multi-Key, Serialized
A POST method that lets you map a segment to a multi-key, serialized cookie destination.
Request
POST https://api.demdex.com/v1/destinations/<destinationId>/mappings/
Sample Request
In the request, the traitAlias and valueAlias set the key and the value in a key-value pair. All request values are required
unless otherwise indicated.
{
"sid":87723,
"traitType":"SEGMENT",
"startDate":"2012-07-04",
"traitAlias":"type",
"valueAlias":"123"
}
Sample Response
{
"destinationMappingId":65340,
"traitType":"SEGMENT",
"traitValue":0,
"destinationId":4038,
"elementName":"Sample Games",
"elementDescription":"Migration of Sample Games Pixel",
"elementStatus":"active",
"createTime":1338941273000,
"updateTime":1338941273000,
"crUID":694,
API
142
"upUID":694,
"sid":87723,
"startDate":"2012-07-03",
"endDate":null,
"priority":2,
"traitAlias":"type",
"valueAlias":"123"
}
Map a Segment to a Server-to-Server Destination
A POST method that lets you map a segment to an existing server-to-server destination. Note, however, that you cannot create
server-to-server destinations with these currently available API methods.
Request
POST https://api.demdex.com/v1/destinations/<destinationId>/mappings/
Sample Request
In the request, the traitAlias corresponds to the key in a key-value pair. All request values are required unless otherwise
indicated.
{
"sid":87723,
"traitType":"SEGMENT",
"startDate":"2012-07-04",
"traitAlias":"123"
}
Sample Response
{
"destinationMappingId":65341,
"traitType":"SEGMENT",
"traitValue":0,
"destinationId":566,
"elementName":"Sample",
"elementDescription":"",
"elementStatus":"active",
"createTime":1338942118000,
"updateTime":1338942118000,
"crUID":308,
"upUID":308,
"sid":84326,
"startDate":"2012-07-03",
"endDate":null,
"priority":null,
"traitAlias":"123"
}
Bulk Create Destination Mappings
A POST method that lets you pass in an array of cookie or URL destination mappings.
Request
POST https://api.demdex.com/v1/destinations/<destinationId>/bulk-create
Sample Request
All request values are required unless otherwise indicated.
[
{
"sid": 105123,
"traitType":"SEGMENT",
"url":"http://adobe.com",
"startDate":"2012-11-20"
API
143
},
{
"sid": 121070,
"traitType":"SEGMENT",
"url":"http://my.adobeconnect.com",
"startDate":"2012-11-21"
}
]
Sample Response
A successful response returns the array of created mappings.
[
{
"mappingId": 103454,
"traitType": "SEGMENT",
"traitValue": 0,
"destinationId": 780,
"elementName": "Case of the Mondays",
"elementDescription": "test",
"elementStatus": "active",
"createTime": 1353373234000,
"updateTime": 1353373234000,
"crUID": 1065,
"upUID": 1065,
"sid": 105123,
"startDate": "2012-11-19",
"endDate": null,
"priority": null,
"url": "http://adobe.com",
"secureUrl": null,
"tagCode": null,
"secureTagCode": null,
"traitAlias": null
},
{
"mappingId": 103455,
"traitType": "SEGMENT",
"traitValue": 0,
"orderId": 780,
"elementName": "Test Trait",
"elementDescription": "This trait",
"elementStatus": 1,
"createTime": 1353373234000,
"updateTime": 1353373234000,
"crUID": 1065,
"upUID": 1065,
"sid": 121070,
"startDate": "2012-11-20",
"endDate": null,
"priority": null,
"url": "http://my.adobeconnect.com",
"secureUrl": null,
"tagCode": null,
"secureTagCode": null,
"traitAlias": null
}
]
Delete Destinations
DELETE and POST methods that let you remove destinations and segment mappings.
Delete a Destination
A DELETE method that removes a destination.
API
144
Note: You must remove all segment mappings before you can delete a destination.
• Request: DELETE https://api.demdex.com/v1/destinations/<destinationId>
• Response: Returns code 204 No Content if successful.
Bulk Delete Destinations
Remove multiple destinations with this POST method. Pass in destination IDs (destinationId) with an array in the request
body.
• Request: POST https://api.demdex.com/v1/destinations/bulk-delete/
• Response: Returns code 204 No Content if successful.
Delete Destination Mappings by Segment Mapping ID
A POST method that removes destination mappings according to the specified segment ID.
• Request: DELETE https://api.demdex.com/v1/destinations/<destinationId>/segments/<mappingId>
• Response: Returns code 204 No Content if successful.
Add Multiple Segments to a Destination
A POST method that lets you map multiple segments to a destination.
Request
POST https://api.demdex.com/v1/destinations/<destinationId>/bulk-create
Sample Request
Create multiple destination mappings in an array. All request values are required unless otherwise indicated.
[
{
"sid": 105123,
"traitType":"SEGMENT",
"url":"http://adobe.com",
"startDate":"2012-11-20"
},
{
"sid": 121070,
"traitType":"SEGMENT",
"url":"http://my.adobeconnect.com",
"startDate":"2012-11-21"
}
]
Sample Response
Returns an array of created mappings.
[
{
"destinationMappingId": 103454,
"traitType": "SEGMENT",
"traitValue": 0,
"destinationId": 780,
"elementName": "Case of the Mondays",
"elementDescription": "test",
"elementStatus": "active",
"createTime": 1353373234000,
"updateTime": 1353373234000,
"crUID": 1065,
"upUID": 1065,
"sid": 105123,
"startDate": "2012-11-19",
API
145
"endDate": null,
"priority": null,
"url": "http://adobe.com",
"secureUrl": null,
"tagCode": null,
"secureTagCode": null,
"traitAlias": null
},
{
"traitToDataOrderId": 103455,
"traitType": "SEGMENT",
"traitValue": 0,
"destinationId": 780,
"elementName": "Test Trait",
"elementDescription": "This trait",
"elementStatus": 1,
"createTime": 1353373234000,
"updateTime": 1353373234000,
"crUID": 1065,
"upUID": 1065,
"sid": 121070,
"startDate": "2012-11-20",
"endDate": null,
"priority": null,
"url": "http://my.adobeconnect.com",
"secureUrl": null,
"tagCode": null,
"secureTagCode": null,
"traitAlias": null
}
]
Update a Destination by Destination ID
A PUT method that lets you update an existing destination by destinationId.
Request
PUT https://api.demdex.com/v1/destinations/<destinationId>
Sample Request
All request values are required unless otherwise indicated.
{
"name":"Updated URL Destination (not serialized)",
"description":"new description",
"destinationType":"PUSH",
"serializationEnabled":false
}
Sample Response
{
"destinationType": "PUSH",
"destinationId": 780,
"dataSourceId": null,
"pid": 1099,
"name": "Updated URL Destination (not serialized)",
"description": "new description",
"startDate": null,
"endDate": null,
"status": 1,
"createTime": 1348851790000,
"updateTime": 1353372029000,
"crUID": 884,
"upUID": 1065,
"domainRestrictions":"all_domains",
"tagType": 0,
API
146
"serializationEnabled": false,
"urlFormatString": null,
"secureUrlFormatString": null,
"delimiter": null,
"mappings": null
}
Update a Mapping to a Destination by Mapping ID
A PUT method that lets you update a mapping to a destination by the specified mappingId.
Request
PUT https://api.demdex.com/v1/destinations/mappings/<mappingId>
Sample Request
All request values are required unless otherwise indicated.
{
"sid": 105123,
"traitType":"SEGMENT",
"url":"http://adobe.com",
"startDate":"2012-11-20"
}
Sample Response
{
"mappingId": 103453,
"traitType": "SEGMENT",
"traitValue": 0,
"destinationId": 780,
"elementName": "sample",
"elementDescription": "test",
"elementStatus": "active",
"createTime": 1353373005000,
"updateTime": 1353373005000,
"crUID": 1065,
"upUID": 1065,
"sid": 105123,
"startDate": "2012-11-19",
"endDate": null,
"priority": null,
"url": "http://www.adobe.com/send?%ALIAS%",
"secureUrl": null,
"tagCode": null,
"secureTagCode": null,
"traitAlias": null
}
Return A Destination by Destination ID
A GET method that returns the destination for the specified destinationId.
Request
GET https://api.demdex.com/v1/destinations/<destinationId>
Note: To populate the mappings field pass in includeMappings=true in the URL.
Sample Response
{
"destinationType":"PUSH",
"destinationId":314,
API
147
"dataSourceId":null,
"pid":1099,
"name":"sample destination",
"description":"Turn",
"startDate":null,
"endDate":null,
"status":"active",
"destinationType":"PUSH",
"createTime":1281997484000,
"updateTime":1300752888000,
"crUID":224,
"upUID":308,
"domainRestrictions":"ALL_DOMAINS",
"tagType":0,
"serializationEnabled":false,
"urlFormatString":null,
"secureUrlFormatString":null,
"delimiter":null,
"mappings":null
}
Return All Destinations
A GET method that returns all destinations for the specified partner.
Request
GET https://api.demdex.com/v1/destinations
Note:
• (Optional) Pass in containsSegment=<sid> to return an array of all destinations mapped to the specified segment.
For example, your query could look similar to this: GET .../destinations/?containsSegment=4321.
• Does not return the full destination object. Get the destination by data order if you need fully populated object.
Optional Query Parameters
You can use these optional parameters with API methods that return all properties for an object. Set these options in the request
string when passing that query in to the API. See Optional Parameters.
Parameter
Description
page
Returns results by page number. Numbering starts at 0.
pageSize
Sets the number of response results returned by the request (10 is default).
sortBy
Sorts and returns results according to the specified JSON property.
descending
Sorts and returns results in descending order. Ascending is default.
search
Returns results based on the specified string you want to use as a search parameter. For example,
let's say you want to find results for all models that have the word "Test" in any of the value fields
for that item. Your sample request could look like this:
GET https://api.demdex.com/v1/models/?search=Test.
You can search on any value returned by a "get all" method.
Sample Response
[
{
API
148
"destinationId":364,
"pid":1099,
"name":"Test",
"description":"",
"status":"active",
"destinationType":"PUSH",
"createTime":1291345192000,
"updateTime":1291347561000,
"crUID":262,
"upUID":262,
"domainRestrictions":"all_domains"
},
{
"destinationId":369,
"pid":1099,
"name":"sample destination",
"status":"active",
"destinationType":"PUSH",
"createTime":1292631706000,
"updateTime":1292631706000,
"crUID":262,
"upUID":262,
"domainRestrictions":"all_domains"
}
]
Return a Destination Mapping With the Mapping ID
A GET method that returns an individual destination mapping based on the mappingId.
Request
GET https://api.demdex.com/v1/destinations/<destinationId>/mappings/<destinationMappingId>
Sample Response
{
"mappingId": 14593,
"traitType": "SEGMENT",
"traitValue": 0,
"destinationId": 314,
"elementName": "sample",
"elementDescription": "Migration Pixel",
"elementStatus": "active",
"createTime": 1281997484000,
"updateTime": 1300752888000,
"crUID": 224,
"upUID": 308,
"sid": 80920,
"startDate": "2010-11-15",
"endDate": null,
"priority": null,
"url": "http://www.adobe.com/send?%ALIAS%",
"secureUrl": "https://www.adobe.com/send?%ALIAS%",
"tagCode": null,
"secureTagCode": null,
"traitAlias": null
}
Return Destination Mappings
A GET method that returns the mappings for a destination.
Note: The returned mapping is specific to the destination type and configuration.
Request
API
149
GET https://api.demdex.com/v1/destinations/<destinationId>/mappings
Note: Supports paging parameters.
Sample Response
{
"total":354,
"page":0,
"pageSize":2,
"list":[
{
"destinationMappingId":14395,
"traitType":"SEGMENT",
"traitValue":0,
"destinationId":314,
"elementName":"sample pixel",
"elementDescription":"Migration Pixel",
"elementStatus":"active",
"createTime":1281997484000,
"updateTime":1300752888000,
"crUID":224,
"upUID":308,
"sid":80920,
"startDate":"2010-11-15",
"endDate":null,
"priority":null,
"url":"http://www.adobe.com/send?%ALIAS%",
"secureUrl":"https://www.adobe.com/send?%ALIAS%",
"tagCode":null,
"secureTagCode":null,
"traitAlias":null
}
{
"destinationMappingId":15934,
"traitType":"SEGMENT",
"traitValue":0,
"destinationId":314,
"elementName":"sample pixel",
"elementDescription":"Migration Pixel",
"elementStatus":"active",
"createTime":1281997484000,
"updateTime":1300752888000,
"crUID":242,
"upUID":803,
"sid":90820,
"startDate":"2010-11-15",
"endDate":null,
"priority":null,
"url":"http://www.adobe.com/send?%ALIAS%",
"secureUrl":"https://www.adobe.com/send?%ALIAS%",
"tagCode":null,
"secureTagCode":null,
"traitAlias":null
}
]
{
Return All Available Destination Platforms
A GET method that returns all available device platforms for destinations.
Request
GET /destinations/configurations/available-platforms/
API
150
Sample Response
[
BROWSER, ANDROID, iOS, ALL
]
Return S2S and Bulk S2S Destination Job History
A GET method that returns outbound Server-to-Server (S2S) and bulk S2S destination job history information.
Request
GET
https://api.demdex.com/v1/destinations/655/history/outbound?startDate=1000000000&endDate=1403034473000
Required query parameters: startDate=<epochtime> and endDate=<epochtime>.
Sample Response
[
{
"pushID":34090,
"orderID":655,
"dataProviderID":269,
"syncType":1,
"fullPublish":false,
"receivedRecords":1,
"attemptedRecords":1,
"successRecords":1,
"startTime":1337292466000,
"endTime":1337292466000,
"dataFileName":"ftp_655_269_iter_1337229891903.sync",
"success":true
},
{
"pushID":34104,
"orderID":655,
"dataProviderID":269,
"syncType":1,
"fullPublish":false,
"receivedRecords":1,
"attemptedRecords":1,
"successRecords":1,
"startTime":1337346397000,
"endTime":1337346397000,
"dataFileName":"ftp_655_269_iter_1337285714581.sync",
"success":true
},
{
"pushID":34124,
"orderID":655,
"dataProviderID":269,
"syncType":1,
"fullPublish":false,
"receivedRecords":1,
"attemptedRecords":1,
"successRecords":1,
"startTime":1337396811000,
"endTime":1337396812000,
"dataFileName":"ftp_655_269_iter_1337338243600.sync",
"success":true
}
]
API
151
Domain Management API Methods
Domain management methods that let you create and manage the domains to which you want to send data (for cookie destinations
only).
Create a New Domain
A POST method that lets you create a new domain for (cookie destinations only).
Request
POST https://api.demdex.com/v1/partner-sites/
Sample Request
{
"url":"example1.com"
}
Sample Response
A successful response returns 201 created and the partner site, including its unique ID.
{
"pid": 1111,
"siteId": 111,
"url": "example1.com"
}
Delete a Domain
A DELETE method that lets you remove a domain (for cookie destinations only).
Request
DELETE https://api.demdex.com/v1/partner-sites/<site-Id>
Sample Response
A successful response returns 204 no content. Returns 404 not found if the partner site cannot be found.
Return Properties for a Domain
A GET method that returns details about the specified domain (for cookie destinations only).
Request
GET https://api.demdex.com/v1/partner-sites/<siteId>
Sample Response
A successful response returns 200 OK and data as shown in the sample below. Returns 404 Not found if the site ID or partner
is not found.
{
"pid": 1111,
"siteId": 111,
"url": "example1.com"
}
Return Properties for all Domains
A GET method that returns information about all your domains (for cookie destinations only).
API
152
Request
GET https://api.demdex.com/v1/partner-sites/
Optional Query Parameters
You can use these optional parameters with API methods that return all properties for an object. Set these options in the request
string when passing that query in to the API. See Optional Parameters.
Parameter
Description
page
Returns results by page number. Numbering starts at 0.
pageSize
Sets the number of response results returned by the request (10 is default).
sortBy
Sorts and returns results according to the specified JSON property.
descending
Sorts and returns results in descending order. Ascending is default.
search
Returns results based on the specified string you want to use as a search parameter. For example,
let's say you want to find results for all models that have the word "Test" in any of the value fields
for that item. Your sample request could look like this:
GET https://api.demdex.com/v1/models/?search=Test.
You can search on any value returned by a "get all" method.
Sample Response
A successful response returns 200 OK and data in an array as shown in the sample below. Returns 404 Not found if the site
ID or partner is not found.
[
{
"pid": 1111,
"siteId": 111,
"url": "example1.com"
},
{
"pid": 2222,
"siteId": 222,
"url": "example2.com"
},
{
"pid": 3333,
"siteId": 333,
"url": "example3.com"
}
]
Segment API Methods
Methods that let you work programmatically with segments.
Create a New Segment
A POST method that lets you create a new segment.
Request
POST https://api.demdex.com/v1/segments/
API
153
Sample Request
All request values are required unless otherwise indicated.
{
"dataSourceId":281,
"name":"Test Segment",
"description":"Test",
"integrationCode":0,
"status":"active",
"segmentRule":"(11960T AND 1234T)",
"folderId":13247
}
Sample Response
A successful update returns response code 201 created as shown below. An unsuccessful update returns response code 4xx.
{
"pid":1099,
"legacyId":15693,
"sid":64821,
"dataSourceId":265,
"name":"Test Segment",
"description":"Test",
"status":"ACTIVE",
"startTime":1334183314000,
"createTime":1335901700000,
"updateTime":1335901700000,
"crUId":507,
"upUId":507,
"segmentRule":"(11960T AND 1234T)",
"segmentRuleVersion":0,
"folderId":13247
}
Note: For information about the effects on segmented users, data, and destinations when you pause or delete an active
segment, see Paused and Deleted Segments (Using API)
Update a Segment
A PUT method that lets you revise a segment's name, description, rules, and storage folder.
Request
PUT https://api.demdex.com/v1/segments/<sid>
PUT https://api.demdex.com/v1/segments/ic:<integration code>
The integration code must be unique. If the code is not unique, the request returns 409 Conflict.
Sample Request
All request values are required unless otherwise indicated.
{
"dataSourceId":281,
"name":"Test Segment",
"description":"Test",
"integrationCode":0,
"status":"active",
"segmentRule":"(11960T AND 1234T)",
"folderId":13247
}
Sample Response
API
154
A successful response returns 200 OK. An unsuccessful response returns error code 4xx.
{
"pid":1099,
"legacyId":15693,
"sid":64821,
"dataSourceId":265,
"name":"Test Segment",
"description":"Test",
"status":"ACTIVE",
"startTime":1334183314000,
"createTime":1335901700000,
"updateTime":1335901700000,
"crUId":507,
"upUId":507,
"segmentRule":"(11960T AND 1234T)",
"segmentRuleVersion":0,
"folderId":13247
}
Note: For information about the effects on segmented users, data, and destinations when you pause or delete an active
segment, see Paused and Deleted Segments (Using API)
Delete a Segment
A DELETE method that lets you remove a segment from your collection.
Request
DELETE https://api.demdex.com/v1/segments/<sid>
DELETE https://api.demdex.com/v1/segments/ic:<integration code>
The integration code must be unique. If the code is not unique, the request returns 409 Conflict.
Sample Response
Returns response code 204 No Content. Delete will fail if your segment is mapped to a destination or used as a baseline for
a model. Remove any mappings before deleting the segment.
Note: For information about the effects on segmented users, data, and destinations when you delete an active segment, see
Paused and Deleted Segments (Using API)
Delete Segments
A POST method that lets you bulk delete multiple segments.
Request
POST https://api.demdex.com/v1/segments/bulk-delete/
Note: For information about the effects on segmented users, data, and destinations when you delete an active segment, see
Paused and Deleted Segments (Using API)
Sample Request
In the request body, pass in a JSON array that includes the segment IDs you want to delete.
[
94257,
API
155
94258
]
Sample Response
Returns response code 204 No Content. Delete will fail if your segments are mapped to destinations or used as a baseline for
a model. Remove any mappings before deleting segments.
Return Properties for an Existing Segment
A GET method that returns details about an individual segment.
Request
GET https://api.demdex.com/v1/segments/<sid>
GET https://api.demdex.com/v1/segments/ic:<integration code>
The integration code must be unique. If the code is not unique, the request returns 409 Conflict.
Optional Query Parameters
• includeMetrics=true: Returns a frequency count of unique visitors for 7, 30, and 60 day intervals.
Sample Response
A successful response returns code 200 OK and data as shown in the sample below.
{
"pid":1099,
"legacyId":15693,
"sid":64821,
"dataSourceId":265,
"name":"Test Segment",
"description":"Test",
"status":"ACTIVE",
"startTime":1334183314000,
"createTime":1335901700000,
"updateTime":1335901700000,
"crUId":507,
"upUId":507,
"segmentRule":"(11960T AND 1234T)",
"permissions: ["READ", "WRITE", "CREATE", "DELETE"],
"segmentRuleVersion":0,
"folderId":13247
}
For details about permissions values, see Optional Query Parameters. The GET method for individual segments always returns
permission values. However, this is optional when you list properties for all your segments.
Note: For information about the effects on segmented users, data, and destinations when you pause or delete an active
segment, see Paused and Deleted Segments (Using API)
Return Properties for all Segments
A GET method that returns details about all your segments.
Request
GET https://api.demdex.com/v1/segments/
Optional Query Parameters
API
156
You can use these optional parameters with API methods that return all properties for an object. Set these options in the request
string when passing that query in to the API. See Optional Parameters.
Parameter
Description
page
Returns results by page number. Numbering starts at 0.
pageSize
Sets the number of response results returned by the request (10 is default).
sortBy
Sorts and returns results according to the specified JSON property.
descending
Sorts and returns results in descending order. Ascending is default.
search
Returns results based on the specified string you want to use as a search parameter. For
example, let's say you want to find results for all models that have the word "Test" in any
of the value fields for that item. Your sample request could look like this:
GET https://api.demdex.com/v1/models/?search=Test.
You can search on any value returned by a "get all" method.
folderId
Returns all the IDs for traits inside the specified folder. Not available to all methods.
permissions
Returns a list of segments based on the specified permission. READ is default. Permissions
include:
• READ: Return and view information about a segment.
• WRITE: Use PUT to update a segment.
• CREATE: Use POST to create a segment.
• DELETE: Delete a segment. Requires access to underlying traits, if any. For example,
you'll need rights to delete the traits that belong to a segment if you want to remove it.
Specify multiple permissions with separate key-value pairs. For example, to return a list
of segments with READ and WRITE permissions, pass in "permissions":"READ",
"permissions":"WRITE".
includePermissions
(Boolean) Set to true to return your permissions for the segment. Default is false.
integrationCode
Integration code for the segments.
The integration code does not need to be unique.
Sample Request
A request with optional parameters could look similar to the example below. All request values are required unless otherwise
indicated.
GET
https://api.demdex.com/v1/segments/?page=1&pageSize=1&sortBy=Name&descending=true
Sample Response
{
"total":3844,
"page":0,
"pageSize":5,
"list":[
{
API
157
"pid":1177,
"csegid":2733,
"sid":64821,
"dataSourceId":281,
"name":"Data provider",
"description":"Sample text here",
"status":"active",
"startTime":1334183314000,
"createTime":1323844715000,
"updateTime":1323844715000,
"crUId":507,
"upUId":507,
"segmentRule":"(11960T)",
"permissions": ["READ", "WRITE", "CREATE", "DELETE", "ADMINISTRATION"],
"segmentRuleVersion":0,
"folderId":13247
},
{
"pid":1177,
"csegid":2733,
"sid":648211,
"dataSourceId":281,
"name":"Sample name",
"description":"Sample text here",
"status":"active",
"startTime":1334183321000,
"createTime":1323844728000,
"updateTime":1323844728000,
"crUId":597,
"upUId":507,
"segmentRule":"(13212T)",
"permissions": ["READ", "WRITE", "CREATE", "DELETE", "ADMINISTRATION"],
"segmentRuleVersion":0,
"folderId":13350
}
]
}
Note: For information about the effects on segmented users, data, and destinations when you pause or delete an active
segment, see Paused and Deleted Segments (Using API).
Estimate Segment Size
A POST method that returns an estimate of the segment size. Returns unique users based on segment rules for 7, 30, and 60 day
intervals.
Request
POST https://api.demdex.com/v1/segments/estimate-size
Sample Request
Pass in a valid segment rule.
{
"rule":"2434T AND 3434T"
}
Sample Response
A successful update returns response code 200 OK. An unsuccessful request returns response code 4xx.
{
"audienceSizes":[
{
API
158
"timeWindow":"DAYS7",
"confidenceInterval":{
"high":15,
"low":0
},
"size":0
},
{
"timeWindow":"DAYS30",
"confidenceInterval":{
"high":15,
"low":0
},
"size":0
},
{
"timeWindow":"DAYS60",
"confidenceInterval":{
"high":15,
"low":0
},
"size":0
}
],
"lastUpdate":"2012-05-15 23:52:01",
"segment":"2434T AND 3434T"
}
Validate a Segment Rule
A POST method that validates a segment's rule logic and returns the expression tree for that rule.
Request
POST https://api.demdex.com/v1/segments/validate
Sample Request
{
"rule":"(14080 OR 14081)"
}
Sample Response
{
"expressionTree":{
"expr1":{
"sid":14080
},
"expr2":{
"sid":14081
},
"expressionName":"or"
},
"codeViewOnly":false
}
Paused and Deleted Segments (Using API)
Describes the effects on segmented users, data, and destinations when you pause or delete an active segment using the Segment
API method.
Note: To pause a segment, send a PUT request to update the segment. Ensure that you set the "status" property to "inactive."
To re-activate the segment, send a PUT request to replace the segment. Ensure that you set the "status" property to "active."
API
159
For more information, see Update a Segment. For more information about how to delete segments, see Delete a Segment
and Delete Segments.
Paused Segment Functionality
A paused (deactivated) segment:
• Stops segmenting new, qualified users
• Retains a user's segmentation status/membership (does not remove a user from the segment)
• Remains in the segment list and can be reactivated
• Does not send data to associated destinations
• Returns data in the available reports (up to the deactivation date)
Deleted Segment Functionality
A deleted segment:
• Stops segmenting new, qualified users
• Removes qualified users from segment membership
• Is removed from the segment list
• Cannot be undeleted
• Does not send data to associated destinations
• Does not return data in the available reports
Note: You can also pause and delete segments from the Segment Builder user interface. For more information, see Paused
and Deleted Segments (Using UI).
Taxonomic API Methods
Methods that let you view the Audience Management common taxonomy. This optional classification scheme organizes traits
into industry standard categories. It is used by various "do not track" opt-out processes.
Note: You cannot create new taxonomic categories or classify traits with these methods. To classify a trait, specify the
appropriate categoryId with a trait create or update method.
Return a Specific Taxonomy
A GET method that returns details about the specified taxonomic category.
Request
GET https://api.demdex.com/v1/taxonomies/0/<categoryId>
Sample Response
A successful response returns 200 OK and the category for the specified ID. An unsuccessful request returns 404 No Content
if the ID does not exist.
{
"crUID": 158,
"name": "Arts & Entertainment",
"upUID": 158,
"description": "Arts & Entertainment",
"categoryID": 1,
API
160
"parentCategoryID": 0
}
Return all Taxonomic Categories
A GET method that returns a list of the top-level categories in an array.
Request
GET https://api.demdex.com/v1/taxonomies/0/
Sample Response
Truncated for brevity.
[
{
"crUID": 158,
"name": "Arts & Entertainment",
"upUID": 158,
"description": "Arts & Entertainment",
"categoryID": 1,
"parentCategoryID": 0
},
{
"crUID": 158,
"name": "Automotive",
"upUID": 158,
"description": "Automotive",
"categoryID": 2,
"parentCategoryID": 0
},
{
"crUID": 158,
"name": "Business",
"upUID": 158,
"description": "Business",
"categoryID": 3,
"parentCategoryID": 0
}
]
Return Taxonomic Sub-Categories
A GET method that returns sub-categories for the specified parent category in an array.
Request
GET https://api.demdex.com/v1/taxonomies/0/<categoryId>/childCategories/
Sample Response
A successful response returns 200 OK and the category for the specified ID. An unsuccessful request returns 404 No Content
if the ID does not exist. Truncated for brevity.
[
{
"crUID": 158,
"name": "Books & Literature",
"upUID": 158,
"description": "Books & Literature",
"categoryID": 25,
"parentCategoryID": 1
},
{
"crUID": 158,
"name": "Celebrity Fan/Gossip",
API
161
"upUID": 158,
"description": "Celebrity Fan/Gossip",
"categoryID": 49,
"parentCategoryID": 1
},
{
"crUID": 158,
"name": "Fine Art",
"upUID": 158,
"description": "Fine Art",
"categoryID": 72,
"parentCategoryID": 1
}
]
Trait API Methods
Methods that let you work programmatically with Trait Builder features.
Create a New Rules-based Trait
A POST method that creates a new trait.
Request
POST https://api.demdex.com/v1/traits/
Sample Request Body
The JSON request requires a trait name and folder ID. All other parameters are optional.
{
"traitType":"RULE_BASED_TRAIT",
"name":"Trait name 1",
"description":"Trait description 1",
"comments":"This is a comment",
"integrationCode":"Code-123",
"traitRule":"key==\"value\"",
"ttl":30,
"dataSourceId":452,
"folderId":425,
"categoryId":1234
}
Sample Response
A successful update returns response code 201 Created and data as shown in the sample below.
{
"traitType":"RULE_BASED_TRAIT",
"sid":241161,
"pid":1111,
"name":"Trait name 1",
"description":"Trait description 1",
"folderId":425,
"comments":"This is a comment",
"integrationCode":"Code-123",
"traitRule":"key==\"value\"",
"traitRuleVersion":0,
"ttl":30,
"crUID":839,
"upUID":839,
"createTime":1354822051000,
"updateTime":1354822051000,
"url":"demofirst.demdex.net/event?d_sid=241161",
"permissions":[
"READ",
"WRITE",
API
162
"CREATE",
"DELETE"
],
"dataSourceId":452,
"categoryId":1234
}
Create a New Onboarded Trait
A POST method that creates a new onboarded trait (a trait from another system's database that is imported into Audience
Management).
Request
POST https://api.demdex.com/v1/traits/
Sample Request Body
The JSON request requires a trait name and folder ID. All other parameters are optional.
{
"traitType":"ON_BOARDED_TRAIT",
"name":"Trait name 1",
"description":"Trait description 1",
"comments":"This is a comment",
"integrationCode":"Code-123",
"traitRule":"key==\"value\"",
"ttl":30,
"dataSourceId":452,
"folderId":425,
"categoryId":1234
}
Sample Response
A successful update returns response code 201 Created and data as shown in the sample below.
{
"traitType":"ON_BOARDED_TRAIT",
"sid":241161,
"pid":1111,
"name":"Trait name 1",
"description":"Trait description 1",
"folderId":425,
"comments":"This is a comment",
"integrationCode":"Code-123",
"traitRule":"key==\"value\"",
"traitRuleVersion":0,
"ttl":30,
"crUID":839,
"upUID":839,
"createTime":1354822051000,
"updateTime":1354822051000,
"url":"demofirst.demdex.net/event?d_sid=241161",
"permissions":[
"READ",
"WRITE",
"CREATE",
"DELETE"
],
"dataSourceId":452,
"categoryId":1234
}
Create a New Algorithmic Trait
A POST method that creates a new algorithmic trait.
API
163
Request
POST https://api.demdex.com/v1/traits/
Sample Request Body
The JSON request body could look similar to the following example. All request values are required unless otherwise indicated.
{
"traitType" : "ALGO_TRAIT",
"name" : "Algo Trait Example",
"dataSourceId" : 265,
"thresholdType" : "ACCURACY",
"accuracy" : 0.95,
"folderId" : 3143,
"algoModelId" : 175,
"description" : "An example of using the post api for algo traits",
"categoryId": 0
}
Sample Response
A successful update returns response code 201 created and data as shown in the sample below.
{
"traitType": "ALGO_TRAIT",
"sid": 778769,
"name": "Algo Trait Example",
"description": "An example of using the post api for algo traits",
"status": 1,
"algoModelId": 175,
"accuracy": 0.95,
"thresholdType": "ACCURACY",
"processingStatus": "UNPROCESSED",
"folderId": 3143,
"dataSourceId": 265,
"categoryId": 0
}
Update a Rules-based Trait
A PUT method that lets you make changes and updates to an existing rules-based trait.
Request
PUT https://api.demdex.com/v1/traits/<sid>
PUT https://api.demdex.com/v1/traits/ic:<integration code>
The integration code must be unique. If the code is not unique, the request returns 409 Conflict.
Sample Request Body
The JSON request body could look similar to the following example.
{
"traitType":"RULE_BASED_TRAIT",
"name":"Trait name 1 - modified",
"description":"Trait description 1 - modified",
"comments":"This is a comment - modified",
"integrationCode":"Code-123-modified",
"traitRule":"\"newkey\"==\"newvalue\"",
"ttl":90,
"dataSourceId":159,
"folderId":362
"categoryId:0
}
API
164
Sample Response
A successful update:
• Returns response code 200 OK.
• Returns JSON response as shown in the sample below.
• Increments the traitRuleVersion value.
An unsuccessful update returns response code 409 Conflict if text in the name field is already in use. Trait names must be
unique.
{
"traitType":"RULE_BASED_TRAIT",
"sid":241161,
"pid":1111,
"name":"Trait name 1 - modified",
"description":"Trait description 1 - modified",
"comments":"This is a comment - modified",
"integrationCode":"Code-123-modified",
"traitRule":"\"newkey\"==\"newvalue\"",
"traitRuleVersion":1,
"ttl":90,
"crUID":839,
"upUID":839,
"createTime":1354822051000,
"updateTime":1354822612000,
"url":"demofirst.demdex.net/event?d_sid=241161",
"permissions":[
"READ",
"WRITE",
"CREATE",
"DELETE"
],
"dataSourceId":159,
"folderId":362,
"categoryId:0
}
Update an Onboarded Trait
A PUT method that lets you make changes and updates to an existing onboarded trait.
Request
PUT https://api.demdex.com/v1/traits/<sid>
PUT https://api.demdex.com/v1/traits/ic:<integration code>
The integration code must be unique. If the code is not unique, the request returns 409 Conflict.
Sample Request Body
The JSON request body could look similar to the following example.
{
"traitType":"ON_BOARDED_TRAIT",
"name":"Trait name 1 - modified",
"description":"Trait description 1 - modified",
"comments":"This is a comment - modified",
"integrationCode":"Code-123-modified",
"traitRule":"\"newkey\"==\"newvalue\"",
"ttl":90,
"dataSourceId":159,
"folderId":362
"categoryId:0
}
API
165
Sample Response
A successful update:
• Returns response code 200 OK.
• Returns JSON response as shown in the sample below.
• Increments the traitRuleVersion value.
An unsuccessful update returns response code 409 Conflict if text in the name field is already in use. Trait names must be
unique.
{
"traitType":"ON_BOARDED_TRAIT",
"sid":241161,
"pid":1111,
"name":"Trait name 1 - modified",
"description":"Trait description 1 - modified",
"comments":"This is a comment - modified",
"integrationCode":"Code-123-modified",
"traitRule":"\"newkey\"==\"newvalue\"",
"traitRuleVersion":1,
"ttl":90,
"crUID":839,
"upUID":839,
"createTime":1354822051000,
"updateTime":1354822612000,
"url":"demofirst.demdex.net/event?d_sid=241161",
"permissions":[
"READ",
"WRITE",
"CREATE",
"DELETE"
],
"dataSourceId":159,
"folderId":362,
"categoryId:0
}
Update an Algorithmic Trait
A PUT method that lets you make changes and updates to an existing algorithmic trait.
Request
PUT https://api.demdex.com/v1/traits/<sid>
PUT https://api.demdex.com/v1/traits/ic:<integration code>
The integration code must be unique. If the code is not unique, the request returns 409 Conflict.
Sample Request Body
The JSON request body could look similar to the following example. All request values are required unless otherwise indicated.
{
"traitType" : "ALGO_TRAIT",
"name" : "Algo Trait Example",
"dataSourceId" : 265,
"thresholdType" : "ACCURACY",
"accuracy" : 0.95,
"folderId" : 3143,
"algoModelId" : 175,
"description" : "An example of using the post api for algo traits",
"categoryId": 0
}
API
166
Sample Response
A successful update returns response code 201 created and data as shown in the sample below.
{
"traitType": "ALGO_TRAIT",
"sid": 778769,
"name": "Algo Trait Example",
"description": "An example of using the post api for algo traits",
"status": 1,
"algoModelId": 175,
"accuracy": 0.95,
"thresholdType": "ACCURACY",
"processingStatus": "UNPROCESSED",
"folderId": 3143,
"dataSourceId": 265,
"categoryId": 0
}
Delete a Trait
A DELETE method that removes an individual trait from your collection.
You can delete a trait using a sid or by using an integration code (id). An integration code can contain as many as 255 characters
and the same integration code used for both a trait and a segment.
Request
DELETE https://api.demdex.com/v1/traits/<sid>
DELETE https://api.demdex.com/v1/traits/ic:<integration code>
The integration code must be unique. If the code is not unique, the request returns 409 Conflict.
Sample Response
Returns response code 204 No Content if successful.
Delete Traits
A POST method that lets you bulk delete multiple traits.
Request Using Trait IDs
POST https://api.demdex.com/v1/traits/bulk-delete/
Sample Request
In the request body, pass in a JSON array that includes the trait IDs you want to delete.
[
1111,
2222
]
Sample Response
Returns response code 204 No Content.
Return Properties for an Existing Rules-based Trait
A GET method that returns details about an individual trait.
API
167
You can return details about a trait using sid or by using an integration code (id). An integration code can contain as many
as 255 characters and the same integration code used for both a trait and a segment.
Request
Request
GET https://api.demdex.com/v1/traits/<sid>
GET https://api.demdex.com/v1/traits/ic:<integration code>
The integration code must be unique. If the code is not unique, the request returns 409 Conflict.
Optional Query Parameters
Specify includeMetrics=true to return data on unique users for 7, 30, and 60 day intervals.
Sample Response
A successful request returns response code 201 Created and data as shown in the sample below.
{
"traitType":"RULE_BASED_TRAIT",
"name":"Trait name 1",
"description":"Trait description 1",
"comments":"This is a comment",
"integrationCode":"Code-123",
"traitRule":"key==\"value\"",
"ttl":30,
"dataSourceId":452,
"folderId":425
}
Return Properties for an Existing Algorithmic Trait
A GET method that returns details about an individual trait.
Request
Request Using a SID
GET https://api.demdex.com/v1/traits/<sid>
GET https://api.demdex.com/v1/traits/ic:<integration code>
The integration code must be unique. If the code is not unique, the request returns 409 Conflict.
Optional Query Parameters
Specify includeMetrics=true to return data on unique users for 7, 30, and 60 day intervals.
Sample Response
A successful request returns response code 200 OK and data as shown in the sample below.
{
"traitType": "ALGO_TRAIT",
"sid": 778770,
"name": "Algo Trait Example",
"description": "An example of using the post api for algo traits",
"status": 1,
"algoModelId": 175,
"accuracy": 0.95,
"thresholdType": "ACCURACY",
"processingStatus": "UNPROCESSED",
API
168
"folderId": 3143,
"dataSourceId": 265,
"categoryId": 0
}
Return Properties for all Traits
A GET method that returns details about all your traits.
Request
GET https://api.demdex.com/v1/traits/
Optional Query Parameters
You can use these optional parameters with API methods that return all properties for an object. Set these options in the request
string when passing that query in to the API. See Optional Parameters.
Parameter
Description
page
Returns results by page number. Numbering starts at 0.
pageSize
Sets the number of response results returned by the request (10 is
default).
sortBy
Sorts and returns results according to the specified JSON property.
descending
Sorts and returns results in descending order. Ascending is default.
search
Returns results based on the specified string you want to use as a search
parameter. For example, let's say you want to find results for all models
that have the word "Test" in any of the value fields for that item. Your
sample request could look like this:
GET https://api.demdex.com/v1/models/?search=Test.
You can search on any value returned by a "get all" method.
folderId
Returns all the IDs for traits inside the specified folder. Not available to
all methods.
intgrationCode
Integration code for the traits.
The integration code does not need to be unique.
Sample Response
A successful update returns response code 200 OK and data (in an array) as shown below.
[
{
"sid":1150,
"traitType":"RULE_BASED_TRAIT",
"name":"Trait 1",
"description":"Trait 1 description",
"status":"ACTIVE",
"url":"demofirst.demdex.net/event?d_sid=1150",
"dataSourceId":159,
"folderId":362
},
{
API
169
"sid":1158,
"traitType":"RULE_BASED_TRAIT",
"name":"Trait 2",
"description":"Trait 2 description",
"status":"ACTIVE",
"url":"demofirst.demdex.net/event?d_sid=1158",
"dataSourceId":159,
"folderId":362
},
{
"sid":6412,
"traitType":"RULE_BASED_TRAIT",
"name":Trait 3",
"description":"Trait 3 description",
"status":"ACTIVE",
"url":"demofirst.demdex.net/event?d_sid=6412",
"dataSourceId":159,
"folderId":362
}
]
Test a Trait Rule Against a URL
A POST method that lets you test trait rules.
Request
POST https://api.demdex.com/v1/traits/test
Sample Request
To test a rule, pass in the key-value pair, comparison operator, and the URL.
{
"code": "camera == \"brand\" AND price > 300",
"url" : "http://sample-website.com/search/?camera=brand&price=400"
}
Sample Response
A successful request returns response code 200 OK and the test results as true or false. A 4xx response code indicates an
error, bad request, or parse exception. Check your code and try again.
Validate Code for a TraitBuilder Rule
A POST method that helps you test and validate a trait rule.
Request
POST https://api.demdex.com/v1/traits/validate
Sample Request Body
To test a rule, pass in the key-value pair and the required comparison operator.
{
"code": "camera == \"brand\" AND price > 400",
}
Sample Response
API
170
A successful request returns response code 200 OK and the expression tree. If there are errors, the API returns the JSON
containing the validation errors. A 4xx response code indicates an error, bad request, or parse exception. Check your request
and try again.
{
"expressionTree":{
"expr1":{
"name":"camera",
"value":"brand",
"expressionName":"=="
},
"expr2":{
"name":"price",
"value":"400",
"expressionName":">"
},
"expressionName":"and"
},
"codeViewOnly":false
}
Traits Schema
The JSON schema used by the Traits API, along with request methods that return the entire schema and sample response.
Request
GET https://api.demdex.com/v1/traits/schema/
JSON Schema for the TraitBuilder API
Name
Data Type
Description
createTime
Number
A Unix timestamp that records the trait creation date and time.
crUID
Integer
ID of the user who created the rule.
description
String
User specified text that describes the resource. Limited to 255-characters
maximum.
integrationCode
String
Information defined and used by the customer only. Limited to
255-characters maximum.
name
String
Text used to name the resource. Limited to 255-characters maximum.
Required.
pid
Integer
Unique partner ID provided by Audience Management. Required.
sid
Integer
Score type ID. Used internally to help identify the resource. Required.
traitRule
String
Key-value data that defines your trait rules. Limited to 4094-characters
maximum.
traitRuleVersion
Integer
Incremented when the traitRule field is changed. Used for logging
and auditing purposes.
ttl
Integer
Time-to-live. Defines how long (in days) a user remains in a segment
after seeing a trait. See also Segment TTL Explained.
updateTime
Number
A Unix timestamp that records the last time a trait was modified.
API
171
Name
Data Type
Description
upUID
Integer
ID of the user who last updated a rule.
Sample Response
A successful request returns the JSON schema and the response code 200 OK.
{
"properties": {
"name": {
"maxLength": 255,
"minLength": 0,
"type": "string",
"required": true
},
"sid": {
"type": "integer",
"required": true
},
"ttl": {"type": "integer"},
"status": {"type": "integer"},
"integrationCode": {
"maxLength": 255,
"minLength": 0,
"type": "string"
},
"pid": {
"type": "integer",
"required": true
},
"updateTime": {"type": "number"},
"traitRule": {
"maxLength": 4095,
"minLength": 0,
"type": "string"
},
"upUID": {"type": "integer"},
"crUID": {"type": "integer"},
"description": {
"maxLength": 255,
"minLength": 0,
"type": "string"
},
"createTime": {"type": "number"},
"traitRuleVersion": {"type": "integer"}
},
"type": "object"
}
Trait Types
Optional methods that let you to assign traits to a user-defined type or category, usually according to function or for your own
internal reporting processes.
Note: Trait type methods do not assign traits to categories used by the common taxonomy. Think of these as labels that are
separate from the common taxonomy.
For visual reference, Trait Types is a dropdown control located in the UI under Traits > Create new trait > Basic Information.
Create a New Trait Type
A POST method that lets you create a new trait type.
API
172
Request
POST https://api.demdex.com/v1/customer-trait-types
Sample Request
{
"name":"Custom trait type"
}
Sample Response
{
"pixelType": 34,
"pid": 1099,
"name": "Custom type",
"description": null,
"crUID": 694,
"upUID": 694,
"createTime": 1358297352000,
"updateTime": 1358297352000
}
Return Properties for a Trait Type
A GET method that returns details about the specified trait type.
Request
GET https://api.demdex.com/v1/customer-trait-types/<customerTraitTypeId>
Sample Response
{
"pixelType": 4,
"pid": 0,
"name": "Delivery Event",
"description": "Delivery Event",
"crUID": 158,
"upUID": 158,
"createTime": 1299115496000,
"updateTime": 1299115496000
}
Return Properties for all Trait Types
A GET method that returns details about all your trait types in an array.
Request
GET https://api.demdex.com/v1/customer-trait-types/
Sample Response
[
{
"pixelType": 200,
"pid": 1099,
"name": "Customer Specific Trait Type",
"description": "Test",
"crUID": 158,
"upUID": 158,
"createTime": 1349990458000,
"updateTime": 1349990458000
},
{
"pixelType": 1,
"pid": 0,
API
173
"name": "User Trait",
"description": "User Trait",
"crUID": 158,
"upUID": 158,
"createTime": 1299115492000,
"updateTime": 1299115492000
},
{
"pixelType": 2,
"pid": 0,
"name": "Site Visitor",
"description": "Site Visitor",
"crUID": 158,
"upUID": 158,
"createTime": 1299115493000,
"updateTime": 1299115493000
}
]
User, Group, and Permissions Management API Methods
Methods that let you work programmatically to manage users, groups, and permissions.
User Management API Methods
Rest API methods to manage users, including creating, updating, listing, deleting, and returning user objects.
Create a User
A POST method to create a new user.
Request
POST /api/v1/users/
Sample Request Body
{
"username" : <string>,
"status" : <"ACTIVE"|"INACTIVE"|"LOCKED">
"firstName" : <string>,
"lastName" : <string>,
"emailAddress" : <string>,
"title" : <string_may_be_null>,
"phoneNumber" : <string_may_be_null>,
"groups" : [<group_1_id>, ...],
"isAdmin" : true | false
}
Sample Response
{
"pid" : <integer>,
"userId": <integer>,
"username" : <string>,
"status" : <"ACTIVE"|"INACTIVE"|"LOCKED">
"firstName" : <string>,
"lastName" : <string>,
"emailAddress" : <string>,
"title" : <string_may_be_null>,
"phoneNumber" : <string_may_be_null>,
"groups" : [<group_1_id>, ...],
"isAdmin" : <"true"|"false">
}
If isAdmin is set to true, the user is created as a partner admin. This property also lets you know whether a user is a partner
admin.
API
174
Returns 409 Conflict if the username is already taken.
Update a User
A PUT method to update a user.
Request
PUT /api/v1/users/<userId>
Sample Request Body
{
"username" : <string>,
"status" : <"ACTIVE"|"INACTIVE"|"LOCKED">
"firstName" : <string>,
"lastName" : <string>,
"emailAddress" : <string>,
"title" : <string_may_be_null>,
"phoneNumber" : <string_may_be_null>,
"groups" : [<group_1_id>, ...]
}
Sample Response
{
"pid" : <integer>,
"userId": <integer>,
"username" : <string>,
"status" : <"ACTIVE"|"INACTIVE"|"LOCKED">
"firstName" : <string>,
"lastName" : <string>,
"emailAddress" : <string>,
"groups" : [<group_1_id>, ...]
}
Returns 409 Conflict if the username is already taken.
Update Logged-In User
A PUT method to update the currently logged-in user.
Note: Whereas most API methods are only callable by partner admins, this method is callable by non-admin users.
Request
PUT /self/update
Sample Request Body
{
"status" : <"ACTIVE"|"INACTIVE"|"LOCKED">
"firstName" : <string>,
"lastName" : <string>,
"emailAddress" : <string>,
"title" : <string_may_be_null>,
"phoneNumber" : <string_may_be_null>
}
Sample Response
{
"userId": <integer>,,
"status" : <"ACTIVE"|"INACTIVE"|"LOCKED">
"firstName" : <string>,
"lastName" : <string>,
"emailAddress" : <string>
"title" : <string_may_be_null>,
API
175
"phoneNumber" : <string_may_be_null>
}
Returns 409 Conflict if the username is already taken.
Update Logged-In User Password
A PUT method to update the currently logged-in user.
Note: Whereas most API methods are only callable by partner admins, this method is callable by non-admin users.
Request
POST /users/self/update-password
Sample Request Body
{ "oldPassword" : "old password", "newPassword" : "new password" }
Returns 200 OK if successful. Returns 400 Bad Request if something is wrong with either password.
Reset Logged-In User Password
A PUT method to reset the currently logged-in user. Audience Management sends the user a system-generated password.
Note: Whereas most API methods are only callable by partner admins, this method is callable by non-admin users.
Request
POST /self/reset-password
Returns 200 OK if successful.
Return User Object for a User ID
A Get method to return the user object for a User ID.
Request
GET /api/v1/users/<userId>
Sample Response
{
"pid" : <integer>,
"userId": <integer>,
"username" : <string>,
"status" : <"ACTIVE"|"INACTIVE"|"LOCKED">
"firstName" : <string>,
"lastName" : <string>,
"emailAddress" : <string>,
"title" : <string_may_be_null>,
"phoneNumber" : <string_may_be_null>,
"groups" : [<groupd_id_1>, ...]
}
Return User Object for Logged-In User
A Get method to return the user object for the currently logged-in user.
Note: Whereas most API methods are only callable by partner admins, this method is callable by non-admin users.
Request
API
GET /api/v1/users/self
Sample Response
{
"pid" : <integer>,
"userId": <integer>,
"username" : <string>,
"status" : <"ACTIVE"|"INACTIVE"|"LOCKED">
"firstName" : <string>,
"lastName" : <string>,
"emailAddress" : <string>,
"title" : <string_may_be_null>,
"phoneNumber" : <string_may_be_null>,
"groups" : [<groupd_id_1>, ...]
}
List Users
A GET method to list users.
Request
GET /api/v1/users/
You can specify multiple group IDs in the query parameters:
GET /api/v1/users/?groupId=343&groupdId=12
This query returns a list of all users in the specified groups.
Sample Response
{
"pid" : <integer>,
"userId": <integer>,
"username" : <string>,
"status" : <"ACTIVE"|"INACTIVE"|"LOCKED">
"firstName" : <string>,
"lastName" : <string>,
"emailAddress" : <string>,
"title" : <string_may_be_null>,
"phoneNumber" : <string_may_be_null>,
"groups" : [<group_1_id>, ...]
}
Delete a User
A DELETE method to delete a user.
Request
DELETE /api/v1/users/<user_id>
Returns 204 No Content if successful. In case of conflict returns 409 Conflict.
Delete Users in Bulk
A POST method to delete multiple users in bulk.
Request
POST /api/v1/users/bulk-delete
Sample Request Body
{[<user_id_1>, <user_id_2>, ...]}
176
API
177
Group Management API Methods
Rest API methods to manage groups, including creating, updating, listing, deleting groups.
Create a Group
A POST method to create a new user group.
Request
POST /api/v1/groups/
Sample Request Body
{
"name" : <string>,
"description" : <string_may_be_null>,
}
Sample Response
{
"groupId" : <integer>,
"pid" : <integer>,
"name" : <string>,
"description" : <string_may_be_null>,
"membershipCount" : <integer>,
"wildcards" : <list of strings>,
"users" : <list of user IDs>
}
Update a Group
A PUT method to update a user group.
Request
PUT /api/v1/groups/<groupId>
Sample Request Body
{
"name" : <string>,
"description" : <string_may_be_null>,
}
Sample Response
{
"groupId" : <integer>,
"pid" : <integer>,
"name" : <string>,
"description" : <string_may_be_null>,
"membershipCount" : <integer>,
"wildcards" : <list of strings>,
"users" : <list of user IDs>
}
List Groups
A GET method to list user groups.
Request
GET /api/v1/groups/
Sample Response
[
{
API
"groupId" : <integer>,
"pid" : <integer>,
"name" : <string>,
"description" : <string_may_be_null>,
"membershipCount" : <integer>,
"wildcards" : <list of strings>,
"users" : <list of user IDs>
}, ...
]
Delete a Group
A DELETE method to delete a user group and remove all members from that group.
Request
DELETE /api/v1/groups/<groupId>
Returns 204 No Content if successful. In case of conflict returns 409 Conflict.
Delete Groups in Bulk
A DELETE method to delete multiple groups in bulk and remove all members from that group.
Request
DELETE /api/v1/groups/bulk-delete
Returns 204 No Content if successful. In case of conflict returns 409 Conflict.
List All Permissions for a Group
A GET method to list the permission objects on a group.
Request
GET /api/v1/groups/{groupId}/permissions
Sample Response
[{
"objectId" : 34,
"objectType": "SEGMENT",
"permissions": ["READ", "WRITE", "DELETE", "MAP_TO_MODELS"]
},
{
"objectId" : "234",
"objectType": "TRAIT",
"permissions": ["READ", "WRITE", "DELETE", "MAP_TO_MODELS"]
},
{
"objectId" : 277,
"objectType": "SEGMENT",
"permissions": ["READ", "WRITE", "MAP_TO_MODELS"]
}
]
Returns 400 Bad Request if the group is inaccessible.
Set Permissions for a Group
A PUT method to update group permissions. This method overwrites the old permissions with the new permissions.
Request
PUT /api/v1/groups/{groupId}/permissions/
178
API
179
Sample Response
[
{ "objectType" : "SEGMENT",
"objectId" : 563,
"permissions" : [ "READ", "WRITE"]
},
{ "objectType" : "SEGMENT",
"objectId" : 2363,
"permissions" : [ "CREATE", "WRITE"]
},
{ "objectType" : "TRAIT",
"objectId" : 83498,
"permissions" : [ "READ", "MAP_TO_SEGMENTS"]
},
{ "objectType" : "DESTINATION",
"objectId" : 304,
"permissions" : [ "READ", "WRITE", "CREATE"]
}
]
The sample response represents the updated list of permission objects.
Returns 200 OK if successful. Returns 400 if any given permission is invalid. Can also return 403 if the object is not accessible
by the logged-in user.
Permissions Management API Methods
Rest API methods to manage permissions for objects and groups.
List Available Object Types
A GET method to list available object types on which role-based access controls can be set.
Request
GET /api/v1/permissionable-object-types/
Sample Response
[ "SEGMENT", "TRAIT", "DESTINATION", "DERIVED_SIGNALS", "TAGS" ]
List Available Permissions for an Object Type
A GET method to list available permissions for an object type.
Request
GET /api/v1/permissionable-object-types/SEGMENT/
Sample Response
{
"wildcard" : [ "VIEW_ALL_SEGMENTS", "EDIT_ALL_SEGMENTS", "CREATE_ALL_SEGMENTS",
"DELETE_ALL_SEGMENTS", "MAP_ALL_SEGMENTS_TO_MODELS", "MAP_ALL_TO_DESTINATIONS" ],
"perObject" : [ "READ", "WRITE", "CREATE", "DELETE", "MAP_TO_MODELS", "MAP_TO_DESTINATION" ]
}
Note: The object types TAGS and DERIVED SIGNALS have no regular permissions to use. Controls on these object types
are changed by the All or Nothing Wild Card Permissions only.
Folder API Methods
Methods that let you work programmatically with trait and segment folders. Folders are directories that hold and organize traits
and segments in logical groups.
API
180
Trait Folders
API methods for working with trait folders.
Create a New Trait Folder
A POST method that creates a new trait folder.
Request
POST https://api.demdex.com/v1/folders/traits/
Sample Request
The JSON request body contains the segment folder name and parent folder ID. All request values are required unless otherwise
indicated.
{
"name":"Sample",
"parentFolderId":0
}
Sample Response
A successful request returns response code 201 OK, the new folder, and its location (path) in the response. A request that fails
validation returns response code 4xx. Also, a request can fail if a new folder has the same name as another folder on the same
level.
{
"path":"/All traits/Sample",
"pid":1099,
"folderId":12345,
"name":"Sample",
"parentFolderId":0
}
Update a Trait Folder
A PUT method that lets you update an existing folder with a new name, description, or parent folder.
Request
PUT https://api.demdex.com/v1/folders/traits/<folderId>
Sample Request
The JSON request body contains the revised folder name or parent folder ID. All request values are required unless otherwise
indicated.
{
"name":"Sample",
"parentFolderId":0
}
Sample Response
A successful response returns 200 OK and JSON as shown in the sample below. An unsuccessful query returns code 4xx.
{
"path":"/All traits/Sample",
"pid":1099,
"folderId":12345,
"name":"Sample",
"parentFolderId":0
}
Delete a Trait Folder
A DELETE method that removes an individual trait folder.
API
181
Request
DELETE https://api.demdex.com/v1/folders/traits/<folderId>
Sample Response
Returns response code 204 No Content if successful. Returns code 4xx if the folder contains child folders or traits. You must
remove all subfolders and content before you can delete a folder.
Return Properties for an Individual Trait Folder
A GET method that returns details about an individual segment folder.
Request
GET https://api.demdex.com/v1/folders/traits/<folderId>
Sample Response
A successful request returns response code 200 OK and individual folder data as shown below.
{
"path":"/All traits/folder 1",
"pid":1177,
"folderId":399,
"name":"folder 1",
"parentFolderId":0
}
Return Properties for All Trait Folders
A GET method that returns details about all your trait folders.
Request
GET https://api.demdex.com/v1/folders/traits/
Optional Query Parameters
Parameter
Description
includeThirdParty="true"
Return properties for third-party folders.
expand="true"
Returns the entire folder tree structure.
Sample Response
A successful request returns response code 200 OK and data (in an array) as shown below.
[
{
"path":"/All traits",
"pid":1099,
"folderId":0,
"name":"All traits",
"parentFolderId":0,
"subFolders":[
{
"path":"/All traits/folder 1",
"pid":1099,
"folderId":399,
"name":"folder 1",
"parentFolderId":0,
"subFolders":[
]
},
API
182
{
"path":"/All traits/folder 2",
"pid":1099,
"folderId":317,
"name":"folder 2",
"parentFolderId":0,
"subFolders":[
]
}
}
]
Segment Folders
API methods for working with segment folders.
Create a New Segment Folder
A POST method that creates a new segment folder.
Request
POST https://api.demdex.com/v1/folders/segments/
Sample Request Body
The JSON request body contains the segment name and a parent folder ID. All request values are required unless otherwise
indicated.
{
"name":"Sample",
"parentFolderId":0
}
Sample Response
A successful request returns response code 201 OK, the new folder, and its location (path) in the response. A request that fails
validation returns response code 4xx. Also, a request can fail if a new folder has the same name as another folder on the same
level.
{
"path":"/All Segments/Sample",
"pid":1099,
"folderId":12345,
"name":"Sample",
"parentFolderId":0
}
Update a Segment Folder
A PUT method that lets you update an existing folder with a new name, description, and/or parent folder.
Request
PUT https://api.demdex.com/v1/folders/segments/<folderId>
Sample Request Body
The JSON request body contains the revised folder name or parent folder ID. All request values are required unless otherwise
indicated.
{
"name":"Sample Updated",
"parentFolderId":0
}
Sample Response
API
183
A successful response returns 200 OK and JSON as shown in the sample below. An unsuccessful query returns code 4xx.
{
"path":"/All Segments/Sample",
"pid":1177,
"folderId":12345,
"name":"Sample",
"parentFolderId":0
}
Delete a Segment Folder
A DELETE method that removes an individual segment folder.
Request
DELETE https://api.demdex.com/v1/folders/segments/<folderId>
Sample Response
Returns response code 204 No Content if successful. Returns code 400 if the folder contains child folders or segments.
Note: You must remove all subfolders and content before you can delete a folder.
Return Properties for an Individual Segment Folder
A GET method that returns details about an individual segment folder.
Request
GET https://api.demdex.com/v1/folders/segments/<folderId>
Sample Response
A successful request returns response code 200 OK and individual folder data as shown below.
{
"path": "/All Segments/Display/APAC",
"pid": 1166,
"folderId": 18681,
"name": "APAC",
"parentFolderId": 17685,
"folderCount": 0,
"subFolders": []
}
Return Properties for all Segment Folders
A GET method that returns details about all your segment folders.
Request
GET https://api.demdex.com/v1/folders/segments/
Optional Query Parameters
Parameter
Description
expand="true"
Returns the entire folder tree structure.
Sample Response
A successful request returns response code 200 OK and data (in an array) as shown below.
[
{
API
184
"path":"/All Segments",
"pid":1099,
"folderId":0,
"name":"All Segments",
"parentFolderId":0,
"subFolders":[
{
"path":"/All Segments/Segment 1",
"pid":1177,
"folderId":399,
"name":"Segment 1",
"parentFolderId":0,
"subFolders":[
]
},
{
"path":"/All Segments/Segment 2",
"pid":1099,
"folderId":317,
"name":"Segment 2",
"parentFolderId":0,
"subFolders":[
]
}
}
]
DCS Region API Methods
Methods that let you programmatically list Audience Management DCS regions.
For a list of regions and their corresponding integers, see the dcs_region row in the Response Parameters section in URL Format
for Passing in Data to the DCS.
List a Specific DCS Region
A GET method to list a specific DCS region.
Request
GET /v1/dcs-regions/<id>
Sample Response
{
"regionId" : <id>,
"location" : "<location>",
"host" : "<host>",
"code" : "<code>",
"status" : "ACTIVE" | "INACTIVE",
"createTime" : long of milliseconds since epoch,
"updateTime" : long of milliseconds since epoch,
"crUID" : <userId who created>,
"upUID" : <userId who updated>
}
Returns 200 OK if successful.
For a list of regions and their corresponding integers, see the dcs_region row in the Response Parameters section in URL Format
for Passing in Data to the DCS.
API
185
List DCS Regions
A GET method to list DCS regions.
Request
GET /v1/dcs-regions/
Sample Response
[
{
"regionId" : <id>,
"location" : "<location>",
"host" : "<host>",
"code" : "<code> # APSE, USE, etc,
"status" : "ACTIVE" | "INACTIVE",
"createTime" : long of milliseconds since epoch,
"updateTime" : long of milliseconds since epoch,
"crUID" : <userId who created>,
"upUID" : <userId who updated>
},
...
]
Returns 200 OK if successful.
For a list of regions and their corresponding integers, see the dcs_region row in the Response Parameters section in URL Format
for Passing in Data to the DCS.
Data Integration Library (DIL) API
The Audience Management DIL API.
Class-level DIL Methods
The class-level DIL APIs let you programmatically create and work with Audience Management objects. The class-level APIs
work with the other instance-level functions to set values or return data.
Getting Started With Class-level DIL APIs
Describes authentication requirements and the text formatting used in the class-level DIL documentation.
When working with the class-level DIL APIs:
• Access requires a partner name and container namespace ID (NSID). Contact your Audience Management account manager
to obtain this information.
• Replace any sample italicized text in the API documentation with value, ID, or other variable as required by the method you're
working with.
• DIL writes encoded data to a destination cookie. For example, spaces are encoded as %20 and semicolons as %3B.
create
Creates a partner-specific DIL instance.
Function Signature: DIL.create: function (initConfig) {}
initConfig Elements
initConfig can consist of the following:
API
186
Name
Type
Description
partner
String
Required. Partner name as provided by Audience
Management.
visitorService
Object
containerNSID
Integer
Optional. Customer NSID. Default is 0.
disableDeclaredUUIDCookie
Boolean
Optional. False by default, which means Audience
Management sets a cookie in the partner's domain (sets
a first party cookie).
disableDestinationPublishingIframe
Boolean
Optional. If true, will not attach the destination
publishing IFRAME to the DOM or fire destinations.
Default is false.
iframeAkamaiHTTPS
Boolean
Optional. Specifies if the destination publishing template
should use Akamai for HTTPS connections. Enabled
on a per-partner basis.
iframeAttachmentDelay
Integer
Optional. Specifies the delay interval (in milliseconds)
before attaching the destination publishing IFRAME to
the DOM.
Required if Visitor ID functionality is present on the
page. See visitorService Properties. Released with v2.9.
Default delay interval is 500 milliseconds.
When disableDestinationPublishingIframe
is true, then:
• The IFRAME is not attached to the DOM.
• This parameter does not apply.
uuidCookie
Object
Sets a cookie with the unique user ID returned from
Audience Management. See uuidCookie Properties.
Released with v2.6.
enableErrorReporting
Boolean
Optional. Set to true to enable error reporting for all
DIL instances on the page. Works with Boolean true
only.
removeFinishedScriptsAndCallbacks
Boolean
Optional. Removes scripts and callbacks. Default is
False. Applies to the current DIL instance only.
Released with v3.3.
mappings
Object
Associates the value from one key-value pair to another.
See Map Key Values to Other Keys. Released with v2.4.
declaredId
Object
Optional. Sends Declared ID variables on every event
call to Audience Management.
API
187
Name
Type
Description
delayAllUntilWindowLoad
Boolean
Optional. If true, defers all requests (IFRAME, event
calls, ID sync, and destinationing) from executing until
the Page Load event fires. Default is false.
Response
A successful response returns the DIL instance. An unsuccessful attempt returns an error object (not thrown) if your code is
configured improperly or whenever an error is encountered.
Sample Code
var partnerObject1 = DIL.create({partner: 'partner name',
containerNSID: 3,
uuidCookie:{
name:'ad_uuid',
days:200,
path:'/test',
domain:'adobe.com',
secure:true
}
});
var partnerObject2 = DIL.create({partner: 'partner name',
containerNSID: 3,
disableDestinationPublishingIframe: true
});
uuidCookie Properties
Defines the properties used by the uuidCookie variable. This variable is part of the DIL.create method.
uuidCookie has the following properties:
Name
Description
name
The cookie name (aam_did is default).
days
Cookie lifetime (100 days is default).
path
Cookie path, e.g., '/test' (/ is default).
domain
The domain the cookie is set in, e.g., 'adobe.com' ('.'+document.domain is default).
secure
Sets a flag to send data over an HTTPS connection only.
visitorService Properties
Defines the properties used by the visitorService variable. This variable is part of the DIL.create method.
visitorService has the following properties:
Name
Type
Description
namespace
String
Required. Represents The Marketing Cloud Org ID. This is needed for Marketing Cloud
Core Service functionality. Same parameter used to instantiate the Visitor ID functionality.
See Visitor ID Service Implementation in the Marketing Cloud Visitor ID Service guide.
API
188
Code Sample:
var vDil = DIL.create({
partner: 'demofirst',
visitorService: {
namespace: "INSERT-MCORG-ID-HERE"
}
});
getDil
Retrieves a partner-specific DIL instance.
Function Signature: getDil: function (partner, containerNSID) {}
Parameters
Name
Type
Description
partner
String
The partner name to search for.
containerNSID
Integer
Defaults is 0. The NSID of the container you're searching for. Optional.
Response
A successful partner and container NSID match returns a partner-specific DIL instance. If there is no match, the API returns
(does not throw) an error with the message, "The DIL instance with partner <name> and containerNSID <ID>
was not found."
Sample Code
DIL.getDil('<partner>', <containerNSID>);
DIL.getDil('<partner>');
dexGetQSVars
Retrieves a specific value from an ad server.
Function Signature: dexGetQSVars: function (variableName, partner, containerNSID) {}
Parameters
Name
Type
Description
variableName
String
The name of the variable you want to get a value for.
partner
String
The partner name to search for.
containerNSID
Integer
The NSID of the container you're searching for. Defaults is 0.
Response
Returns the variable value for a DIL instance.
Sample Code
var value = DIL.dexGetQSVars('variableName','partnerName',containerNSID);
isAddedPostWindowLoad
Used to let DIL know that it is loaded after the window loads.
API
189
Function Signature: isAddedPostWindowLoad: function()
Sample Code
DIL.isAddedPostWindowLoad();
Instance-level DIL Methods
The instance-level DIL APIs let you programmatically create and work with Audience Management objects. The instance-level
methods enhance API functionality established by the class-level methods.
Getting Started With Instance-level DIL APIs
Describes authentication requirements and the text formatting used in the instance-level DIL documentation.
When working with the instance-level DIL APIs:
• Access requires a partner name and container namespace ID (NSID). Contact your Audience Management account manager
to obtain this information.
• Replace any sample italicized text in the API documentation with value, ID, or other variable as required by the method you're
working with.
signals
Adds customer and platform-level mappings to the query string of a pending request.
Function Signature: signals: function ({key1:value1, key2:value2},prefix){}
Note:
• You can chain other API calls to this method.
• If the Adobe Marketing Cloud JavaScript library is on the page, submit() waits for the Cloud to set a cookie before sending
a request.
Reserved Request Keys
The following request keys are reserved and cannot be overwritten by this method:
• sids
• pdata
• logdata
• callback
• postCallbackFn
• useImageRequest
Parameters
Name
Type
Description
obj
Object
An object representing the key-value pairs for platform-level mappings. Parameter accepts
strings and arrays as property values in the object.
prefix
String
Optional. The string value prefixed to each object key (replaces original key).
return
DIL.api
Returns the API object of the current DIL instance.
Response
API
190
Returns the API object of the current DIL instance.
Sample Code
var dataLib = DIL.create({
partner: 'partnerName'
containerNSID: containerNSID
});
// Method 1
var obj = { key1 : 1, key2 : 2 };
dataLib.api.signals(obj, 'c_').submit();
// Method 2
dataLib.api.signals({c_zdid: 54321}).submit();
// Method 3
// Will send 'c_key=a&c_key=2&c_key=3' to Audience Manager
var obj = { key : ['a', 'b', 'c'] };
dataLib.api.signals(obj, 'c_').submit();
traits
Adds SIDs to the query string of a pending request.
Function signature: traits:function (sids){}
Note: You can chain other API calls to this method.
Parameters
Name
Type
Description
sids
Array
Trait segment IDs in an array.
Response
Returns the API object of the current DIL instance.
Sample Code
var partnerObject = DIL.create({
partner: 'partner name',
containerNSID: NSID
});
partnerObject.api.traits([123, 456, 789]);
logs
Add data to log files in the pending request.
Function signature: logs: function {key1:value1, key2:value2}
Response
Returns the API object of the current DIL instance.
Sample Code
var partnerObject = DIL.create({
partner: 'partner',
containerNSID: NSID
});
partnerObject.api.logs({
API
191
file: 'dil.js',
message: 'This is the first request'
});
submit
Submits all pending data to Audience Management for the DIL instance.
Function Signature: submit: function () {}
Note: You can chain other API calls to this method. Also, DIL writes encoded data to a destination cookie. For example,
spaces are encoded as %20 and semicolons as %3B.
Response
Returns the API object of the current DIL instance.
Sample Code
var dataLib = DIL.create({
partner: 'partnerName',
containerNSID: containerNSID
});
dataLib.api.traits([123,456, 789]).logs({
file: 'dil.js',
message: 'This is the first request'
}).signals({
c_zdid: 1111
d_dma: 'default'
}).submit();
afterResult
A function that executes after the default destination publishing callback.
Function Signature: afterResult: function (fn) {}
Note: You can chain other API calls to this method.
Parameters
Name
Type
Description
fn
Function
The function you want to execute after JSON is processed by the default callback that handles
destination publishing.
Response
Returns an API object of the current DIL instance.
Sample Code
var dataLib = DIL.create({
partner: 'partnerName',
containerNSID: containerNSID
});
dataLib.api.signals({
c_zdid: 54321
d_dma: 'default'
}).afterResult(function(json){
API
192
//Do something with the JSON data returned from the server.
}).submit();
clearData
Clears all data in a pending request.
Function Signature: clearData: function () {}
Note: You can chain other API calls to this method.
Response
Returns the API object of the current DIL instance.
Sample Code
var dataLib = DIL.create({
partner: 'partnerName',
containerNSID: containerNSID
});
dataLib.api.traits([123,456, 789]).logs({
file: 'dil.js'
message: 'This is the first request'
}).signals({
c_zdid: 1111
d_dma: 'default'
});
//Reset the pending data
dataLib.clearData();
customQueryParams
Adds custom query parameters that are not explicitly defined by the data collection server to a pending request.
Function Signature: customQueryParams: function (obj) {}
Note: You can chain other API calls to this method.
Reserved Request Keys
The following request keys are reserved and cannot be overwritten by this method:
• sids
• pdata
• logdata
• callback
• postCallbackFn
• useImageRequest
Response
Returns the API object of the current DIL instance.
Sample Code
var partnerObject = DIL.create({
partner: 'partner',
containerNSID: NSID
API
});
partnerObject.api.customQueryParams({
nid: 54231,
ntype: 'default'
});
getContainerNSID
Returns the value of the container NSID for the DIL instance. Useful for debugging and troubleshooting.
Function Signature: dil.api.getContainerNSID: function () {}
Sample Code
var dataLib = DIL.create({
partner: 'partnerName',
containerNSID: containerNSID
});
//Verify the container NSID
var nsid = dataLib.api.getContainerNSID();
getEventLog
Returns chronologically sorted event log data as an array of strings. Useful for debugging and troubleshooting.
Function Signature: dil.api.getEventLog: function () {}
Sample Code
var dataLib = DIL.create({
partner: 'partnerName',
containerNSID: containerNSID
});
dataLib.api.traits([123, 456, 789]).logs({
file: 'dil.js',
message: 'This is the first request'
});.signals({
c_zdid: 1111
d_dma: 'default'
});.submit();
//Check log for messages
var log = dataLib.api.getEventLog();
if (log && log.length) {
alert(log.join('\n'));
}else{
alert('No log messages');
}
getPartner
Returns the partner name for a DIL instance. Useful for debugging and troubleshooting.
Function Signature: dil.api.getPartner: function () {}
Sample Code
var dataLib = DIL.create({
partner: 'partnerName'
containerNSID: containerNSID
});
//Verify the partner name
var partner = dataLib.api.getPartner();
193
API
194
getState
Returns the state of the current DIL instance. Useful for debugging and troubleshooting.
Function Signature: dil.api.getState: function () {}
Sample Code
var dataLib = DIL.create({
partner: 'partnerName',
containerNSID: containerNSID
});
dataLib.api.traits([123, 456, 789]).logs({
file: 'dil.js',
message:'This is the first request'
});.signals({
c.zdid: 1111
d_dma: 'default'
});.submit();
var state = dataLib.api.getState();
/*Object outline of state
state = {
pendingRequest: {pending data for call to server},
otherRequestInfo:{
firingQueue: [],
fired: [],
firing: false,
errored: [],
reservedKeys: {
sids: true,
pdata: true,
logdata: true,
callback: true,
postCallbackFn: true,
useImageRequest: true,
},
firstRequestHasFired: false,
num_of_jsonp_responses: 0,
num_of_jsonp_errors: 0,
num_of_img_responses: 0,
num_of_img_errors: 0
},
destinationPublishingInfo: {
THROTTLE_START: 3000,
throttleTimerSet: false,
id: ''destination_publishing_iframe_' + partner + '_' + containerNSID,
url: (constants.isHTTPS ? 'https://' : 'http://fast.') + partner +
'.demdex.net/dest3.html?d_nsid='
+ containerNSID + '#' + encodeURIComponent(document.location.href),
iframe: null,
iframeHasLoaded: false,
sendingMessages: false,
messages: [],
messageSendingInterval: constants.POST_MESSAGE_ENABLED ? 15: 100,
//Recommend 100ms for IE 6 & 7, 15ms for other browsers
jsonProcessed: []
}
}
*/
idSync
Consists of two functions that let data partners exchange and synchronize user IDs among themselves and Audience Management.
API
195
Function Signature:
Works with DIL versions 2.10 and 3.1 or higher.
Code
Synchronizes User IDs
dil.Instance.api.idSync(initConfig)
Between different data partners and Audience Management. For
example, partner x would use this to synchronize a user ID with
partner y and then send that to Audience Management.
dil.Instance.api.aamIdSync(initConfig)
When you already know the user ID and want to send it to Audience
Management.
idSync Elements
idSync can consist of the following:
Name
Type
dpid
String
dpuuid
String
minutesToLive
Number
url
String
Description
Data provider ID assigned by Audience Management.
The data provider's unique ID for the user.
(Optional) Sets the cookie expiration time. Must be an integer.
Default is 20160 minutes (14 days).
Destination URL.
Macros
idSync accepts the following macros:
• %TIMESTAMP%: Generates a timestamp (in milliseconds). Used for cache busting.
• %DID%: Inserts the Audience Management ID for the user.
• %HTTP_PROTO%: Sets the page protocol (http or https).
Response
Both functions return Successfully queued if successful. They return an error message string if not.
Sample Code
dilInstance.api.idSync(initConfig)
// Fires url with macros replaced
dilInstance.api.idSync({
dpid: '23', // must be a string
url: '//su.addthis.com/red/usync?pid=16&puid=%DID%&url=%HTTP_PROTO%%3A%2F%2Fdpm.demdex.net
%2Fibs%3Adpid%3D420%26dpuuid%3D%7B%7Buid%7D%7D',
minutesToLive: 20160 // optional, defaults to 20160 minutes (14 days)
});
dilInstance.api.aamIdSync(initConfig)
// Fires 'http:/https:' + '//dpm.demdex.net/ibs:dpid=<dpid>&dpuuid=<dpuuid>'
dilInstance.api.aamIdSync({
dpid: '23', // must be a string
API
196
dpuuid: '98765', // must be a string
minutesToLive: 20160 // optional, defaults to 20160 minutes (14 days)
});
result
Adds a callback (that receives JSON) to the pending request.
Function Signature: result: function (callback) {}
This callback replaces the default callback that handles destination publishing.
Note: You can chain other API calls to this method.
Parameters
Name
Type
Description
callback
Function
JavaScript function executed by the JSONP callback.
Response
Returns the API object of the current DIL instance.
Sample Code
var dataLib = DIL.create({
partner: 'partnerName',
containerNSID: containerNSID
});
dataLib.api.traits([123, 456, 789]).result(function(json){
//Do something, possibly with the JSON data returned from the server.
});.submit();
useImageRequest
Changes the request type to image <img> from script <src>.
Function Signature: useImageRequest: function () {}
Note: You can chain other API calls to this method.
Response
Returns an API object of the current DIL instance.
Sample Code
var dataLib = DIL.create({
partner:'partnerName',
containerNSID: containerNSID
});
dataLib.api.traits([123, 456, 789]).useImageRequest().submit();
DIL Modules
Describes methods in the DIL.modules namespace. These modules let you programmatically collect data and work with
Audience Management objects.
API
197
siteCatalyst.init
Works with DIL to send Analytics tag elements (variables, props, eVars, etc.) to Audience Management. Returns data in a comma
separated list. Available in version 2.6.
Function Signature: DIL.modules.siteCatalyst.init(siteCatalystReportingSuite, dilInstance, trackVars,
options)
Note: You must place this code on the page before the s.t(); function.
Parameters
Names
Type
names
String
iteratedNames
Object
maxIndex
Integer
siteCatalystReportingSuite
Object
dilInstance
Object
options
Object
Description
An array of strings that contains un-enumerated Analytics
variables like pageName, channel, campaign, product,
etc.
An array of objects that contains enumerated Analytics
variables like props and evars (e.g. prop1, prop2, evar3,
evar4).
Indicates how many iterated names you want to return. For
example, to return two props or evars, set maxIndex:2.
An object that represents the Analytics object.
An object that represents DIL.
Additional options:
replaceContextDataPeriodsWith: If you do not specify
something else, periods are replaced with the default
underscore ( _ ). For example s.contextData =
{abc.def = '123'}would result in
c_contextData_abc_def=123 in the event call query
string.
This option is available only in DIL version 5.0.
Data Captured by siteCatalyst.init
This function returns details on the following Analytics properties:
• pageName
• channel
• campaign
• products
• events
API
198
• eVar (1 - 250)
• prop (1 - 75)
• pe
• pev1
• pev2
• pev3
Sample Code
This code creates a comma separated list of Analytics events (props, eVars, etc.) if values for them exist.
// Get the Site Catalyst object instance:
var s = s_gi(s_account);
// Instantiate DIL code:
var scDil = DIL.create({
partner: 'adobe',
containerNSID: 5
});
// Use the module:
DIL.modules.siteCatalyst.init(s, scDil, {
//Specify the Site Catalyst variables you want to capture:
names: ['pageName', 'channel', 'campaign'],
//Use this to create iterated variable names:
iteratedNames: [{
name: 'eVar',
maxIndex: 75
}, {
name: 'prop',
maxIndex: 75
}]
});
To track all the monitored Analytics data points without the additional function shown above, invoke siteCatalyst.init
by itself like this:
DIL.modules.siteCatalyst.init(s, scDil);
GA.init
Works with DIL to send data for certain Google Analytics (GA) function calls to Audience Management. Available in version
2.8.
Function Signature: DIL.modules.GA.init(_gaq, dilInstance, trackVars);
Parameters
Name
Type
Description
_gaq
Array
An array that contains GA commands.
dilInstance
Object
An object that contains the DIL instance.
trackVars
Object
(Optional) An object that consists of the names property. This property is
an array of GA command names that you want to track.
Supported GA Function Calls
By default, GA.init captures data from the following functions:
• _setCustomVar
API
199
• _addItem
• _addTrans
• _setAccount
• _trackSocial
DIL Creates Keys for GA Data
Audience Management accepts data in the form of key-value pairs while GA works with items in an array. To work with GA
data, DIL creates a key-value pair automatically and forms a key like this: c_<key name>. Also, items in GA arrays appear in
a specific order. As a result, you must supply all parameters in that order, even when they contain no data. DIL maps keys for
the following GA methods:
// Tracking Social Interactions
_gaq.push(['_trackSocial',
'facebook',
'like',
'http://www.adobe.com/cool.php',
'/cool.php'
]);
//
//
//
//
c_socialNetwork
c_socialAction
c_socialTarget
c_socialPagePath
// Tracking a Transaction
_gaq.push(['_addTrans',
'1234',
// c_transOrderId
'Womens Apparel', // c_transAfflication
'28.28',
// c_transTotal
'1.29',
// c_tranTax
'15.00',
// c_transShipping
'San Jose',
// c_transCity
'California',
// c_transState
'USA'
// c_transCountry
]);
// Tracking an item
_gaq.push(['_addItem',
'1234',
//
'DD44',
//
'T-Shirt',
//
'Olive Medium',
//
'11.99',
//
'1'
//
]);
c_itemOrderId=1234
c_itemSku
c_itemName
c_itemCategory
c_itemPrice
c_itenQuantity
Sample Code
// DIL JavaScript library needs to be loaded and executed here
var dilInstance = DIL.create({
partner : "adobe"
});
// Assume ga.js has not loaded
var _gaq = _gaq || [];
_gaq.push(
['_setAccount', 'UA-XXXXX-X'],
['_setDomainName', 'example.com'],
['_setCustomVar', 1, 'Section', 'Life & Style', 3],
['_trackPageview']
);
_gaq.push([
'_addItem',
'1234',
// order ID - necessary to associate item with transaction
'DD44',
// SKU/code - required
'T-Shirt',
// product name - necessary to associate revenue with product
'Olive Medium', // category or variation
'11.99',
// unit price - required
'1'
// quantity - required
]);
API
200
To track all the monitored GA metrics without the additional function shown above, invoke GA.init by itself like this:
DIL.modules.GA.init(_gaq, dilInstance).submit();
Sample Event Call
The URL event call to Audience Management could look similar to this:
http://adobe.demdex.com/event?...c_accountId=UA-XXXXX-X&c_Section=Life%20%26%20Style
&c_itemOrderId=1234&c_itemSku=DD44&c_itemName=T-Shirt&c_itemCategory=Olive%20Medium&
c_itemPrice=11.99&c_itemQuantity=1
DIL Tools
Describes methods in the DIL.tools namespace. These utility functions help you perform specific tasks.
getSearchReferrer
Returns search terms used to reach the current page.
Purpose of getSearchReferrer
In DIL, getSearchReferrer returns search results (names and key words) used to reach your site. You can pass in specific
search terms to this function or let it search the supported search engines (AOL, Ask, Bing, Google, and Yahoo) against
document.referrer by default.
Function signature: DIL.tools.getSearchReferrer(uri, initConfig)
Function Parameters
getSearchReferrer accepts:
• {string}: (Optional) A string containing the search URL (uses document.referrer if undefined).
• {object}(Optional) An object containing the configuration for the hostPattern, queryParam, or queryPattern.
And returns:
• {object}: An object that contains valid names and keywords.
Examples
API
201
Search Type
Description
Default Search
Returns keyword search terms used by var results =
the AOL, Ask, Bing, Google, and Yahoo DIL.tools.getSearchReferrer();
search engines.
Pass in a Custom URL
Returns the search referrer based on a
custom URL.
Match URL Hostname
with a Custom Regex
Pass in a custom regex to match the host var results =
DIL.tools.getSearchReferrer("http://www.ehow.com/
name of the referring URL.
Match Search Patterns Pass in a custom regex to perform a
with a Custom Regex
custom search.
Code Sample
var results =
DIL.tools.getSearchReferrer("http://www.ehow.com/
search.aspx?q=adobe+rules");
search.aspx?q=adobe+rules",{
hostPattern:/ehow\./,
queryParam:"p"
});
var results =
DIL.tools.getSearchReferrer("http://www.ehow.com/
search.aspx?q=adobe+rules,{
hostPattern:/ehow\./,
search_pattern:/[&\?]p=([^&]+/
});
decomposeURI
Disassembles a Uniform Resource Identifier (URI) into its constituent components: hash, host, href, pathname, protocol, search,
and uriParams.
Function signature: DIL.tools.decomposeURI
Function Parameters
decomposeURI accepts:
• uri {string}: (Optional) A string containing the URI. Defaults to document.location.href if not specified.
And returns:
• {object}: An object that contains valid names and keywords.
Sample Code
var uriData = DIL.tools.decomposeURI('http://www.adobe.com/?arg1=123&arg2=456#am');
{
hash : "#am",
host : "www.adobe.com",
hostname : "www.adobe.com",
href : "http://www.adobe.com/?arg1=123&arg2=456#am",
pathname : "",
protocol : "http:",
search : "?arg1=123&arg2=456",
uriParams : {
arg1 : "123",
arg2 : "456"
}
}
getMetaTags
Searches for specific content defined in the meta tags on a Web page and returns that data in an object.
API
202
Function signature: DIL.tools.getMetaTags(1 or more parameters)
Function Parameters
getMetaTags accepts one or more name parameters (string type) to search for. It returns an object composed of key-value
pairs.
Sample Code
var dataLib = DIL.create({
partner: 'partnerName',
containerNSID: containerNSID
});
dataLib.api.signals(DIL.tools.getMetaTags('application', 'keywords',
'description'), 'c_').submit();
DIL Use Cases and Code Samples
Code samples and descriptions for specific DIL use cases.
Send Data Elements to Audience Management with DIL
Create an object variable that sends information about page elements to Audience Management. This is useful for general data
collection or as an alternative to gathering data with Analytics variables.
Description
The following code demonstrates how to collect page data and send it to Audience Management with DIL. These examples use
a variable to hold data elements in a flat list or an array. Remember, pass in variables as key-value pairs. Also, note the c_ prefix
before the key in the key-value pair. This required prefix identifies information as user-defined data. In the first example, you
need to manually append c_ to the key. In the second example, DIL does this for you automatically.
Keep Value Properties Consistent
Remember to keep the value properties the same when passing in data. For example, if you have two identical keys with different
values, the value of the last key-value pair takes precedence over the preceding value objects. For example, passing in color:blue
and color:red sets the returned value to red (overwrites blue).
Example 1: Send Data as Key-Value Pairs
This basic example sends color and price data to Audience Management in the form of key-value pairs. Your code could look
similar to the following:
var sample_dil = DIL.create({partner:"partner name"});
sample_dil.api.signals({
c_color:"blue",
c_price:"900"
});
sample_dil.api.submit();
Example 2: Send Data in an Object
This advanced example demonstrates how to send data in an object to Audience Management. When working with this method,
DIL lets you pass an object as a function parameter into the signals() method. DIL Your code could look similar to the
following:
var my_object = {
color : "blue",
price : "900"
};
var sample_dil = DIL.create({ partner : "partner name" });
API
203
//Load the object and append "c_" to all keys in the key-value pairs and send data to
AudienceManager.
sample_dil.api.signals(my_object,"c_").submit();
Example 3: Send Page Data in an Array
In this case, the variable my_object uses an array to hold data. This example builds on the information passed in by the
recommended method above, but adds an additional layer to accommodate a product type and model. Your code could look
similar to the following:
var my_objects = [{
color : "blue",
price : "900"
}, {
type : "acura",
model : "tl"
}];
var sample_dil = DIL.create({ partner : "partner name" });
for (var i = 0; i < my_objects.length; i++)
//Load the object and append "c_" to all the keys in the key-value pairs.
{
sample_dil.api.signals(my_objects[i], "c_");
}
sample_dil.api.submit();
Capture Referring URL
Capture and send a referring URL to Audience Management.
Note: This method works only when users move between pages with similar protocols (HTTP vs HTTPS). For example, the
browser retains a referring URL when you navigate from a secure site to another secure site. Browsers do not retain the
referring URL when you move between secure and unsecure sites. This behavior is normal browser functionality and cannot
be circumvented by DIL.
Code Sample
Your code could look similar to the following:
var adobe_dil = DIL.create({ partner : "partner name" });
adobe_dil.api.signals({ d_referer : document.referrer }).submit();
Capture Search Engine Types and Keyword Search Terms
Send information about search engine type and keyword searches to Audience Management.
Supported Search Engines
By default, DIL.getSearchReferrer recognizes searches from these search engines (including international variations):
• AOL
• Ask
• Bing
• Google
• Yahoo!
Description
API
204
The following code demonstrates how to get the search referrer for any of the supported search engines. In this case, let's assume
a user searched on the term "homes" from Google Canada (www.google.ca). This code will help you capture those search
terms and send them to Audience Management.
Basic Code
Basic code for getting the search referrer (from google.com, for example) looks like this:
var search_referrer = DIL.tools.getSearchReferrer();
Listed Search Engine Code Sample
In this case, let's assume that a user searched for the term "homes" from Google Canada (www.google.ca). Note how the code
prefixes the required c_ parameter to search engine (c_se) and search term (c_st). c_ is a required prefix that identifies these
as customer-defined variables to Audience Management.
var adobe_dil = DIL.create({partner:"partner name"});
var se = DIL.tools.getSearchReferrer();
if (se && se.valid) {
adobe_dil.api.signals({
c_se : se.name,
c_st : se.keywords
}).submit();
}
Unlisted Search Engine Code Sample
In this case, let's assume that a user searched for the term "homes" from dogpile.com. Because Dogpile is not supported by
default, you can configure DIL to recognize this search engine and return the search terms to Audience Management. Your
code could look similar to the following:
var adobe_dil = DIL.create({partner:"partner name"});
var search_referrer = DIL.tools.getSearchReferrer(document.referrer, {
hostPattern:/dogpile\./,
queryParam:"q"
});
if (se && se.valid) {
adobe_dil.api.signals({
c_se : se.name,
c_st : se.keywords
}).submit();
}
Map Key Values to Other Keys
Associate the value from a key-value pair to another key.
Description
In a key-value pair, the c_ prefix appended to the key identifies the signal as customer-defined data. Customer-defined data is
used for targeting on the specific site that passed in data on an event call. However, sometimes you want this information available
across all properties in your Audience Management account. To do this, map the value in a c_ key-value pair to a platform level
key. A platform level key is prefixed with d_ and makes the signal available for targeting across all properties in your account.
As an example, you collect ZIP code data from a particular site but want to target it to all your Audience Management properties.
To make the ZIP code available at the platform level, you could map your customer-defined ZIP code key (e.g. c_zip) to a
platform defined key as shown below.
Code Sample
API
205
Your code could look similar to the following:
var adobe_dil = DIL.create({
partner : "adobe",
mappings : {
c_zip : 'd_zip',
d_key2 : 'h_dil_key2'
}
});
adobe_dil.api.signals({c_zip : '10010'}).submit();
// Request will look like /event?c_zip=10010&d_zip=10010
Traffic DIL in Google Tag Manager
Set up and serve DIL through a Google Tag Manager container.
This procedure assumes you have a Google Tag Manager account, some working knowledge of that product, and your Audience
Management dil.js file.
To traffic the dil.js file in Google Tag Manager:
1. Create a new container or open an existing container.
2. Add a new tag to the container.
3. Open the tag to edit it and:
•
•
•
•
Name the tag.
Select "Custom HTML Tag" from the Tag Type drop-down list.
In the HTML field, provide the absolute or relative file path to the hosted dil.js file. For example, your code could
look similar to this, <script src="dil.js"></script>. You need to put DIL in another directory because this code
exceeds the character count limit for the HTML field.
Click Save.
4. Publish the container.
5. Generate container tag code and place it on your inventory.
Flash DIL
Collect data sent from FLA files to Analytics and work with that information in Audience Management.
Flash DIL is an ActionScript code library that lets you work with video playback data in Audience Management. Flash DIL
works by capturing SWF content the Adobe AppMeasurement library passes in to Analytics. Flash DIL sends that data to the
separate DIL JavaScript data collection module, which passes that information to Audience Management. Analytics data (Props,
eVars, events, etc.) captured from the FLA file is available in Audience Management as traits or unused signals.
Requirements for Flash DIL Data Collection
General implementation and code-related requirements.
Implementation Requirements
Flash data collection requires:
• The DIL class library (dil.swc). Obtain the DIL class library from your Partner Solutions contact.
• JavaScript DIL data collection code on the page. See Data Integration Library documentation.
• DIL ActionScript library loaded in the Flash object you want to collect data from.
• Adobe AppMeasurement AS library (version 3.5.2, or later) loaded the Flash object you want to collect data from.
API
206
Set AllowScriptAccess to Always or sameDomain
The AllowScriptAccess in HTML code that loads a SWF file controls the ability to perform outbound URL access from
within the SWF file. When you configure a Flash DIL data integration, make sure the Flash AllowScriptAccess parameter
is set to always or sameDomain. Flash DIL data collection will not work if AllowScriptAccess is set to never. See Control
Access to Scripts or Host Web Page.
JS DIL Code Placement
Try to place the JS DIL data collection module on the page so it loads before the FLA file. When the FLA file loads first, before
DIL data collection is ready, you can miss the initial data signals that Flash DIL sends to that module. However, once instantiated,
the DIL data collection module will capture all subsequent SWF file data passed in by Flash DIL.
Data Collected by Flash DIL
Flash DIL captures page view, link tracking, media tracking, and other media view events from the Adobe AppMeasurement
library.
Page View Events
Unless specified otherwise by s.trackVars, Flash DIL collects the following data from Adobe AppMeasurement:
• pageName
• channel
• campaign
• products
• events
• prop1 - prop75
• eVar1 - eVar75
Link Tracking Events
Unless specified otherwise by s.linkTrackVars, Flash DIL collects the following data from Adobe AppMeasurement:
• pe (Type of track link called)
• pev1 (Link URL)
• pev2(Link text)
Media Tracking Events
Unless specified otherwise by s.Media.trackVars, Flash DIL collects all the data enumerated in the Page View Events section.
Other Data Points
Data from these parameters is collected by default:
• mediaName (Media/video element name)
• mediaAdName (Ad name)
• mediaAdParentName (Name of the primary media content the ad is nested under)
• mediaAdParentPod (The pod or ad break within the primary content where the ad plays)
• mediaAdParentPodPos (The numeric position within the pod where the ad plays. More than one ad can play within a pod.
Flash DIL Data in Audience Management
The Flash DIL module turns Adobe AppMeasurement data into Audience Management traits and unused signals.
Analytics Props, eVars, and events work like traits in Audience Management. Traits are key-value pairs and are used to build
segments. For example, in an Analytics prop like prop35=foo, prop35 is the key (a constant) and foo is the value (a variable).
API
207
Match Audience Management Traits to Analytics Variables
To use the Analytics data passed by Flash DIL, you should create Audience Management traits that have:
• The same names as their Analytics equivalents.
• A key value prefixed with c_.
See the table for examples:
Analytics Data Element
Analytics Example
As Audience Management Trait
prop
c30=foo
c_prop35=foo
evar
v35=bar
c_evar=bar
events
events=event10
c_events=event10
Flash DIL/Analytics Data as Unused Signals
Audience Management accepts Analytics Props, eVars, and events even without a corresponding trait. In this case, the data is
unavailable for trait creation and appears in the Unused Signals report instead. To make the most of this information, create
Audience Management traits that match the Analytics data passed in by the Flash DIL library.
Flash DIL ActionScript Library
Code for your Flash object to send Analytics data to Audience Management.
Note:
• For each Flash object, the code supports one partner instance (d.partner) only.
• Requires the Adobe AppMeasurement AS library version 3.5.2 or higher. See AppMeasurement Flash, Flex, and OSMF
Implementation Guide for instructions on updating the library.
import com.omniture.AppMeasurement; // Omit this line if it already exists in the code
import com.adobe.am.DIL;
var s:AppMeasurement = new AppMeasurement(); // Omit this line if it already exists in the code
var d:DIL = new DIL();
d.partner = "<partner>";// Partner name
d.containerNSID = <container NSID>; // Optional, defaluts to 0
s.loadModule(d);
Tag Manager Integration
Steps to integrate Tag Manager and Audience Management.
1. (Conditional) Contact your Adobe Account Manager to set up an Audience Management account, if necessary.
You must be an Audience Management customer and have an Audience Management account to use this integration.
2. When you add Audience Management, enter the following code in the On Load text area, then customize the code to your
account.
Note: Your Account Manager usually performs this step.
// <partner_name> : Obtain this for your account rep
var _dil = DIL.create({partner : '<partner_name>'});
// Now use DIL to fire events or use the Analytics integration
_dil.api.submit(); // example
API
208
3. Ensure that the Synchronous check box is deselected.
You should select this check box if you need the DIL code to be loaded synchronously on the page. This is not a typical use
case.
4. Click Save.
After saving, you must wait a few minutes to ensure that the code has propagated to the Tag Manager 2.0 servers.
After the integration is complete, you should see the following Audience Management event call on your web page:
// Example: partner_name=adobe
[http|https]://adobe.demdex.com/event?...
Implementing Audience Management
209
Implementing Audience Management
This section outlines and explains the processes related to getting started with the Audience Management data management
platform (DMP). This section is designed to help business teams, project managers, and technology managers understand the
Audience Management implementation process.
Implementation Overview
Getting started with Audience Management can take approximately six weeks to three months, depending on your data collection
needs.
Our implementation techniques help create consultative partnership with new clients. This process is designed to:
• Discover and understand your business requirements
• Produce an actionable plan to address those demands
• Develop custom solutions to help meet unique requirements or use cases
• Ensure that your proprietary data is imported and made available in the Audience Management
Our Partner Solutions and Account Management teams will work closely with you before, during, and after the implementation
process.
Audience Management takes a phased approach to setup and implementation.
Define Phase
The define phase introduces you to our Partner Solutions project leads and begins the project management process.
This step is designed to help potential clients define and agree on project scope, understand custom requirements, establish
milestones, and set up communications.
The following table describes key activities that take place during this phase:
Activity
Purpose/Description
Suggested Participants
Kick-off call/meeting
• Introduce project leads
Business and technical teams
• Define roles and responsibilities
• Establish goals and milestones tied to delivery dates
• Confirm plans for on-site work
• Establish communications for questions and status
updates
Provide access
Establish access to shared resources and distribute
log-in credentials
Business and technical teams
Status reports and project team calls Establish and maintain clear communication about Business and technical teams
plans and progress
Deliverables for this phase can include the following:
• Documents that identify roles and responsibilities
• Documents that establish the scope of work
• A plan to schedule project meetings and calls
• A process to share resources and access
Implementing Audience Management
210
Discovery Phase
The discovery phase is dedicated to gathering requirements, conducting research, and working toward a deeper understanding
of your business needs and data-collection strategies.
The following table describes key activities that take place during this phase:
Activity
Purpose/Description
Suggested Participants
Requirements and goal setting • Develop plans for tag management and data collection Business teams
• Develop plans that meet customer needs, goals, and
expectations
Evaluate data
• Determine how to collect your data and the sources of
that data
Business and technical teams
• Discover sources of your first-party, second-party, and
third-party data
Find destinations
Discover if the client sends data to other ad servers, DSPs, Business teams
networks, or exchanges
Breakout sessions
Refine business requirements and needs
Follow-up communication
Regular communication for follow-up and development Business and technical teams
purposes
Business teams
Deliverables for this phase can include:
• A completed first-party, second-party, and third-party data collection strategy
• A completed CRM or data warehouse ingestion plan
• Defined audience-segmentation requirements
• a completed data taxonomy
• A developed third-party data-integration plan
Build, Test, and Train Phase
During the build, test, and train phase, you will review the data collection strategy and prototype with a designated Partner
Solutions lead.
Your data collection strategy will undergo end-to-end QA testing. Partner Solutions will track discovered bugs and coordinate
problem resolutions with our systems engineers. Customer training can start in parallel with these other efforts.
The following table describes key activities that take place during this phase:
Activity
Purpose/Description
Participants
Prepare a data collection
strategy
Work with Adobe technical teams to build a data-collection Business and technical teams
plan that satisfies your business requirements
Deploy and test code
Test the proposed solution in a staging environment and
perform cross-browser testing
Technical teams
Implementing Audience Management
211
Activity
Purpose/Description
Participants
Verify functionality and
resolve bugs
Examine and communicate results, resolve bugs, and re-test Technical teams
User training
Provide education and understanding about Audience
Management features, tools, and reports
Business teams
Deliverables for this phase can include:
• A completed and accepted data-collection plan
• End-to-end QA testing
• Basic instruction on Audience Management user interface features
• Acceptance and sign-off
Launch, Support, and Optimize Phase
During the launch, support, and optimize phase, your data-collection and prototyped implementation moves from development
to a live, production environment. We’ll continue training on product familiarization and strategies that can help increase your
ROI through data-driven optimization.
The following table describes key activities that take place during this phase:
Activity
Purpose/Description
Participants
Data analysis and
optimization
Analyze data trends and provide recommendations for
optimization
Business teams
Create traits and segments
Create real traits and segments for data collection:
Business teams
• Create real traits and segments
• Discuss segment-creation strategies
• Consider and review use cases
Further training
Continue to build understanding and familiarity with product Business teams
features, tools, and reports
Follow-up communications Regularly scheduled communication to keep abreast of your Business and technical teams
user experience with Audience Management
Tasks for this phase can include:
• Generating and interpreting report data
• Understanding custom reports
• How to get product support
• Responding to or soliciting feature requests, bugs, and user feedback
• Deepening familiarity with Audience Management features and reports
Code Implementation
Though the deployment process may seem complex, the code implementation is as simple as adding a few lines of JavaScript
adjacent to the closing </body> tag of your website.
Deployment
Implementing Audience Management
212
The Audience Management code snippet calls Akamai to download the business rules set up previously in the user interface.
Furthermore, client browsers cache this information, which helps reduce page and server load times. Our code and data collection
methodology is designed to maintain the user experience across your inventory.
Participants
Partner Solutions can work directly with your technical teams to help deploy code, address final concerns, and fulfill other
requirements.
Post-Implementation Support
Our collaborative efforts don’t stop with final deployment. After implementation is complete, our Account Management team
takes over.
Account managers provide continuing support and consultation services after the product implementation process is complete.
You can expect to have regular meetings with your account manager. These meetings ensure that you get the maximum amount
of use and value from Audience Management.
Contact us here for more information and to get started with Audience Management.
Integration Guides
213
Integration Guides
Work with Audience Management data in other Adobe products or external systems.
Data Integration Methods
A high-level overview of how Audience Management exchanges information with other data providers and systems.
Choosing the right integration method depends on a combination of business requirements and the technical capabilities of
your data partner.
Data Integration Methods
A high-level overview of how Audience Management exchanges information with other data providers and systems.
Supported Data Integration Methods: Real-Time and Batch (Server-to-Server)
Audience Management exchanges visitor information with other data providers by either of the following methods:
• Real-Time: Transfers data immediately as a user visits your site. This method is also known as a synchronous integration.
• Batch (Server-to-Server): Transfers data between servers on a set schedule after a visitor has left the page. This method is also
known as an out-of-band or asynchronous integration.
Choosing the right integration method depends on a combination of business requirements and the technical capabilities of
your data partner.
Prerequisites: Create a Trait Taxonomy
Before the integration process begins, you must provide a comprehensive segment taxonomy. The taxonomy will contain all
your traits organized in a logical hierarchy. Additionally, you must provide a translation key that maps key values to each trait.
How to Choose a Data Delivery Method
Describes technical and business reasons for sending data via synchronous (real-time) or asynchronous (server-to-server)
methodologies.
Selecting a Data Delivery Type
• Technical Considerations: Data delivery depends on the technical capabilities of the data partner. Audience Management
can send/receive data in real-time from the browser or by batch updates through offline, server-to-server communication
processes.
• Business Considerations: The business reasons for selecting one delivery method or another depend on the technical capabilities
of your destination partner and how you want to use this data. Typically, synchronous data transfers are useful when you need
to take action on user data immediately. Asynchronous data transfers may be useful when immediate action is not required
and when you have time to build deeper user profiles for later use.
Integration Use Cases
A use-case summary of Audience Management data integration methods along with the advantages and disadvantages of each.
Real-Time Server-to-Server Integrations
A real-time server-to-server data integration rapidly synchronizes user data between Audience Management servers and another
targeting system. In most cases, data exchange takes place within seconds or minutes, depending on the refresh rate of the
targeting system. Note, however, the targeted system determines this refresh interval, not Audience Management. Furthermore,
Integration Guides
214
the refresh rate can vary between different systems. A real-time, server-to-server integration is the preferred integration type
for data exchanges. Audience Management uses this method whenever targeting partners can support it.
Advantages:
• Lets you qualify users for segments without seeing them again on the page, in a video player, etc.
• Reduces the number of HTTP calls from the page. Fewer calls helps preserve the user experience.
• Helps with time sensitive targeting so you can take action on a qualified user quickly.
• Useful when moving to a DSP for offsite targeting.
Disadvantages:
Less useful for onsite targeting when you need to target the user on the same page, or the next page,
based on qualifying a user for that segment.
Server-to-Server Batch Integrations
A server-to-server batch integration bundles data and sends it to other systems at set intervals rather than in near real time. Data
transfer intervals can range from 2 to 24 hours. Some data providers support this integration type only. However, we've seen a
general trend away from batch integrations towards real-time integration methodologies.
Advantages:
• Lets you qualify users for segments without seeing them again on the page, in a video player,
etc.
• Useful for targeting that is not time sensitive.
Disadvantages:
The synchronization interval can delay targeting against the most current data.
Real-time Calls
Real-time calls exchange data with Audience Management immediately, as a user visits your site or takes action on the page.
With this method, targeting systems get the most updated segment qualification data and can take that information into account
during a content or ad delivery decision. Also, this process works with publisher ad servers where we update qualified segments
to a first-party cookie that is read into an ad call as key-value pairs. Currently, Audience Management uses real-time calls to
integrate with Target, Adobe Auditude/Primetime, and other content management systems.
Future developments include making these calls between servers rather than directly from the page. For example, Target could
make a single request for a new content area and then message Audience Management via server-to-server protocols. This helps
reduce calls made to the page. However, this process is in a proof-of-concept phase only. A production release has not been
scheduled. Furthermore, most external systems do not support this type of server-side call, although Audience Management
can support it now.
Advantages:
Lets you target the next page, content area, or ad impression based the most recent segment
qualification.
Disadvantages:
Adds a call to Audience Management from the page.
Pixels Syncs to Targeting Systems
Pixel synchronization maps segments to pixels on the page. The pixel fires and transmits data when a user qualifies for a particular
segment. Pixel synchronization is a rudimentary and unreliable data transfer mechanism. Top tier data providers and systems
rarely use it.
Advantages:
Real-time data transfers.
Integration Guides
Disadvantages:
215
• Can add a lot of client-side calls from the page.
• Unreliable for data transmission. 5% to 20% loss is normal.
Data Translation File
You must organize and classify traits into a data translation file (or taxonomy) before the data transfer process begins. Create
the translation file according to these specifications.
Purpose
A translation file classifies data according to uniform and logical hierarchy. This taxonomy helps you organize information
from general categories (e.g., geography) to more precise classifications (e.g., geography > United States > New York). Also, it
labels your data with to easy to understand names such as "Gender-Male" or "Color-green" instead of with SKUs, abbreviations,
or other classifications. The file lets Audience Management present your data in the UI in a readable, logical manner. You and
your data partners must create and share the translation file with Audience Management before any real-time or server-to-server
data transfers can begin.
Organization and File Format
You choose how to organize, classify, and name traits in the translation file.
Create the data taxonomy as a simple flat file or Excel spreadsheet. Also, the translation file structure is different depending on
how you work with trait data. Some customers use IDs to identify traits while others work with key-value pairs. See the following
examples.
Example 1: Trait IDs
If you identify traits by ID, your translation file should include a category name, separate subcategories (if required), and the
unique trait ID. Your translation file could look similar to this:
Category
Segment or Subcategory
Trait ID
Demographic
Age 18-25
18
Demographic
Education - College Grad
19
Career
Accounting
20
Example 2: Key-Value Pairs
If you work with traits as key-value pairs, your translation file should include the key, value, and trait name. Your translation
file could look similar to this:
Key
Value
Name
gender
m
Gender - Male
gender
f
Gender - Female
age group
18-24
Age 18 - 24
signed up
y
Has signed up
signed up
n
Has not signed up
Integration Guides
216
Key-Value Translation File Contents are Case, Space, and Character Sensitive
The key-values in the translation file are case, space, and character sensitive. They must match the data your servers send to
Audience Management. Our system drops records when it cannot match those key-values to a corresponding record in the
translation table. For example, if the actual server data passed in contains a key-value like "city"="San Francisco" and the
translation file contains "city"="san francisco" then this record does not get processed. Make sure the contents of your
translation file match the contents of the actual data file.
Updates and Revisions
Follow these guidelines when you need to update the translation file:
• Update limits: Limit updates to once per month.
• Update contents: Send updated content in a flat file or spreadsheet.
• Maintain consistency: Avoid significant structural changes in the translation file. These can be difficult to integrate into a
running, real-time system.
Send the Translation File to Audience Management
Mail your taxonomy (and any updates) to DL-Data-Partners-AAM <Data-Partners-AAM@adobe.com>. You'll
receive a notification when the file import or update process is complete.
Real-Time Data Transfer Process
A general overview of how Audience Management performs a synchronous data exchange with a third-party vendor.
Real-Time Data Transfer
Real-time data transfers send and receive segment IDs as a user visits or takes action on your site. Typically, synchronous data
transfers are useful when you need to qualify or segment users right away, as they navigate through your inventory.
Data Integration Steps
The real-time data integration process works as follows:
1. A user visits a customer's site that contains Audience Management code.
2. Audience Management loads an Iframe and makes a call to the Data Collection Server (DCS).
3. The DCS calls the third-party server (in real time) to check if the vendor has any segment information about the user.
4. The third party returns segment information about that user to Audience Management.
5. Audience Management ingests segment information and makes it available for targeting.
Integration Guides
217
Batch Data Transfer Process
A general overview of how Audience Management exchanges data synchronously (in real time) with a third-party vendor.
Batch Data Integration
The batch (server-to-server) data integration process follows most of the steps outlined in the real-time data transfer process.
However, instead of returning segment IDs immediately, user information is saved to our servers and synchronized with a
third-party data provider at regular intervals. The asynchronous data transfer process is useful when:
• Immediate data transfers are not required.
• Collecting data to build a large pool of segmented users.
• You want to reduce data discrepancies and HTTP calls from the browser.
Data Integration Steps
1.
2.
3.
4.
A user visits a customer site.
Audience Management and the third-party data provider assign the visitor a unique ID (usually with a cookie).
Audience Management calls the third-party data provider to match visitor IDs.
A scheduled request, usually on a daily interval, exchanges visitor segment data between Audience Management and your
third-party data provider.
Integration Guides
218
For information describing the time frames when Audience Management processes inbound and outbound Server-to-Server
(S2S) file transfers, see Reporting and File Transfer Time-Frame Guidelines.
Customer Data Feeds
Obtain hourly data log files created by the Data Collection Servers that contain user data (IDs and associated qualified traits).
Customer Data Feed Overview
Information about working with customer data feeds, including input/output, fields, filtering, and notifications.
Audience Management delivers files every hour using Amazon S3. You should use the HTTPS option to ensure that data is
encrypted during transit. Audience Management does not currently encrypt the data.
Using Amazon S3 lets Audience Management use its distributed environment to deliver files in a timely manner. Audience
Management sends an hourly .info file to notify you that data for the hourly process is complete.
For more information about the benefits of using Amazon S3 and links to help you get your implementation up and running,
see About Amazon S3.
Note: Audience Management does not allow the use of FTP, SFTP, or SCP to obtain customer data feed log files.
Input/Output
Information about the input/output that Audience Management performs on customer data feeds.
Integration Guides
219
Input
The input to this hourly process is data from the raw DCS logs. Audience Management starts processing this data as soon as a
full hour has passed since the last process finished.
Output
Consider the following information when working with the output log files:
• You can have the data delivered to one or to multiple S3 buckets. By default, Audience Management delivers data to the bucket
mentioned in the next bullet.
• The default bucket is owned by Audience Management and is named aam-cdf.
• In this bucket, each client has its own directory with access to that directory only. The directory is named after the client, for
example "atc" for AutoTrader, and is located at the root of the S3 bucket.
• Audience Management provides you with a set of AWS credentials (access key and secret key) that you can use to authenticate
to AWS and download the data.
• You will have only Read access to this bucket and directory. You will not have Write access.
• If you want another S3 bucket in addition to the standard S3 bucket we provide, it is your responsibility to manage this bucket.
• The directory in S3 where the files are delivered can be customized per client, but the default is
%(name)s/day=%(day)s/hour=%(hour)s/, where %(name)s is the name of the client, %(day)s is the day in format
yyyy-mm-dd and %(hour)s is the 0-padded hour from "00" to "23" (for example "01" or "19"). If you want to customize this
path, contact your Audience Management Account Manager.
• Data is compressed with the gzip compression codec by default. If you want to use a different kind of compression, you must
contact the Audience Management team, which will evaluate with engineering if your compression codec can be supported.
• For every hour, multiple files are delivered instead of one large file. Each file is named with the following convention:
AAM_CDF_%(pid)s_%(index)s_%(failures)s.%(compression)s, where:
• %(pid)s is the client PID
• %(index)s is a 0-padded number (five characters) corresponding to the data block ID.
There is no ordering so the number doesn't mean anything. The number is used simply to break data down into multiple
blocks to take advantage of parallelization. We cannot make any guarantee regarding the number of files. For example an
index can be "00000", or "00001," or "00123."
• %(failures)s represents the number of failures before a file was successfully delivered. This number is usually 0, but in
some situations, this number is non-zero. This does not impact you whatsoever because the data is complete if it's in S3. This
number is useful for operational purposes only.
• %(compression)s is an extension representing the compression codec used. Because the default is using gzip compression,
the default extension will be gz. If you request a different compression, this extension may differ.
This naming convention is the default. If you want to modify the prefix (AAM_CDF), contact your Audience Management
Account Manager.
• You cannot make any assumption as to how large each of these files might be. Similarly, not all of the files will be the same
exact size. As a general guideline, each file should be between 10 MB and 100 MB.
• If there was no data for a particular hour, the directory contains a .info file only (no data file).
• A missing directory means that something is wrong on the Audience Management side, and you can expect to see this directory
appear in the future.
• You can make no assumption as to how many files are delivered. It will typically be around a hundred files, but in practice it
could be anywhere between 1 and 1 million, depending on the data size.
• Data is deleted after 14 days in the S3 buckets that Audience Management manages. If you have different needs, contact your
Audience Management Account Manager.
Fields
List of standard fields used in customer data fields.
Integration Guides
Field
EventTime
Uuid
SiteId
RealizedTraits
RealizedSegments
RequestParameters
220
Value/Example
Description
2013-09-23 21:05:24
Human-readable string representing the time when the
event happened, in the format of "1970-01-01 00:00:00".
00007682154970027091624395207520495427
The Audience Management User ID is represented by
a 38-digit string.
18
ID for the TIM container deployed. For more
information, see The TIM Container.
232961,10787
Array containing the traits that were realized on the
current event call.
2673,2672,32619,1734
Array containing the segments that were realized on the
current event call. This will not contain segments that
are realized with onboarded traits.
d_cb:demdexDestCallback1379970391554,d_dst:1 Dictionary containing key/values representing the
request parameters passed on the event call.
Referer
IP
Marketing
Cloud ID
AllSegments
AllTraits
http://www.acmeauto.com/dealers/dda/index.jsp?dealership_view_name=www.americanauto.us The referrer URL.
70.37.207.149
Raw IP of the visitor tied to this event.
00246995636614562581647886982853007892
The Adobe Marketing Cloud user ID.
2673,2672,32619,1734
All segments realized based on both new traits and
pre-existing ones.
232961,10787
A list of unique trait IDs representing which traits this
user qualifies for. This includes newly realized traits in
this call as well as old ones.
Note that RealizedTraits and RealizedSegments are arrays, while RequestParameters is a dictionary.
In the reports, the following delimiters are used:
• For field separation, the ASCII character corresponding to code 01. This is usually referred to as SOH (start of heading).
• For array separation, the ASCII character corresponding to code 02. This is usually referred to as STX (start of text).
• For dictionaries:
• Key/value separation will be the ASCII character corresponding to code 03. This is usually referred to as ETX (end of text).
• Elements separation will be the same as for arrays (02). These separator characters occur very infrequently in raw data, so
there is no risk of having data mixed up.
If you require additional fields, contact your Audience Management Account Manager.
Integration Guides
221
Note: For more information about common data collection and integration questions and issues, see Data Collection and
Product Integration FAQ.
Filtering
Information about how Audience Management filters customer data feeds.
Audience Management performs the following filtering for each client:
• Filters the events for this PID only.
• Filters events for this particular day and hour.
• Excludes events that have a request parameter named d_event, regardless of its value. We remove these events because this
key is a marker that the event was just being used to track a pixeled creative for advertising delivery attribution.
These filters are standard. If you want different filtering options, contact your Audience Management Account Manager.
Notifications
Information about notifications that Audience Management provides to let you know if a process is complete.
Even though Audience Management writes data to Amazon S3, you need a way to know if the data you are looking at for a given
hour is complete, or if it is still being written. For this purpose, Audience Management includes a .info file. This .info file
is uploaded to S3 in each hourly directory after all the data has been written. If this file exists, you can confidently download the
data for this hour.
In addition to serving as a notification, this file also contains some useful information in the form of a JSON object:
• Totals: Contains global metrics aggregated across all files:
• Day: Day for which the data is available.
• Hour: Hour for which the data is available. Along with Day, this can be a bit redundant because the directories already contain
day and hour, but can be useful if you do not want to manually parse the directory names.
• TotalByteSize: Total number of bytes contained, summed over all of the files delivered.
• TotalNumberFiles: Total number of files uploaded for this hour.
• Files: Contains metrics specific to each file:
• FileByteSize: The size in bytes for that file.
• FileName: The name of the file.
• FileSequenceNumber: The index of this file. This is a monotonically increasing number, starting at 1.
• FileChecksumMD5 :The MD5 checksum of the file.
Example .info file:
{
"Files": [
{
"FileByteSize": 2709730,
"FileChecksumMD5": "a9ea418e79511642cff11c2a898037dc",
"FileName": "AAM_CDF_1109_000000_0.gz",
"FileSequenceNumber": 1
},
{
"FileByteSize": 2783351,
"FileChecksumMD5": "7b469485d60274b6991acd0817855840",
"FileName": "AAM_CDF_1109_000001_0.gz",
"FileSequenceNumber": 2
Integration Guides
222
},
...
{
"FileByteSize": 2669570,
"FileChecksumMD5": "348a7170f0d1a6199550cfa5c00b725b",
"FileName": "AAM_CDF_1109_000054_0.gz",
"FileSequenceNumber": 55
},
{
"FileByteSize": 2757124,
"FileChecksumMD5": "c6f8bd48b950813aa87e6f84f287f449",
"FileName": "AAM_CDF_1109_000055_0.gz",
"FileSequenceNumber": 56
}
],
"Totals": {
"Day": "2013-09-26",
"Hour": "18",
"TotalByteSize": 150092997,
"TotalNumberFiles": 56
}
}
The .info file is prefixed with the same prefix as the regular data file. The following filename illustrates the naming convention:
AAM_CDF_1109.info
Customer Data Feeds Implementation
For any new integration, please consult with you Audience Management Account Manager.
Customer Data Feeds Getting Started
Information to help you understand and start working with customer data feeds.
This section contains examples using the customer data feeds system for a fictional customer named "anonymous" with a PID
of 1234. These examples use a tool called s3cmd, which is a simple, standard and easy way to access files stored in Amazon S3.
More information can be found on the S3 Tools Organization website.
If you want to access S3 with programming languages, several APIs are available, for example:
Python: Access S3 using the boto library.
Java: Access S3 using the Java AWS SDK.
C++: Access S3 using the libs3 library.
Determine if Files are Available
Determine whether customer data feed files are available for a given day and hour.
$ s3cmd ls s3://aam-cdf/anonymous/day=2013-10-01/hour=18/
2013-10-01 19:29
14328
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234.info
2013-10-01 19:27
2791012
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000000_0.gz
2013-10-01 19:27
2869216
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000001_0.gz
2013-10-01 19:27
2726614
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000002_0.gz
2013-10-01 19:27
2758371
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000003_0.gz
2013-10-01 19:27
2915035
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000004_0.gz
2013-10-01 19:27
2874818
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000005_0.gz
2013-10-01 19:27
2822752
Integration Guides
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000006_0.gz
2013-10-01 19:27
2931709
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000007_0.gz
2013-10-01 19:28
2873344
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000008_0.gz
2013-10-01 19:28
2846825
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000009_0.gz
2013-10-01 19:28
2896432
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000010_0.gz
2013-10-01 19:28
2838296
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000011_0.gz
2013-10-01 19:28
2867915
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000012_0.gz
2013-10-01 19:28
2883941
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000013_0.gz
2013-10-01 19:28
2927182
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000014_0.gz
2013-10-01 19:28
2978566
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000015_0.gz
2013-10-01 19:28
2922342
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000016_0.gz
2013-10-01 19:28
2955889
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000017_0.gz
2013-10-01 19:28
2694690
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000018_0.gz
2013-10-01 19:28
2976889
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000019_0.gz
2013-10-01 19:28
2928639
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000020_0.gz
2013-10-01 19:28
2868285
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000021_0.gz
2013-10-01 19:28
2756921
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000022_0.gz
2013-10-01 19:28
2834288
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000023_0.gz
2013-10-01 19:28
2807185
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000024_0.gz
2013-10-01 19:28
2851014
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000025_0.gz
2013-10-01 19:28
3055701
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000026_0.gz
2013-10-01 19:28
2684026
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000027_0.gz
2013-10-01 19:28
2857990
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000028_0.gz
2013-10-01 19:28
2646229
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000029_0.gz
2013-10-01 19:28
2948097
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000030_0.gz
2013-10-01 19:28
2746211
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000031_0.gz
2013-10-01 19:28
2858033
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000032_0.gz
2013-10-01 19:28
2718488
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000033_0.gz
2013-10-01 19:28
2825010
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000034_0.gz
2013-10-01 19:28
2747415
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000035_0.gz
2013-10-01 19:28
2971541
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000036_0.gz
2013-10-01 19:28
2892273
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000037_0.gz
2013-10-01 19:28
2873868
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000038_0.gz
2013-10-01 19:28
2895880
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000039_0.gz
2013-10-01 19:28
2975552
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000040_0.gz
223
Integration Guides
224
2013-10-01 19:28
2941391
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000041_0.gz
2013-10-01 19:28
3042072
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000042_0.gz
2013-10-01 19:28
2979775
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000043_0.gz
2013-10-01 19:28
2873350
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000044_0.gz
2013-10-01 19:28
2869144
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000045_0.gz
2013-10-01 19:28
2824391
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000046_0.gz
2013-10-01 19:28
3058264
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000047_0.gz
2013-10-01 19:28
2841097
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000048_0.gz
2013-10-01 19:28
2817626
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000049_0.gz
2013-10-01 19:28
2906812
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000050_0.gz
2013-10-01 19:28
2937478
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000051_0.gz
2013-10-01 19:28
2953161
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000052_0.gz
2013-10-01 19:28
3055322
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000053_0.gz
2013-10-01 19:28
2974555
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000054_0.gz
2013-10-01 19:28
2836694
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000055_0.gz
2013-10-01 19:28
2787243
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000056_0.gz
2013-10-01 19:29
2796356
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000057_0.gz
2013-10-01 19:29
2801108
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000058_0.gz
2013-10-01 19:29
2895750
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000059_0.gz
2013-10-01 19:29
2784504
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000060_0.gz
2013-10-01 19:29
3125536
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000061_0.gz
2013-10-01 19:29
2885012
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000062_0.gz
2013-10-01 19:29
2767172
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000063_0.gz
2013-10-01 19:29
2803890
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000064_0.gz
Download a Particular File
Command to download a specified customer data feed file.
$ s3cmd get s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000004_0.gz /path/to/dir
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000004_0.gz ->
/path/to/dir/AAM_CDF_1234_000004_0.gz [1 of 1]
2915035 of 2915035
100% in
0s
8.05 MB/s done
$ ls /path/to/dir
AAM_CDF_1234_000004_0.gz
Synchronize a Full Hour of Data
Command to synchronize a full hour of data to your local disk.
Note that the output directory must already exist.
$ s3cmd sync s3://aam-cdf/anonymous/day=2013-10-01/hour=18/ /path/to/dir
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234.info -> /path/to/dir/AAM_CDF_1234.info
Integration Guides
[1 of 66]
14328 of 14328
100% in
0s
217.98 kB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000000_0.gz
/path/to/dir/AAM_CDF_1234_000000_0.gz [2 of 66]
2791012 of 2791012
100% in
0s
6.40 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000001_0.gz
/path/to/dir/AAM_CDF_1234_000001_0.gz [3 of 66]
2869216 of 2869216
100% in
0s
4.39 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000002_0.gz
/path/to/dir/AAM_CDF_1234_000002_0.gz [4 of 66]
2726614 of 2726614
100% in
0s
7.89 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000003_0.gz
/path/to/dir/AAM_CDF_1234_000003_0.gz [5 of 66]
2758371 of 2758371
100% in
0s
9.40 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000004_0.gz
/path/to/dir/AAM_CDF_1234_000004_0.gz [6 of 66]
2915035 of 2915035
100% in
0s
10.06 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000005_0.gz
/path/to/dir/AAM_CDF_1234_000005_0.gz [7 of 66]
2874818 of 2874818
100% in
0s
7.94 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000006_0.gz
/path/to/dir/AAM_CDF_1234_000006_0.gz [8 of 66]
2822752 of 2822752
100% in
0s
9.67 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000007_0.gz
/path/to/dir/AAM_CDF_1234_000007_0.gz [9 of 66]
2931709 of 2931709
100% in
0s
9.59 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000008_0.gz
/path/to/dir/AAM_CDF_1234_000008_0.gz [10 of 66]
2873344 of 2873344
100% in
0s
6.01 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000009_0.gz
/path/to/dir/AAM_CDF_1234_000009_0.gz [11 of 66]
2846825 of 2846825
100% in
0s
5.99 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000010_0.gz
/path/to/dir/AAM_CDF_1234_000010_0.gz [12 of 66]
2896432 of 2896432
100% in
0s
4.23 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000011_0.gz
/path/to/dir/AAM_CDF_1234_000011_0.gz [13 of 66]
2838296 of 2838296
100% in
0s
6.18 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000012_0.gz
/path/to/dir/AAM_CDF_1234_000012_0.gz [14 of 66]
2867915 of 2867915
100% in
1s
2.55 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000013_0.gz
/path/to/dirt/AAM_CDF_1234_000013_0.gz [15 of 66]
2883941 of 2883941
100% in
0s
4.86 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000014_0.gz
/path/to/dir/AAM_CDF_1234_000014_0.gz [16 of 66]
2927182 of 2927182
100% in
0s
4.87 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000015_0.gz
/path/to/dir/AAM_CDF_1234_000015_0.gz [17 of 66]
2978566 of 2978566
100% in
0s
9.29 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000016_0.gz
/path/to/dir/AAM_CDF_1234_000016_0.gz [18 of 66]
2922342 of 2922342
100% in
0s
6.48 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000017_0.gz
/path/to/dir/AAM_CDF_1234_000017_0.gz [19 of 66]
2955889 of 2955889
100% in
0s
4.66 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000018_0.gz
/path/to/dir/AAM_CDF_1234_000018_0.gz [20 of 66]
2694690 of 2694690
100% in
0s
3.79 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000019_0.gz
/path/to/dir/AAM_CDF_1234_000019_0.gz [21 of 66]
2976889 of 2976889
100% in
0s
5.59 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000020_0.gz
/path/to/dir/AAM_CDF_1234_000020_0.gz [22 of 66]
2928639 of 2928639
100% in
0s
6.78 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000021_0.gz
/path/to/dir/AAM_CDF_1234_000021_0.gz [23 of 66]
2868285 of 2868285
100% in
1s
2.50 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000022_0.gz
225
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
Integration Guides
/path/to/dir/AAM_CDF_1234_000022_0.gz [24 of 66]
2756921 of 2756921
100% in
0s
6.78 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000023_0.gz
/path/to/dir/AAM_CDF_1234_000023_0.gz [25 of 66]
2834288 of 2834288
100% in
0s
7.34 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000024_0.gz
/path/to/dir/AAM_CDF_1234_000024_0.gz [26 of 66]
2807185 of 2807185
100% in
0s
7.95 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000025_0.gz
/path/to/dir/AAM_CDF_1234_000025_0.gz [27 of 66]
2851014 of 2851014
100% in
0s
6.72 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000026_0.gz
/path/to/dir/AAM_CDF_1234_000026_0.gz [28 of 66]
3055701 of 3055701
100% in
0s
12.30 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000027_0.gz
/path/to/dir/AAM_CDF_1234_000027_0.gz [29 of 66]
2684026 of 2684026
100% in
0s
5.88 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000028_0.gz
/path/to/dir/AAM_CDF_1234_000028_0.gz [30 of 66]
2857990 of 2857990
100% in
0s
11.65 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000029_0.gz
/path/to/dir/AAM_CDF_1234_000029_0.gz [31 of 66]
2646229 of 2646229
100% in
0s
6.26 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000030_0.gz
/path/to/dir/AAM_CDF_1234_000030_0.gz [32 of 66]
2948097 of 2948097
100% in
0s
6.40 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000031_0.gz
/path/to/dir/AAM_CDF_1234_000031_0.gz [33 of 66]
2746211 of 2746211
100% in
0s
6.31 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000032_0.gz
/path/to/dir/AAM_CDF_1234_000032_0.gz [34 of 66]
2858033 of 2858033
100% in
0s
11.56 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000033_0.gz
/path/to/dir/AAM_CDF_1234_000033_0.gz [35 of 66]
2718488 of 2718488
100% in
0s
6.79 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000034_0.gz
/path/to/dir/AAM_CDF_1234_000034_0.gz [36 of 66]
2825010 of 2825010
100% in
0s
4.98 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000035_0.gz
/path/to/dir/AAM_CDF_1234_000035_0.gz [37 of 66]
2747415 of 2747415
100% in
0s
9.72 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000036_0.gz
/path/to/dir/AAM_CDF_1234_000036_0.gz [38 of 66]
2971541 of 2971541
100% in
0s
7.54 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000037_0.gz
/path/to/dir/AAM_CDF_1234_000037_0.gz [39 of 66]
2892273 of 2892273
100% in
0s
9.25 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000038_0.gz
/path/to/dir/AAM_CDF_1234_000038_0.gz [40 of 66]
2873868 of 2873868
100% in
0s
14.11 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000039_0.gz
/path/to/dir/AAM_CDF_1234_000039_0.gz [41 of 66]
2895880 of 2895880
100% in
0s
7.33 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000040_0.gz
/path/to/dir/AAM_CDF_1234_000040_0.gz [42 of 66]
2975552 of 2975552
100% in
0s
4.08 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000041_0.gz
/path/to/dir/AAM_CDF_1234_000041_0.gz [43 of 66]
2941391 of 2941391
100% in
0s
9.10 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000042_0.gz
/path/to/dir/AAM_CDF_1234_000042_0.gz [44 of 66]
3042072 of 3042072
100% in
0s
17.49 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000043_0.gz
/path/to/dir/AAM_CDF_1234_000043_0.gz [45 of 66]
2979775 of 2979775
100% in
0s
5.70 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000044_0.gz
/path/to/dir/AAM_CDF_1234_000044_0.gz [46 of 66]
2873350 of 2873350
100% in
0s
9.12 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000045_0.gz
226
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
Integration Guides
/path/to/dir/AAM_CDF_1234_000045_0.gz [47 of 66]
2869144 of 2869144
100% in
0s
6.66 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000046_0.gz
/path/to/dir/AAM_CDF_1234_000046_0.gz [48 of 66]
2824391 of 2824391
100% in
0s
7.28 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000047_0.gz
/path/to/dir/AAM_CDF_1234_000047_0.gz [49 of 66]
3058264 of 3058264
100% in
0s
6.14 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000048_0.gz
/path/to/dir/AAM_CDF_1234_000048_0.gz [50 of 66]
2841097 of 2841097
100% in
0s
8.21 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000049_0.gz
/path/to/dir/AAM_CDF_1234_000049_0.gz [51 of 66]
2817626 of 2817626
100% in
0s
8.89 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000050_0.gz
/path/to/dir/AAM_CDF_1234_000050_0.gz [52 of 66]
2906812 of 2906812
100% in
0s
9.44 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000051_0.gz
/path/to/dir/AAM_CDF_1234_000051_0.gz [53 of 66]
2937478 of 2937478
100% in
0s
12.87 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000052_0.gz
/path/to/dir/AAM_CDF_1234_000052_0.gz [54 of 66]
2953161 of 2953161
100% in
0s
7.66 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000053_0.gz
/path/to/dir/AAM_CDF_1234_000053_0.gz [55 of 66]
3055322 of 3055322
100% in
0s
9.75 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000054_0.gz
/path/to/dir/AAM_CDF_1234_000054_0.gz [56 of 66]
2974555 of 2974555
100% in
0s
8.12 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000055_0.gz
/path/to/dir/AAM_CDF_1234_000055_0.gz [57 of 66]
2836694 of 2836694
100% in
0s
7.59 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000056_0.gz
/path/to/dir/AAM_CDF_1234_000056_0.gz [58 of 66]
2787243 of 2787243
100% in
0s
10.29 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000057_0.gz
/path/to/dir/AAM_CDF_1234_000057_0.gz [59 of 66]
2796356 of 2796356
100% in
0s
7.83 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000058_0.gz
/path/to/dir/AAM_CDF_1234_000058_0.gz [60 of 66]
2801108 of 2801108
100% in
0s
8.47 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000059_0.gz
/path/to/dir/AAM_CDF_1234_000059_0.gz [61 of 66]
2895750 of 2895750
100% in
0s
11.84 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000060_0.gz
/path/to/dir/AAM_CDF_1234_000060_0.gz [62 of 66]
2784504 of 2784504
100% in
0s
6.44 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000061_0.gz
/path/to/dir/AAM_CDF_1234_000061_0.gz [63 of 66]
3125536 of 3125536
100% in
0s
7.94 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000062_0.gz
/path/to/dir/AAM_CDF_1234_000062_0.gz [64 of 66]
2885012 of 2885012
100% in
0s
8.63 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000063_0.gz
/path/to/dir/AAM_CDF_1234_000063_0.gz [65 of 66]
2767172 of 2767172
100% in
0s
8.24 MB/s done
s3://aam-cdf/anonymous/day=2013-10-01/hour=18/AAM_CDF_1234_000064_0.gz
/path/to/dir/AAM_CDF_1234_000064_0.gz [66 of 66]
2803890 of 2803890
100% in
0s
8.33 MB/s done
Done. Downloaded 186666515 bytes in 26.5 seconds, 6.72 MB/s
227
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
Sample File
Sample portion of one of the files contained in this directory.
$ zcat /path/to/dir/AAM_CDF_1234_000001_0.gz | head -5 | tr '\001' '|' | tr '\002' ',' | tr
'\003' ':'
2013-10-01
18:11:09|00042314524877950034124736683724775790|1083|318722|32619|\N|http://www.acmeflights.com/?cs:e=m&cs:q=&cs:m=&cs:cid=&seg=dap&cs:tv=449&cs:a=pb_retention_search&cs:pro=cpb&cs:ki=581078065|199.30.25.94
Integration Guides
228
2013-10-01
17:48:52|00067720900173020484560039672852520207|684|64766|\N|d_cb:demdexDestCallback1380649775741,d_dst:1,d_px:19400,d_ld:vin_crm%3D5138.1380649775159.4959%26containerid%3D684%26_ts%3D1380649775741,d_rtbd:json,d_cts:1|http://www.acmemotors.com/|165.234.104.46
2013-10-01
17:48:52|00067720900173020484560039672852520207|684|64675|32619,20406,20407,2246,20396|d_cb:demdexDestCallback1380649775740,d_dst:1,d_px:19315,d_ld:containerid%3D684%26_ts%3D1380649775740,d_rtbd:json,d_cts:1|http://www.acmemotors.com/|165.234.104.46
2013-10-01
17:49:14|00067720900173020484560039672852520207|684|64766|\N|d_cb:demdexDestCallback1380649797960,d_dst:1,d_px:19400,d_ld:vin_crm%3D5138.1380649775159.4959%26containerid%3D684%26_ts%3D1380649797960,d_rtbd:json,d_cts:1|http://www.acmemotors.com/inventory/newsearch/Used/|165.234.104.46
2013-10-01
17:49:14|00067720900173020484560039672852520207|684|64675|32619,20406,20407,2246,20396|d_cb:demdexDestCallback1380649797957,d_dst:1,d_px:19315,d_ld:containerid%3D684%26_ts%3D1380649797957,d_rtbd:json,d_cts:1|http://www.acmemotors.com/inventory/newsearch/Used/|165.234.104.46
Note that for readability purposes, some binary delimiter characters have been replaced with readable characters.
Sending Audience Data
Send audience data from other sources to Audience Management.
Real-Time Inbound Data Integration
Information about the Real-Time Audience Management integration.
Real-Time Data Transfer Process Described
A general overview of how Audience Management performs real-time data transfers with a third-party content provider.
Real-Time Data Transfers
Real-time data transfers send and receive segment IDs as a user visits or takes action on your site. Typically, synchronous data
transfers are useful when you need to qualify or segment users right away, as they navigate through your inventory.
Data Integration Steps
The real-time data integration process works as follows:
1. A user visits a customer's site that contains Audience Management code.
2. Audience Management loads an iframe and makes a call to our Data Collection Server (DCS).
3. The DCS calls the third-party server (in real time) to check if the vendor has any segment information about the user.
4. The content provider returns segment information about that user to Audience Management.
5. Audience Management receives this segment information and makes it available for targeting and building new traits and
segments.
Integration Guides
229
Technical Specifications for Inbound, Real-Time Data Transfers
Third-party content providers can expect to exchange data with Audience Management according to these technical specifications.
A real-time (synchronous) integration transfers data in near-real time as a user visits or takes actions on your site. Technical,
engineering, or development teams should use this material to help set up real-time data transfers with Audience Management.
Pixel-based Data Transfers
Simple pixels (also called traits) perform real-time data transfers. The Audience Management interface lets clients create any
number of pixels on a self-service basis. Pixel strings consist of simple IDs or key-value pairs.
To enable inbound data transfers, the vendor and client would:
1. Determine which segments the vendor and client wants to use.
2. Create Audience Management pixels (traits) for each segment and deliver them to the vendor.
3. The vendor fires a relevant signal upon encountering a user that qualifies for the segments identified in Step 1.
Examples
A basic pixel call could look similar to the URL below. This pixel fires a single data point with ID 1234.
http://something.demdex.net/event?d_sid=1234"
Also, you can serialize pixels to help reduce HTTP calls from the page. Append additional segment IDs to the URL string as
shown in the following example:
http://something.demdex.net/event?d_sid=1234,5678,9876,5432"
Real-Time Inbound Data Ingestion
The real-time inbound data ingestion process uses a series of HTTP requests from a user's browser to pass in data to Audience
Management.
Integration Guides
230
Inbound data should be formatted as key-value pairs called signals. Typically, each signal is mapped to a segment created or
managed through the user interface or API.
URL String Parameters and Syntax
The URL for an inbound data transfer should contain the variables described below. Remember, create and submit a data
taxonomy to Audience Management before setting up real-time data transfers.
Note: Replace italicized content with actual parameter values.
Parameter
Description
<KEY>
A unique identifier in a key-value pair (e.g., gender, color, price).
<VAL>
A variable that belongs to the data set defined by the key (e.g., gender=male,
color=green, price=100)
URL Syntax
During a real-time inbound data ingestion process, a properly formatted URL string uses the following syntax:
http://client.demdex.net/event?KEY1=VALA&KEYB=VAL2&KEY2=VALC
Data Translation File
You must organize and classify traits into a data translation file (or taxonomy) before the data transfer process begins. Create
the translation file according to these specifications.
Purpose
A translation file classifies data according to uniform and logical hierarchy. This taxonomy helps you organize information
from general categories (e.g., geography) to more precise classifications (e.g., geography > United States > New York). Also, it
labels your data with to easy to understand names such as "Gender-Male" or "Color-green" instead of with SKUs, abbreviations,
or other classifications. The file lets Audience Management present your data in the UI in a readable, logical manner. You and
your data partners must create and share the translation file with Audience Management before any real-time or server-to-server
data transfers can begin.
Organization and File Format
You choose how to organize, classify, and name traits in the translation file.
Create the data taxonomy as a simple flat file or Excel spreadsheet. Also, the translation file structure is different depending on
how you work with trait data. Some customers use IDs to identify traits while others work with key-value pairs. See the following
examples.
Example 1: Trait IDs
If you identify traits by ID, your translation file should include a category name, separate subcategories (if required), and the
unique trait ID. Your translation file could look similar to this:
Category
Segment or Subcategory
Trait ID
Demographic
Age 18-25
18
Demographic
Education - College Grad
19
Integration Guides
231
Category
Segment or Subcategory
Trait ID
Career
Accounting
20
Example 2: Key-Value Pairs
If you work with traits as key-value pairs, your translation file should include the key, value, and trait name. Your translation
file could look similar to this:
Key
Value
Name
gender
m
Gender - Male
gender
f
Gender - Female
age group
18-24
Age 18 - 24
signed up
y
Has signed up
signed up
n
Has not signed up
Key-Value Translation File Contents are Case, Space, and Character Sensitive
The key-values in the translation file are case, space, and character sensitive. They must match the data your servers send to
Audience Management. Our system drops records when it cannot match those key-values to a corresponding record in the
translation table. For example, if the actual server data passed in contains a key-value like "city"="San Francisco" and the
translation file contains "city"="san francisco" then this record does not get processed. Make sure the contents of your
translation file match the contents of the actual data file.
Updates and Revisions
Follow these guidelines when you need to update the translation file:
• Update limits: Limit updates to once per month.
• Update contents: Send updated content in a flat file or spreadsheet.
• Maintain consistency: Avoid significant structural changes in the translation file. These can be difficult to integrate into a
running, real-time system.
Send the Translation File to Audience Management
Mail your taxonomy (and any updates) to partner-taxonomy-demdex@adobe.com. You'll receive a notification when
the file import or update process is complete.
Batch Data Transfer Process Described
A general overview of how Audience Management performs an asynchronous batch data exchange with a third-party vendor.
Batch Data Integration
The batch data integration process saves visitor information on our servers and synchronizes that material with data sent by a
provider at regular intervals. The asynchronous data transfer process is useful when:
• Immediate data transfers are not required.
• Collecting data to build a large pool of segmented users.
• You want to reduce data discrepancies and HTTP calls from the browser.
Integration Guides
232
Data Integration Steps
1.
2.
3.
4.
A user visits a customer site.
Audience Management and the third-party data provider assign the visitor a unique ID (usually with a cookie).
Audience Management calls the third-party data provider to match visitor IDs.
A scheduled request, usually on a daily interval, exchanges visitor segment data between Audience Management and your
third-party data provider.
5. Whenever an inbound Server-to-Server file is processed, a receipt is sent via email to partner solutions and, if configured,
to the partner. For more information, see Sample Message to Partners after Inbound Processing.
Send Batch Data to Audience Management Overview
An overview for technical and non-technical customers who want to bring data from other systems (offline) into Audience
Management.
Advantages
You can make data from other systems available in Audience Management. Our system can help you unlock value and leverage
user data that you've collected previously. This includes information about purchases, customer surveys, registration data, CRM
databases, etc. While each integration presents its own challenges, they all share these common steps. Review this material to
help reduce the effort required to bring your offline data online.
Step 1: Synchronize User IDs
During synchronization, Audience Management assigns unique IDs to clients and their users. These IDs are known as the Data
Provider ID (DPID) and Unique User ID (UUID), respectively. Audience Management uses the DPID and UUID to identify
users and qualify them for traits, segments, audience groups, and for reporting. Additionally, our data collection code (DIL)
Integration Guides
233
looks for these IDs to capture visitor data from your website. When this step is complete, Audience Management and your
offline repository should contain corresponding IDs for each user record.
Important considerations about this step:
• Client ID placement: Audience Management needs to know where your client ID appears on your website (e.g., is it stored
in a cookie, an Analytics variable, in page code, etc.).
• Exclude PII: User IDs must not contain personally identifiable information (PII).
• Case and content sensitivity: During a real-time data sync, user IDs captured from your site by Audience Management must
correspond to IDs passed in from your offline repository. For example, if offline records hold information about User123, but
your site renders that ID as USER123, Audience Management sees these as different visitors. As a result, online information
for this visitor cannot be associated with the corresponding records in your offline database. IDs must match exactly.
See ID Synchronization for Inbound Data Transfers.
Step 2: Create a Translation File
A translation file classifies data according to uniform and logical hierarchy. It is a taxonomy that helps you organize information
from general categories (e.g., geography) to more precise classifications (e.g., geography > United States > New York). Also, it
labels data with to easy to understand names such as "gender=male" or "color=green" instead of with your internal SKUs,
abbreviations, or other names. The file lets Audience Management display this information in a readable, logical manner. You
and your data partners must create and share the translation file with Audience Management before any real-time or
server-to-server data transfers can begin. You can update this file on a schedule relevant to your business needs.
Important considerations about this step:
• Create a comprehensive list: The translation file must include all the possible values that can be passed in on a particular key.
For example, if you have category key called "color" and it accepts the values "red," "green," and "blue," the translation file must
contain all those elements.
• Case and content sensitivity: The key-values in the file must match the values actually passed in to Audience Management
from your website.
See Data Translation File.
Step 3: Data File Format
File names and content follow very strict guidelines. You must name and organize data files according to these specifications:
Data File Element
Format Requirements
Name
ftp_dpm_<DPID>_<DPID_TARGET_DATA_OWNER>_<TIMESTAMP>.sync
Contents
<UUID><TAB><TIMESTAMP>-<SEGMENT_1>,<TIMESTAMP>-<SEGMENT_2>,...-<SEGMENT_N>
See: Inbound Data File Name: Syntax and Parameters and Inbound Data File Contents: Syntax and Parameters.
Online Data is Available for Offline Marketing Efforts
When you bring offline data online, you can still use this information for offline campaigns. To do this, Audience Management
exports trait and segment information to an FTP location of your choice. Contact your Partner Solutions manager for additional
information or assistance.
Environments
Audience Management provides the following environments for file drop-off:
Integration Guides
Environment
Production
Sandbox
234
Hostname
ftp-in.demdex.com
sandbox-ftp-in.demdex.com
Note: We refresh the sandbox environment every weekend with the production data set. You should be able to use your
production account credentials to log in based on your account a week prior.
Further Technical Reading
Systems engineers, developers, or technical/implementation teams should review Real-Time Inbound Data Integration and Batch
Data Transfer Process Described. These sections provide details about transfer protocols, file content, and file name requirements.
Technical Specifications for Inbound Batch Data Transfers
Third-party content providers should format and send data to Audience Management according to these specifications.
For a list of frequently asked questions about onboarding an offline CRM database into Audience Management, see Inbound
CRM Data Ingestion.
ID Synchronization for Inbound Data Transfers
Describes the syntax and parameters used in the initial HTTP call to synchronize user IDs between a vendor and Audience
Management. ID synchronization can begin after you send your data taxonomy to Audience Management.
ID synchronization is the first step in the inbound, asynchronous data transfer process. In this step, Audience Management and
the vendor compare and match IDs for their respective site visitors. For example, an Audience Management customer may
know a user by ID 123. However, your data partner could identify this user with ID 456. The synchronization process allows
Audience Management and a data vendor to reconcile these different IDs and identify users in their respective systems. Once
complete, Audience Management and your third-party partner should have corresponding IDs for each unique user seen on
our networks.
You can use the following methods to get your data into Audience Management:
• ID Synchronization HTTP Request
• Declared ID Event
•
• ID Synchronization From an Email Embedded Image
ID Synchronization HTTP Request
In an ID exchange, a properly formatted URL string should look like this:
http://dpm.demdex.net/ibs:dpid=<VENDOR_ID>&dpuuid=<VENDOR_UUID>&redir=<REDIRECT_URL>
The URL for your inbound ID synchronization call should contain variables described in the table below.
Note: Replace italicized content with actual parameter values.
Parameter
Description
<VENDOR_ID>
Unique ID for the content provider (assigned by Audience Management).
Integration Guides
235
Parameter
Description
<VENDOR_UUID>
URL (Percent) Encoded representation of your Unique User ID. In addition to encoding
reserved ASCII characters, any non-ASCII characters should be percent encoded based on
the UTF-8 character encoding table.
For more information, see the URL Encode/Decode Online website.
<REDIRECT_URL>
An encoded URL redirect with the macro ${DD_UUID} embedded within it.
Note: Added only when the content provider initiates the call.
Declared ID Event
For more information, see Declared IDs.
ID Synchronization From an Email Embedded Image
The format for matching IDs via an email image is the same as shown above. Note, however, that images in an email must be
enabled for this to work. This can affect ID synchronization via email because most mail systems disable images by default.
File-Based ID Synchronization
Describes the required fields, syntax, and conventions used for file-based ID synchronization.
Filename Syntax
adobe_id_<Master DPID>_<DPID 2>_...._<DPID N>_<timestamp>.sync
Filename Example
adobe_id_123_898_456_1409757089.sync
File Format Syntax
<Master DPID ID><tab><DPID 2 ID><tab>…<DPID N ID>
File Format Example
fjdi7fdskjsf3
kiyed87f7sjff
123456323
988776563
ABN-111-FGD
JYH-453-RCX
Parameters
The table lists the variables used to define contents in a properly formatted data file.
Note: Replace italicized content with actual parameter values.
Parameter
Description
<Master DPID>
The Master DPID is a the Data Source Id that holds IDs that are currently synced with
Audience Management.
The Master DPID is used to look up the AAM UUID and the subsequent IDs in the
file are synced with Audience Management.
Integration Guides
236
Parameter
Description
DPID N
The Data Source ID that will hold the new IDs to be synced. You must provide at least
one DPID.
<timestamp>
A 10-digit UNIX timestamp in seconds, in the UTC time zone.
<TAB>
A single tab delimiter that separates the UUID and segment ID parameters.
The file format should be TAB delimited. The columns of IDs should correspond
respectively to the DPID order in the name.
Best Practices
• User IDs cannot contain tabs.
• User IDs cannot contain any Personally Identifiable Information (PII). For example, if a partner uses an email address for an
ID, the partner must convert it to something without PII before sending it to Audience Management.
• User IDs in the adobe_id import file should not be URL (Percent) Encoded. This is different from IDs sent via an ibs event
or a declared id event, which must be URL decoded because they are sent in a URL.
Inbound Data File Name: Syntax and Parameters
Describes the required fields, syntax, and conventions used to name an inbound data file. You must name your data file according
to these specifications.
Audience Management accepts inbound server-to-server files submitted using the following methods:
• Partners Drop Files into an Assigned AWS S3 Bucket (Preferred Method)
• Partners FTP Inbound Files
In both cases, the format of the data in the file is the same. A real-time server-to-server inbound capability is in the Audience
Management roadmap.
Partners Drop Files into an Assigned AWS S3 Bucket (Preferred Method)
Syntax
Name your data file as shown in the example:
ftp_dpm_<DPID>[_<DPID_TARGET_DATA_OWNER>]_<TIMESTAMP>.<FILE_TYPE>[.<SPLIT_NUMBER>][.gz]
The example uses the following conventions:
Convention
Explanation
<variable>
Substitute the appropriate value for variable.
[optional]
Items in square brackets are optional.
(one|another)
Alternation. Include one OR another.
literal
All other text must be included exactly as shown.
Parameters
Integration Guides
237
The table defines the variables used in a properly named data file.
Note: Replace italicized content with actual parameter values.
Parameter
Description
<DPID>
A unique ID assigned by Audience Management to the Data Partner who is sending
the data. For example, ftp_dpm_21_1234567890.sync shows that the data file
was sent by partner ID 21.
<DPID_TARGET_DATA_OWNER>
An optional field that contains a unique integer (provided by Audience
Management) that identifies a data owner in our system.
For example, ftp_dpm_21_33_1234567890.sync shows vendor ID 21 passed
in data owned by Audience Management client ID 33.
If not present, the data partner who is sending the data is assumed to own the data.
<TIMESTAMP>
A 10-digit UNIX timestamp in seconds, in the UTC time zone.
<FILE_TYPE>
Could be sync or overwrite.
sync: Normal scenario when third-party data providers send traits on a per-user
basis to be added or removed in the Audience Management system.
overwrite: Lets data providers send a list of traits on a per-user basis that should
overwrite all of this user's existing third-party traits for this data provider in the
Audience Management system.
<SPLIT_NUMBER>
Integer. If a large file is split into multiple parts for efficient processing, this number
indicates which part of the original file this is.
[.gz]
If the file is gzipped, indicate that with the standard .gz extension.
Additional Requirements
1. Files should be dropped in a folder on your S3 bucket/directory named date=yyyy-mm-dd based on UTC time (not local
time) of when the files are delivered.
2. Compressed files must be less than 100 MB. There is no limit on uncompressed file size.
Best Practices
1. Files should be gzip compressed (and have a .gz file extension.)
2. Optimal split sizes, for fastest/earliest processing of your files, is approximately 1 GB uncompressed or 20-30 MB compressed.
Examples
s3n://<AWS_Bucket>/<partner_name>/date=2013-05-09/ftp_dpm_478_1366545717.sync.1.gz
s3n://<AWS_Bucket>/<partner_name>/date=2013-05-09/ftp_dpm_478_1366545717.sync.2.gz
s3n://<AWS_Bucket>/<partner_name>/date=2013-05-09/ftp_dpm_478_1366545717.sync
Integration Guides
238
s3n://<AWS_Bucket>/<partner_name>/date=2013-05-09/ftp_dpm_478_567_1366545717.sync.gz
s3n://<AWS_Bucket>/<partner_name>/date=2013-05-09/ftp_dpm_478_1366545717.overwrite
Note: Contact your Account Manager for the <AWS_Bucket> name and credentials as well as for FTP server details.
Partners FTP Inbound Files
Syntax
ftp_dpm_<DPID>[_<DPID_TARGET_DATA_OWNER>]_<TIMESTAMP>.<FILE_TYPE>[.<SPLIT_NUMBER>][(.gz|.tar|.tgz
|.zip)]
The example uses the following conventions:
Convention
Explanation
<variable>
Substitute the appropriate value for variable.
[optional]
Items in square brackets are optional.
(one|another)
Alternation. Include one OR another.
literal
All other text must be included exactly as shown.
Parameters
The table defines the variables used in a properly named data file.
Note: Replace italicized content with actual parameter values.
Parameter
Description
<DPID>
A unique ID assigned by Audience Management to the Data Partner who is sending
the data. For example, ftp_dpm_21_1234567890.sync shows that the data file
was sent by partner ID 21.
<DPID_TARGET_DATA_OWNER>
An optional field that contains a unique integer (provided by Audience
Management) that identifies a data owner in our system.
For example, ftp_dpm_21_33_1234567890.sync shows vendor ID 21 passed
in data owned by Audience Management client ID 33.
If not present, the data partner who is sending the data is assumed to own the data.
<TIMESTAMP>
A 10 digit UNIX timestamp in seconds, in the UTC time zone.
<FILE_TYPE>
Could be sync or overwrite.
sync: Normal scenario when third-party data providers send traits on a per-user
basis to be added or removed in the Audience Management system.
Integration Guides
239
Parameter
Description
overwrite: Lets data providers send a list of traits on a per-user basis that should
overwrite all of this user's existing third-party traits for this data provider in the
Audience Management system.
<SPLIT_NUMBER>
Integer. If a large file is split into multiple parts for efficient processing, this number
indicates which part of the original file this is.
.gz | .tar | .tgz | .zip
If the file is compressed, end the filename with the appropriate extension(s).
Examples:
ftp_dpm_478_1366545717.sync.1.gz
ftp_dpm_478_1366545717.sync.zip
ftp_dpm_478_1366545717.sync.tgz
ftp_dpm_478_1366545717.overwrite
Note: For FTP, we do not use date= subdirectories.
Inbound Data File Contents: Syntax and Parameters
Describes the required fields, syntax, and conventions used to organize information in an inbound data file.
Syntax
Fields in the data file must appear in the following order:
<UUID><TAB><SEGMENT_1>,<SEGMENT_2>,...<SEGMENT_N>
Parameters
The table lists the variables used to define contents in a properly formatted data file.
Note: Replace italicized content with actual parameter values.
Parameter
Description
<UUID>
A unique user ID assigned by Audience Management or a data provider's ID for the user.
<TAB>
A single tab delimiter that separates the UUID and segment ID parameters.
<SEGMENT_N>
<SEGMENT_N> . Can consist of either:
• SID or
• Key-value pairs, where the key and value are alphanumeric strings. For example, "age"="24" or
"gender"="m".
Integration Guides
Parameter
240
Description
Note:
• SID refers to the Audience Management Segment ID. SID can be found by using the GET method
that returns details about all your traits. For more information, see Return Properties for all
Traits.
• Enclose strings in quotes " ".
• SIDs are validated that they belong to DPID_TARGET_DATA_OWNER in the filename.
:0 or :-1
Optional flags set to exclude a user from a segment. This functionality currently exists only when the
segment is a SID, not when a key-value pair is passed in.
Note: Use :0. The flag :-1 is deprecated but retained for legacy purposes. SID removals are
ignored in a .overwrite file type.
Special Characters and Formatting the <SEGMENT> Parameter: Best Practices
When naming segments, try to avoid using special characters such as:
• Tabs
• Commas
• Dashes
• Vertical bar/pipe
• Hyphenated segment names (e.g., 123-gender or used-car-buyer).
Escaping Special Characters
Place double quotes " " around these special characters if you must use them. For example, like this "123-gender" or
"city"="New York, NY". However, it's best to avoid potential difficulties and refrain from using these enumerated (or other)
special characters whenever possible.
Example 1: Using Key-Value Pairs
This sample uses a key-value pair to include females who are luxury shoppers.
59767559181262060060278870901087098252 “gender”=”female”,“luxury_shopper”=”yes”
Example 2: Basic File Format
A properly formatted data file could look similar to the following sample. This file entry indicates a user qualifies for segments
24, 26, and 27. A tab separates the UUID and SIDs.
59767559181262060060278870901087098252 24,26,27
Example 3: Exclude Visitors From a Segment
This sample uses the :0 flag to exclude a user from a segment. In this case, the user is removed from Audience Management
segment ID 27.
59767559181262060060278870901087098252 24,26,27:0
File Compression for Inbound Data Transfer Files
As an option, you can compress data files when sending them to Audience Management.
Audience Management supports the following file compression types for inbound, asynchronous data transfers:
Integration Guides
241
• tar (.tar)
• gzip (.gz)
• tar and gzip (.tgz and .tar.gz)
• zip (.zip)
Audience Management also supports uncompressed files.
For delivery to AWS S3, you must use .gz or uncompressed files. Compressed files must be smaller than 100 MB. There is no
limit on uncompressed file size.
Best Practices
1. Files should be gzip compressed (and have a .gz file extension.)
2. Optimal split sizes, for fastest/earliest processing of your files, is approximately 1 GB uncompressed or 20-30 MB compressed.
File PGP Encryption for Inbound Data Types
As an option, you can encrypt data files with PGP encryption when sending them to Audience Management.
1. Download the Audience Management public key
(http://microsite.omniture.com/t2/help/en_US/demdex/adobe_pgp.pub).
2. Import the public key to your trusted store.
For example, if you use GPG, the command could be similar to the following:
gpg --import adobe_pgp.pub
3. Validate that the key has been imported correctly by running the following command:
gpg --list-keys
You should see a message similar to the following:
pub
uid
sub
4096R/8496CE32 2013-11-01
Adobe AudienceManager
4096R/E3F2A363 2013-11-01
4. Encrypt the inbound data using the following command:
gpg --recipient "Adobe AudienceManager" --cipher-algo AES --output $output.gpg
--encrypt $inbound
All encrypted data must use .pgp or .gpg as the file extension (e.g. ftp_dpm_100_123456789.sync.pgp or
ftp_dpm_100_123456789.overwrite.gpg).
Note: Audience Management supports only the Advanced Encryption Standard (AES) data-encryption algorithm.
Audience Management supports any key size.
Sample Message to Partners after Inbound Processing
Whenever an inbound Server-to-Server file is processed, a receipt is sent via email to partner solutions and, if configured, to the
partner.
The following example is a sample email message. The table below the message describes the various lines in the message.
From: s2s-delivery-receipt-demdex@demdex.com[s2s-delivery-receipt-demdex@demdex.com]
Subject: SFTP Server-To-Server Processing Result:
Integration Guides
242
Dear Adobe Partner: (ID:7)
We have received your SFTP file delivery.
File name:
s3n://<bucket_name>/2013-05-17/ftp_dpm_7_901_1368806402.sync
s3n://<bucket_name>/2013-05-16/ftp_dpm_7_901_1368655202.sync
s3n://<bucket_name>/2013-05-17/ftp_dpm_7_901_1368784804.sync
s3n://<bucket_name>/2013-05-17/ftp_dpm_7_901_1368806403.sync
s3n://<bucket_name>/2013-05-17/ftp_dpm_7_901_1368784802.sync
s3n://<bucket_name>/2013-05-17/ftp_dpm_7_901_1368784803.sync
s3n://<bucket_name>/2013-05-17/ftp_dpm_7_901_1368806404.sync
Records received: 40669900
Invalid lines: 7
Invalid UUIDs: 112
Failed UUID lookup: 0
Records without traits: 26730823
Records processed: 40669900
Succeeded: 13938958
User without new traits: 26730823
Total signals: 918878926
Total unused signals: 660348376
Total realized traits: 258086908
Total new traits: 258086908
Total removed traits: 0
Total skipped duplicated users: 0
Job start time: 2013-05-17 18:07:49
Job end time: 2013-05-17 18:45:02
The following table contains rows corresponding to lines in the received email message.
Line
File name
Description
List of all inbound files that Adobe received for this partner that were processed together. In the
previous sample email message, the partner ID is 7 and the data owner ID is 901.
The tail number (1,2,3...) is the split number added either by the customer or by the inbound
distributor.
Integration Guides
Line
Records received
Invalid lines
Invalid UUIDs
Failed UUID lookup:
Records without traits
Records processed
Succeeded
User without new traits
Total signals
Total unused signals
Total realized traits
Total new traits
Total removed traits
Total skipped duplicated
users
243
Description
Total number of records Adobe received across all files. In most cases, this should be the total
number of lines in inbound files.
Number of lines that did not match the expected format. These lines were not recognizable by
the inbound job.
Number of audience management UUIDs that did not match the expected 38-digit format. Or
the audience management UUIDs are not numbers.
Total number of users for whom audience management failed to find a matching UUID. These
files have not been ID synced, so audience management cannot look up the UUID.
Number of records where none of the signals on the line maps to an audience management trait.
Total number of records audience management processed. In most cases, this number should
be the same as "Records received."
Number of records resulting in data to be loaded into the system = records processed - invalid
lines - invalid UUIDs - failed UUID lookup - records without traits.
For full syncs only, number of users that had exactly the same traits as they did after the last job.
These users are not processed.
Total number of signals for all users across all inbound files (total number of key/value pairs in
the records processed).
Total number of unused signal for all users across all inbound files (key/value pairs that did not
map to audience management traits). In most cases, this means that audience management does
not have rules defined for the signal.
Number of audience management traits for all users across all inbound files based on the signals.
Total number of audience management traits minus (for full syncs) the number of traits realized
in a previous inbound job. Only the new traits are passed to downstream processing.
Total number of removed traits for all users across all inbound files. For full syncs, this happens
if the user had the trait in a previous run but not in the current run.
This is the total number of users that inbound job skipped to process because there were no new
traits for them.
For full syncs, if a user has records with two different timestamps, only the newer record is used
and the older one is skipped.
Integration Guides
244
Line
Description
Job start time
The time the inbound job starts.
Job end time
The time the inbound job ends.
Receiving Audience Data
Receive audience data from Audience Management.
ID Synchronization for Outbound Data Transfers
Describes the syntax and parameters used in the initial HTTP call to synchronize user IDs between a Audience Management
and a third-party data provider. ID synchronization can begin after you send your data taxonomy to Audience Management.
Purpose of ID Synchronization
ID synchronization is the first step in the outbound, asynchronous data transfer process. In this step, Audience Management
and the vendor compare and match IDs for their respective site visitors. For example, an Audience Management customer may
know a user by ID 123. However, your data partner could identify this user with ID 456. The synchronization process allows
Audience Management and a data vendor to reconcile these different IDs and identify users in their respective systems. Once
complete, Audience Management and the third-party data provider should have corresponding IDs for each unique user seen
on our networks.
URL Syntax
In an ID exchange, a properly formatted URL string should look like this:
http://dpm.demdex.net/ibs:dpid=<VENDOR_ID>&dpuuid=<VENDOR_UUID>&redir=<REDIRECT_URL>
URL Parameters
The URL for your inbound ID synchronization call should contain variables described in the table below.
Note: Replace italicized content with actual parameter values.
Parameter
Description
<VENDOR_ID>
Unique ID for the data provider (assigned by Audience Management).
<VENDOR_UUID>
Unique user ID.
<REDIRECT_URL>
An encoded URL redirect with the macro ${DD_UUID} embedded within it.
Note: Added only when the data provider initiates the call.
Real-Time Outbound Data Transfers
The outbound real-time data transfer process returns user data as a series of JSON objects passed in with a POST method.
Prerequisites
To use this method, make sure your data partner:
Integration Guides
245
• Accepts data in JSON format.
• Provides a URL that can be used by the POST call to return data.
Parameters
The following table defines the elements in the returned JSON data file.
Parameter
Data Type
Description
ProcessTime
DateTime
Time when the request was executed.
Client_ID
String
Client ID used by the system you're sending data to.
AAM_Destination_ID
Integer
The ID assigned to you by your destination partner.
User_count
Integer
Total number of users in the POST request.
Users
Array
An array of user objects.
AAM_UUID
String
The Audience Management UUID.
DataPartner_UUID
String
Data partner UUID. Leave blank if your data partner does not have
a UUID.
Segments
Array
An array of segment objects.
Segment_ID
Integer
The Audience Management segment ID.
Status
Integer
Defines the status of a user in the segment. Accepts the following:
• 1 - active
• 0 - inactive or opted out
Set to 1 by default. Currently, you cannot change this setting.
DateTime
DateTime
Time that a site visitor qualified for the trait.
Code Sample
A real-time data response can look similar to the following:
{“ProcessTime”:”Fri Jul 15 04:52:21 GMT 2012”,
“Client_ID”:”74323”,
“AAM_Destination_Id”:”423”,
“User_count”:”2”,
“Users”:
[
{
“AAM_UUID”:”19393572368547369350319949416899715727”,
“DataPartner_UUID”:”4250948725049857”,
“Segments”:
[
{
“Segment_ID”:”14356”,
“Status”:”1”
“DateTime”:” Fri Jul 14 01:23:21 GMT 2012”
},
{
“Segment_ID”:”12176”,
“Status”:”0”,
“DateTime”:” Fri Jul 14 02:59:01 GMT 2012”
}
]
},
Integration Guides
246
{
“AAM_UUID”:”0578240750487542456854736923319946899715232”,
“DataPartner_UUID”:”848457757347734”,
“Segments”:
[
{
“Segment_ID”:”10329”,
“Status”:”1”,
“DateTime”:” Fri Jul 15 01:23:21 GMT 2012”
},
{
“Segment_ID”:”23954”,
“Status”:”1”,
“DateTime”:” Fri Jul 15 11:02:21 GMT 2012”
}
]
}
]
}
Batch Outbound Data Transfers
Audience Management sends batch data to third-party content providers according to these specifications.
Outbound Data File Name: Syntax and Parameters
Describes the required fields, syntax, and conventions used to name an outbound data file.
Syntax
<SYNC_TYPE>_<DID>_<DPID>_<SYNC_MODE>_<TIMESTAMP>[-<SPLIT_NUMBER>].sync[.gz]
The example uses the following conventions:
Convention
Explanation
<variable>
Substitute the appropriate value for variable.
[optional]
Items in square brackets are optional.
(one|another)
Alternation. Include one OR another.
literal
All other text must be included exactly as shown.
Parameters
The table defines the variables used in a properly named data file.
Parameter
Description
<SYNC_TYPE>
Sync Type. Represents transfer type: FTP, S3, or HTTP.
<DID>
Destination ID. A unique ID assigned by Audience Management to the customer's
export configuration.
<DPID>
Data-provider ID. A unique ID assigned by Audience Management to the Data
Partner who is receiving the data.
Integration Guides
247
Parameter
Description
<SYNC_MODE>
"iter" or "full" based on whether this file represents an incremental sync or a full
sync.
<TIMESTAMP>
A 13-digit UNIX timestamp in milliseconds, in the UTC time zone.
<SPLIT_NUMBER>
Integer. If a large file is split into multiple parts for efficient processing, this number
indicates which part of the original file this is.
Examples:
ftp_1122_987_iter_1394677103422.sync.gz
ftp_2210_312_full_1394677102765.sync
ftp_3210_123_iter_1394677101321.sync
ftp_1234_321_full_1394677102853-1.sync.gz
Outbound Data File Contents: Syntax and Parameters
Describes the fields, syntax, and conventions used to organize information in an outbound data file.
Syntax
Fields in the data file appear in this order:
<UUID><SPACE><SEGMENT_1>,<SEGMENT_2>,...<SEGMENT_N>
Parameters
The table lists variables that define the contents of a data file.
Parameter
Description
<UUID>
A unique user ID assigned by Audience Management.
<SPACE>
A space delimiter that separates the UUID and segment data.
<SEGMENT_N>
The segment ID that a visitor belongs to. Commas separate multiple segments.
Example: Basic File Format
A properly formatted data file could look similar to the following sample. This file entry indicates a user qualifies for segments
24, 26, and 27. As required, a space separates the UUID and segment IDs.
59767559181262060060278870901087098252
24,26,27
Transfer-Control Files for Log File Transfers
Transfer-control (.info) files provide metadata information about file transfers so that partners can verify that Audience
Management handled file transfers correctly.
Audience Management sends a transfer-control file to a partner with every file transfer. Due to the multi-thread nature of the
FTP publisher, the transfer-control file might be sent before the actual files are finished transferring.
The metadata in the .info file lets partners:
Integration Guides
248
• Determine when a full transfer cycle is complete (the total number of files in the sequence have been delivered)
• Determine whether any given file in the sequence is complete/correct (by examining the size of the file in bytes and the total
number of lines)
• Validate the number of rows in raw files verses the number of rows after the files have been loaded in the database on the
receiving end (size of file in lines)
File Naming Conventions
The transfer-control file has the same name as the root of the batch/sequence with a .info file extension.
For example, if the first file in the sequence were named: ftp_946_325_iter_1359334907441-1.sync, the control
file would be named ftp_946_325_iter_1359334907441.info.
File Format
{
"TransferData": {
"Totals": { "TotalNumberFiles": 50, "TotalNumberLines": 50, "TotalByteSize": 50 },
"Files": [
{"FileName": "ftp_946_325_iter_1359334907441-1.sync", "FileSequenceNumber": 1,
"FileByteSize": 5000, "FileLineCount": 500},
{"FileName": "ftp_946_325_iter_1359334907441-2.sync", "FileSequenceNumber": 2,
"FileByteSize": 5000, "FileLineCount": 500}
]
}
}
Notes:
The batch total numbers are exclusive of the .info file itself. That is, the totals do not include the .info file, its byte size, or
its line count.
Where "50" exists in the file-format example, you receive a numeric integer value. The value is not comma separated to denote
thousand blocks.
Byte sizes of files and line counts are inclusive of any header and spacer (blank) lines/rows. In order to get the count of actual
data lines/rows, subtract headers.
Total lines in batch and total byte size are inclusive of any header and spacer rows.
DCS Integration
This material describes the attributes and syntax used to send data to the Audience Management Data Collection Server (DCS).
It is intended for engineering teams that work with proprietary systems to send and receive data from the DCS without accessing
the Audience Management user interface.
Variable Prefix Requirements
Defines the variable prefixes that identify the type of data passed in to the DCS.
Identifying Audience Management and Customer Variables
Prefixes identify the parameter passed in to the DCS as either Audience Management or customer variable types. The following
table defines the prefixes used identify these variables.
Prefix
Identifies the Parameter as
c_
A customer defined variable.
Integration Guides
249
Prefix
Identifies the Parameter as
d_
A system variable used by Audience Management.
h_
An HTTP header variable.
p_
As personally identifiable information (PII).
Note: Note Audience Management uses PII data for trait qualification purposes
only. Our system does not record or store PII data.
Reserved Variable Names
The following d_ and h_ variable names are reserved by our system for special use.
Variable Prefix
Variable Name
Used to Define
d_
d_zx
Zip code variables (e.g., d_zx=10022).
d_fn
Gender probabilities based on first names.
d_dma
Metro Codes: IDs and Names (DMA) data.
h_<http header>
Any HTTP header such as referer, IP, accept-language, etc.
h_
Supported Variables
Lists the supported Audience Management variables. In most cases, none of these are required.
Variable
Definition
d_cb
Encloses the JSON response in a callback wrapper.
d_dpid
Data partner ID assigned by Audience Management.
Audience Management compares the combined dpid and dpuuid to a corresponding user ID in our
system. If an ID does not exist, Audience Management creates and synchronizes a new user ID to the
dpid/dpuuid combination.
d_dpuuid
The data provider's unique ID for the user.
Audience Management compares the combined dpid and dpuuid to a corresponding user ID in our
system. If an ID does not exist, Audience Management creates and synchronizes a new user ID to the
dpid/dpuuid combination.
d_dst=1
Prompts the DCS to return destination inside the JSON response.
d_pftm
Allows Audience Management to distinguish mobile requests from desktop requests.
Supported values include the following:
• ios
Integration Guides
Variable
250
Definition
• android
• browser
• all
If the value is "ios" or "android," the request is treated as a mobile request and id-syncing is disabled.
d_rtbd=json
Returns a JSON response. Required only if you want to receive data from the DCS.
d_sid
The trait ID (as shown in the user interface).
d_uuid
Unique user ID. Identifies a visitor when this value is not available from a cookie.
d_zc
ZIP code: Maps to DMA traits.
URL Format for Passing in Data to the DCS
Describes how to format a URL to pass data in to the DCS and defines fields used in the URL string.
Syntax: http://<domain>/event?key1=val1[,val2][&key2=val2]...
Note: When the value in a key-value pair contains string values, enclose the string in double quotes (e.g., age="41 to
55").
Parameters
Input
Field Name
Description
domain
Domain alias (e.g., my_domain.demdex.net).
event
Defines the start of a URL string that contains attributes or variables passed in as key-value pairs.
key
A unique identifier in the key-value pair. Prefix with d_ or c_ to identify it as an Audience
Management or customer attribute.
Examples
When passing in event data to the DCS, your URL string could look similar to the sample below.
Note: The request uses d_cb to encapsulate the JSON response in a wrapper
Request
http://my_domain.n.net/event?d_stuff=1&d_dst=1&d_rtbd=json&
d_px=123,456,789&c_likes=britney+spears&c_loves=lady+gaga&
d_ld=some+data+to+log&d_cb=myCallback
Response
The URL response from the DCS could look similar to the sample response. Parameters are defined after the example.
Integration Guides
251
Note: Omit the d_cb parameter if you need a JSON response without the myCallback() wrapper.
myCallback({"dests":[ {"dt":802,"ts":999999,"y":"js","c":"
http://ad.doubleclick.net/adi/<domain>/homepage;vid=0;ugc=0;sz=300x250;;
u=cat-_scat-_sscat-_art-_dmd-E34D8B7C-5208-4411-B91F-C676F8A19D6D;tile=2;
ord=7159960932631?"}], "dpm":[],"segments":[]} {"stuff":[ {"cn":"cookie-name1",
"cv":"cookie-value1","ttl":0,"dmn":"www.my_domain.com","u":"abc123"}, {"cn":"cookie-name2",
"cookie-value2":"make=ford;audi","uuid":"abc123",
"ttl":1,"dmn":"www.my_domain.com"}]})
Response Parameters
To help you parse the response, some of the important parameters are defined as follows:
Parameter
Description
c:
Non-secure URL (http).
cn:
Cookie name.
cv:
Cookie value.
dcs_region
Integer representing the geographic region of the Data Collection Server (DCS).
The integers map to the following regions:
3: Asia Pacific (Singapore)
4: South America (Sao Paulo)
5: US West (N. California)
6: EU (Ireland)
7: US East (N. Virginia)
8: Asia Pacific (Sydney)
9: US West (Oregon)
10: US West (Dallas)
11: Asia Pacific (Tokyo)
You can also use API methods to list the latest DCS regions.
dests:
Destination traits fired from your page.
dmn:
Domain to stuff (cookie stuffing).
dpm:
Third-party information about a user.
e:
Secure URL (https).
y:
Destination type: iframe (iframe) or image (img).
stuff:
Cookie or JS variable set on the page or domain.
Integration Guides
252
Parameter
Description
ts:
Timestamp in Unix seconds (UTC).
u: and UUID:
Unique user ID assigned by Audience Management (long integer).
DCS Appendix
Additional information about the Audience Management Data Collection Server (DCS).
DCS Location Information in the HTTP Response Header
Data returned by the DCS contains information about its geographic location.
Purpose of Location Information in the DCS Response
The HTTP response headers contain information about the server’s location (prefixed by either NY or LA), its name, and DCS
version. DCS header information is useful for troubleshooting purposes. Sample header data could look similar to these:
• NY-PDCS-07 1.2.100
• LA-PDCS-07 1.2.100
The responses came back from the servers in New York or Los Angeles and are running DCS version 1.2.100
Race Conditions and Error Handling
Describes how to prevent race conditions and DCS error handling.
Preventing Race Conditions
A race condition can occur if you send multiple calls simultaneously (or in rapid succession) to the DCS before it finishes
responding to the initial queries and writing data to the user’s cookie. A race condition is undesirable because it can corrupt or
improperly overwrite cookie data. As a best practice, consider the following methods to help avoid this problem:
• Don't make simultaneous calls, or calls in rapid succession, to the DCS from the same user.
• Wait for each response to come back before making subsequent calls.
Error Handling
Error handling is limited for invalid or poorly formed queries. An invalid request returns an HTTP 200 OK response and no
data. Also, the DCS stops processing a request, discards trait data, and returns an HTTP 200 OK response when a user:
• Opts out of tracking at the Audience Management or partner level.
• Comes from an invalid/unselected geographic region.
• Disables browser cookies (either all or third-party).
Format and Delimiter Standards for Key-Value Pairs
Describes "standard" and "serialized" key-value pairs along with the characters you should use to delineate values within and
between key-values.
Standard and Serialized Key-Value Pairs: About
The DCS accepts key-value data in a "standard" or "serialized" format.
Integration Guides
253
Format Type
Definition
Example
Standard
Organizes data into separate key-value pairs. Each key key1=val1&key1=val2& key2=val2
is stated explicitly, even when it’s used again to define
a different value.
Serialized
Uses a single key to define multiple values and separates key1=val1,val2,val3
values with a specific indicator.
Requirements for Delimiters and Separators
Working with key-value attributes means you must specify the markers that separate values within and between these variables.
Audience Management requires the following delimiters and separators:
Requirements for
Symbol
Separates Individual
Delimiters
Ampersand &
Key-value pairs:
key1=val1&key2=val2
Separators
Comma ,
Values within key-value pairs:
key1=val1,val2,val3
Cookie Checking and First Time Users
Describes how the DCS attempts to set a cookie for a new user.
Cookie Setting: About
A first time user is anyone without an Audience Management cookie set in his or her browser. When the DCS encounters a user
for the first time it tries to determine if their browser accepts third-party cookies. To determine if a browser accepts third-party
cookies, the DCS:
1. Sets a cookie in user's browser.
2. Changes the syntax in the event URL to /firstevent from /event.
3. Upon receiving the second request (from the /firstevent URL), the DCS checks if a previously set cookie exists. If the
cookie:
• Is set, the event gets processed normally.
• Is not set, the DCS stops processing the request.
Metro Codes: IDs and Names
Lists the metro code IDs and names you can use to build traits that qualify users by geographic location.
Supported DMA IDs and Marketing Areas
Trait Builder lets you target users according to generally accepted demographic marketing areas. This process works when you
pass in site visitor ZIP codes with the d_zc variable. When our system receives the ZIP code, it performs a lookup to match the
postal code with an associated metro code ID. You can then go into Trait Builder and construct a trait with the d_dma variable
as a key and a specific ID as the value. The table below lists the metro code IDs and regions used by Trait Builder.
Integration Guides
254
Note: To work with other metrics like area code, gender, latitude/longitude, etc. see the documentation on platform level
keys.
DMA ID
Marketing Area
1
Abilene-Sweetwater
2
ADA-Ardmore
3
Albany, GA
4
Alpena
5
Albuquerque - Santa Fe
6
Alexandria, LA
7
Alpena
8
Amarillo
9
Anchorage
10
Atlanta
11
Augusta
12
Austin
13
Bakersfield
14
Baltimore
15
Bangor
16
Baton Rouge
17
Beaumont - Port Arthur
18
Bend, OR
19
Billings
20
Biloxi - Gulfport
21
Binghamton
22
Birmingham
23
Bluefield - Beckley - Oak Hill
24
Boise
25
Boston
26
Bowling Green
27
Buffalo
28
Burlington - Plattsburgh
29
Butte
Integration Guides
255
DMA ID
Marketing Area
30
Casper - Riverton
31
Cedar Rapids - Waterloo and Dubuque
32
Champaign and Springfield - Decatur
33
Charleston, SC
34
Charleston - Huntington
35
Charlotte
36
Charlottesville
37
Chattanooga
38
Cheyenne - Scottsbluff - Strling
39
Chicago
40
Chico - Redding
41
Cincinnati
42
Clarksburg - Weston
43
Cleveland
44
Colorado Springs - Pueblo
45
Columbia, SC
46
Columbia - Jefferson City
47
Columbus, GA
48
Columbus, OH
49
Columbus - Tupelo - West Point
50
Corpus Christi
51
Dallas - Ft. Worth
52
Davenport - Risland - Moline
53
Dayton
54
Denver
55
Des Moines - Ames
56
Detroit
57
Dothan
58
Duluth - Superior
59
El Paso
60
Elmira
Integration Guides
256
DMA ID
Marketing Area
61
Erie
62
Eugene
63
Eureka
64
Evansville
65
Fairbanks
66
Fargo - Valley City
67
Flint - Saginaw - Bay City
68
Florence - Myrtle Beach
69
Fort Wayne
70
Fresno - Visalia
71
Ft. Myers - Naples
72
Ft. Smith
73
Gainesville
74
Glendive
75
Grand Junction - Montrose
76
Grand Rapids - Kalamazoo - BCRK
77
Great Falls
78
Green Bay - Appleton
79
Greensboro - High Point - Winston Salem
80
Greenville - NBERN -WASHNGTN
81
Greenville - SPART - Asheville
82
Greenwood - Greenville
83
Harlingen - Weslaco - Brownsville
84
Harrisburg - LNCSTER - LEB - York
85
Harrisonburg
86
Hartford and New Haven
87
Hattiesburg - Laurel
88
Helena
89
Honolulu
90
Houston
91
Huntsville - Decatur (FLOR)
Integration Guides
257
DMA ID
Marketing Area
92
Idaho Falls - Pocatello
93
Indianapolis
94
Jackson, MS
95
Jackson, TN
96
Jacksonville - Brunswick
97
Johnstown - Alatoona
98
Jonesboro
99
Joplin - Pittsburg
100
Juneau
101
Kansas City
102
Knoxville
103
La Crosse - Eau Claire
104
Lafayette, IN
105
Lafayette, LA
106
Lake Charles
107
Lansing
108
Laredo
109
Las Vegas
110
Lexington
111
Lima
112
Lincoln and HSTNGS - KRNY
113
Little Rock - Pine Bluff
114
Los Angeles
115
Louisville
116
Lubbock
117
Macon
118
Madison
119
Mankato
120
Marquette
121
Medford - Klamath Falls
122
Memphis
Integration Guides
258
DMA ID
Marketing Area
123
Meridian
124
Miami - Ft. Lauderdale
125
Milwaukee
126
Minneapolis - St. Paul
127
Minot - Bismarck - Dickinson
128
Missoula
129
Mobile - Pensacola
130
Monroe - El Dorado
131
Monterey - Salinas
132
Montgomery
133
Nashville
134
New Orleans
135
New York
136
Norfolk - Port Smith - Newport News
137
North Platte
138
Odessa - Midland
139
Oklahoma City
140
Omaha
141
Orlando - Daytona Beach - MELBRN
142
Ottumwa - Kirksville
143
Paducah - CGIRD - HARBG - MT
144
Palm Beach
145
Palm Springs
146
Panama City
147
Parkersburg
148
Peoria - Bloomington
149
Philadelphia
150
Phoenix
151
Pittsburgh
152
Portland, OR
153
Portland - Auburn
Integration Guides
259
DMA ID
Marketing Area
154
Presque Isle
155
Providence - New Bedford
156
Quincy - Hannibal - Keokuk
157
Raleigh - Durham
158
Rapid City
159
Reno
160
Richmond - Petersburg
161
Roanoke - Lynchburg
162
Rochester, NY
163
Rochester - Mason City - Austin
164
Rockford
165
Sacramento - STKTN - Modesto
166
Saint Joseph
167
Salisbury
168
Salt Lake City
169
San Angelo
170
San Antonio
171
San Diego
172
San Francisco - Oakland - San Jose
173
Santa Barbara - SANMAR - San Luis Obispo
174
Savannah
175
Seattle - Tacoma
176
Shreveport
177
Sioux City
178
Sioux Falls - Mitchell
179
South Bend - Elkhart
180
Spokane
181
Springfield, MO
182
Springfield - Holyoke
183
St. Louis
184
Syracuse
Integration Guides
260
DMA ID
Marketing Area
185
Tallahasse - Thomasville
186
Tampa - St. Petersburg - Sarasota
187
Terre Haute
188
Toledo
189
Topeka
190
Traverse City - Cadillac
191
Tri - Cities TN-VA
192
Tucson - Sierra Vista
193
Tulsa
194
Twin Falls
195
Tyler
196
Utica
197
Victoria
198
Waco - Temple - Bryan
200
Washington DC
201
Wausau - Rhinelander
202
Wheeling - Steubenville
203
Wichita Falls - Lawton
204
Wichita - Hutchinson
205
Wilkes Barre - Scranton
206
Wilmington
207
Yakima - Pasco - Richland - KNNWCK
208
Youngstown
209
Yuma - El Centro
210
Zanesville
Ad Server Integration
Integrate Audience Management with popular ad servers.
Integration Guides
261
DART Enterprise as an Audience Management Destination
Set up DART Enterprise as a destination and send Audience Management segment data to that platform. Once configured,
Audience Management segment data appears in DART as seg vars that you can use to perform on-site targeting.
DART Destination Requirements
Standards for code placement, supported key-value formats, reports, and the type of segment data sent to DART Enterprise.
Requirements
This destination type requires the following:
• DE Cookie Reader Plug-in: Used by DART to read Audience Management segment data.
• get_aamCookie Function: Code that captures the Audience Management UUID and lets the DART ad request pass that ID
in on the u= value. Place this code on the top of the page or inside the <head> codeblock.
• Custom JavaScript Code: Special JavaScript code (provided by Audience Management) that loads an Iframe on the page. The
Iframe contains Audience Management cookie information that can be read by DART.
• Send Delivery Logs to Audience Management: If you want a segment delivery report (optional), provide Audience Management
with a daily log that contains impression-level delivery data. The data can be in a raw format, but each record must contain
the Audience Management UUID. Audience Management can pick up or receive these via FTP.
Cookie Format and Key-Value Data
Audience Management can send segment data to a browser cookie as follows:
• Single keys (x=1&x=2).
• Multiple keys (x=1&x=2&y=3&y=4).
• Serialized values (x=1,2,3)
• A standard value delimiter used to separate individual key-value pairs.
Only Qualified Segments are Sent to DE
The amount data passed in to DART depends on how many segments a particular user qualifies for. For example, say you set
up 100 Audience Management segments. If a site visitor qualifies for five of them, then only those five segments get sent to
DART (not all 100).
Common Configuration Examples
Refer to these examples when you serve ads on a parent domain (from a common sub-domain) or on different domains from
another location.
Example 1: Serving Ads on a Parent Domain from a Sub-Domain
In this case, ads serve from a site sub-domain to a parent domain and associated pages. For example, ads from ads.mydomain.com
would serve on www.mydomain.com. This is a common and simple ad serving configuration supported by an Audience
Management - DART Enterprise data integration. Also, remember to prefix the cookie domain name with a period when you
create the cookie destination.
Example 2: Serving Ads on Different Domains from Central Domain
In this case, ads serve from a central domain to other sites that you own. For example, the domain ads.publisher.com could
serve creatives to other sites like example.com, website.com, and mydomain.com. Keep the following in mind when your
creative delivery processes work with this configuration:
• DIL code: Place DIL data collection code on your pages.
Integration Guides
262
• CNAME: Create sub-domain with a CNAME alias that points to the ad serving domain. For example, the ad serving domain
ads.publisher.com would need sub-domain aam.ads.publisher.com.
• Cookie setup: When you create a cookie destination in Audience Management, make the cookie domain name identical to
the CNAME alias. Remember to prefix the cookie domain name with a period (e.g., .aam.ads.publisher.com).
• Custom JavaScript: Place the custom JavaScript on the pages you want to collect data from. Your Partner Solutions manager
will provide you with this code. This code loads an Iframe and sets a cookie that can be read by the ad server.
Create a DART Enterprise Destination
Create a cookie-based destination for DART Enterprise in Audience Management.
In Audience Management, a destination is any other system (ad server, DSP, ad network, etc.) that you want to share data with.
Destination Builder provides the tools that let you create and manage these data delivery processes. Audience Management
destination features are located in Manage Data > Destinations. To get started, click Add New Destination and follow the steps
below.
Step 1: Basic Information
To complete the Basic Information section:
1. Name the destination.
2. Select "Cookie" from the Type drop-down list.
3. Click Save and move on to the Configuration and Segment Mappings sections.
Step 2: Configuration Information
To complete the Configuration section:
1. Cookie Name: Provide a short, descriptive name for your cookie.
2. Cookie Domain: Leave blank to set a cookie in the domain of the user's current page. If you want to specify a domain, prefix
the name with a period like this, .mydomain.com.
3. Choose a key option in the Data Format section.
4. If your keys use data with serialized values, select the Serialize control and specify the serial delimiter (the character that
separates the serialized values).
5. Click Save and expand the Segment Mappings section.
Step 3: Segment Mappings
To add a segment to a cookie destination:
1. Find segments: The Segment Mappings section provides two search tools to help locate segments. To search for a segment:
• Option 1: Start typing a segment name in the search field. The field updates automatically based on the segment name.
Click Add after you find the segment you want to use.
• Option 2: Click Browse All Segments to open a window that lets you browse for segments by name or storage location.
Click Add Selected Segments when done.
2. Add Mappings: In the mappings pop, enter the segment ID in the mappings field and click Save.
3. Click Done.
DART Enterprise Setup
When setting up targeting for a campaign, enter seg vars in the campaign targeting sections exactly as they appear in the Audience
Management cookie configuration screen. See the DART documentation for more information about campaign management.
Integration Guides
263
GPT as an Audience Management Destination
Set up Google Publisher Tags (GPT) as a destination to send Audience Management segment data to DFP.
GPT Destination Requirements
Requirements and related information about setting up Google Publisher Tags (GPT) as an Audience Management destination.
Consider the following points when you want to set up GPT as an Audience Management destination:
• Add DIL: Deploy Data Integration Library (DIL) code on all the pages you want to target. DIL writes Audience Management
segment data and user IDs to cookies that get used by GPT for targeting.
• Create a Cookie Destination: GPT must be set up as a cookie-based destination in Audience Management.
• Implement Cookie Checking Code: Wrap the GPT .setTargeting API method in our recommended cookie checking code.
This code helps prevent errors by looking for valid AAM cookies before the .setTargeting method gets invoked.
• Add the AamGpt Function: The AamGpt code captures data from Audience Management cookies and sends it to GPT. Place
this code at the top of the page or inside the <head> codeblock.
Note: The AamGpt function is not required if you use your own code to read Audience Management cookie data.
• Send Delivery Logs to Audience Management: If you want a segment delivery report (optional), provide Audience Management
with a daily log that contains impression-level delivery data. The data can be in a raw format, but each record must contain
the Audience Management UUID. Audience Management can pick up or receive these via FTP.
Only Qualified Segments are Sent to GPT
The amount of data passed in to GPT depends on how many segments a particular user qualifies for. For example, say you set
up 100 Audience Management segments. If a site visitor qualifies for five of them, then only those five segments get sent to GPT
(not all 100).
Note: There are no limits to the number of key-values you can send, but the Google request URL does have limits to the
number of characters it can accept. See Setting targeting and sizes with GPT.
See Also
Google Publisher Tag API reference guide
Create a GPT Destination
Create a cookie-based destination for Google Publisher Tags in Audience Management.
Destinations
In Audience Management, a destination is any other system (ad server, DSP, ad network, etc.) that you want to share data with.
Destination Builder provides the tools that let you create and manage these data delivery processes. Audience Management
destination features are located in Manage Data > Destinations. To get started, click Add New Destination and follow the steps
below.
Basic Information
To complete the Basic Information section:
1. Name the destination.
2. Select "Cookie" from the Type drop-down list.
Integration Guides
264
3. Click Next and move on to the Configuration and Segment Mappings sections.
Cookie Configuration
Provide the following to complete the Configuration section (other fields are optional):
1. Cookie Name: Provide a short, descriptive name for your cookie.
2. Data Format: Select the "Single Key" option.
3. Key: Provide a key name.
4. Serialize: Select the Enable checkbox.
5. Serial Delimiter: Use a comma only.
Segment Mappings
To add a segment to a cookie destination:
1. Find segments: The Segment Mappings section provides two search tools to help locate segments. To find a segment:
• Option 1: Start typing a segment name in the search field. The field updates automatically based on entered text. Click Add
once you find the segment you want to use.
• Option 2: Click Browse All Segments to open a window that lets you browse for segments by name or storage location.
Click Add Selected Segments when done.
2. Add Mappings: In the mappings pop, enter the segment ID in the mappings field and click Save.
3. Click Done.
Modify the GPT setTargeting API Call
Add an if statement to check for Audience Management cookies before calling the Google Publisher Tag .setTargeting
method.
Check for Audience Management Cookies With an IF Statement
The .setTargeting method gets data from the Audience Management destination cookie and the unique user ID cookie
(aam_uuid). However, if .setTargeting gets invoked before DIL writes these cookies, or the cookies are empty, you may
see errors when the page loads. To help avoid this, wrap the .setTargeting method in an if statement that checks for these
cookies. If they're not set, this statement prevents .setTargeting from calling the AamGpt function.
IF Statement Code Sample
In this example, the Audience Management destination cookie name is Sample. You set this name when you create the destination
cookie in the Audience Management UI. DIL sets the aam_uuid cookie and the name cannot be changed.
if(typeof AamGpt.getCookie("Sample") != "undefined"){
googletag.pubads().setTargeting(AamGpt.getKey("Sample"),AamGpt.getValues("Sample"));
};
if(typeof AamGpt.getCookie("aam_uuid") != "undefined" ){
googletag.pubads().setTargeting("aamId", AamGpt.getCookie("aam_uuid"));
};
AamGpt Functions and Data Types
Defines the key variables used in the if statement.
Function
Type
Description
AamGpt.getKey
String
Returns the key in the key-value segment pair. For example, if
your key-value pair consisted of color=blue, this returns color.
Integration Guides
265
Function
Type
Description
AamGpt.getValues
Array of strings
Returns values in an array, e.g., ["value1","value2"].
AamGpt.getCookie
Int
Returns the Audience Management user ID, e.g., 12345.
AamGpt Code
A JavaScript function that reads Audience Management cookie data and sends that information to Google Publisher Tags.
Note: This function is not required if you have your own code to read Audience Management cookie data from the UUID
and destination cookies.
Sample Code
Place the AamGpt code at the top of the page, ideally within the <head> codeblock. The AamGpt code is available below:
var AamGpt = {
strictEncode: function(str){
return encodeURIComponent(str).replace(/[!'()]/g, escape).replace(/\*/g, "%2A");
},
getCookie: function(c_name)
{
var i,x,y,c=document.cookie.split(";");
for (i=0;i<c.length;i++)
{
x=c[i].substr(0,c[i].indexOf("="));
y=c[i].substr(c[i].indexOf("=")+1);
x=x.replace(/^\s+|\s+$/g,"");
if (x==c_name)
{
return unescape(y);
}
}
},
getKey: function(c_name){
var c=this.getCookie(c_name);
c=this.strictEncode(c);
if(typeof c != "undefined" && c.match(/\w+%3D/)){
var cList=c.split("%3D");
if(typeof cList[0] != "undefined" && cList[0].match(/\w+/))
{
return cList[0];
}
}
},
getValues: function(c_name){
var c=this.getCookie(c_name);
c=this.strictEncode(c);
if(typeof c != "undefined" && c.match(/\w+%3D\w+/)){
var cList=c.split("%3D");
if(typeof cList[1] != "undefined" && cList[1].match(/\w+/))
{
var vList=cList[1].split("%2C");
if(typeof vList[0] != "undefined")
{
return vList;
} else {
return null;
}
} else {
return null;
}
} else {
return null;
Integration Guides
266
}
}
};
DFP as an Audience Management Destination
Set up DFP as a destination and send Audience Management segment data to that platform.
DFP Destination Requirements
Standards for code placement, supported key-value formats, reports, and the type of segment data sent to DFP.
Requirements
This destination type requires the following:
• DIL: Data Integration Library code should be deployed on your inventory. DIL helps eliminate the need to write special code
for data collection, integration, reading cookie values, and recovering page data.
• get_aamCookie Function: Code that captures the Audience Management user ID and cookie data. Place this code on the top
of the page or inside the <head> codeblock.
• Send Delivery Logs to Audience Management: If you want a segment delivery report (optional), provide Audience Management
with a daily log that contains impression-level delivery data. The data can be in a raw format, but each record must contain
the Audience Management UUID. Audience Management can pick up or receive these via FTP.
Cookie Format and Key-Value Data
Audience Management can send segment data to a browser cookie as follows:
• Single keys (x=1&x=2).
• Multiple keys (x=1&x=2&y=3&y=4).
• Serialized values (x=1,2,3)
• A standard value delimiter separates individual key-value pairs.
Only Qualified Segments are Sent to DFP
The amount data passed in to DFP depends on how many segments a particular user qualifies for. For example, say you set up
100 Audience Management segments. If a site visitor qualifies for five of them, then only those five segments get sent to DFP
(not all 100).
Create a DFP Destination
Create a cookie-based destination for DFP in Audience Management.
In Audience Management, a destination is any other system (ad server, DSP, ad network, etc.) that you want to share data with.
Destination Builder provides the tools that let you create and manage these data delivery processes. Audience Management
destination features are located in Manage Data > Destinations. To get started, click Add New Destination and follow the steps
below.
Step 1: Basic Information
To complete the Basic Information section:
1. Name the destination.
2. Select "Cookie" from the Type drop-down list.
3. Click Next and move on to the Configuration and Segment Mappings sections.
Step 2: Configuration Information
Integration Guides
267
To complete the Configuration section:
1. Cookie Name: Provide a short, descriptive name for your cookie.
2. Cookie Domain: Leave blank to set a cookie in the domain of the user's current page. If you want to specify a domain, prefix
the name with a period like this, .mydomain.com.
3. Choose a key option in the Data Format section.
4. If your keys use data with serialized values, select the Serialize control and specify the serial delimiter (the character that
separates the serialized values).
5. Click Save and expand the Segment Mappings section.
Step 3: Segment Mappings
To add a segment to a cookie destination:
1. Find segments: The Segment Mappings section provides two search tools to help locate segments. To find a segment:
• Option 1: Start typing a segment name in the search field. The field updates automatically based on the text. Click Add
once you find the segment you want to use.
• Option 2: Click Browse All Segments to open a window that lets you browse for segments by name or storage location.
Click Add Selected Segments when done.
2. Add Mappings: In the mappings pop, enter the segment ID in the mappings field and click Save.
3. Click Done.
DFP Setup
Modify DFP settings to work with Audience Management segment data.
To set up DFP
• Install DIL code across your site.
• Create DFP as a cookie destination in Audience Management.
• Place the get_aamCookie function at the top of the page, ideally within the <head> codeblock. The get_aamCookie code
is available here.
• Modify your ad tag to call the get_aamCookie function and include the cookie name you provided when setting up the DFP
destination. For example, if you named the cookie test_cookie, then the ad tag should call get_aamCookie and reference
the cookie name. Your ad tag could look similar example below.
<a href= “http://client.adserver.net/?” + get_aamCookie(‘test_cookie’) +
“&etc&u=” + get_aamCookie(‘aam_uuid’)
Remember to include the u= variable. It holds the actual unique user ID (UUID) passed in during an ad call.
OAS as an Audience Management Destination
Set up OAS as a destination and send Audience Management data to that platform.
OAS Destination Requirements
Standards for code placement, supported key-value formats, reports, and the type of segment data sent to OAS.
This destination type requires the following:
• DIL: Data Integration Library code should be deployed on your inventory. DIL helps eliminate the need to write special code
for data collection, integration, reading cookie values, and recovering page data.
• get_aamCookie Function: Code that captures the Audience Management user ID and cookie data. Place this code on the top
of the page or inside the <head> codeblock.
Integration Guides
268
• Send Delivery Logs to Audience Management: If you want a segment delivery report (optional), provide Audience Management
with a daily log that contains impression-level delivery data. The data can be in a raw format, but each record must contain
the Audience Management UUID. Audience Management can pick up or receive these via FTP.
Cookie Format and Key-Value Data
Audience Management can send segment data to a browser cookie as follows:
• Single keys (x=1&x=2).
• Multiple keys (x=1&x=2&y=3&y=4).
• Serialized values (x=1,2,3)
• A standard value delimiter used to separate individual key-value pairs.
Only Qualified Segments are Sent to OAS
The amount data passed in to OAS depends on how many segments a particular user qualifies for. For example, say you set up
100 Audience Management segments. If a site visitor qualifies for five of them, then only those five segments get sent to OAS
(not all 100).
Create an OAS Destination
Create a cookie-based destination for OAS in Audience Management.
In Audience Management, a destination is any other system (ad server, DSP, ad network, etc.) that you want to share data with.
Destination Builder provides the tools that let you create and manage these data delivery processes. Audience Management
destination features are located in Manage Data > Destinations. To get started, click Add New Destination and follow the steps
below.
Step 1: Basic Information
To complete the Basic Information section:
1. Name the destination.
2. Select "Cookie" from the Type drop-down list.
3. Click Save and move on to the Configuration and Segment Mappings sections.
Step 2: Configuration Information
To complete the Configuration section:
1. Cookie Name: Provide a short, descriptive name for your cookie.
2. Cookie Domain: Leave blank to set a cookie in the domain of the user's current page. If you want to specify a domain, prefix
the name with a period like this, .mydomain.com.
3. Choose a key option in the Data Format section.
4. If your keys use data with serialized values, select the Serialize control and specify the serial delimiter (the character that
separates the serialized values).
5. Click Save and expand the Segment Mappings section.
Step 3: Segment Mappings
To add a segment to a cookie destination:
1. Find segments: The Segment Mappings section provides two search tools to help locate segments. To find a segment:
• Option 1: Start typing a segment name in the search field. The field updates automatically based on the text. Click Add
once you find the segment you want to use.
Integration Guides
269
• Option 2: Click Browse All Segments to open a window that lets you browse for segments by name or storage location.
Click Add Selected Segments when done.
2. Add Mappings: In the mappings pop, enter the segment ID in the mappings field and click Save.
3. Click Done.
OAS Setup
Modify OAS settings to work with Audience Management segment data.
To set up OAS
• Install DIL code across your site.
• Create OAS as a cookie destination in Audience Management.
• Place the get_aamCookie function at the top of the page, ideally within the <head> codeblock. The get_aamCookie code
is available here.
• Modify your ad tag to call the get_aamCookie function and include the cookie name you provided when setting up the OAS
destination. For example, if you named the cookie test_cookie, then the ad tag should call get_aamCookie and reference
the cookie name. Your ad tag could look similar example below.
<a href= “http://client.adserver.net/?” + get_aamCookie(‘test_cookie’) +
“&etc&u=” + get_aamCookie(‘aam_uuid’)
Remember to include the u= variable. It holds the actual unique user ID (UUID) passed in during an ad call.
OpenX as an Audience Management Destination
Set up OpenX as a destination and send Audience Management segment data to that platform.
Note: For onsite ad server targeting only.
OpenX Destination Requirements
Standards for code placement, supported key-value formats, reports, and the type of segment data sent to OpenX.
Review the following before setting up OpenX as an Audience Management destination:
• DIL: Data Integration Library code should be deployed on your site. DIL helps eliminate the need to write special code for
data collection, integration, reading cookie values, and recovering page data.
• get_aamCookie Function: Code that captures the Audience Management user ID and cookie data. Place this code on the top
of the page or inside the <head> codeblock.
• Send Delivery Logs to Audience Management: If you want a segment delivery report (optional), provide Audience Management
with a daily log that contains impression-level delivery data. The data can be in a raw format, but each record must contain
the Audience Management UUID. Audience Management can pick up or receive these via FTP.
Key-Value Data: Format Requirements
Audience Management sends data in the form of key-value pairs. Create key-value pairs according to the following specifications:
• Preface keys with c. (e.g., c.color or c.price).
• Separate serialized values attached to a single key with a comma (e.g., c.color = red, green, blue).
• Separate multiple key-value pairs with an ampersand (e.g., c.color=red & c.price = 100 & c.condition = new).
• Key names should not contain special characters like accent and punctuation marks or other symbols.
Integration Guides
270
Only Qualified Segments are Sent to OpenX
The amount data passed in to OpenX depends on how many segments a particular user qualifies for. For example, say you set
up 100 Audience Management segments. If a site visitor qualifies for five of them, then only those five segments get sent to
OpenX (not all 100).
Create an OpenX Destination
Create a cookie-based destination for OpenX in Audience Management.
In Audience Management, a destination is any other system (ad server, DSP, ad network, etc.) that you want to share data with.
Destination Builder provides the tools that let you create and manage these data delivery processes. Audience Management
destination features are located in Manage Data > Destinations. To get started, click Add New Destination and follow the steps
below.
Step 1: Basic Information
To complete the Basic Information section:
1. Name the destination.
2. Select "Cookie" from the Type drop-down list.
3. Click Next and move on to the Configuration and Segment Mappings sections.
Step 2: Configuration Information
To complete the Configuration section:
1. Cookie Name: Provide a short, descriptive name for your cookie.
2. Cookie Domain: Leave blank to set a cookie in the domain of the user's current page. If you want to specify a domain, prefix
the name with a period like this, .mydomain.com.
3. Choose a key option in the Data Format section.
4. If your keys use data with serialized values, select the Serialize control and specify the serial delimiter (the character that
separates the serialized values).
5. Click Save and expand the Segment Mappings section.
Step 3: Segment Mappings
To add a segment to a cookie destination:
1. Find segments: The Segment Mappings section provides two search tools to help locate segments. To find a segment:
• Option 1: Start typing a segment name in the search field. The field updates automatically based on the text. Click Add
once you find the segment you want to use.
• Option 2: Click Browse All Segments to open a window that lets you browse for segments by name or storage location.
Click Add Selected Segments when done.
2. Add Mappings: In the mappings pop, enter the segment ID in the mappings field and click Save.
3. Click Done.
OpenX Setup
Modify OpenX settings to work with Audience Management segment data.
To set up OpenX
• Install DIL code across your site.
• Create OpenX as a cookie destination in Audience Management.
Integration Guides
271
• Place the get_aamCookie function at the top of the page, ideally within the <head> codeblock. The get_aamCookie code
is available here.
• Modify your ad tag to call the get_aamCookie function and include the cookie name you provided when setting up the
OpenX destination. For example, if you named the cookie test_cookie, then the ad tag should call get_aamCookie and
reference the cookie name. Your ad tag could look similar example below.
<a href= “http://client.adserver.net/?” + get_aamCookie(‘test_cookie’) +
“&etc&xid=” + get_aamCookie(‘aam_uuid’)
Remember to include xid= . It holds the actual unique user ID (UUID) passed in during an ad call.
The fully formed ad call could look similar to this:
http://client.adserver.net/?c.key1=val1&c.key2=val2&etc& xid =3286487458745343
Share Data between Marketing Cloud Solutions
Guides to help you integrate Adobe Marketing Cloud solutions with Audience Management.
Analytics Data Integration
This document describes how to use the Audience Management Data Information Library (DIL) module to bring Analytics
data in to Audience Management.
The Audience Management Data Integration Library (DIL)
DIL is a self-contained code module that helps you collect data from Analytics and send that information to Audience Management.
You can set up DIL through Tag management or by direct placement within the source code of a website.
Data Collection with DIL
DIL reads the data contained in the Analytics s_code.js file and sends that information to Audience Management through a
separate data call.
Data Collection Overview
This method uses Tag management to set up an Audience Management - Analytics data integration. However, you can set up
s_code.js and DIL independently of Tag management, but the data collection process works the same way. Data
collection/integration works as follows:
1. Analytics collects data when your page loads.
2. The s_code.js object calls s.t() to send data to Analytics.
3. DIL reads the data collected by s_code.js and:
• Appends c_ to the Props, eVars, andevent variables, which marks them as user-defined variables in Audience Management.
• Makes a separate HTTP call that passes in Analytics data to Audience Management.
Note: Always make sure your DIL code appears on the page before the Analytics s.t() function.
Sample Analytics and DIL HTTP Calls
The separate HTTP calls sent by Analytics and DIL could look similar to the following:
Integration Guides
272
HTTP Call To
Looks Like
Analytics
http://...107.net?c30=foo&v35=bar&events=event10
Audience Management
http://...demdex.net/event?c_prop30=foo&c_evar35=bar&c_events=event10
Analytics Data in Audience Management
Audience Management turns Analytics Props, eVars, and events into traits.
Analytics Props, eVars, and events work like traits in Audience Management. Traits are key-value pairs and are used to build
segments. For example, in an Analytics prop like prop35=foo, prop35 is the key (a constant) and foo is the value (a variable).
Match Audience Management Traits to Analytics Variables
To use the Analytics data passed in by DIL, you should create Audience Management traits that have:
• The same names as their Analytics equivalents.
• A key value prefixed with c_.
See the table for examples:
Analytics Data Element
Analytics Example
As Audience Management Trait
prop
c30=foo
c_prop35=foo
evar
v35=bar
c_evar=car
events
events=event10
c_events=event10
Analytics Data as Unused Signals
Audience Management accepts Analytics Props, eVars, and events even without a corresponding trait. In this case, the data is
unavailable for trait creation and appears in the Unused Signals report instead. To make the most of this information, create
Audience Management traits that match the Analytics data passed in by DIL.
Integration Methods
Supported Audience Management - Analytics data integration methods.
Note: Always place your DIL code on the page before the Analytics s.t() function.
Recommended Integration With DIL and Tag Management
Bring Analytics data into Audience Management by serving DIL and s_code.js through Tag management. This is the preferred
data integration method.
Prerequisites
To use this method you must:
• Have an active Analytics account and access to the s_code.js file.
• Obtain the customized DIL code and from your Audience Management Partner Solutions manager.
• Serve DIL and s_code.js through Tag management.
Configuration Steps
Integration Guides
273
1. Create a new Tag management container. See the Tag management quick start documentation if you need help with this
step.
2. Find the Tag management container you want to work with and click Edit.
3. Select the Add Product or Code dropdown and choose JavaScript from the menu.
This opens the Create Partner Tag pop. Provide a description and click Add Tag.
4. Paste your customized DIL code into the text field and click Save and Deploy.
5. Check the source code on your site to make sure DIL gets placed before the Analytics s.t() function.
Alternate Method: Direct Page Placement
Bring Analytics data into Audience Management by loading DIL through Tag management when the s_code file is already set
up on your site.
Prerequisites
To use this method you must:
• Place the Analytics s_code.js code on the page you want to collect data from.
• Obtain the customized DIL code and from your Audience Management Partner Solutions manager.
Configuration Steps
To capture Analytics data with Tag management and DIL:
1. Create and save a new Tag management container. Review the quick start documentation for Tag management if you need
help with this step.
2. In the container list, click the container name to open theContainer Environment Overview.
3. In the Container Environment Overview, find the Setup section and click Download JS Loader to download the s_code.js
file.
Change the name to atm_code.js and save it to your computer.
4. Open atm_code.js in a text editor. Insert s.tagContainerSynchronous=trueafter the line s.tagContainerDC="
" and save the changes.
Your modified file could look similar to this:
/* Adobe Tag Container Loader version: 1.0.7
Copyright 1996-2012 Adobe, Inc. All Rights Reserved
More info available at http://www.omniture.com */
var s=new TagContainerLoader()
s.tagContainerDC="d2"
s.tagContainerSynchronous=true
s.tagContainerNamespace="demdex"
s.tagContainerName="Newcontainer"
s.loadTagContainer()
5. Push the atm_code.js file to your Web server (e.g., http://www.YourSite.com/tagLoader/atm_code.js).
6. In Tag management (Container Environment Overview section), click View Page Code.
This opens the View Page Code pop.
7. Edit the page code in a text editor. Replace src="s_code.js" with the location of the loader file hosted on your server and
save it as a text (.txt) file on your computer.
Your modified file could look similar to this:
<!-- Adobe Digital Marketing Suite Tag Management code
Copyright 1996-2012 Adobe, Inc. All Rights Reserved
More info available at http://www.adobe.com -->
<script type="text/javascript" src="http://www.YourSite.com/tagLoader/atm_code.js"></script>
<script type="text/javascript">//<![CDATA[
if(s){
s.pageName = ""
s.server = ""
s.channel = ""
Integration Guides
274
s.t()
}
//]]></script>
<!-- End Adobe Digital Marketing Suite Tag Management code -->
8. Remove the s.t( ) call from your page and traffic the modified page code after the s_code.js on all pages where you
want to collect or action data with Audience Management.
9. In Tag management, select the container you want to work with and click Edit.
10. Expand the Custom Core Javascript section, paste in your customized DIL code, click Save and Deploy.
Master Marketing Profile Integration
Use the Master Marketing Profile (MMP) to send data directly from Adobe Analytics to Audience Management rather than
using the Data Integration Library (DIL).
For more information about the Master Marketing Profile, see Audience Services - Master Marketing Profile.
Configure the Audience Management Module
The Audience Management Module is added to your Analytics JavaScript code.
1. Complete the Profiles and Audiences Access Request form, then contact your Audience Management consultant to have MMP
enabled for your account.
2. Download AppMeasurement version 1.4 for JavaScript or later from Analytics Code Manager.
3. Update your AppMeasurement code to the version that is included in the download zip.
4. Copy all of the code from AppMeasurement_Module_AudienceManagement.js (included in the download zip)
and paste it just above the DO NOT ALTER ANYTHING BELOW THIS LINE" section (see Example AppMeasurement.js
Code for an example of where to place module code).
5. Update the following code and paste in the Module section of AppMeasurement.js. For more information, see create.
s.loadModule("AudienceManagement");
s.AudienceManagement.setup({
"partner":"partner name",
"containerNSID":0,
"disableDefaultRequest": true,
"disableScriptAttachment": true
});
Request Types
Data is sent for page views, tracked links and video views (both milestone and heartbeat) that are tracked by your Analytics
implementation.
Data Sent
Config (d_*) Variables
Notes
d_rs
Set to the report suites(s) passed in with the hit to Analytics.
d_dst
Set to 1 if the request to Analytics is expecting destinationing content to be sent back to the
client.
d_mid
Marketing Cloud Visitor ID passed in to Analytics.
HTTP Header
Notes
Host
Set to the client specific DCS hostname specified in the Analytics host config
(PARTNER.demdex.net).
Integration Guides
275
HTTP Header
Notes
User-Agent
Set to the User-Agent header passed into Analytics.
X-Original-User-Agent
Only set if an alternate User-Agent was specified by one of these headers: *
X-Device-User-Agent\
• X-Original-User-Agent\
• X-OperaMini-Phone-UA\
• X-Skyfire-Phone\
• X-Bolt-Phone-UA\
X-Forwarded-For
Set to the IP address of the requesting client. Analytics will have already parsed the incoming
X-Forwarded-For header and determined the correct IP address to use.
Accept-Language
Set to the Accept-Language header passed in to Analytics.
Referer
Set to the page URL passed in to Analytics or gathered from the Referer header passed in to
Analytics.
Signal
Notes
c_latitude
Numeric latitude
c_longitude
Numeric longitude
c_pageName
The name of the page (if set)
c_pageURL
The address of the page in the address bar of the browser
c_referrer
Page prior to the current page
c_server
Web server name (set by s.server)
c_state
Geographical region (set by s.state)
c_zip & d_zc
Zip code (set by s.zip)
c_currencyCode
Type of currency for the transaction
c_purchaseID
Unique ID for the purchase
c_transactionID
Unique ID for the transaction
c_events
s.events
c_products
product string, set by s.products
c_linkClick
"custom," "download," or "exit"
c_linkCustomName
custom name (if any) provided for the link
c_linkDownloadURL
URL of download links
c_linkExitName
Custom name (if any) of exit links
c_linkExitURL
URL of exit links
c_mediaPlayerType
"other" or "primetime" for media stream tracking requests
c_screenResolution
width x height
c_colorDepth
Bits of color ("16", "32")
Integration Guides
276
Signal
Notes
c_clientDateTime
DD/MM/YYYY HH:MM:SS W TZ (TZ is in minutes and matches the return of JavaScript
Date.getTimezoneOffset)
c_timezone
Offset in hours
c_browserWidth &
c_browserHeight
width x height of browser window
c_cookiesEnabled
"Yes," "No," or "Unknown"
c_connectionType
"modem" or "lan"
c_javaScriptVersion
Version of JavaScript supported by browser
c_javaEnabled
"Yes," "No," or "Unknown"
c_channel
s.channel
c_campaign
s.campaign
c_prop#
Custom props
c_eVar#
Custom eVars
c_list#
Custom list variables
c_hier#
custom hierarchy variables
c_contextData.*
Example:
AppMeasurement: s.contextData["category"] = "news";
Signal: c_contextData.category=news
The following data is not sent by this integration:
• errorPage (Yes/No)
• codeVersion (code_ver)
• customTimestamp (ts)
Auditude Data Integration
An Audience Management - Auditude integration lets you send segments (in the form of key-value pairs) to Auditude. Once
configured, you can use Audience Management segment data to help display context or customer-specific content through the
Auditude player plug-in. Both products contain the tools and features you need to set up this data integration.
Benefits and Requirements
Describes benefits and requirements of an Audience Management - Auditude data integration.
Benefits of Audience Management - Auditude Data Integration
Advantages of integrating Audience Management with Auditude include:
• Access to a broad range of user data from other vendors.
• Creating more accurate and customized user experiences in Auditude with third-party data.
• Working with continually updated data (internal Audience Management synchronization processes help keep information
current).
Integration Guides
277
• Extensive code changes are not required (but you will have to add two small functions to the Auditude plug-in). The Audience
Management interface and the Auditude plug-in contain all the tools and code you need to make requests for segment data,
build segments, and transmit that data to Auditude.
Requirements
You must be an Auditude customer to perform this data integration.
Add Auditude as a Cookie Destination
As a first step, you must set up Auditude as a cookie-based destination in Audience Management.
Destinations
In Audience Management, a destination is any other system (ad server, DSP, ad network, exchange, etc.) that you want to share
data with. Destination Builder provides the tools that let you create and manage these data delivery processes. Audience
Management destination features are located in Manage Data > Destinations. To get started, click Add New Destination and
follow the steps below.
Step 1: Basic Information
Describes the required fields or steps in the Basic Information section you must complete to set up Auditude as a cookie-based
destination. To complete the Basic Information section:
1. Name the destination.
2. Select "Cookie" from the Type dropdown.
3. Click Save and move on to the Configuration and Segment Mappings sections.
Step 2: Configuration Information
Describes the required fields or steps in the Configuration section you must complete to set up Auditude as a cookie-based
destination. To complete the Configuration section:
1.
2.
3.
4.
5.
Name the cookie aud.
Choose Single Key option in the Data Format section.
Name the key segs.
Select the Serialize control and put a comma in the Serial Delimiter field.
Click Save and expand the Segment Mappings section.
Step 3: Segment Mappings
Describes the required fields or steps in the Configuration section you must complete to set up Auditude as a cookie-based
destination. To add a segment to a cookie destination:
1. Find segments: The Segment Mappings section provides two different tools that help you find segments. To search for a
segment:
• Option 1: Start typing a segment name in the search field. The field updates automatically based on the segment name.
Click Add once you find the segment you want to use.
• Option 2: Click Browse All Segments to open a window that lets you browse for segments by name or storage location.
Click Add Selected Segments when done.
2. Add Mappings: In the mappings pop, enter the segment ID in the mappings field and click Save.
3. Click Done.
Integration Guides
278
Auditude Setup
For the Auditude portion of this data integration, you'll need to modify plug-in code, add custom segments, and set up custom
targeting.
Add New Properties to the Auditude Plug-in
The Auditude plug-in requires 2 new properties so it can call Audience Management and retrieve segment data.
Set Domain URL
This code tells the Auditude plug-in what URL to use when it requests segment data from Audience Management. Replace the
italicized parameter with the following Audience Management URL, where mycompany is the domain alias used by your company
(e.g., http://mycompany.demdex.net?d_rtbd=json&d_dst=1).
_auditude.setProperty("audienceManagerURL",<url>);
Activate Audience Management Data Fetching
When set to true, this code tells the Auditude plug-in that you want to call Audience Management and retrieve segment data.
_auditude.setProperty("useAudienceManager",true);
Required Code Sequence
Instantiate these properties after creating a new plug-in instance and before calling _auditude.init as shown in the code
sample below.
_auditude=new AuditudePlugin();
...
_auditude.setProperty("audienceManagerURL",<url>);
_auditude.setProperty("useAudienceManager",true);
...
_auditude.init();
Add Custom Segments
In Auditude, you must set up custom key-value pairs that let you target Audience Management segments.
Define Custom Key-Value Pairs
To work with Audience Management data in Auditude, set up key-value pairs in the Custom Targeting module. Once defined,
you can target these key-value expressions in the Campaign Manager. To define new Audience Management key-value
expressions:
1. Go to Custom targeting > Key-value definitions.
2. Choose a publisher from the Select a publisher drop-down list.
3. Add the following to fields in the "Create new or edit existing" panel:
• Key:aud_aam_segments.
• Display name:AAM segments.
• Value: Enter the 6-digit Audience Management segment ID.
• Display name: Provide a short, descriptive name.
4. (Optional) Click Add Value if you need to add more values to the key.
Managing Saved Key-Value Pairs
Saved key-value pairs appear in the "Saved Definitions" panel on the left of the "Key-value definitions" subtab. Once saved, you
can edit key-value pairs or create expressions with Boolean operators.
Integration Guides
279
Target Audience Management Expressions in Custom Targeting
The Auditude custom targeting features let you create display qualification requirements for Audience Management data. Access
custom targeting features in Campaign Manager > Ad details > Targeting > Custom targeting.
Targeting
In Auditude, custom targeting passes context or user-specific information to the player when it loads. Also, the targeting interface
lets you set up display criteria by applying Boolean expressions to your Audience Management data. Create custom targeting
rules with standard point-and-click tools (by selection) or by manually writing code (by expression).
Target by Selection
Click the By selection tab to create targeting rules with basic point-and-click features in the user interface. The targeting
expressions you created previously appear in the targeting fields with the key aud_aam_segments.
Target by Expression
Click the By expression tab to create targeting rules by writing expressions with simple code and symbols. To define and identify
the Audience Management key, use the first 2 letters of the key name specified in the custom segments display name field (e.g.,
au).
Further Help With Targeting
For more information about how to target by selection or expression, see the Auditude guides from Zendesk.
Experience Manager Integration
Information to help you integrate Audience Management and Adobe Experience Manager.
As part of the Adobe Marketing Cloud, Audience Management consolidates audience information from all available sources.
It identifies, quantifies, and optimizes high-value target audiences, which can then be offered to advertisers via an integrated,
secure, privacy-friendly management system that works across all advertising distribution platforms.
Adobe Experience Manager (AEM) provides a complete suite of applications for the Web Experience Management (WEM) of
organizations.
For detailed, step-by-step instructions about integrating Audience Management and Experience Manager, see the Integrating
with Adobe Audience Manager guide.
Target Data Integration
This integration brings Audience Management segment data into Adobe Target. When complete, you can create Target offers
and experiences with Audience Management data.
Benefits and Requirements
Describes benefits and requirements of an Audience Management and Target data integration
Audience Management User Profile Data in Target
Data integration lets you use Audience Management data in Target to help improve rules-based content delivery. The advantages
of bringing Audience Management segment data into Target include:
• Access to other third-party data (useful when you're limited to your own, first-party data).
• Working with continually updated user profile data (internal Audience Management synchronization processes help keep
user profiles current).
• Access to profile data older than 14 days.
Integration Guides
280
• Creating customized user experiences based on first- and third-party data.
• Cross-domain visitor targeting.
Requirements
You must be an Audience Management and Adobe Target customer to perform this data integration.
Data Exchange Process
A general overview of how the Audience Management and Adobe Target data integration process works.
At a high level, Audience Management sends data to Target as described below:
1. As the page loads, API code makes a call to Audience Management.
2. Audience Management returns a JSON object that contains visitor-profile data.
3. The mbox.js file processes the returned JSON object. Any mbox on the page sends this data to Target.
Note: You do not need to update the mboxes in the <body> section of your page. Edit the mbox.js file instead.
4. Target evaluates this data against existing rules and returns appropriate content.
Data Integration Steps
Follow these procedures to bring Audience Management data into Adobe Target.
The data integration process uses the available features in Audience Management and Target. Other steps require code changes
to the Target mbox.js file.
The following table summarizes the integration workflow.
Product or Platform
Action
Audience Management
Create a cookie destination for Target.
Integration Guides
281
Product or Platform
Action
Adobe Target
• Add the plug-in code and the API call to your mbox.js file.
• Create profiles and campaigns that use Audience Management data.
Your Website
Upload the new mbox.js file to your website.
Audience Management Set Up
As a first step, set up Adobe Target as a cookie-based destination in Audience Management.
Destinations
In Audience Management, a destination is any other system (ad server, DSP, ad network, exchange, etc.) that you want to share
data with. Audience Management destination features are located in Manage Data > Destinations. To get started, click Add
New Destination and follow the steps below.
Step 1: Basic Information
To complete the Basic Information section:
1. Name the destination.
2. Select "Cookie" from the Type drop-down list.
3. Click Save and move on to the Configuration and Segment Mappings sections.
Step 2: Configuration Information
To complete the Configuration section:
1. Name the cookie aam_tnt.
2. Leave the domain name blank to set the cookie in the current domain of the page, otherwise specify the domain that should
be used for the cookie.
3. Choose the Multi Key option in the Data Format section. This automatically sets the default values used by the key-value
separator (=) and value delimiter (,) fields. Do not change these.
4. Click Save and expand the Segment Mappings section.
Step 3: Segment Mappings
To add a segment to a cookie destination:
1. Find segments: The Segment Mappings section provides two different tools that help you find segments. To search for a
segment:
• Option 1: Start typing a segment name in the search field. The field updates automatically based on the segment name.
Click Add after you find the segment you want to use.
• Option 2: Click Browse All Segments to open a window that lets you browse for segments by name or storage location.
Click Add Selected Segments when done.
2. Add Mappings: In the mappings pop, enter the segment ID in the mappings field and click Save.
3. Click Done.
Target Set Up
Create an Adobe Target campaign and add integration code to your website.
Integration Guides
282
Edit the Target mbox.js File
Add the plug-in code and the API call into the mbox.js file.
Set Up a Target Campaign
Target uses campaigns to set the rules for displaying content. For data integration, you set up a Target campaign (its locations,
experiences, and conversion metrics, etc.) to use data from the Mbox that captures Audience Management data. See the Target
campaign creation overview for more information.
Website Code Placement Sequence
Proper code placement is crucial to making the data integration process work properly. Incorrect placement won't break your
page, but it can prevent proper content delivery if these modules are out of order. This example assumes you're an Audience
Management customer using Tag Management to deploy and collect data with DIL.
Source Code Location
<head>
<body>
Placement Sequence
1. Target
Inside the Tag Management container:
1. Analytics s_code.js file (if used)
2. Audience Management DIL module
3. Analytics s.t() code (if used)
Edit the Target mbox.js File
Add the integration plug-in to your mbox.js file. This code lets Target work with Audience Management segment data. Obtain
the plug-in code from your Adobe account consultant.
Prerequisite: In Audience Management, create cookie-based destination for Target.
To add the integration code to a Target mbox.js file:
1. Click Configuration > mbox.js > Edit.
2. Insert the mbox.js file plug-in into the Extra JavaScript field.
The plug-in allows Target to read and parse Audience Management data. Obtain the plug-in from your Target or Audience
Management consultant.
Your code could look similar to the following sample:
/*Defines the function that adds parameters to a mbox call*/
function aam_tnt_cb() {
if (typeof (arguments[0].stuff) != "undefined" && arguments[0].stuff != "") {
for (var i = 0; i < arguments[0].stuff.length; i++) {
if (arguments[0].stuff[i].cn == "aam_tnt") {
if (arguments[0].stuff[0].cv.split(",")) {
var demdex_raw = arguments[0].stuff[i].cv.split(",");
var tapMboxBuilder = mboxFactoryDefault.getUrlBuilder();
tapMboxBuilder.addParameters(demdex_raw);
}
}
}
}
}
Integration Guides
283
3. Directly after the plug-in code in the previous step, paste the API call into the Extra JavaScript field, then click Save.
The API call captures data from Audience Management. Obtain a customized API call from your Target or Audience
Management consultant.
Your code will look similar to the following sample:
document.write('<script src="' + document.location.protocol +
'//omniture.demdex.net/event?d_stuff=1&d_dst=1&d_rtbd=json&d_cb=aam_tnt_cb"></script>');
4. Download the modified mbox.js file and save it to your host files or server.
Parameter and Response Reference
List of parameters, their descriptions, and a sample response.
Parameters
The following parameters are used in the API call to Audience Management:
Parameter
Description
omniture.demdex.net/event?
The event call to the Audience Management Data Collection Server (DCS).
d_stuff=1
Defines an array returned by the DCS that contains Audience Management data you
can use in Target.
d_dst=1
Returns a JSON response from the DCS.
d_rtbd=json
Prompts the DCS to return data inside a JSON response.
d_cb=<aam_tnt_cb>
Invokes the name of the code module that parses the array of JSON objects returned
by Audience Management. This makes Audience Management data available in
Target.
Sample Response
In the response, the Audience Management DCS returns a JSON response to the page. The stuff section contains data that
you can use in Target to create a new offer or experience. In this example, the JSON response contains a key-value pair make=ford.
tnt_dmdx_data({"dests":[],"dpm":[],"traits":[1234],"segments":[8404],
"stuff":[{"cn":"tnt","cv":"make=ford",ttl":30,"dmn":""}],
"uuid":"123456789987654321123456789"})
Reference
284
Reference
Contains technical documentation about system functionality, data integration, and help files.
FAQ
Frequently asked questions about Audience Management features, functions, and common issues.
API FAQ
Common API questions and issues.
The REST API documentation contains details about specific methods and code samples.
What do the REST APIs allow me to do?
The REST APIs let you work programmatically with most Audience Management features and functions that are available in
the user interface.
How do I obtain a REST API client ID and secret?
Contact your Partner Solutions representative to obtain API access credentials. Our APIs use OAuth 2.0 standards for token
authentication, authorization, and renewal. See OAuth Authentication for more information.
Data Collection and Product Integration FAQ
Common data collection and integration questions and issues.
How can I differentiate Inbound traffic from DCS traffic in DCS log file exports?
Traits onboarded via Inbound are populated by Inbound the same way they get populated by DCS. There are a few different
ways to tell that traffic came from Inbound:
• Remote IP will be set to 68.67.173.18
• DomainID will be set to 5325
• Region will be set to 0
What are the code placement and page load requirements for a DIL/Analytics Data Integration?
To bring Analytics data into Audience Management, load DIL after the s_code module but before the s.t() function. For
example, place your code, or make sure it loads, in this order:
1. Analytics s_code
2. Audience Management DIL module
3. Analytics s.t() function
As a best practice, set up your Audience Management-Analytics integration with either of these 2 methods:
• Put DIL directly in the s_code.
• Serve DIL and the s_code through Adobe Tag Manager.
See also: Analytics Data Integration.
Why are my Analytics variables missing from an Audience Management event call?
This usually happens when:
• You serve DIL through a tag management system that loads it asynchronously with other code elements on the page.
Reference
285
• The s.t() function loads before DIL.
What versions of Analytics work with DIL?
You must use Analytics version 20.2 (or higher) and the Adobe AppMeasurement AS library version 3.5.2 (or higher) to work
with DIL. If you don't know your Analytics or AppMeasurement version, check the Analytics call that gets made from the page.
Version information shown below:
This customer uses Analytics version 24.4:
http://112.2o7.net/b/ss/.../1/H.24.4/...
This customer uses AppMeasurement version 3.5.2:
http://112.2o7.net/b/ss/.../0/FAS-3.5.2-AS3/...
Can I collect page data if I'm not a Analytics Customer?
Yes. The DIL module helps you collect page data even if you're not using Analytics. When set up properly, DIL can capture data
from and about:
• Meta tags
• URLs and URL headers
• Search engine types
• Keywords
Additionally, clients can deploy a simple onsite object and populate it with key-value pairs that you want DIL to collect data on.
This lets you add and remove specific audience data points on your site without any Audience Management updates. Work with
your Partner Solutions representative to properly set this up and ensure the DIL module references the page object correctly.
Can DIL collect data from Google Analytics?
Yes. DIL can collect some Google Analytics (GA) elements and pass that data to Audience Management. However, Audience
Management accepts data in the form of key-value pairs while GA works with objects in an array. To work with GA data, DIL
automatically creates key-value pairs from GA data and passes in to Audience Management.
Can I get raw data from Audience Management and how granular is it?
Yes, Audience Management can provide you with data collected for users we've seen on your inventory. This includes:
• The unique user ID (UUID) assigned by Audience Management
• Trait and segment IDs
• Unused signals
• Time stamps
• Page URLs
I want to collect data on one site and target users via a DFP on a different site. Do I need to deploy code on the other property
if I don't want to collect data from that location?
Yes. Audience Management DIL code must be on the other site's page to target ads to a user. To target a user in the ad server,
we need to send segment information to DFP before the creative loads. To do this, Audience Management code must be on the
page where you want to target the user. The code identifies the user and sends that information to DFP. If Audience Management
code is absent from the target page, then we cannot send segments to DFP and target the user based on that data. Without DIL,
Audience Management cannot get segment information to DFP.
What is the best third-party data provider?
Reference
286
Each provider brings something unique to the table, so the answer depends on what you're looking for. We can enable overlap
reporting (at no cost) to help you understand which provider may work best for you.
How does Audience Management set cookies and pass variables to DFP?
Audience Management sets 2 cookies: One sends segment variables to the DFP ad tag and the other sets our unique user ID
(UUID), which is also read by DFP. Adding the UUID to the ad tag means we can do user-level reporting and audience discovery.
Can we send a DSP information about points in the conversion funnel reached by a user?
Yes. We can send funnel data, but the DSP must have the technical capability to use it. A DSP must confirm they can handle
multiple segments. If they cannot, we may need to create specific segments to pull a user out of other segments based on their
conversion progress (e.g., completed step 1 and 2 but not step 3). You may want to send this information to a DSP so they can
retarget users, direct them to a specific landing page, or display specific creatives.
How can I confirm that data sent via FTP has been picked up by Audience Management?
A file has been picked up when the extension changes from .sync to .processed. When this happens, the file is in the ingestion
queue. Also, your account manager can confirm when a file has been uploaded.
Inbound CRM Data Ingestion
Frequently asked questions about onboarding an offline CRM database into Audience Management.
The process to onboard your offline CRM database into Audience Manager can be broken down into three core components:
ID sync, Data Translation File (or Taxonomy File), and Inbound Data File (.sync/.overwrite file).
For details about the various components, see Technical Specifications for Inbound Batch Data Transfers.
Below is a list of questions and answers you might find helpful after reviewing the documentation.
Note: Some examples representing data-file contents are simplified for illustration purposes. For exact format specifications
of data file contents, refer to the online documentation.
Can you summarize the deployment process?
We recommend the following:
1. Work with your CRM provider to format the daily inbound data file according to Adobe specifications.
2. Transfer a test data file to Adobe for format verification.
3. Work with your Adobe consultant to produce a taxonomy file suitable for interpreting the contents of the data file. This is
a one-time upload of the taxonomy file.
4. In the staging/development environment, confirm that the ID sync is configured to properly pick up the CRM user ID and
transfer to the Audience Management servers in realtime.
5. Deploy DIL/ID sync to production. The ID sync will already be configured as a module within the DIL code by your Adobe
consultant.
6. Transfer production data files from CRM to Audience Management. Given the dependencies on ID sync mappings, it might
make sense to begin transferring data up to one week after production-code deployment, although you can start transferring
the data files as soon as code goes into production.
Can I upload an inbound data file (.sync file) before deploying Audience Management code into production?
The process works by first mapping an Audience Management ID to the CRM ID (ID sync) and then ingesting CRM data
(inbound data file) keyed off the CRM ID to associate to the Audience Management profile. Audience Management only
Reference
287
recognizes individual CRM IDs in the inbound data file that have been previously synched/matched back to an Audience
Management cookie ID.
Consider the following two scenarios:
Scenario 1: On Monday, CRM user ABC logs in, which initiates a client-side ID sync. Audience Management stores the mapping
of CRM user ABC to Audience Management user 123.
On Tuesday, the CRM database transfers a data file (.sync) to the Audience Management FTP server with the following record:
CRM user ABC = male,nyc,bird_enthusiast
Audience Management recognizes CRM user ABC from the stored ID sync mapping and pushes the traits “male,” “nyc,” and
“bird_enthusiast” to Audience Management user 123’s profile.
Scenario 2: On Monday, the CRM database pushes a data file (.sync) to the Audience Management FTP server with the
following record:
CRM user DEF = female,chi,reptile_enthusiast
Audience Management does not have a record of this user (or an associated Audience Management user ID) so this record is
not processed.
On Tuesday, CRM user DEF logs in, which initiates that user’s first client-side ID sync. CRM user DEF is mapped to Audience
Management user 456.
This new CRM user DEF / Audience Management user 456 does not have CRM data associated to his or her profile. Audience
Management does not go back and reprocess old files.
On Wednesday, the CRM database pushes another data file to the Audience Management FTP server with the following record:
CRM user DEF = female,chicago,reptile_enthusiast
Audience Management recognizes CRM user DEF from the stored ID sync mapping and pushes the traits “female,” “chicago,”
and “reptile_enthusiast” to Audience Management user 456’s profile.
What time of day should I transfer my file?
Audience Management queues uploaded files and processes them multiple times throughout each day, so you can upload the
file whenever makes sense for you.
How long does it take between when I upload an FTP file and when that data is targetable?
Depending on many factors, including where the individual user is located, it can take between 12-24 hours for all data to
propagate.
How often should I send files? Should I send full files or incremental files?
Generally it is a best practice to send a file once per day. Audience Management accepts two types of files: incremental (.sync)
files and full (.overwrite) files. With incremental (.sync) files, Audience Management handles the data points by appending
new data to records (not a complete erase/overwrite of user profiles). With full (.overwrite) files, Audience Management
preforms a complete overwrite of all user profiles (for that data source) that exist in the file.
For example:
Scenario 1:
• Day 1 .sync file contents: user123 = a,b,c
Reference
288
• Day 2 .sync file contents: user123 = c,d,e
• Day 3 user123’s profile in Audience Management contains a,b,c,d,e
Scenario 2:
• Day 1 .sync file contents: user123 = a,b,c
• Day 2 .overwrite file contents: user123 = c,d,e
• Day 3 user123’s profile in Audience Management contains c,d,e
Note: The .overwrite files overwrite profile data associated to this data source only. In other words, all Adobe Analytics
data associated to the user remains intact after a .overwrite file has been processed.
Many Audience Management customers send a daily incremental file and a weekly full file, but this is flexible and you should
send data in increments that make sense for your data set.
What happens if I send a file with IDs for users that have never performed the on-page ID sync?
During processing, Audience Management simply skips that record and moves on to the next.
What is the timestamp and what is it for? Can you provide an example?
The timestamp is a UTC UNIX timestamp in seconds, and looks like: 1368735453. The timestamp in the filename provides a
unique name for each incoming file and provides a time to associate data to user profiles for reporting.
What is the DPID and how do I get it?
Your Adobe consultant will assign a static three- or four-digit ID to your particular CRM instance. The DPID will not change.
How large can the daily data files be?
If the files are larger than 5 GB, please discuss the file and transfer process with your Adobe consultant. Although Audience
Management can handle very large files, there may be ways to reduce the file size or make transfer of data more efficient.
Does Audience Management support file compression?
Yes, we support .gz, .tar, .tgz, and .zip. Naming should be as follows: ftp_dpm_[dpid]_[timestamp].sync.gz
(or .sync.tar, etc.).
Note: The file contained should be named ftp_dpm_[dpid]_[timestamp].sync (or .overwrite), where the
timestamp matches the timestamp in the compressed container file.
What is the taxonomy (data translation file) for?
The taxonomy is in place so Audience Management can resolve data contained in the inbound data file (some of it potentially
unstructured) into a structured trait and folder hierarchy. Additionally, some customers store their CRM data as codes (e.g.
008937) so the taxonomy also gives you a way to assign human-readable designations to codes like these. Without a taxonomy
in place, Audience Management fails to translate data in inbound files to traits.
How often should I update the taxonomy? How do I do this?
For most use cases, the taxonomy isn’t something that needs to be updated very often. Generally, CRM databases have a finite
number of data points that don’t change often (gender, age, product subscription, etc.).
Reference
289
If you have the need to start collecting new data points, in preparation of new data points coming in the inbound data files, you
can update the taxonomy in one of two ways:
Using the Audience Management UI:This method is best used if you have a few new traits to update.
1. Click Traits > Create New Trait (Onboarded Trait).
2. Select the DPID associated to your CRM instance.
3. Specify the trait logic to parse your new data.
For example, if the new data to be expected in the inbound files will look like: gender=male, you might set up a new
onboarded trait called Male Users with the trait logic gender == male. If the new data looks like: income=[integer],
you might set up several onboarded traits—perhaps one called Upper Income with the trait logic income >= 250000.
Using an API though your Adobe consultant: This method is best used if you have many new traits or you need a trait overhual.
When you have many new data points, it might be more efficient to upload them programmatically in bulk. If you are using
Adobe REST APIs, please refer to the documentation for guidelines on creating/modifying onboarded traits. If you prefer to
use your Adobe consultant to upload, please allow sufficient lead time for processing.
The primary key in my CRM database is an email address. Is that considered personally identifiable information?
Yes. Audience Management does not store email addresses in our database. Users should be assigned a random ID or a
one-way-hashed version of the email address prior to initiating ID syncs.
Are the data file contents case-sensitive? How about the ID sync?
There are two basic components of a data file: User ID and Profile data (key-value pairs or codes).
User ID: This is case-sensitive. The case of the browser ID syncs must match the case of the IDs in the file. For example, Audience
Management will not find a match between ID sync occurrence 009uwwp0lwl and data file record 009UWWP0LWL.
Key-value pairs or codes: These are not case-sensitive. In other words, if the server-side trait logic is key=value and the data
file contents contain Key=Value, there will be a match.
Privacy FAQ
Common privacy-related questions and issues.
The Adobe Privacy Center contains additional information about common privacy topics.
Can Audience Management clients in the US target users on EU properties?
Yes. Audience Management works with clients who have international properties and inventory. The EU has strict privacy laws,
but Audience Management has clients who use first-party data for audience targeting in Europe. Furthermore, many EU
properties disclose that they collect data, which satisfies privacy laws. Audience Management can support targeting to EU
audiences, but it is your responsibility to comply with local privacy regulations.
Why does the IP address need to be removed from log files?
While still an open question in the US, regulators in Europe consider IP addresses as personally identifiable information (PII).
As a result, companies that collect IP addresses in the EU are subject to strict data processing requirements. To support expansion
into the EU, and help reduce compliance requirements for our customers, we remove IP addresses from log files. Also, this
change addresses where we believe industry self-regulation and legally required regulations are moving within the United States.
Removing IP addresses is a proactive change that will help Audience Management (and our partners) comply with existing and
future PII-related legislation.
Reference
290
Product Features and Functions FAQ
Common product and function-related questions and issues.
Can I create traits or destinations in bulk?
Yes. To make bulk changes, send a detailed request outlining the changes to your Partner Solutions contact. Be sure to detail
the changes in an Excel file.
Reporting FAQ
Common reporting-related questions and issues.
Some segments are missing from an Overlap report. Where are they?
To help reduce computational demand, these reports omit statistically insignificant data from the results. Your segments are
not missing, they're just dropped because they do not yield meaningful results or useful pools of users that you can target. See
Reports and Data Sampling Methodologies and Counting Unique Users in Overlap and General Reports.
If I run an email marketing campaign, how can I determine if redirected users come to my site from that campaign or from
other sources?
Append a campaign-specific query string to the URL of the site section you want to monitor. Next, set up a trait rule to capture
this variable. For example, if your URL passes in a campaign ID like this, www.test123.com/electronics?campaign=123,
then create a trait rule to capture that data from the h_referer variable with a trait rule that looks for a header like h_referer
= 'campaign=123').
What is the difference between real-time and total segment population counts?
• Real time: The actual number of unique users who identified themselves in that segment on your property during a set time
period.
• Total segment population: An aggregation of all users who are currently classified in that segment.
Why is data available for total fires for traits but not segments?
Total fires correspond to page loads. Total trait fires provide the number of times that specific trait has fired. This number will
always be equal to, or greater than, your unique user count. By contrast, segments are audience profiles that represent groups
of users. Segments don't correlate to page loads or views because they're tied to logic that classifies users based on rules, not
individual traits.
I have a segment consisting of just one trait. When I look at Reporting metrics, their counts don’t line up. Why is that?
Audience Management uses different methodologies to count traits and segments.
For traits, the counts essentially represent receipt of delivery. Every time a user realizes a particular trait, either in realtime via
the DCS, or offline via Inbound, the count for that trait goes up by 1.
For example, a trait count of 2340 over the range of 7 days means that 2340 unique users realized that trait over the last 7 days.
Segments are counted differently because their primary purpose is to help you understand your Audience better. Every time
Audience Management sees a user who is a member of a given segment, even if that segment isn’t being realized on a request,
the count for that segment goes up by 1.
For example, a segment count of 2340 over the range of 7 days means that Audience Management saw 2340 unique users in
real-time data-collection events over the last 7 days who were members of that segment at the time that Audience Management
saw them.
Reference
291
Targeting FAQ
Common targeting-related questions and issues.
Where can I find a full list of third-party data providers supported by Audience Management?
See the Adobe Exchange Marketplace
(https://marketing.adobe.com/resources/content/resources/en/exchange/marketplace/audience.html) for a complete list of
third-party data providers that Audience Management supports.
To target users I've never seen on my site with third-party data, should I use third-party data in Audience Management or
in a DSP?
The answer depends on your goals. For example, if your campaign is designed to find new clients with third-party data, then
work directly with a DSP. Remember, Audience Management synchronizes data with a third-party data provider only when we
see that user. If we have never seen a user before, our system will not have any information for that site visitor. For campaigns
that only want to use third-party data to target users who have never visited any of your properties, then create those segments
through the DSP.
Can I market to individuals?
Audience Management lets you aggregate users and market to them based on shared attributes or traits. However, to comply
with industry regulations, we do not let personally identifiable information (PII) to flow through our systems. As a result, you
cannot use email addresses, individual names, physical addresses, etc. for targeting.
How do I keep retargeting data secure?
We recommend you use a server-to-server connection to exchange data with your preferred retargeting platform. Audience
Management exchanges data with most of the major DSPs through server-to-server connections. Server-to-server data transfers
help prevent other actors from intercepting your data and re-selling that audience information.
Is the Audience Management unique user ID (UUID) tied to an ad server's unique user ID by ID synching directly on the
page?
No. ID synchs are not made on the page for on-site publishers or servers. The Audience Management UUID is inserted into
the u= field of the ad server log files. This happens as segment gets passed in for targeting. The DIL code module performs this
function. This is the same mechanism that allows us to map the server's user ID to an Audience Management user for segment
performance reporting. However, if an ad server is present on site, then we synch IDs directly on the page.
Does Audience Management count a user who logs on from different devices as one unique user or different unique users?
Declared ID Targeting helps Audience Management identify a visitor across multiple devices with a single unique identifier.
However, from a targeting or destination perspective, this is still 2 (or more) users because DSPs cannot reconcile those multiple
IDs.
Can Audience Management identify a user from display and mobile devices.
Yes. See Declared ID Targeting.
Can I score users with data collected online and retarget them based on this model score?
Yes. Audience Management can provide data files to help you score users, but you must work with other vendors or software
to analyze and rank this information. Send this data to Audience Management in the form of key-value pairs. We can take this
information and append it to existing user profiles. Contact your Partner Solutions representative to review this process.
What are the cookie deletion rates over a given 1 - 2 month period?
Reference
292
Cookie deletion is difficult to measure. Most cookie deletion comes from a few visitors who delete cookies frequently. However,
most browser cookies are stable for at least 30 days, even though some may have a limited life. Some studies suggest upper-funnel
targeting that is greater than 30 days would effectively eliminate 7% of the browser target audience over a 30-day period. As you
know, 30 day campaigns for a given creative message are standard in the industry. From what we’ve seen, that 7% drop-off is
accurate.
Cookie deletion has an adverse effect on reach and frequency calculations. As a result, we stress the value of behavioral data
when trying to understand the true nature of consumer trends for display campaign planning. Our clients can leverage Audience
Management segment overlap reports, optimal impression frequency reports, and unique user trends over specific date ranges
to be more scientific about campaign planning and optimal date ranges for running campaigns.
What is the expiration window for Audience Management cookies?
The user interface lets you determine the cookie expiration interval. You can set cookies to expire after n number of days or
never.
Does implementing a campaign creative in an event call cost us more?
It depends. Cost is based on unique users. If a campaign results in net new users, then yes, this will cost more. If your campaign
reaches places where we're already collecting data, then there's no additional cost. If your campaign runs on related sites where
there is significant overlap, there will be additional cost for the new unique users we see.
Campaign Data Integration
You can capture campaign data using pixel calls to Audience Management (often called pixeling the creative) or by ingesting
log files.
Capturing Campaign Data Via Pixel Calls to Audience Managment
Information about how to capture campaign impression and click data via Pixel calls to Audience Management.
Capturing Campaign Impression Data via Pixel Calls
One approach for sending media data to Audience Management is to leverage ad-server macro functionality (such as DFA or
Pointroll) to send campaign attributes to the Audience Management servers.
This is approach is often referred to as "pixeling the creative." Those data points are dynamically inserted into the Audience
Management pixel code by the third-party ad server macros, which are used to map and report all impressions and clicks based
on the key reporting attributes of the campaign. The aggregated data provides a unified view of campaign performance, helps
identify custom conversion paths, and helps customers improve the sequence of ad server events that lead to conversions.
This section contains the following information:
• Event Call Syntax and Main Key-Value Pairs
• Main Key-Value Pairs
Event Call Syntax and Main Key-Value Pairs
The event call collects impression and conversion data and sends it to the Audience Management data collection servers (DCS).
This process relies on third-party ad servers that place the call in the creative to control what content gets inserted into the code.
The third-party ad servers (for example, DFA) can place this code within each ad impression. Furthermore, an ad call does not
use JavaScript or employ frame-busting techniques to access publisher data outside of the ad tag.
Reference
293
Event calls consist of key-value pairs that look similar to the following example:
http://clientname.demdex.net/event?d_event=imp&d_src=<datasource_id>&d_site=<sideID>&d_creative=<creative_id>&d_adgroup=<adgroup_id>&d_placement=<placement_id>&d_campaign=<campaign_id>&d_bust=<cache
buster value>
The value, in the key-value pair, is the macro dropped in by the ad server for campaign tracking. When the ad tag loads, that
%macro% gets replaced with the required, corresponding values. This call does not return a response.
Main Key-Value Pairs
The Audience Management event call passes in data as key-value pairs. The following table describes these common objects:
Key
d_event=imp
d_creative
d_adgroup
d_placement
d_campaign
d_site
d_bu
d_bust
Value
Required?
Adobe ad call classification.
Required
Numeric creative ID from the ad server.
Optional
Numeric ad group ID from the ad server.
Optional
Numeric placement ID from the ad server.
Optional
Numeric campaign ID from the ad server.
Optional
Numeric site ID from the ad server.
Optional
Name of the business unit.
Optional
Cache-busting value.
Optional
Audience Management automatically sends
cache-control headers that are honored by most
browsers and proxies. If you want to perform
additional cache busting, include this parameter
in an event call, followed by a random string.
d_src
DPID of the source from where Audience
Management pulls the metadata.
Required
Note: Please contact your Adobe Audience Management consulting or account lead for the exact URL specific to the client
domain.
Capturing Campaign Click Data via Pixel Calls
Click tracking enables measurement of visitor engagement throughout your campaign, as it records click-based activity for
third-party creatives. Similar to impressions collection, an event call is sent to the Audience Management data collection servers
(DCS) for processing. The visitor is then redirected to the intended web address.
Request
http://client.demdex.net/event?d_event=click&d_creative=123&d_rd=http%3A%2F%2Fadobe.com%2Fcallback%3Fcreative%3D%25d_creative%25
Reference
294
Response
HTTP/1.1 302 Found
The browser will then be redirected to the URL specified in the d_rd parameter with the appropriate values specified by any
macros, if used, as explained below.
Based on the above example, the browser is redirected to the following URL:
http://adobe.com/callback?creative=123
Click tracking calls require that the following parameters be present:
• d_event=click, an Audience Management call classification.
• d_rd, which will contain the redirect link in URL encoded format.
In addition, the call can contain key value pairs that can be used for trait qualification.
Macro support is provided for these types of calls. A macro is key value pair that is dropped when the ad tag loads for campaign
and user tracking. The macros will be passed along with the destination URL, as long as they are marked with the following
format: %macro%.
Supported Macros
Name
Description
Macro Format
Required?
d_creative
Numeric creative ID from the ad server.
%d_creative%
Required
d_adgroup
Numeric adgroup ID from the ad server.
%d_adroup%
Required
d_src
DPID of the source from where Audience Management pulls %d_src%
the metadata.
Required
d_campaign
Numeric campaign ID from the ad server.
%d_campaign%
Optional
d_placement
Numeric placement ID from the ad server.
%d_placement%
Optional
d_site
Numeric site ID from the ad server.
%d_site%
Optional
d_bu
Name of the business unit.
%d_bu%
Optional
d_dpuuid
User ID of the visitor, as known in the partner's system.
%d_dpuuid%
Optional
d_uuid
Specify the ID of the visitor directly in the URL instead of
relying on Demdex cookie.
%d_uuid%
Optional
d_dpid
Data Provider ID. Should always be specified in conjunction
with d_dpuuid.
%d_id%
Optional
r_rand
Random number.
%r_rand%
Optional
Reference
295
Macros Example
This example demonstrates passing creative, adgroup, and placement macros.
This example assumes that the following values for each parameter are passed in the non-redirect portion of the click-tracking
call:
creative=1235
campaign=4709
adgroup=3408
placement=1001
src=203
Request
http://client.demdex.net/event?d_event=click&d_creative=1235&d_src=203&d_campaign=4709&d_adgroup=3408&d_placement=1001&d_rd=http%3A%2F%2Fadobe.com%2Fcallback%3Fcreative%3D%25d_creative%25%26campaign%3D%25d_campaign%25%26adgroup%3D%25d_adgroup%25%26d_placement%3D%25placement%25%26src%3D%25d_src%25
Response
HTTP/1.1 302 Found
Based on the above example, the browser is redirected to the following URL:
http://adobe.com/callback?creative=1235&campaign=4709&adgroup=3408&placement=1001
Delivery Performance Report: Log File Recommendations
Guidelines to help improve log file ingestion and processing times.
Create and format your Delivery Performance report log files according to these recommendations.
This topic contains the following information:
• Prerequisite Information to Provide to Adobe
• Data/File Formatting
• Commonly Used Dimensions
Prerequisite Information to Provide to Adobe
Recommendation
File Access
Description
We strongly recommend that you work with Adobe to set up an Amazon S3 bucket.
Note: Audience Management uses Amazon S3 to store data. Rather than send us
data via FTP, deliver the logs to an S3 directory instead. We can process data directly
from this location. Your Partner Solutions manager can help you get access to S3.
For more information, see About Amazon S3.
Listing of Preferred Dimensions
Provide the exact dimensions you request to be used in your various reports. Also specify
how that data will be accessed (for example, match tables, lookup files, API, and so forth).
If providing metadata files, provide the mappings of metadata fields to dimensions. Contact
your Partner Solutions manager if you require custom dimensions.
If providing API information, provide exact references to the following:
Reference
Recommendation
296
Description
• Service names
• Object names
• Field names
• Endpoints
• Method names
• Authentication methodology
• Throttling/rate limiting, if necessary
• Mapping of file fields to endpoints
Reporting Requirement
List your exact reporting requirements and necessary dimensions for each report.
For more information, see:
• DFP Premium
• DFP
• DFA
• MediaMath
• 24/7 Open AdStream
• FreeWheel
Preferred Ad Server
The most popular ad servers that we currently use include DFP version 2 (Google
DoubleClick for Publishers), DFA (Google DoubleClick for Advertisers), MM
(MediaMath), FreeWheel, and OAS (Open Ad Server).
Using one of these ad servers greatly reduces initial set-up time. Contact your Partner
Solutions manger for other configurations.
Data/File Formatting
Recommendation
File Name
Date/Time Stamps
Time Zone
File Content
Description
Include your Audience Management client ID (the DPID) in the file name.
Add a timestamp to the file name. We recommend that you use UNIX UTC seconds by
default.
Audience Management uses UTC. We recommend that you send data in UTC.
Ensure that your file content conforms to the following specifications:
• Separate impression, click, and conversion data into individual files.
• Remove metadata (non-ID data) from the logs. Store that information in separate lookup
tables. See Improve Log File Processing Times with Lookup Tables.
• Fix the schema to ensure that each record contains the same number of delimited
columns, even when blank or null values are returned.
Reference
297
Recommendation
Description
• No special characters in fields (newline, etc.).
• No delimiter characters in the fields.
File Size
Keep files small. It's easier to import several small files in parallel than it is to process one
big file. As a general rule, more files and smaller files are better than one or two really
large files. As best practice, we recommend a 100 MB maximum uncompressed file size.
The uncompressed file should not be larger than 5 GB.
Send Compressed Files
Use AAM UUID
Send compressed files with Amazon S3. We recommend using gzip.
Use the 38-digit AAM UUID as the join ID.
Send Incremental Data
Send incremental data only, ideally one set of files per hour.
Audience Management will only begin processing one day's data when the first hour of
the next day's data has been delivered.
Audience Management cannot begin populating files for a new day until the previous
day's files have been processed.
Field Delimiter
Specify the field delimiter that you will be using in your files. Binary delimiters are
preferred.
Commonly Used Dimensions
Dimension
Description
Example
Advertiser
Name of advertiser.
AMERICAN PRODUCTS
Ad
A placeholder for multiple creatives of a
particular size.
Fitness
Campaign
A set of related ads that are served during Teen Party Season 3 Premiere
a specified flight.
Order
23919_NEWS 889 (DELORIAN MOTORS LTD) PREROLL
- JUL 22-DEC 29 2013
Lineitem
1580745-1_Today's Parent - ROS - DISPLAY - BB + LB
Site
A property where a given ad ran.
Comedy Mobile (comedy.mb)
Strategy
Wrestling_Weekly_Tomorrow_7.25
Creative
The image file or assets that are displayed Bio.Broadcast(Homepage)-160x600
to the user.
Keyval
Placement
video_id=294869
Creative size and delivery scope.
Core_Travel_HotelChecker_ROS__728x90
Reference
298
DFP Premium
Information that you need to provide to Adobe when using DoubleClick for Publishers Premium and Audience Management.
This topic contains the following information:
• Log File Access Information
• Default Dimensions
• UserID Values
Log File Access Information
Provide Adobe with the following information:
• Your Google Storage access key
• Your Google Storage secret key
• The Google Storage bucket name, for example gdfp-xxxx
• The field delimiter used for the Google Storage log files
• The version of the desired DFP API that you want to use
• Your DFP API username and password
• Your DFP API network code
Default Dimensions
The dimensions that Adobe uses are defined by DFP. For more information, see the Google DoubleClick Developers site.
Dimension
DFP Service
DFP Object
DFP Field Name
Ad
InventoryService
AdUnit
name
Advertiser
CompanyService
Company
name
Creative
CreativeService
Creative
name
size
Order
OrderService
Order
name
po_number
Lineitem
LineitemService
Lineitem
name
If you want to use different dimensions, please provide us with the appropriate DFP service, object, and field name information
for each dimension.
UserID Values
Specify whether you will be using the Audience Management UserID or your own UserID. If you are using your own UserID,
please provide Adobe with the following information:
• Sample UserID values
• Field containing the UserID
• Delimiters used in that field
• The key used as the identifier for the UserID value
Reference
299
DFP
Information that you need to provide to Adobe when using DoubleClick for Publishers and Audience Management.
Note: We strongly recommend that you useDFP Premium rather than DFP, described below.
This topic contains the following information:
• Log File Access Information
• Default Dimensions
• UserID Values
Log File Access Information
Provide Adobe with the following information:
• The hostname of the FTP server
• Your FTP username and password
• The name of the FTP server directory that contains the dimension file
• The delimiters used in the log files
Default Dimensions
• Ad
• Advertiser
• Creative
• Zone
• Site
• Order
• Keyvalue
If you want to use different dimensions, provide us with the log files containing the appropriate dimension IDs and dimension
names.
UserID Values
Specify whether you will be using the Audience Management UserID or your own UserID. If you are using your own UserID,
please provide Adobe with the following information:
• Sample UserID values
• Field containing the UserID
• Delimiters used in that field
• The key used as the identifier for the UserID value
DFA
Information that you need to provide to Adobe when using DoubleClick for Advertisers and Audience Management.
This section contains the following information:
• Log File Access Information
• Default Dimensions
Reference
300
Log File Access Information
Provide Adobe with the following information:
• The version of the desired DFA API that you want to use
• Your DFA API username and password
• The desired protocol that you want to use to access the DFA API: HTTP or HTTPS.
Default Dimensions
The dimensions that Adobe uses are defined by DFA. For more information, see the DoubleClick For Advertisers Developer site.
Dimension
DFA Service
DFA Object
DFA Field Name
Advertiser
advertiser
Advertiser
name
Creative
creative
CreativeBase
name
Creative Size
size
Size
sizeId
Campaign
campaign
Campaign
name
Placement
placement
Placement
name
Strategy
strategy
PlacementStrategy
name
Site
site
Site
name
If you want to use different dimensions, please provide us with the appropriate DFA service, object, and field name information
for each dimension.
MediaMath
Information that you need to provide to Adobe when using MediaMath and Audience Management.
This topic contains the following information:
• Log File Access Information
• Default Dimensions
• UserID Values
Log File Access Information
MediaMath will contact Adobe for the appropriate access to the appropriate Amazon S3 bucket.
Default Dimensions
• Advertiser
• Campaign
• Strategy
If you want to use different dimensions, provide us with the log files containing the appropriate dimension IDs and dimension
names.
UserID Values
Specify whether you will be using the Audience Management UserID or your own UserID. If you are using your own UserID,
please provide Adobe with the following information:
Reference
301
• Sample UserID values
• Field containing the UserID
• Delimiters used in that field
• The key used as the identifier for the UserID value
24/7 Open AdStream
Information that you need to provide to Adobe when using 24/7 Open AdSteam and Audience Management.
This topic contains the following information:
• Log File Access Information
• Default Dimensions
• UserID Values
• Event Type Definitions
Log File Access Information
Provide Adobe with the following information:
• The hostname of the FTP server
• Your FTP username and password
• The filenames of the different logs files you will be sending to Adobe
• The delimiters used in the log files
Default Dimensions
• Advertiser
• Campaign
• Creative
If you want to use different dimensions, provide us with the log files containing the appropriate dimension IDs and dimension
names.
UserID Values
Specify whether you will be using the Audience Management UserID or your own UserID. If you are using your own UserID,
please provide Adobe with the following information:
• Sample UserID values
• Field containing the UserID
• Delimiters used in that field
• The key used as the identifier for the UserID value
Event Type Definitions
24/7 Open AdStream log files use the following event types:
Event Type
Description
0 (zero, not capital O)
Impression (no flag)
c
Indicates caller was a click-through
n
Indicates a new user that is neither a robot nor a click-through
Reference
302
Event Type
Description
p
Page view. It is shown for MJX tags regardless of the number of positions, even one. It is shown in
the first request, and in rapid sequence for coordinated requests.
r
Indicates caller is a robot
When combining these flags, the following rules apply:
• "c" is always alone unless preceded by "r"
• "p" is always preceded by one of the following:
•r
•n
• 0 (zero)
Please provide Adobe the correct combinations of event types to impressions, clicks, and so forth.
FreeWheel
Information that you need to provide to Adobe when using FreeWheel and Audience Management.
This topic contains the following information:
• Log File Access Information
• Default Dimensions
• UserID Values
Log File Access Information
Provide Adobe with the following information:
• The hostname of the FTP server
• Your FTP username and password
• The delimiters used in the log files
Default Dimensions
• Advertiser
• Ad
• Campaign
• Creative
• Order
• PO Number
• Site
If you want to use different dimensions, provide us with the log files containing the appropriate dimension IDs and dimension
names.
UserID Values
Specify whether you will be using the Audience Management UserID or your own UserID. If you are using your own UserID,
please provide Adobe with the following information:
• Sample UserID values
• Field containing the UserID
Reference
303
• Delimiters used in that field
• The key used as the identifier for the UserID value
Pre-Submission Data Integration Checklist
Information that you should gather before requesting report setup from your Audience Management Account Manager.
As best practice, you should print and complete this checklist to help ensure that your setup is completed as quickly and efficiently
as possible.
Pre-Submission Data Integration Checklist
Integration Type: Specify your desired integration type:
DoubleClick for Publishers Premium (DFP Premium)
DoubleClick for Publishers (DFP)
DoubleClick for Advertisers (DFA)
MediaMath (MM)
24/7 Open Adstream
FreeWheel
Data Source Name and ID: Specify your data source name and ID:
File Delivery Mechanism: Specify your desired file delivery mechanism:
Amazon S3 (preferred)
SFTP
Google Storage
Pixeling Creative
Metadata Delivery Mechanism: Specify your desired metadata delivery mechanism for dimensions:
Flat file
Delivery mechanism:
API
API endpoint:
API method (SOAP or REST):
API access credentials:
Throttling limit (max requests per second/minute):
API documentation:
Dimensions and Mappings: Specify the necessary dimensions and the corresponding input data field mappings:
Advertiser:
Ad:
Campaign:
Order:
Lineitem:
Reference
304
Pre-Submission Data Integration Checklist
Site:
Strategy:
Creative
Keyval:
Placement:
For more information, see Commonly Used Dimensions.
Metrics: Specify the necessary metrics:
Ad Server/Demand-Side-Platform
Impressions
Clicks
Conversions
Email Service Providers (ESP)
Sends
Opens
Clicks
Conversions
UserID Type: Specify the UserID type:
Audience Management UserID:
Data provider UserID:
UserID Syntax and Containing Name Field: Specify your UserID syntax and containing field name:
Syntax and name:
For example, u=24757051475150277921078323837696047435
Time Zone: Specify your desired time zone (UTC preferred):
Time Zone:
Reporting and File Transfer Time-Frame Guidelines
Information describing the time frames when Audience Management receives information to populate reports and when
Audience Management processes inbound and outbound Server-to-Server (S2S) file transfers.
Note: The time frames and schedules outlined in this section are general guidelines only. These time frames and schedules
are not Service-Level Agreements (SLAs) or firm commitments. Adobe reserves the right to change the time frames and
schedules at any time without notice.
Reference
305
Reporting Numbers
The following information explains the time frames used to populate events in various reports:
• Real-time Numbers: Real-time numbers today are for hours 00:00-23:59:59 UTC yesterday.
• Total Segment Population: Total Segment Population today is for roughly the hours of 17:50:00 of the day before yesterday
to 17:49:59 UTC yesterday.
• General Reports: The data in the General Reports (that feeds the real-time and total segment numbers in the user interface)
is dependent on multiple jobs finishing and how much data there is for that particular day. The general reporting numbers
should be updated by 15:00 UTC each day. Adobe will attempt to pro-actively notify customers about late reporting only if
reporting numbers are not in by 17:00 UTC.
As a result of these time frames, data coming into the Audience Management system should be available in reports the next day,
under normal operating conditions. For more information about the available reports in Audience Management, see Reports.
Inbound and Outbound File Transfers
The following information explains the schedules when Audience Management processes inbound and outbound Server-to-Server
(S2S) file transfers:
• Inbound File Ingestion (offline data): Two daily jobs kick off at 03:00 UTC and 15:00 UTC.
• OutBound File Export: Two daily jobs kick off at 06:00 UTC and 18:00 UTC. These jobs start the pre-jobs for these files, so
the actual files might be exported a little later, depending on the file job.
As a result of these schedules and the cut-off times, you might see discrepancies with new segments between real-time and total
segment numbers.
About Amazon S3
Information about Amazon Simple Storage Service (Amazon S3).
As best practice, we recommend using Amazon S3 as a method for getting files from and delivering files to partners. Amazon
S3 provides a simple web services interface that can be used to store and retrieve any amount of data, at any time, from anywhere
on the web.
The benefits of using Amazon S3 include:
• Scalability: Amazon S3 provides almost limitless scalability.
• Reliability and Availability: Amazon S3 provides high durability (99.999999999%) and high availability (99.99%).
• Speed: Amazon S3 allows fast data transfers.
• Ease of Use: Amazon S3 is very easy to use and to implement. Your implementation can be up and running in about an hour.
• Multi-Part Uploads: Large files can be uploaded quickly and efficiently as multi-part file uploads.
• Security: Amazon S3 provides strong security.
• All directories are accessible only to the appropriate customer or client.
• HTTPS protocol support for uploads and downloads. You should always use HTTPS when transferring files in Audience
Management.
• Debug and Backup Support: Amazon S3 allows Audience Management to retain exact copies of files to make debugging or
re-transfers easier.
For more information about Amazon S3, see the following resources:
Amazon Simple Storage Service (Amazon S3) on the Amazon Web Services website.
Get Started with Amazon Simple Storage Service on the AWS Documentation website.
Firefox Organizer for Amazon S3 and Amazon CloudFront (S3Fox) on the Amazon Web Services website.
Reference
306
s3cmd: Command Line S3 Client on the S3 Tools website.
Use Cases for Advertisers and Publishers
Common advertiser and publisher use cases.
Advertiser Use Cases
A look at some common advertiser needs met by Adobe Audience Management.
Create a Unified View of all Your Users
Goal
Benefit
Example
• Create a single audience repository to
unify customers or prospect data across
display impressions, on-site acquisition
data, site behavior, email initiatives, and
promotions.
A unified customer data repository helps
improve audience discovery, business
planning, and provides in-depth
understanding of audience segments.
For quarterly display media planning,
highlight unique audience behaviors
across prospect profiles and shift budget
to a specific segment or inventory source.
• Understand user attributes to help
improve media buying efforts.
Create High Value Segments and Improve Reach with Look-alike Modeling
The Models documentation contains details about the Audience Management algorithmic modeling process.
Goal
Benefit
Example
• Leverage site behavior, offline data,
third-party data, campaign metrics to
create valuable audience profiles.
• Identify new audiences with behaviors • Identify customers who make expensive
and profiles that mirror the original
purchases.
audience.
• Run an Audience Management
• Model those segments against other data • Search against your own data and other look-alike model to identify the most
sources to increase reach.
third-party data that you have access to. influential audience members in that
This helps you find and identify the
segment.
most influential data points for
• Target those segments to improve
high-value audience profiles.
current display advertising or through
on-site personalization via Test&Target.
• Include the new data in future display
campaigns through Test&Target.
Retarget First-Party Data Through a Demand-side Platform (DSP)
Goal
Benefit
Example
Retarget visitors on advertiser or partner • Align analytics data points with display • Create a "Vacations - Searchers No
sites through a DSP to increase ad
advertising.
Conversion" segment.
targeting effectiveness.
• Reduction in wasted impressions (don't • Add a rule to exclude recent converters.
show impressions to current customers).
Reference
Goal
307
Benefit
Example
• Retarget through a DSP with a special
offer and subsequent on-site
personalization.
• Continue to show required content
through Test&Target.
Use Partner Data to Create Special Offers for Current Customers
Goal
Benefit
Example
• Offer customers special rates based on • Improve offer management and
• Import partner data segments, combine
segment data from business partners.
conversion rates by taking advantage of them with your own, and offer relevant
data from strategic partners.
experiences with Test&Target.
• For in-segment customers, reinforce
this special offer through email
marketing.
• Break down organization and data silos • Increase the scale of email marketing
with systems designed to manage and
initiatives or DSP campaign alignment.
optimize cross-channel marketing
initiatives.
Use CRM Data to Create Special Offers for Current Customers
Goal
Benefit
Example
Integrate your separate data sets in
Audience Management to help manage
customer offers based on seasonal or
other purchasing behavior.
• Leverage Audience Manager's
integration capabilities to support the
use of offline data.
• In Audience Management, create a
segment for Fall vacation travelers.
• In Test&Target, create a campaign to
• Increase conversion rates and loyalty by offer airline points for seasonal
offering customers relevant creative
purchases.
experiences.
• Use Analytics to track customer activity
through the conversion funnel. If a
customer does not convert, retarget with
email marketing.
Run Email Marketing with On-Site Behavioral and Current Customer Data
Goal
Benefit
Example
Use Analytics search behavior to target
email marketing messages.
• Align analytics data with marketing
initiatives.
• Create a "Purchase Intenders - No
Conversion" segment.
• Combine Analytics data with customer • Target that segment with related emails.
data.
• Continue to offer content on-site
• Improve collaborative offer
through Test&Target.
management.
Tailor the Visitor's Purchase Path with Current Customer and Third-party Data
Reference
308
Goal
Benefit
Example
Take advantage of existing and
third-party visitor data to optimize and
personalize a customer's digital
experience.
Personalized customer experience helps • In Audience Management, ingest
increase conversion rates. Presenting the third-party segment data targeted to
small business owners.
right products, offers, and creative
experiences can drive purchase activity • In Test&Target, create an on-site
and improve customer engagement or
campaign that offers small business
loyalty.
owners targeted messages and offers.
• Track performance with Audience
Management reports.
Improve First-party Data Monetization
Goal
Benefit
Example
Create and manage a single first-party
data taxonomy for distribution across
monetization platforms.
• Single point of management for
first-party data.
• Work with first-party data in Analytics
to create a travel enthusiasts segment.
• Align Analytics data with audience
segments.
• Target and monetize that segment
off-site through demand and sell-side
platforms and trading desks.
Publisher Use Cases
A look at some common publisher needs met by Adobe Audience Management.
Unify View of User and Highlight Audience Insight
Goal
Benefit
Create a single audience repository that • Discover audiences, run smarter ad or
provides you with an overview of all your sales campaigns, and manage customer
users and data points. This includes
insight.
information like site behavior (potentially
• Aggregate related customer insights
from Analytics), display impressions,
across all your channels.
offline registration databases, CRM
databases, video consumption, email
initiatives and promotions.
Example
Empower your Ad Sales Research team
to monetize publisher audience profiles,
highlight "Do it yourself" enthusiasts as
relevant for a forthcoming Home Depot
campaign.
Create Advertising Audience Segments With First-Party Analytics Data
Goal
Benefit
Extract maximum value from first-party Enhance revenue by monetizing
data to create actionable audience
audiences instead of content.
segments, package them, and sell these
segments to advertisers looking for
specific audiences.
Example
• Aggregate a first-party segment of "Tech
Geeks" across a network of properties.
• Include technical email newsletter
registrants.
Reference
Goal
309
Benefit
Example
• Monetize "Tech Geeks" as a premium
product on the digital rate card for
relevant advertisers.
Improve Personalized Site Content Delivery
Goal
Benefit
Example
Present specific content to the user to
help:
• Analytics provides first-party data about
Audience Management's real-time
audience interest in travel content.
analysis helps improve audience
• Increase segment size, page views, and recognition, which enhances the on-site Create a segment called "Travel
impressions.
Enthusiasts" based on this information.
experience by delivering relevant,
personalized
content.
• Create a more relevant experience for
• Integrate Audience Management with
that site visitor.
a system like Adobe CQ to manage
This gives you the opportunity to add
content personalization campaigns.
content personalization as a line item to
•
Target the travel segment to an airline,
your premium audience products.
hotel, or hospitality advertiser to help
improve ad revenue generated by your
inventory.
Improve Off-site Reach Extension
This use case works with first-party, Analytics data sent to a demand-side platform (DSP).
Goal
Benefit
Example
Extend audience-targeted buys to off-site Align analytics data points with on-site • Create an "Income Tax Researchers"
inventory sources through a DSP.
and off-site display advertising and
segment.
monetize audience inventory in 'sold-out'
• Align on-side ad campaign sold to
situations.
Turbo Tax with an off-site reach
extension campaign through a DSP like
Adobe AdLens.
Create High Value Segments and Improve Reach with Look-alike Modeling
The Models documentation contains details about Audience Management's algorithmic modeling process.
Goal
• Leverage site behavior, offline data,
third-party data, campaign metrics to
create valuable audience profiles.
Benefit
Example
• Identify new audiences with behaviors • Identify "Xbox gamers" in your
and profiles that mirror the original
customer database.
audience.
• Run a look-alike model to find and
• Model those segments against other data • Search against your own data and other identify the most influential users in that
sources to increase reach.
third-party data that you have access to. segment.
This helps you find and identify the
Reference
Goal
310
Benefit
most influential data points for
high-value audience profiles.
Example
• Target those segments to optimize
on-site display advertising with
Test&Target.
Reach an Advertiser's Requested Demographics with First and Third-Party Data
Goal
Benefit
Example
• Combine first and third-party data to
create more relevant, actionable
audience segments.
• Improved monetization for digital ads. • Answer demo-targeted RFPs with
ready-made, third-party audience
• Identify the most valuable first-party
data and improve that information with segments aligned with your first-party
data.
• Package and sell enhanced segments to complimentary third-party data.
advertisers looking for specific
• Provide recommendations to the
demographics like age, gender, income,
advertiser based on the historical
etc.
segment performance.
• Create the right kinds segments for ad
sales for any campaign strategy.
Advertiser and Publisher Use Cases
A PDF of common advertiser and publisher use cases.
Download the use case white paper.
Profile Merge
Audience Management uses Profile Merge to combine profiles from authenticated accounts and anonymous devices into a
single profile to deepen segmentation and targeting.
Advertising and content customization has traditionally been focused on browsers, devices, and cookies. In the past, Audience
Management's data-model centered on the concept of the device: all user data that Audience Management stored was tied to
this device profile. As people increasingly use multiple devices (work computer, home computer, smart phone, tablet, and so
forth), a device-centric way of storing data is no longer sufficient.
The central idea behind Profile Merge is that we distinguish between authenticated (known) and anonymous (device) profiles
and provide the ability to merge those data sets as needed. We will continue to tie any anonymous activity to the device used,
which will typically be a browser or mobile device. However, activity while the user is authenticated will be attributed to their
authenticated account, including CRM on-boarded data. When our data collection servers (DCS) see a given user who is
authenticated, we will retrieve both their authenticated data tied to the known-user profile, as well as anonymous data tied to
the browser/device, and combine these data sets into a single “merged” profile, which will be used to evaluate segment rules.
Because Audience Management can tie data directly to the authenticated account when one is present, we can also onboard
customers' CRM data without having to wait for an ID-sync or declared ID event to happen. After an ID sync occurs, the data
will be pushed to the edge region where that known user has last been seen.
The following sections contain more information:
Reference
311
Profile Merge Terminology
Terms used in Audience Management Profile Merge.
Term
Definition
Device
A browser or a mobile application that provides its own ID. Think of a device as not necessarily
a physical entity, but rather anything that has a unique tag, stored in either a cookie or some
other form of persistent storage in the case of mobile applications. For example, three different
browsers installed on the same computer are treated as three separate devices.
Authenticated ID
An ID that the customer provides to us that uniquely identifies the currently authenticated or
known user. It is important to note that this ID cannot contain personally identifiable information
(PII) or be linkable back to PII. If you have a username or email address, which might constitute
PII, it should never be passed into Audience Management directly for privacy and legal reasons.
It is the customer’s responsibility to encrypt the ID by using a one-way, non-reversible hash
function (such as SHA-2) prior to passing it into Audience Management.
Data Source
Different sources of data for the same customer. A customer might have one data source as a
container for its offline CRM data, another data source provisioned for its online data, and a
separate data source provisioned for data from a partner, which is being leveraged in the customer’s
account. Data sources can be used to contain both visitor profile data (traits and segments) as
well as customer IDs, such as device IDs from a first-party cookie or authenticated IDs that are
tied to known-user accounts.
Cross-Device Data Source
A data source used as a container for IDs, which is tied to a customer’s authenticated account
namespace, and not to a device-level ID. For example, a customer’s CRM database should be
labeled as a Cross-Device Data Source.
Profile Merge Architecture
Illustration showing a detailed view of the Audience Management Profile Merge architecture.
Reference
312
There’s two conceptual tables to store the behavioral data. The “Known User” table stores the authenticated data. The “Device”
table stores the anonymous data. Offline data first gets inserted into AAM Backend. The data gets replicated between AAM
Backend and the Edge databases in each geographical region.
Profile Merge Customer Enablement
Steps to enable Profile Merge
To enable Profile Merge functionality, label the data source that contains your declared known-profile IDs as “Cross Device.”
Note: Profile Merge works best for authenticated IDs that span multiple devices. You must have administrator privileges
in your UI Portal account to perform the following steps.
1. Navigate to Data Sources, and select the data source you want to mark as “Cross Device.”
Reference
313
2. From the ID Type drop-down list, select Cross Device.
From this point forward, any offline data received from this data source will be inserted into the “known user” table, and will
be tied directly to the Authenticated ID from which it was received.
An important question that arises is what happens to the existing data that Audience Management has already collected. The
answer is that this data is still stored as before. The enablement of “Cross Device” on a given data source only affects the way
that traits are stored going forward, it does not delete or move any of the traits previously collected and stored on the device
level.
If you want to start from a clean slate, you can elect to send an overwrite file into Audience Management. When the overwrite
file is processed, Audience Management removes all the traits previously received for a given data source and replace them with
those received. See Inbound Data File Name: Syntax and Parameters for more information about sending an overwrite file.
Profile Merge Implications and Limitations
Implications and limitations of Profile Merge.
Implications
Implication
PII IDs
Recency and Frequency
Algo Modeling
Reporting
Details
Ensure that you do one-way hashing of any PII IDs before sending them to Audience Management.
Recency and frequency functionality doesn’t change with this release. If a user realized a given
trait 5 times while signed in, and 5 times anonymously, we will add up both counts to 10. If the
segment rule is to realize that trait 10 times or more, the visitor will qualify for the segment.
Nothing with respect to Algo Modeling changes with this release. Algo traits will continue working
on the device level, as they did before.
Nothing changes with respect to reporting in this release. We are currently not adding additional
reports driven off the new “crm” table. We may look at adding it in a future phase.
Supported Destinations
Supported destinations include URL, cookie, and HTTP real-time sever-to-server.
Current Limitations
Profile Merge does not currently support cross device functionality in outbound batch server-to-server destinations, which send
data to either FTP or Amazon S3. This means that cross device will not work when we push data to DSPs that accept data only
via FTP or S3.
Reference
314
Declared IDs
How declared IDs work, set up procedures, code examples, and variables.
Declared ID Targeting
Exchange and synchronize user IDs with Audience Management from devices or browsers that do not use or accept persistent
storage mechanisms, such as third-party cookies.
This section contains the following information:
• Purpose of Declared ID Targeting
• Getting Started
• Do Not Target (Opt-out) Calls
• Declared ID Opt-Out Examples
Purpose of Declared ID Targeting
Some browsers, and most mobile devices, do not accept third-party cookies. This makes it difficult to retain information about
site visitors or assign persistent IDs. To resolve this issue, Audience Management uses DIL to let you pass in declared IDs on
an event call. A declared ID sends your own customer ID, user IDs, or even Audience Management IDs in a URL to our Data
Collection Servers (DCS). Your unique IDs get matched to a corresponding Audience Management ID and returned in a cookie
in your own domain. As a result, declared ID targeting lets Audience Management identify and work with IDs from devices or
applications that do not accept third-party cookies.
The following table describes the ID targeting/matching process:
Process
Event Call
Description
During an event call, DIL code on the page sends your unique visitor and client ID to the DCS.
The DIL variables dpid and dpuuid hold your client and visitor ID, respectively.
These variables are part of dpids, an object in the DIL create method and a function in other
DIL methods that return an API object of the current DIL instance (e.g., various instance-level
methods).
Note: You're responsible for developing the code that passes these IDs to DIL.
Match ID
Audience Management attempts to match the client and visitor ID with a corresponding ID in
our system. If a matching ID does not exist, Audience Management creates a new ID and
associates it with the client and visitor ID.
Note: The most recent mapping is used if your ID maps to more than one Audience
Management ID.
Return ID
Audience Management writes its synchronized ID to a first-party cookie (or other addressable
storage space) in the client domain or application.
Reference
Process
Subsequent Event Calls
315
Description
Additional event calls read the Audience Management ID from the client's domain and send
that to Audience Management.
Getting Started
Send declared IDs to the DCS through the DIL code module on your page (the preferred method). If you use the preferred
method, make sure your page code has the latest version of visitor.js code and that it loads before DIL. visitor.js is a
Marketing Cloud code module that you can to obtain from your account representative. In this case, the d_mid query string
parameter, which represents the Marketing Cloud ID, is sent on every event call to Audience Management.
Also, you can send IDs directly by adding the required variables to an event call (not recommended). Review the URL Variables
and Syntax for Declared IDs section if you want to send in declared IDs through your own processes.
Do Not Target (Opt-out) Calls
The declared ID process honors site visitor preferences to opt-out of Audience Management targeting by your website. When
Audience Management receives an opt-out request, the DCS returns an empty JSON object instead of the Audience Management
user ID.
Audience Management can pass in a declared ID opt-out alongside an Audience Management UUID in the URL.
The declared ID opt-out is stored in the Profile Cache Server (PCS) on a per-partner basis. There is no platform-level opt-out
using declared IDs. Additionally, Audience Management opts the user out from that particular region on the edge (the opt-out
does not cross DCS regions).
Declared ID Opt-Out Examples
You can make a declared ID opt-out request with the following combinations:
• d_uuid only:
http://<domain>/demoptout.jpg?d_uuid=<AAM ID>
A partner level opt-out gets stored for this AAM ID.
• d_dpuuid and d_dpid only:
http://<domain>/demoptout.jpg?d_dpuuid=<Data provider user ID>&d_dpid=<Data provider's AAM
ID>
A partner level opt-out gets stored for the latest mapping of this dpid + dpuuid pair to an AAM UUID. If there is no previously
existing mapping, Audience Management checks whether the request contains an AAM UUID in the cookie, and if it does,
uses that for storing the opt-out. Otherwise, Audience Management generates a new AAM UUID and stores the opt-out under
it.
• d_dpuuid + d_dpid and explicit d_uuid:
http://<domain>/demoptout.jpg?d_uuid=<AAM UUID>&d_dpuuid=<Data provider's visitor
ID>&d_dpid=<Data provider's AudienceManager ID>
d_uuid always takes precedence. If the dpid + dpuuid combination maps to another AAM UUID, the opt-out is stored under
the AAM UUID passed in the request (d_uuid).
Reference
316
URL Variables and Syntax for Declared IDs
Describes the variables and event call URLs that send IDs directly to Audience Management. You can use this information to
pass in data via your own processes, but we recommend you use the DIL code module to send declared IDs to Audience
Management instead.
Variables
The following table lists the declared ID variables you can pass in on an event call. The d_ prefix indicates that these are
platform-level variables available across your account.
Variable
Description
d_uuid
Unique User ID, an ID assigned by Audience Management to identify site visitors.
d_dpuuid
The data provider's unique ID for the user.
Audience Management uses the combined dpid and dpuuid to look up a corresponding
unique user ID in our system. If an ID does not exist, Audience Management creates and
synchronizes a new user ID to the dpid/dpuuid combination.
d_dpid
Data partner ID assigned by Audience Management.
Audience Management uses the combined dpid and dpuuid to look up a corresponding
unique user ID in our system. If an ID does not exist, Audience Management creates and
synchronizes a new user ID to the dpid/dpuuid combination.
Event Call URLs
You can pass in declared IDs with the following combinations:
• d_uuid only:
http://<domain>/event?key=val&d_uuid=<AudienceManager user ID>
• d_dpuuid and d_dpid only:
http://<domain>/event?key=val&d_dpuuid=<Data provider user ID>&
d_dpid=<Data provider's AudienceManager ID>
• All 3 variables:
Note: d_uuid takes precedence if the dpid/dpuuid combination maps to another uuid.
http://<domain>/event?key=val&d_uuid=<AudienceManager user ID>&
d_dpuuid=<Data provider's visitor ID>&d_dpid=<Data provider's AudienceManager ID>
Request Example
This sample JSON request passes in a dpuuid and dpid.
http://my_domain.net/event?d_rtbd=json&d_cb=myCallback&key=val&d_dpuuid=1234&d_dpid=5678
Response Example
Your sample response could look similar to this. Note, the keys u and uuid both return the visitor's Audience Management ID.
See URL Format for Passing in Data to the DCS for details about the key-values contained in the request and response.
myCallback({
"dests":[
Reference
317
{
"id":"123-1354180261",
"y":"img",
"c":"http://<some destination URL>"
},
{
"id":"1934-1234567899",
"y":"img",
"c":"http://<another destionation URL>"
}
],
"stuff":[
{
"cn":"cookie-name1",
"cv":"some_value-some_key",
"ttl":0,
"dmn":"www.my_domain.com",
"u":"abc123"
}
],
"uuid":"abc123"
})
Declared ID Variables
Configuration variables contained in the declaredId object. Used by DIL.create (and other API methods) to synchronize
your user and customer IDs with related Audience Management IDs.
The following table describes the variables used by the declaredId object:
Name
Type
dpid
String
dpuuid
String
Description
Data partner ID assigned by Audience Management.
The data provider's unique ID for the user.
dpid and dpuuid
Audience Management compares and matches the combined dpid and dpuuid to a corresponding user ID in our system. If
an ID does not exist, Audience Management creates a new user ID and synchronizes it to the dpid/dpuuid combination. Once
Audience Management matches or creates a user ID (the uuid) it returns that ID in the JSON response to the cookie in the
client's domain (first-party cookie) or other local storage.
Do Not Target (Opt-out) Calls
The declared ID process honors site visitor preferences to opt-out of Audience Management targeting by your website. When
Audience Management receives an opt-out request, the DCS returns an empty JSON object instead of the Audience Management
user ID.
Code Samples
Note: Note, you need to programmatically develop the code that supplies the ID values for the d_dpuuid and d_dpid keys.
Basic Requests
DIL.create({
partner : "test name",
declaredId : {
dpuuid : <dpuuid>,
dpid : <dpid>
Reference
318
}
});
Pass In IDs After DIL Instantiates
Note: If you make an API call with a different declaredID combination, the new combination will be used for that call
only. Further regular event calls will use the original DIL.createdeclaredID combination.
DIL.getDil('partner name').api.signals({...}).declaredId({
dpuuid : <dpuuid>
dpid : <dpid>
}).submit();
Request/Response Examples
The request sends a data provider and user ID to Audience Management:
http://my_domain.net/event?d_rtbd=json&d_cb=myCallback&key=val&d_dpuuid=1234&d_dpid=5678
The response returns the Audience Management ID (e.g., uuid) which is written to a first-party cookie in the page domain.
myCallback({
...
"uuid":"abc123"
})
Signals, Traits, and Segments
Describes the components of an Audience Management segment, the expressions used to set audience qualification criteria,
and how data is transmitted in an event call.
Composition and Purpose
Audience Management data consists of signals, traits, segments, and related qualification rules. The data elements and rules
combine to create segments. Segments organize site visitors into related groups. The following table defines the three principal
components in an Audience Management segment.
Element
Consists of
Example
Signal
Signals are the smallest data units in Audience Management • product=camera
and are expressed as key-value pairs.
• price>1000
• The key is a constant that defines a data set (e.g., gender, • type=digital SLR
color, price).
• The value is a variable related to the constant (e.g.,
male/female, green, 100).
Comparison operators join the key-value pair and set the
relationship between them.
Trait
Combinations of one or more signals.
Boolean expressions and comparison operators let you
create trait qualification rules.
Create precise qualification requirements with
combinations of traits and trait groups.
From the available signals, you could
create a "High End Camera Browser" rule
expressed as:
product=camera AND price>1000
Reference
Element
Segment
319
Consists of
Example
Users who share a set of common attributes and qualify for From the available traits and signals, you
related traits.
could create a segment rule expressed as:
Boolean expressions, along with recency/frequency
requirements, let you create segment qualification rules.
(product=camera AND
Create precise qualification requirements with
combinations of trait and segment rules.
(price>1000)
type=digital SLR) OR
Build Traits and Segment Rules With Visual Tools and Code Editors
Clients manage traits and segments with visual tools and code editors in the Audience Management user interface. The visual
tools let you create rules using search features, pop-up options, dropdown menus, and drag and drop functionality. The code
editors provide advanced users with a way to programmatically develop audience segmentation criteria.
Event Calls Send Data to Audience Management
An event call sends data from your website to Audience Management. The call contains signal, trait, and segment data in an
HTTP request. The event itself is everything after the /event part of a URL string. As shown in the example below, this process
requires only a single event call to pass in multiple variables to Audience Management.
http://<domain>/event?product=camera&price>100
Boolean Expressions in Trait and Segment Builder
This article explains how the Audience Management trait and segment tools use the Boolean expressions AND, OR, and NOT.
Boolean Expressions
Boolean logic is a branch of algebra that uses a few basic expressions (or operators) to determine if a statement is true or false.
The most common operators are AND, OR, and NOT. Combinations of these expressions help you make focused trait or
segment qualification rules uniquely suited to your data requirements. The following illustration shows how basic Boolean
expressions work.
Note: The NOT operator uses an implied "and" condition and is sometimes written as AND NOT.
How to Use Boolean Expressions in Trait and Segment Builder
You build trait and segment qualification rules with Boolean expressions. The table below describes general best practices for
creating qualification criteria with AND, OR, and NOT.
Reference
320
Expression
Use it to create
To qualify
AND
Narrow, focused audience qualification requirements.
Users must belong to all specified traits
or segments.
OR
Broad, less focused audience qualification requirements. Users can belong to any specified traits or
segments.
NOT
Narrow, focused audience qualification requirements.
Useful when there are multiple conditions that make
defining audience qualification requirements difficult or
inefficient. Occasionally, it’s easier to validate against
requirements that exclude rather than include.
Users must not belong to an excluded trait
or segment.
AND Use Case Example
The AND operator is useful when you have easily enumerated trait membership requirements. For example, say you need to
create an audience of “expensive camera shoppers.” With a pixel model, you would have to create and place pixels for cameras
and a numeric price value on your page. By contrast, with traits you can apply Boolean operators to handle both conditions
(cameras AND price). The result is efficient data collection with fewer HTTP calls, which, in turn, helps preserve the user
experience on your site.
OR Use Case Example
The OR operator is useful when you want to create signals with broad audience qualification requirements. If you have several
trait or segment qualification requirements, the OR operator will evaluate to true when your site visitors exhibit any of those
characteristics. OR may be most useful when you want to rapidly create a broad audience of qualified site visitors.
AND NOT Use Case Example
The AND NOT operator is useful when it’s easier to define an audience by exclusion rather than inclusion. For example, say
you're having a sale and want to segment visitors into customers who look at full price items only. Rather than create a list of
signals for all qualifying full or sale-price items, it may be easier qualify visitors if they have not seen a sale price item. This is
administratively efficient because you usually have fewer sale price items compared to those offered at full price. With a Boolean
NOT, visitors must not exhibit the sale signal to qualify for full-price audience membership. By contrast, AND NOT is the
opposite of the AND use case, which showed how audience membership is determined by inclusion (i.e., the visitor qualified
based on 2 explicitly stated signals).
Key-Value Pairs Explained
Defines and describes standard and serialized key-value pairs.
A key-value pair consists of two related data elements: A key, which is a constant that defines the data set (e.g., gender, color,
price), and a value, which is a variable that belongs to the set (e.g., male/female, green, 100). Fully formed, a key-value pair could
look like these:
• gender = male
• color = green
• price > 100
The following sections contain more information:
Reference
321
• Standard and Serialized Key-Value Pairs
• Keys, Delimiters, and Separators
• Standard and Serialized Key-Value Elements
Standard and Serialized Key-Value Pairs
Destinations accept key-value data in standard or serialized format. Standard formatting organizes data into separate key-value
pairs. Each key is stated explicitly, even when used again to define a different value. By contrast, serialized formatting condenses
multiple values into one set defined by a single key. Also, in a serialized pair, a special indicator is used to separate the values
within the key-value set. Finally, standard and serialized key-values can contain single or multiple values. The following table
provides examples of standard and serial key-value formats.
Formatting
Single Key
Key-Value Pairs
Standard
x=1&x=2
x=1&x=2&y=3&y=4
Serialized
x=1;2
x=1;2&y=3;4
Keys, Delimiters, and Separators
When working with serialized data, you must specify the characters that separate values within and between the key-value pairs.
Elements in key-value pairs are defined as follows:
• Key: A unique identifier in the key-value pair.
• Value delimiter: Separates individual key-value pairs.
• Key-value separator: Separates a key from the values within a key-value pair.
• Serial separator: Separates individual values within serialized key-value pairs.
Standard and Serialized Key-Value Elements
Type
Example
Key
Key-Value
Separator
Key-Value
Delimiter
Serial Separator
Single key
x=1&x=2
x
=
&
n/a
;
(standard)
Key-value pairs
x=1&x=2&y=3&y=4 x, y
(standard)
Single key
x=1;2;3
x
n/a
x=1;2&y=3;4
x, y
&
(serial)
Key-value pairs
(serial)
Password Requirements, Locked Accounts, and Forgotten Passwords
This article describes password requirements and how to recover a lost/forgotten password.
Password Requirements
Your Audience Management password must be:
Reference
322
• At least eight characters in length
• Contain at lease one uppercase character
• Contain at least one lowercase character
• Contain at least one number
• Contain at least one special character
• Begin and end with an alpha-numeric character
• Be different from your previous 12 passwords
For information about resetting your password, see Edit Your Account Settings.
Account Lockout
Accounts are locked after 5-failed log in attempts. Contact your company's Audience Management administrator or a Partner
Services representatives to unlock your account.
Lost/Forgotten Password
Click the Forgot password link from the login page to reset your password. You will receive an automated email with a temporary
password that expires in 24 hours. Click the link in the email to access your account and reset your password.
Supported Browsers
Lists the browsers supported by the Audience Management user interface.
Unless indicated otherwise, Audience Management is supported on the latest versions of the following browsers:
• Chrome
• Firefox
• Internet Explorer (version 9 or greater)
• Safari
Other browsers may work, but are not supported by our technical and product teams. If you're having trouble working with
Audience Management, make sure you're using an updated, supported browser.
Sandbox (Beta) Environment
Use the Audience Management sandbox environment for beta testing purposes. The sandbox environment lets you test your
implementation in a beta environment without affecting your production environment.
Note: If you are interested in using the sandbox environment for beta testing, contact your Audience Management Partner
Solutions representative.
Service
URL/Hostname
FTP
sandbox-ftp-in.demdex.com
DCS
https://sandbox.demdex.net/...
UI
https://sandbox.demdex.com
API
https://sandbox-api.demdex.com/...
Reference
323
Note: We refresh the sandbox environment every weekend with the production data set. You should be able to use your
production account credentials to log in based on your account a week prior.
To access the DCS in the sandbox environment:
1. Determine the load balancer's endpoint IP addresses.
For example:
dig sandbox.demdex.net
...
sandbox-dcs-561555539.us-east-1.elb.amazonaws.com. 60 IN A 50.19.209.211
sandbox-dcs-561555539.us-east-1.elb.amazonaws.com. 60 IN A 184.73.217.253
2. Using one of the addresses in the above table, add a static DNS entry in the /etc/hosts file.
On Windows, modify c:\WINDOWS\system32\drivers\etc\hosts.
For example:
50.19.209.211 samplepartner.demdex.net
Note: The addresses change occasionally, so you must keep your /etc/hosts file up to date.
Additionally, if you need to set up ID synchronization, you must add a similar entry for dpm.demdex.net.
50.19.209.211 dpm.demdex.net .
3. Make a DCS call.
For example:
https://<domain>/event?product=camera
4. Verify that your request was served by sandbox DCS by looking for "sandbox" in the DCS response header.
For example:
DCS: use-sandbox-dcs1.ec2.demdex.com
Documentation Updates
324
Documentation Updates
All updates (additions, deletions, and corrections) to the Audience Management User Guide, by date.
This section contains detailed information about updates to this guide that might not be included in the Release Notes. Consult
the Release Notes for information about new features, enhancements, and fixes.
Date and Topic
Description
December 5, 2014
Edited the d-creative and d_adgroup rows to indicate that these are optional parameters.
Capturing Campaign Impression
Data via Pixel Calls
December 3, 2014
Added information about the d_bust parameter.
Capturing Campaign Impression
Data via Pixel Calls
November 21, 2014
New topic.
Adobe Media Optimizer Search and
Delivery Report
November 21, 2014
Revised entire section.
Target Data Integration
In addition to making the integration process easier to follow, changed the instructions
for the API code snippet by placing it in the mbox.js file via document.write, instead
of separately in the <head>.
November 21, 2014
Added information and an illustration explaining what zeroes and blank entries indicate
in Trended Trait reports.
Run a Trend Report
November 12, 2014
Changed the description for the visitorService element.
create
November 12, 2014
Changed the description for the namespace property.
visitorService Properties
Added the code sample.
October 31, 2014
Reworked topics to include information about Role Based Access Control (RBAC) and
new functionality.
General Reports
Run a General Report
October 31, 2014
Trend Reports
Run a Trend Report
Reworked topics to include information about Role Based Access Control (RBAC) and
new functionality.
Documentation Updates
325
Date and Topic
Description
October 23, 2014
Added the following information:
Create a New Data Source
If you specify an "integrationCode", it must be unique across all data sources for the
partner.
October 23, 2014
New topic.
Outbound History Report
October 22, 2014
New topic.
Onboarding Status Report
October 21, 2014
Added descriptions for each customer data field.
Fields
Added rows for the AllSegments and AllTraits fields.
October 21, 2014
Added dcs_region to the Response Parameters table.
URL Format for Passing in Data to
the DCS
October 20, 2014
Added information about the idType parameter.
Create a New Data Source
Update a Data Source
Return Properties for a Data Source
Return Properties for All Data
Sources
October 20, 2014
Generate DIL
Added information about the delayAllUntilWindowLoad parameter included in Data
Integration Library (DIL) version 5.2.
October 20, 2014
Added information about the following parameters in the request and response samples:
Create a New Data Source
• "uniqueTraitIntegrationCodes"
• "uniqueSegmentIntegrationCodes"
October 20, 2014
Added information for the following options:
Create a Data Source
• Marketing Cloud Visitor ID Version
Edit a Data Source
• ID Type
October 16, 2014
Added File Format Example.
File-Based ID Synchronization
Documentation Updates
326
Date and Topic
Description
October 16, 2014
Removed the following topic (this feature is no longer available in Audience Management):
"Build Gender Qualification Rules with Demographic Variables."
October 9, 2014
New topic.
Update an Onboarded Trait
October 3, 2014
Updated sample code.
Master Marketing Profile
Integration
September 26, 2014
Added information about clients escaping incoming data.
Data Security
September 26, 2014
Changed the sample request to indicate that keys are quoted in trait rules.
Create a New Rules-based Trait
September 26, 2014
Changed the sample request to indicate that keys are quoted in trait rules.
Update a Rules-based Trait
September 25, 2014
Changed both code examples to examples with URL encoding.
Capturing Campaign Click Data
via Pixel Calls
September 19, 2014
Added information about the d_pftm variable.
Supported Variables
September 16, 2014
Added best practices for storing access and refresh tokens.
OAuth Authentication
Explained the "expires_in" property in more detail.
Added information about issuing a refresh token to generate a new access token before it
expires and how to tell when an access token has already expired.
September 5, 2014
Topic
Third-Party Data Collection
Description
Added link to the Adobe Exchange Marketplace
(https://marketing.adobe.com/resources/content/resources/en/exchange/marketplace/audience.html)
that contains a complete list of third-party data providers that Audience Management
supports.
Documentation Updates
Topic
Overlap Reports
327
Description
Edited the following sentence:
Contain a minimum of 5,000 users.
The sentence now reads the following:
Contain a minimum of 70,000 total users during the last 14 days.
Targeting FAQ
File-Based ID Synchronization
Capturing Campaign Click Data
via Pixel Calls
Real-Time Inbound Data Ingestion
Added link to the Adobe Exchange Marketplace
(https://marketing.adobe.com/resources/content/resources/en/exchange/marketplace/audience.html)
that contains a complete list of third-party data providers that Audience Management
supports.
New topic.
New topic.
Edited topic.
August 22, 2014
Topic
Description
Capturing Campaign Impression
Data via Pixel Calls
Changed the event call example.
Fields
Master Marketing Profile
Integration
siteCatalyst.init
Profile Merge
Added Marketing Cloud ID to the list of standard fields used in customer data fields.
New topic.
The Audience Management (08/18/14) release includes an update to the DIL SiteCatalyst
module (DIL.modules.siteCatalyst). The module now tracks additional eVars
76-250 by default. This change makes the module compatible with the 08/21/14 release of
AppMeasurement JavaScript v1.4.
New topics:
• Profile Merge
• Profile Merge Terminology
• Profile Merge Architecture
• Profile Merge Customer Enablement
• Profile Merge Implications and Limitations
Documentation Updates
328
July 28, 2014
Topic
Comparing Segments to Traits
Description
Changed description for Find Inefficient Segments.
July 17, 2014
Topic
Description
Return Available Data Source ID
Types
New topic.
Return All Active Marketing Cloud
New topic.
Visitor ID Versions
Return Data Onboarding File
Status
New topic.
Return All Available Destination
Platforms
New topic.
Return S2S and Bulk S2S
Destination Job History
New topic.
Declared ID Targeting
Added new section: Declared ID Opt-Out Examples.
June 27, 2014
Topic
Data Privacy
Delivery and Performance Report
create
Destination Publishing
API URLs
Send Batch Data to Audience
Management Overview
Description
Added Collection of IP Addresses section.
Added note explaining how often reports are updated.
Added the following row to the table: declaredId.
Added two paragraphs under Supported Destination Types explaining DIL code and
iframes.
Changed information in the environments table.
Added Environments section.
Transfer-Control Files for Log File
Added sentence explaining that the .info file might be sent before all files are transferred.
Transfers
Sandbox (Beta) Environment
New topic.
Documentation Updates
329
June 2, 2014
Topic
Functional Architectural Diagrams
Create a Data Source
Edit a Data Source
Add Segment Mappings
Description
New topic.
Added information for the following options: Unique Trait Integration Codes, Unique
Segment Integration Codes, and Share Associated Visitor or Device IDs with All Platform
Customers.
Added information for the following options: Unique Trait Integration Codes, Unique
Segment Integration Codes, and Share Associated Visitor or Device IDs with All Platform
Customers.
Added the following paragraph:
After a segment mapping is added to a destination, the change is pushed to our edge servers
within 30 minutes to allow for user targeting.
Update Schedule for Algorithmic
Models and Traits
Create a New Data Source
Update a Data Source
Return Properties for a Data Source
Return Properties for All Data
Sources
File PGP Encryption for Inbound
Data Types
Inbound CRM Data Ingestion
siteCatalyst.init
Added additional information in the description for Update a Model.
Added marketingCloudVisitorIdVersion property. For more information, see
Marketing Cloud Visitor ID Service.
Added marketingCloudVisitorIdVersion property. For more information, see
Marketing Cloud Visitor ID Service.
Added marketingCloudVisitorIdVersion property. For more information, see
Marketing Cloud Visitor ID Service.
Added marketingCloudVisitorIdVersion property. For more information, see
Marketing Cloud Visitor ID Service.
Updated the Audience Management public key. This new key never expires. Audience
Management now supports any key size.
New topic.
Added information about the new options parameter in DIL 5.0.
Delivery Performance Report: Log
Revised the descriptions in the File Size and Send Incremental Data rows.
File Recommendations
May 8, 2014
Topic
Description
File PGP Encryption for Inbound
Data Types
Provided a new Audience Management public key that never expires.
Documentation Updates
330
April 2, 2014
Topic
Inbound Data File Contents:
Syntax and Parameters
Description
Edited the <Segment_N> parameter and description. A hyphen preceding the parameter
is no longer necessary.
Edited the three examples.
Outbound Data File Contents:
Syntax and Parameters
Removed information about excluding users from a segment using the :0 or :1 flags,
which is not supported.
March 21, 2014
Topic
Return Properties for all Segments
Return Properties for all Traits
Create a New Onboarded Trait
User, Group, and Permissions
Management API Methods
Description
Modified the intgrationCode row in the table to state that the integration code does
not need to be unique.
Modified the intgrationCode row in the table to state that the integration code does
not need to be unique.
New topic.
Added the following topics:
• User Management API Methods
• Create a User
• Update a User
• Update Logged-In User
• Reset Logged-In User Password
• Update Logged-In User Password
• Reset Logged-In User Password
• Return User Object for a User ID
• Return User Object for Logged-In User
• List Users
• Delete a User
• Delete Users in Bulk
• Group Management API Methods
• Create a Group
• Update a Group
• List Groups
• Delete a Group
• Delete Groups in Bulk
• List All Permissions for a Group
• Set Permissions for a Group
• Permissions Management API Methods
• List Available Object Types
Documentation Updates
Topic
331
Description
• List Available Permissions for an Object Type
DCS Region API Methods
Added the following topics:
• List a Specific DCS Region
• List DCS Regions
Capturing Campaign Impression
Data via Pixel Calls
Added information for d_src. Also added a column to indicate whether each key is
required.
Outbound Data File Name: Syntax
Added information about <SYNC_TYPE>.
and Parameters
Edited the description for <TIMESTAMP>.
ID Synchronization for Inbound
Data Transfers
Edited the description for <VENDOR_UUID>.
Inbound Data File Contents:
Syntax and Parameters
Added additional information about what Segment ID refers to and how to obtain the SID.
File PGP Encryption for Inbound
Data Types
New topic.
Reporting FAQ
Reporting and File Transfer
Time-Frame Guidelines
Added information explaining the methodology that Audience Management uses to count
traits and segments.
Changed the general reporting time when all updates should be completed from 10 a.m.
(14:00 EDT) to 15:00 EDT.
February 24, 2014
Topic
Declared ID Targeting
API URLs
Description
Added additional information about the opt-out process using declared IDs.
Changed "Staging" to "Sandbox" in the Environments section (in the Environment column
and the URLs).
January 16, 2014
Topic
Description
Return Properties for an Individual
Changed the code sample to include the folder count property.
Segment Folder
Visitor Profile Viewer
New topic.
Documentation Updates
332
December 2, 2013
Topic
Description
Reports and Data Sampling
Methodologies
Changed the values for the minimum unique visitor requirements for traits and segments.
Campaign Data Integration
New section and sub-topics.
October 5, 2013
Topic
About Amazon S3
Description
New section.
September 30, 2013
Topic
Customer Data Feeds
Description
New section.
September 5, 2013
Topic
Inbound Data File Name: Syntax
and Parameters
Inbound Data File Contents:
Syntax and Parameters
Description
Updated the syntax examples in both sections (S3 and FTP) and added information about
the <File_Type>sync and overwrite parameters.
Added the third bullet under the note in the -<SEGMENT_N> row to explain Segment ID
validation.
Added the final sentence to the note in the :0 or :-1 row to explain that SID removals are
ignored in a .overwrite file type.
Geotargeting With Platform-level
Keys
Added two rows to the Platform Level Keys Defined by IP Address table: d_region and
d_isp. Also updated the downloadable files (city list, country list, region list, and so forth).
August 28, 2013
Topic
Data Sources
Description
Added new section with the following topics:
• Data Sources
• Data Sources List View
• Create a Data Source
• Edit a Data Source
• Delete Data Sources
Documentation Updates
Topic
333
Description
Modify the GPT setTargeting API
Replaced the If Statement code sample.
Call
Data Integration Library API
Methods
Added new section with the following topics:
• Data Integration Library API Methods
• Return Versions for DIL
• Return JSON Schema for Version
• Generate DIL
Data Source API Methods
Updated information and samples in the following topics:
• Create a New Data Source
• Return Properties for a Data Source
• Return Properties for All Data Sources
Added the following new topics:
• Update a Data Source
• Delete a Data Source
• Delete Multiple Data Sources in Bulk
Segment API Methods
Added information about using integration codes in Segment API methods to the following
topics:
• Update a Segment
• Delete a Segment
• Return Properties for an Existing Segment
• Return Properties for all Segments
Trait API Methods
Added information about using integration codes in Trait API methods to the following
topics:
• Update a Rules-based Trait
• Update an Algorithmic Trait
• Delete a Trait
• Return Properties for an Existing Rules-based Trait
• Return Properties for an Existing Algorithmic Trait
• Return Properties for all Traits
Inbound Data File Contents:
Syntax and Parameters
Data Collection and Product
Integration FAQ
Removed information about the requirement to provide the timestamp for each segment,
which is no longer necessary to specify.
Added information explaining how to differentiate Inbound traffic from DCS traffic in
DCS log file exports.
Documentation Updates
334
August 15, 2013
Topic
Return Properties for all Segments
Paused and Deleted Segments
(Using API)
Data Actionability Components
Data Translation File
File Compression for Inbound
Data Transfer Files
Description
Replaced code sample to fix a syntax error.
New topic.
New topic.
Changed email address under Send the Translation File to Audience Management.
Added information about uncompressed files and best practices.
Inbound Data File Name: Syntax
Removed information about full syncs. This functionality has been deprecated.
and Parameters
Added Additional Requirements and Best Practices sections.
Inbound Data File Contents:
Syntax and Parameters
Added information about optional flags.
Sample Message to Partners after
New topic.
Inbound Processing
Send Data Elements to Audience
Management with DIL
Tag Manager Integration
Replaced code sample to fix a syntax error.
New topic.
Capturing Campaign Impression
Replaced all text in topic.
Data via Pixel Calls
Provide Cookie Details
Experience Manager Integration
User Management
Updated the text in the Expire After row.
New topic.
New topics:
• User Management
• Create Users
• Create Groups
• Edit Your Account Settings
Reporting and File Transfer
Time-Frame Guidelines
Data Security
New topic.
Added new section: Inbound Server-to-Server (S2S) Transfers.
Data Privacy
335
Data Privacy
Describes Audience Management integration and compliance with generally accepted best practices related to consumer privacy
and opt-out procedures.
This section contains the following information:
• Consumer Privacy Protection
• DoNotTarget and Partner Opt-outs
• Privacy Integrations
• Collection of IP Addresses
Consumer Privacy Protection
Audience Management recognizes the implicit pact between consumers and the online brands with which they interact. Both
parties benefit from the transparent exchange of anonymous data elements. Consumers receive personalized content, discounted
product offers, and streamlined user experiences. Similarly, brands receive vital revenue streams supporting multiple online
business models. In our continuing support of this model, Audience Management remains committed to providing transparency
and control to consumers, and meeting or exceeding the Online Behavioral Advertising (OBA) Self-Regulatory Principles.
DoNotTarget and Partner Opt-outs
Audience Management owns and operates the portal DoNotTarget.com, which provides opt-out access to all consumers.
Consumers will not be tracked across the Audience Management network when they opt-out via DoNotTarget.com.
Privacy Integrations
Audience Management provides the following privacy integrations:
Do Not Track: Audience Management processes recognize and take action on “Do Not Track” HTTP headers.
Evidon: Audience Management works with Evidon, a leading privacy compliance vendor, to enhance our commitment to data
privacy. Current efforts include:
• Enabling Audience Management and partner-level opt out capabilities within the Evidon "Ad Choices" interface.
• Working as a partner in the Open Data Partnership, which provides segment-level transparency across multiple data companies
to all consumers.
• Improved workflow for ad notice tag trafficking.
Other Industry Affiliations: Audience Management understands the benefit of industry standards and their ability to build
scale in emerging sectors of the economy. As a result, we constantly engage with industry certification providers such as the
Network Advertising Initiative, the Digital Advertising Alliance, and TRUSTe.
Collection of IP Addresses
Adobe has enabled processes and offers settings that allow customers to use Audience Management in compliance with applicable
data privacy laws.
The IP address of a visitor to a customer’s website is transmitted to an Adobe Data Processing Center (DPC) where the IP address
may be stored. Depending on the network configuration for the visitor, the IP address does not necessarily represent the IP
address of the visitor’s computer. For example, the IP address could be the external IP address of a Network Address Translation
(NAT) firewall, HTTP proxy, or Internet gateway.
Replacement of Last Octet of the IP Address: Adobe has developed a new “privacy by design” setting that can be enabled by
Audience Management Consulting. When this setting is enabled, the last octet (the last portion) of the IP address is immediately
Data Privacy
336
hidden when the IP address is collected by Adobe. This anonymization is performed prior to any processing of the IP address,
including before an optional geo-lookup of the IP address.
For example:
123.45.67.89
is changed to
123.45.67.0
When this feature is enabled, the IP address is made sufficiently anonymous so it is no longer identifiable as personal information.
As a result, Adobe Audience Management can be used in compliance with data privacy laws in countries that do not permit the
collection of personal information. Obtaining city-level information will likely be significantly impacted by the obfuscation of
the IP address. Obtaining region- and country-level information should only be slightly impacted.
Note: Contact your Audience Management Consulting representative to enable the IP obfuscation feature.
GeoSegmentation: If customers enable the replacement of the last octet of the IP address, the remaining values of the IP address
can still be utilized for geo-segmentation and reporting in Audience Management. If the last octet of the IP address has not been
obfuscated, the full IP address is used. Customers can use the GeoSegmentation feature that allows the customer to map out
visitor location by geographic area in either case, but with some slight loss of precision when IP obfuscation is being used.
GeoSegmentation data is granular only to the city level or zip code level, and not to the individual level.
If There's a Problem
337
If There's a Problem
Customer Care is prepared to help you solve any issues that might arise. This page contains the information you need when
contacting Customer Care to expedite a resolution.
Basic Information
If you encounter issues or have questions when using Audience Management, you have a number of options:
For questions, ask the Adobe Audience Management experts:
• Online: Marketing Cloud community
http://help-forums.adobe.com/content/adobeforums/en/media-optimizer-forum/adobe-media-optimizer.html
• Twitter: @AdobeMktgCare
http://twitter.com/adobemktgcare
For technical issues or to log a bug, contact Customer Care.
• Telephone: 1-800-497-0335
Toll free numbers outside the United States can be found at http://helpx.adobe.com/marketing-cloud/contact-support.html.
When asked to select an option for your product, press 4 to contact the Audience Management team.
• Email: amsupport@adobe.com
For the quickest triage of your issue, please have the following basic information ready when you are contacting us:
Summary
Brief summary of the overall issue
Account information
Company Name.
Audience Management sub-domain (if known), i.e., the URL domain where data
collection events are sent in to Adobe.
For example: mycompany.demdex.net
Steps to reproduce
Include as much detail as possible, including any URLs needed to duplicate as
well as the expected result.
Include enough detail that somebody unfamiliar with Audience Management
should be able to follow the directions and reproduce the problem.
Priority
P1 (most important) to P4 (least important).
Business impact
What is the impact to your business? For example, is this issue causing revenue
loss or rendering the product unusable, and is there a viable workaround?
Expectations
What do you expect to happen?
Also prepare information related to the specific issue.
If There's a Problem
338
In Case of an Outage
If you suspect there is an outage, first check the Marketing Cloud System Status page (http://status.adobe.com) This
has a record of all outages, incidents and maintenance for Marketing Cloud Solutions, including Audience Management, and
includes latest updates from our Tech Ops team. If you still require assistance, please ensure you know the following in addition
to the information listed above when you contact Customer Care:
• Time outage started
• Explanation of what is occurring
• Scope
• Expectation of resolution (ETA, severity, and so on)
Contact and Legal Information
339
Contact and Legal Information
Information to help you contact Adobe and to understand the legal issues concerning your use of this product and documentation.
Help & Technical Support
The Adobe Marketing Cloud Customer Care team is here to assist you and provides a number of mechanisms by which they
can be engaged:
• Check the Marketing Cloud help pages for advice, tips, and FAQs
• Ask us a quick question on Twitter @AdobeMktgCare
• Log an incident in our customer portal
• Contact the Customer Care team directly
• Check availability and status of Marketing Cloud Solutions
Service, Capability & Billing
Dependent on your solution configuration, some options described in this documentation might not be available to you. As
each account is unique, please refer to your contract for pricing, due dates, terms, and conditions. If you would like to add to
or otherwise change your service level, or if you have questions regarding your current service, please contact your Account
Manager.
Feedback
We welcome any suggestions or feedback regarding this solution. Enhancement ideas and suggestions for the Analytics suite
can be added to our Customer Idea Exchange.
Legal
© 2014 Adobe Systems Incorporated. All Rights Reserved.
Published by Adobe Systems Incorporated.
Terms of Use | Privacy Center
Adobe and the Adobe logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States
and/or other countries. A trademark symbol (®, ™, etc.) denotes an Adobe trademark.
All third-party trademarks are the property of their respective owners. Updated Information/Additional Third Party Code
Information available at http://www.adobe.com/go/thirdparty.
12112014
1/--pages
Пожаловаться на содержимое документа