Audience Manager Help - Adobe Marketing Cloud

Transcription

Adobe® Marketing Cloud
Audience Manager Help
Contents
Audience Manager Product Documentation.......................................................10
Overview.................................................................................................................11
History and Background........................................................................................................11
Types of Data Collected........................................................................................................12
First-Party Data Collection.......................................................................................................................12
Second-Party Data Collection..................................................................................................................13
Third-Party Data Collection......................................................................................................................14
Custom Segment Generation................................................................................................14
Performance Reporting.........................................................................................................15
Ad Server Integration............................................................................................................16
Destination Publishing...........................................................................................................16
Tag Management...................................................................................................................16
Data Security and Privacy.....................................................................................................17
Data Security............................................................................................................................................17
Data Privacy.............................................................................................................................................19
Features and Tools................................................................................................21
Addressable Audiences.........................................................................................................21
Addressable Audience Metrics.................................................................................................................23
Causes of Low Match Rates for Addressable Audiences.........................................................................23
Troubleshooting with Addressable Audiences..........................................................................................24
Administration........................................................................................................................24
Create Users............................................................................................................................................24
Create a Group........................................................................................................................................25
Edit Your Account Settings.......................................................................................................................25
Understanding Wild Card Permissions.....................................................................................................26
Usage Limits............................................................................................................................................26
Algorithmic Models................................................................................................................27
Understanding Algorithmic Models..........................................................................................................28
Last updated 10/25/2016
Contents
TraitWeight...............................................................................................................................................28
Update Schedule for Algorithmic Models and Traits.................................................................................30
Models List View.......................................................................................................................................30
Models Summary View.............................................................................................................................31
Model Builder...........................................................................................................................................31
Audience Lab........................................................................................................................32
Create Segment Test Groups...................................................................................................................34
Edit Segment Test Groups.......................................................................................................................36
Delete Segment Test Groups...................................................................................................................36
Test Group Information.............................................................................................................................36
Test Group Reporting ..............................................................................................................................37
Audience Marketplace...........................................................................................................40
Audience Marketplace for Data Providers................................................................................................40
Audience Marketplace for Data Buyers....................................................................................................48
Private Data Feeds...................................................................................................................................56
Data Export Controls.............................................................................................................59
Data Sources........................................................................................................................61
Data Sources List View............................................................................................................................61
Create a Data Source..............................................................................................................................62
Delete a Data Source...............................................................................................................................63
Data Source Settings Defined..................................................................................................................64
Declared IDs.........................................................................................................................64
Declared ID Targeting...............................................................................................................................64
URL Variables and Syntax for Declared IDs.............................................................................................66
Declared ID Variables...............................................................................................................................67
Derived Signals.....................................................................................................................69
Create a Derived Signal...........................................................................................................................69
Edit a Derived Signal................................................................................................................................70
Delete a Derived Signal............................................................................................................................70
Destinations..........................................................................................................................70
How to Choose a Destination Type..........................................................................................................70
Destination Builder...................................................................................................................................71
Create a Cookie Destination....................................................................................................................72
Create a URL Destination........................................................................................................................74
Optional Settings for Cookie Destinations................................................................................................75
Add or Edit Segments for Server-to-Server Destinations.........................................................................76
Add Data Export Labels to a Destination.................................................................................................77
Destination Serialization...........................................................................................................................77
Standard and Serial Key-Value Pairs.......................................................................................................78
Destination Macros Defined.....................................................................................................................79
Cache Busting with Destination Macros...................................................................................................81
get_aamCookie Code..............................................................................................................................81
Profile Link............................................................................................................................82
Profile Merge Rules Dashboard...............................................................................................................83
Getting Started With Profile Merge Rules................................................................................................84
Profile Merge Rule Options Defined.........................................................................................................87
Use Cases for Merge Rules.....................................................................................................................89
Report Metrics for Profile Merge Rules....................................................................................................91
Reports..................................................................................................................................93
Advertiser Analytics Reports....................................................................................................................93
Custom Reports.....................................................................................................................................101
General Reports.....................................................................................................................................101
Interactive Reports.................................................................................................................................103
Onboarding Status Report: About..........................................................................................................118
Outbound History Report.......................................................................................................................123
Trend Reports.........................................................................................................................................124
Counting Unique Users in Overlap and General Reports......................................................................126
Reports Dashboard................................................................................................................................127
Reports and Data Sampling Methodologies...........................................................................................129
Segments............................................................................................................................130
Segments: Purpose, Composition, and Rules........................................................................................130
Segments List View................................................................................................................................131
Segment Summary View........................................................................................................................131
Retrieving Segment Metadata................................................................................................................131
Segment Builder.....................................................................................................................................132
Tags.....................................................................................................................................140
Traits....................................................................................................................................140
Trait List View.........................................................................................................................................140
Contents
Active Audience Traits and Data Source Synced Traits..........................................................................141
Trait Summary View...............................................................................................................................142
Trait Builder............................................................................................................................................143
Trait Storage...........................................................................................................................................148
Trait Builder Reference...........................................................................................................................149
Visitor Profile Viewer...........................................................................................................159
API and SDK Code...............................................................................................160
API Code Migration.............................................................................................................160
Data Integration Library (DIL) API.......................................................................................161
Understanding the Data Integration Library (DIL)..................................................................................161
Class-level DIL Methods........................................................................................................................162
Instance-level DIL Methods....................................................................................................................166
DIL Modules...........................................................................................................................................174
DIL Tools................................................................................................................................................178
DIL Use Cases and Code Samples.......................................................................................................180
Flash DIL................................................................................................................................................183
Tag Manager Integration........................................................................................................................185
REST APIs..........................................................................................................................186
Getting Started.......................................................................................................................................186
Algorithmic API Methods........................................................................................................................191
Data Integration Library API Methods....................................................................................................198
Data Source API Methods......................................................................................................................204
Derived Signals API Methods.................................................................................................................205
Destination API Methods........................................................................................................................207
Domain Management API Methods.......................................................................................................225
Segment API Methods...........................................................................................................................227
Taxonomic API Methods.........................................................................................................................234
Trait API Methods...................................................................................................................................235
Trait Type Methods.................................................................................................................................246
User, Group, and Permissions Management API Methods....................................................................248
DCS Region API Methods......................................................................................................................259
SDK Code...........................................................................................................................260
Implementation and Integration Guides............................................................261
Ad Server Integration..........................................................................................................261
DART Enterprise as an Audience Manager Destination........................................................................261
GPT as an Audience Manager Destination............................................................................................263
DFP as an Audience Manager Destination............................................................................................266
OAS as an Audience Manager Destination............................................................................................268
OpenX as an Audience Manager Destination........................................................................................269
Campaign Data Integration.................................................................................................271
Capturing Campaign Impression Data via Pixel Calls............................................................................271
Capturing Campaign Click Data via Pixel Calls......................................................................................274
Delivery Performance Report: Log File Recommendations...................................................................277
Pre-Submission Data Integration Checklist............................................................................................284
Customer Data Feed Overview...........................................................................................286
Customer Data Feeds Getting Started...................................................................................................286
Input/Output...........................................................................................................................................292
Fields in the Customer Data Feed..........................................................................................................293
Filtering..................................................................................................................................................294
Notifications............................................................................................................................................295
Data Integration Methods....................................................................................................296
Data Integration Methods.......................................................................................................................296
Data Translation File...............................................................................................................................298
Real-Time Data Transfer Process..........................................................................................................299
Batch Data Transfer Process..................................................................................................................300
Data and Metadata Files for Advertiser Analytics Reports..................................................301
Data Files for Advertiser Analytics Reports............................................................................................301
Overview and Mappings for Metadata Files...........................................................................................304
Naming Conventions for Metadata Files................................................................................................309
Content Format for Metadata Files.........................................................................................................310
Delivery Methods for Metadata Files......................................................................................................311
Status Updates for Metadata Files.........................................................................................................312
DCS Integration...................................................................................................................314
Variable Prefix Requirements.................................................................................................................314
Supported Variables...............................................................................................................................314
Contents
URL Format for Passing Data to the DCS..............................................................................................315
Format and Delimiter Standards for Key-Value Pairs.............................................................................317
DCS Location Information in the HTTP Response Header....................................................................318
Metro Codes: IDs and Names................................................................................................................318
Cookie Checking and First Time Users..................................................................................................325
Race Conditions and Error Handling......................................................................................................325
DCS Error Codes, Messages, and Examples........................................................................................326
Implementing Audience Manager........................................................................................328
Implementation Overview.......................................................................................................................328
Post-Implementation Support.................................................................................................................331
Import DCM Data Files Into Audience Manager.................................................................331
Real-Time Data Transfers With the DCS API......................................................................332
Get User IDs and Regions Through the Marketing Cloud ID Service....................................................333
Get User IDs and Regions From a DCS Response...............................................................................334
Making DCS API Calls...........................................................................................................................336
Receiving Audience Data....................................................................................................338
ID Synchronization for Outbound Data Transfers...................................................................................338
Real-Time Outbound Data Transfers......................................................................................................338
Batch Outbound Data Transfers.............................................................................................................345
Sending Audience Data.......................................................................................................353
Real-Time Inbound Data Integration......................................................................................................353
Batch Data Transfer Process Described.................................................................................................357
Send Segments to a Google AdWords Remarketing List...................................................373
Share Data between Marketing Cloud Solutions.................................................................374
Analytics Data Integration......................................................................................................................375
Auditude Data Integration.......................................................................................................................381
Experience Manager Integration............................................................................................................384
Marketing Cloud Audiences in Analytics................................................................................................384
Target Data Integration...........................................................................................................................384
Server Side Forwarding.......................................................................................................388
Requirements for Server-Side Forwarding.............................................................................................389
Implement Server-Side Forwarding........................................................................................................391
How to Determine if Your Account is Ready to Receive Forwarded Data..............................................394
How to Determine if Your Account is not Ready to Receive Forwarded Data........................................395
Reference.............................................................................................................398
Amazon S3: About...............................................................................................................398
Advertiser and Publisher Use Cases...................................................................................398
Advertiser Use Cases............................................................................................................................398
Publisher Use Cases..............................................................................................................................401
Boolean Expressions in Trait and Segment Builder.............................................................403
Bulk Management Tools......................................................................................................404
Getting Started With Bulk Management.................................................................................................405
Bulk Requests........................................................................................................................................408
Bulk Updates..........................................................................................................................................408
Bulk Create............................................................................................................................................409
Bulk Estimates.......................................................................................................................................410
Bulk Delete.............................................................................................................................................411
Create or Update Trait Rules and Segment Rules.................................................................................412
Troubleshooting Tips for Bulk Management Tools..................................................................................413
Bulk Management Tools Glossary..........................................................................................................414
CID Replaces DPID and DPUUID.......................................................................................416
Data Retention....................................................................................................................417
Key-Value Pairs Explained..................................................................................................417
Password Requirements, Locked Accounts, and Forgotten Passwords..............................419
Reporting and File Transfer Time-Frame Guidelines...........................................................419
Beta Environment................................................................................................................420
Signals, Traits, and Segments.............................................................................................421
Supported Browsers............................................................................................................422
System Components...........................................................................................................423
Key Components in the Audience Manager System..............................................................................423
Data Action Components.......................................................................................................................424
Data Collection Components.................................................................................................................426
Data Processing Components...............................................................................................................428
Tag Management Components..............................................................................................................430
Platform Architecture: Data Flow Map....................................................................................................431
Understanding the Edge Data Center....................................................................................................432
Contents
Style Conventions for Code and Text Elements..................................................................433
Time Zones in Audience Manager......................................................................................434
FAQ........................................................................................................................435
API FAQ..............................................................................................................................435
Data Collection and Product Integration FAQ......................................................................435
Inbound Customer Data Ingestion FAQ..............................................................................437
Privacy FAQ.........................................................................................................................441
Product Features and Functions FAQ.................................................................................441
Reporting FAQ.....................................................................................................................442
Targeting FAQ......................................................................................................................443
Documentation Updates.....................................................................................446
2015: New and Revised Documentation.............................................................................450
Help, Privacy, and Legal......................................................................................457
If There's a Problem............................................................................................................457
Data Privacy........................................................................................................................458
Contact and Legal Information............................................................................................459
Audience Manager Product Documentation
10
Audience Manager Product Documentation
Audience Manager 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.
New and Featured Items
Release Notes
Hover over a title for a brief description.
• See the latest Marketing Cloud Release Notes for new
features and fixes.
• See the Previous Release Notes for older
announcements.
• Import DCM Data Files Into Audience Manager
• GA.init
• Amazon S3: About
• Privacy FAQ
• Cookies used in the Marketing Cloud
See also Documentation Updates.
Marketing Cloud Resources
• Adobe Marketing Cloud
• Adobe Training and Tutorials
• Product Documentation Home
Overview
11
Overview
Information about the history of Adobe Audience Manager, the types of data collected, segmentation, reporting, and
more.
Audience Manager 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 Manager offers easy tag deployment and management with robust data
collection, control, and protection.
With Audience Manager, you are not tied to a data seller, exchange, or demand-side platform. Additionally, Audience
Manager is completely agnostic when it comes to our partners’ data assets. With access to multiple data sources,
Audience Manager 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 Manager started as Demdex in 2008. It was acquired by Adobe Systems in 2011 and subsequently
rebranded as Audience Manager.
History
Since 2008, Audience Manager (formerly, Demdex) has been a pioneer in the on-line audience management market.
Audience Manager 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 Manager and its Data Management Platform (DMP)
Audience Manager 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
Manager provides tools for tag management and audience analytics while simultaneously meeting the privacy and
data security needs of clients and consumers.
Overview
12
Types of Data Collected
Audience Manager 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 Manager 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 Manager 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 Manager 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
13
After the raw data is collected, it gets mapped back to customer-defined traits within the Audience Manager 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 Manager 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 Manager partner site for consumers who configured
different types of vehicle options (e.g., color, model, etc.).
Overview
14
Third-Party Data Collection
Third-party data is information collected and shared by vendors outside of Audience Manager.
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 Manager 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 Manager, see the Adobe
Exchange Marketplace
(https://marketing.adobe.com/resources/content/resources/en/exchange/marketplace/audience.html).
Audience Manager 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
Manager 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.
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 Manager interface, publisher team members
can browse traits and segments to combine them into new marketing segments.
Overview
15
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 Manager interface. Our system uses two methods
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.
Performance Reporting
Audience Manager 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. Audience Manager 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
Overview
16
• 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 Manager 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).
Destination Publishing
In Audience Manager, 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 Manager allows publishers to easily set up new targeting partners
(destinations) in the interface.
Audience Manager 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 Manager consultant can enable them on your request. The purpose of an ID sync is to
reconcile unique-visitor identifiers between Audience Manager 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 Manager 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 Manager. Furthermore, Audience Manager 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.
Overview
17
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 Manager takes data security and privacy very seriously. We work to keep our systems secure and protect
your valuable data.
Audience Manager 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 Manager, 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 Manager tests security on an annual and quarterly basis.
• Yearly: Once a year, Audience Manager 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 Manager:
• 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 Manager has a dedicated network operations team that monitors firewalls and
intrusion-detection devices. Only key personnel have access to our security technology and data.
Overview
18
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 Manager 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 Manager contractually prohibits 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.
IP Addresses: Audience Manager 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 Manager 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 Manager customer.
Inbound Server-to-Server (S2S) Transfers
Adobe Audience Manager 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.
To add PGP encryption to your data files, see File PGP Encryption for Inbound Data Types.
Overview
19
Protecting Data by Escaping
Note that Audience Manager 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 Manager integration and compliance with generally accepted best practices related to consumer
privacy and opt-out procedures.
• Consumer Privacy Protection
• Data Privacy
• Collection of IP Addresses
Consumer Privacy Protection
Audience Manager 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 Manager remains
committed to providing transparency and control to consumers, and meeting or exceeding the Online Behavioral
Advertising (OBA) Self-Regulatory Principles.
Data Privacy
See the Adobe Privacy Center.
Collection of IP Addresses
Adobe has enabled processes and offers settings that allow customers to use Audience Manager 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 Manager 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 Manager 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
Overview
20
impacted by the obfuscation of the IP address. Obtaining region- and country-level information should only be slightly
impacted.
Note: Contact your Audience Manager 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 Manager. 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.
Features and Tools
21
Features and Tools
User interface (UI) controls and workflows that let you create and manage important aspects of your Audience
Manager account.
Addressable Audiences
Addressable Audiences shows you the overlap between the audiences you see across all of your properties where
Audience Manager collects data and your selected destination.
To help you understand what we mean by an "addressable audience," take a look illustration below. The overlap
between each circle represents the total addressable audience or segment audience you and a destination partner
share in common.
Addressable Audience Interface
The Addressable Audience feature turns this abstract concept into quantifiable data. In Audience Manager, this
feature displays audience overlap with data visualizations that provide at-a-glance information along with numeric
data in tabular form.
Addressable Audiences is located in Manage Data > Destinations. Click on the name of a server-to-server
destination to view your addressable audience data. Note, this feature returns data for server-to-server destinations
only and access requires administrator permissions.
Features and Tools
Use Cases for Addressable Audiences
Reviewing this data can help you with campaign:
22
Features and Tools
23
• Forecasting and planning: Segment Addressable Audience data gives you more granularity into the segments
you are planning to send to a destination for audience targeting and activation.
• Performance reviews: The Addressable Audienes feature is also a troubleshooting tool. It lets you review
campaign performance, understand campaign reach, and lets you cross-check with targeting/activation partners
if you don't see the results you expect.
Related Information
Addressable Audience Metrics
Lists and defines metrics provided by Addressable Audiences.
Note: Unless indicated otherwise, all metrics return data for the last 60-days.
Metric
Description
Current Segment
Addressable Audience
A statistically significant sampled count of the overlap between your segments and the
destination for the last day.
Your Addressable
Audience
The total overlap between:
• All of the profiles that you see on all of your properties where Audience Manager
collects data.
• The destination you're sending data to.
Your Total Audience
The total number of users you have seen on all your properties.
Your Addressable
Audinece Match Rate
Your addressable audience / your total audience expressed as a %.
Adobe Audience
The total number of platform-level uniques for the overlap between Audience Manager
Manager's Addressable and your destination.
Audience
Causes of Low Match Rates for Addressable Audiences
Common elements responsible for low Addressable Audience match rates or discrepancies in reported numbers.
Cause
Description
Mobile Traffic
Most server-to-server integrations rely on synchronization processes facilitated by
third-party cookies. However, mobile environments do not use third-party cookies. As a
result, your Addressable Audience numbers may seem low compared to segment size.
Safari Traffic
Safari blocks third-party cookies. This prevents Audience Manager from synchronizing
with the destination.
Features and Tools
24
Cause
Description
Tracked Media
Impressions
Due to ad server best practices, ID syncs are not made within ad tags. Customers who
do a large amount of offsite advertising will not synchronize users to third-party
integrations in those environments. Also, a large amount of collected media impression
data could reduce addressable audience numbers.
Troubleshooting with Addressable Audiences
In addition to surfacing match rates, you can also use Addressable Audiences as a troubleshooting tool.
For example, let's say you send a segment to a destination and that destination shows low reporting numbers.
Checking the Addressable Audience results will show you if this is a technical problem or just a case of low match
rates. A low match rate shows your destination isn't all that great for your selected segments. However, a difference
in the total addressable audience numbers between Audience Manager and the destination indicates an integration,
synchronization, or other technical problem. In these cases, contact your account manager.
Administration
The options under the Administration menu let you create Audience Manager users and assign them to groups.
You can also view limits (traits, segments, destinations, and AlgoModel).
Enterprise customers using Audience Manager 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, also referred to as Role-Based Access Control (RBAC).
Audience Manager 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 Administration > 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 Manager.
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 Manager 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.
Features and Tools
25
Is Admin: Specify if this user is an Audience Manager 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 Manager and you can simple reactivate them, if
necessary. If you remove users, you must re-create them if they need to use Audience Manager 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 a Group.
6. Click Save.
Create a Group
A group is a collection of users that share access rights to destination, segment, and trait objects. You can limit
groups to single objects only or give them broad access to combinations of different objects.
To create a group:
1. Click Administration > Groups.
2.
Click
to open the Group Settings page.
3. In Group Details:
• Name the group.
• Provide a brief group description.
4. In Group Members, click a user from Add Users options to add them to the group.
5. In Group Permissions, select a trait, segment, or destination from Add Object.
This opens a permissions window for your selected object.
6. Select the check box for the permissions you want group members to have.
7. (Optional) Assign Wild Card Permissions to the group.
8. 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 a Group.
1.
In the Audience Manager 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.
Features and Tools
26
Audience Manager 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.
See also, Password Requirements, Locked Accounts, and Forgotten Passwords.
5. Click Save.
Understanding Wild Card Permissions
Simplify group rights management with Wild Card Permissions.
Wild Card Permissions give group members automatic access to each data source associated to a segment,
destination, or trait. By comparison, regular permissions only lets you assign specific data sources to the one of
these objects. And, when you add new data sources, group members don't get access to those new sources. You
have to open the group permissions and assign those new data sources to the group. Wild Card Permissions let
you avoid this manual data source update process. Groups with Wild Card permissions get access to new data
sources without explicit authorization.
Usage Limits
Audience Manager sets a maximum limit on the number of traits, segments, destinations, and algorithmic models
that you can create for an account. Limits apply to these items whether created in the user interface or
programmatically through API methods. Usage limits help protect Audience Manager from automated processes
that may attempt to compromise our APIs or user interface.
Contents:
Item Limits
Monitor Usage
Increase Item Limits
Item Limits
The tables list the current limits by item type. You cannot create new traits, segments, destinations, or Algorithmic
Models if you reach a specific limit for one of these items. If do reach a limit, you must delete an older item before
you can create a new one.
Trait Limits
Trait Type
Maximum Limit
Total Traits
100,000
Algorithmic
50
Rule Based
100,000
Onboarded
100,000
Features and Tools
27
Segment Limits
Segment Type
Maximum Limit
Total Segments
20,000
Destination Limits
Destination Type
Maximum Limit
Total Destinations
1,000
Cookie
1,000
URL
1,000
S2S
100
Algorithmic Model Limits
Segment Type
Maximum Limit
Total AlgoModels
20
Monitor Usage
You can see usage and limits for your account by going to Administration > Limits. Access requires administrator
permissions.
Increase Item Limits
The default limits listed here should provide enough capacity for your business needs. If your organization consistently
reaches these limits, contact your account representative to discuss an increase.
Algorithmic Models
Build and manage the traits or segments used in algorithmic modeling. Model features are located in Manage Data
> Models.
Features and Tools
28
Understanding Algorithmic Models
A summary of algorithmic modeling in Audience Manager. 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 Manager 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 Manager 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 Manager).
• 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 Manager 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.
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 Manager.
Features and Tools
29
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. In fact, our
model recognizes these large, common traits and does not assign excess priority to data sets with high correlations.
Rare traits get higher priority because they 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 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
Features and Tools
30
Audience Manager 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
Description
Create or Clone a
For new or cloned algorithmic models, the creation process runs once per day at:
Model
• 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
Under ideal conditions, existing models rerun at 8-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. Note,
the model update process requires a tremendous amount of computational power. As a result,
sometimes it may take longer than 8-days to update a model.
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:
• Create new models.
• Manage existing models (edit, pause, delete, or clone).
• Search for models by name.
Features and Tools
31
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 Manager 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.
Features and Tools
32
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
Select a Baseline Trait or Segment
Description
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.
Audience Lab
Create mutually exclusive test segments in Segment Test Groups to compare and measure effectiveness of different
destinations. You can set aside a control group and divide your segment into percentages of a whole, in order to
test efficacy.
Audience Lab enables several use cases by allowing you to use baseline segments for creating test groups. You
can divide test groups into several mutually exclusive test segments, map these to different destinations and then
determine which of the segments are most effective in driving conversions.
Audience Lab uses Profile Link to power cross-device testing. This helps ensure a user qualifies for the same test
segment and receives the same treatment across devices. The test segments in test groups will inherit the Profile
Merge Rule the base segment has assigned to it.
The Audience Lab default view displays a card for each of the test groups. Click a card to access the Test Group
view. This view includes the following information:
• Test Group Information
Features and Tools
33
• Test Group Reporting
You are able to create up to 10 test groups, each one with up to 15 test segments.
Status
The status of a test group can be draft, pending, active, paused or completed. More information on each of them in
the table below:
Features and Tools
34
Status
Description
Draft
A draft test group is not yet active and can still be edited. It does not yet send
data to the mapped destinations.
Pending
A pending test group is not yet active but cannot be edited anymore. It will
become active at the start date you selected in the Create Test Groups wizard.
Active
An active test group means that data is currently being sent to destinations.
Press Pause Test in the Test Group card to suspend sending data to
destinations.
Paused
A paused test group does not currently send data to destinations. Press Make
Active in the Test Group card to resume sending traits.
Completed
A completed test group has reached the end date you selected in the Create
Test Groups wizard and has stopped sending reporting data.
Actions
Actions
Description
Edit
Available only for draft test groups. Allows you to resume the Create New
Test Group wizard.
Pause
Available for active test groups. Allows you to pause sending the test segments
to destinations.
Make Active
Available for paused test groups. Allows you to resume sending the test
segments to destinations.
View
Available for completed test groups. Allows you to view the reporting information
the test has generated.
Duplicate
Allows you to create a new test group with the same configuration as the one
you are duplicating.
Delete
Allows you to delete a test group. The test segments will be unmapped from
the destinations, the baseline segment and conversion traits associated to the
test group are fully editable. An alert will prompt you to download the CSV file
when you delete a test group to save the reporting if you wish.
Create Segment Test Groups
This procedure walks you through the process of creating a new test group in Audience Lab.
Features and Tools
35
• You need to have at least one conversion trait set up. You can set up conversion traits in the Trait Builder, by
selecting conversion as the Event Type.
• For companies using Role-Based Access Control: Assign the Audience Labwildcard permission to User Groups
to provide access.
To create a new Segment Test Group
1. Select Create New Test Group in the Audience Lab dashboard to start the wizard.
2. Basic Info & Choose Segment
•
•
•
•
Fill in a Test Group Name and a Description.
Choose the Base Segment either by navigating in the file browser or by typing in the search bar, confirm by
pressing Choose Segment.
You can save the test group as a draft and resume working on it later.
An alert will show up in case the base segment you selected is already used in other test groups. Using the
base segment twice may distort the conversion results for both tests.
3. Allocate Test Segments
•
•
•
You can create up to 15 test segments and divide the percentage of devices as you wish.
You can edit the name of the test segments by clicking on them.
The percentages automatically divide evenly to 100% when new test segments are allocated. You can then
manually edit the percentages. Click the checkbox after editing the percentages and make sure they add up
to 100%, otherwise you will not be able to proceed to the next step.
4. Set a Control Segment
•
•
•
Select a control segment if you want to set aside a certain part of the segment to be used as a control group.
Control groups allow you to see the impact of the test segments you created compared to a benchmark.
You can select a test segment as control segment in the drop-down list, or you can choose None for no
control.
Click Next when you're done.
5. Select Conversion Traits
•
•
•
Add conversion traits by typing in the conversion trait window. This is a mandatory step and you cannot
proceed to the next step unless you add at least one conversion trait.
You can add up to 5 conversion traits if you wish.
An alert will show up in case you select a conversion trait already used for other test groups.
6. Choose Destinations & Dates
•
•
•
•
•
•
•
Type in the desired destinations in the search field or use the drop-down arrow. Audience Lab test segments
can be sent to URL, cookie, or server-to-server destinations.
Drag & drop segments to destinations.
After dropping a segment in a destination, fill in the Destination Mapping Value in the blind.
You can send the same test segment to multiple destinations and you can add multiple test segments to a
single destination.
Destinations are grayed out if they are not available for a certain test segment based on Data Export Controls.
Users will only see the destinations they have access to based on the RBAC User Group they belong to.
Finally, you are required to select a start date for your test group. This date marks the start of the period in
which your test group will be published to destinations. Select No End Date for an indefinite comparison of
the test segments.
Features and Tools
36
Note: Profile Merge Rules with an authenticated profile are only supported in Real-time destinations. If a
test segment with a profile merge rule of that configuration is sent to a file-based server-to-server destination,
the audiences might not populate.
Click Next to review and finalize your test group.
7. Summary & Finalize
•
•
Review the information you added in the previous steps and select Finalize Group.
Remember that once you finalize a test group, it can be duplicated or deleted, but not edited.
Note:
• You can save the test groups at any point in the creation process and return to the wizard at a later time.
The test group status will be Draft and the test group will not send any data to destinations until you
finalize the segment test group.
• For draft tests, you can go back and edit the test groups by clicking Edit in the test group card in the main
Audience Lab view.
Edit Segment Test Groups
This procedure describes how to edit a test group. In Audience Lab, you are only able to edit draft test groups. In
the Create Segment Test Groups wizard, you can save your test group as a draft and resume working on it later.
1. Navigate to the Audience Lab main view.
2. Search for your draft test groups and select the Edit control in the test group card.
3. Resume the Create Segment Test Groups wizard and select Finalize Group when you're done.
Delete Segment Test Groups
This procedure describes how to delete a test group.
1. Navigate to the Audience Lab main view.
2. Find the test group you want to delete. You can either:
•
•
press the Delete control in the test group card, or
press the test group title in the test group card to go to the Test Group Information view and press the Delete
control in the title bar.
3. For completed test segments, an alert will prompt you to download the CSV file to save the reporting if you wish.
Test Group Information
This section displays general information on the test group and the test segments it is divided into, the selected
conversion traits and mapped destinations. The section also provides controls for duplicating or deleting the test
group.
The page displays information on the baseline segment you used for the test group and how the test segments are
divided.
The Test Segments are populated randomly with users from the baseline segment you used for the test group. The
overview shows the percentages of users you allotted to each test segment.
Features and Tools
37
The Conversion Traits drive the reporting for the test groups. To designate a trait as a conversion, when creating
or editing traits in the Trait Builder, select Conversion as Event Type.
The Destinations card is collapsible. Press the arrows to open or close individual destinations and obtain the
following information for test segments, grouped by the destinations these are mapped to:
• the number of devices from the base segment's total population allocated to each destination.
• mapping key;
• mapping value;
• URL & secure URL for URL destinations.
Note: Remember that you can't edit test groups after you finalize them, you can only pause, delete or duplicate
them.
Test Group Reporting
The test group reporting section returns information on test group conversions, allowing an easy comparison of test
segment efficacy. Numerous filters and dimensions are available for data visualization.
Audience Lab returns detailed reporting information for the test segments you created and allows you to save the
reporting data as CSV files. You can select between Aggregate Reporting and Trend Reporting.
Aggregate Reporting returns the absolute numbers for your test segments. Trend Reporting returns a graph of
the trend over a specific period. Four tabs enable you to customize the reports:
Features and Tools
38
Parameter
Description
Population Conversion Rate
Returns the percentage of devices belonging to a particular test segment, which
have converted.
Converters
Returns the number of devices that have exhibited the conversion trait(s)
selected in the test groups.
Total Conversions
Returns the number of conversions generated by the test segments.
Test Segment Populations
Returns the number of devices belonging to the test segments. Toggle between
Total Population or Real-time Population. The difference is explained in the
Reporting FAQ
.
You can select a specific conversion trait for which to generate the report or you can select all traits combined. You
can define a date range for which the information should be returned and export the report as a CSV file.
Note:
• Reporting for a test group will populate the day after its start date.
• A conversion is only counted for a device after the start date of a test and after the device has been added
to a test segment. If a conversion happens for that device before it is assigned a test group, the conversion
will not be counted.
A returned Aggregate Reporting chart could look like this:
Features and Tools
39
A returned Trend Reporting chart could look like the one below. Select Normalized in the check box if you want
to ignore the absolute numbers and simply focus on the test segments trends.
Features and Tools
40
Audience Marketplace
Audience Marketplace lets data providers and buyers execute data deals in a self-service manner with minimum
effort. It does this by providing specialized features that vary depending on your role as a data buyer or data seller.
In fact, you can even be a buyer and a seller at the same time. And, if this couldn’t get any better, Audience
Marketplace takes care of contracts, billing, and payments between data providers and sellers.
Talk to your Audience Manager sales specialist to get started. They can activate Audience Marketplace for you.
Note: User roles control what you can and cannot do in Audience Marketplace.
• Administrators can create data feeds, manage subscribers, and subscribe to data feeds.
• Users can search and view feeds only.
Audience Marketplace for Data Providers
Overview and workflow for data providers who want to sell data from within Audience Manager.
Features and Tools
41
Note: Role-based permissions control access to Audience Marketplace features.
My Shared Data: About
My Shared Data is an Audience Marketplace feature for data providers (sellers). As a provider, it lets you bundle
traits into data feeds and sell them for a flat fee or CPM rate to buyers from within Audience Manager. When activated,
buyers can subscribe to a feed with a few mouse clicks. Furthermore, simple reporting tools track revenue and
manage subscribers. Finally, with Audience Marketplace, Adobe takes care of invoice, billing, and fee payments for
you. These features let you concentrate on building the effective and profitable data feeds that buyers want.
Features include:
• Search: A search fields helps you find data feeds by name or text descriptions.
• Name: The name of your data feed. You can hide this from buyers with a private, unbranded data feed.
• Description: Tell buyers about the contents of your data feed.
• Traits: The number of traits in each data feed. You can hide this from buyers with a private data feed.
• Last 30 Day Uniques: The number of unique users seen in the last 30 days. You can hide this from buyers with
a private data feed.
• Last Month's Total Fees: The amount subscribed data buyers owe you. The reporting period ends on the 10th
of each month. Overdue accounts get flagged with the triangle/exclamation mark icon. You can deactivate a
subscriber's data feed if they misuse your data or if their account is overdue.
• Status: Shows if a feed is active, inactive, private, or public.
• Subscribers: Shows how many buyers are using a data feed. Click the number in this column to see a buyer's
company name, subscriptions, billing, and subscription status.
• Requests: The number of access requests for a data feed.
Private Data Feeds
In My Shared Data, sometimes a feed status is marked as private. This indicates a private data feed. A private data
feed lets sellers limit buyer access to their data and even the name of the data feed. Sellers can make feeds private
when they're offering special deals, discounts, or when privacy and access control are important. With private data
feeds, providers review and approve all buyer access requests. For more information, see Private Data Feeds. To
create a public or private data feed, see Create a Public or Private Data Feed.
Features and Tools
42
Create a Public or Private Data Feed
A data feed requires a name, description, data source, and a plan type. Feeds are disabled until you save and
activate the feed. Set up public or private data feeds in Audience Marketplace > My Shared Data. Available to
data sellers only.
You must have administrator rights to create a public or private data feed.
To create a data feed:
1. Click New Data Feed.
2. Name the data feed.
Data buyers can search for your feed based on the name.
3. Provide a brief description (255 characters maximum).
A good description should describe your feed accurately. For example, you could include text for marketing
categories, demographics, and geographic coverage (e.g., "US" or "North America). Description text is searchable
and helps buyers find or evaluate your feed. A good description is an important part of attracting subscribers to
your data feed.
4. Select a data source from the Data Source options.
5. In Plan Types, select the options you want to use and click Add Plan.
Feeds can contain multiple plans. Plans can contain multiple use cases. For details, see Plan Types for Data
Feeds.
6. Click Save to save your data fee without activating it.
7. To save and activate a data feed:
a) Move the Availability slider to Active.
b) Click Save.
Note:
• Saved and activated data feeds cannot be deleted.
• Buyers see active feeds only.
Optional: Create a Private Data Feed
In the Settings section, move the slider to:
• Private and Branded: The buyer's Marketplace list shows the seller's name in the provider column and all other
data is hidden.
• Private and Unbranded: The buyer's Marketplace list shows the data feed name and description only. The data
provider name appears as "Private Seller."
To see what a private feed looks like to buyers, see the buyers section in Private Data Feeds.
Plan Types for Data Feeds
Plan types are essential components in an Audience Marketplace data feed. As a data provider, they let you create
multiple use cases and price options for your feeds. Furthermore, it can be a good strategy to create a few plans
for each data feed. This gives buyers different options to choose from when they're looking for data to model or send
to a destination.
Create a data feed to select Plan Types.
Features and Tools
43
Plan Types and Use Case Options
The Use Case settings let sellers control how buyers can use your data.
Segments and Overlap
A Segments and Overlap use case creates a plan that lets buyers compare trait data in atrait-to-trait overlap report.
Furthermore, buyers can add your data to segments and make comparisons with thesegment-to-trait and
segment-to-segment reports.
Each Data Feed must include at least 1 Segments and Overlap use case. Buyers cannot subscribe to other plans
in a Data Feed if the feed does not contain a Segments and Overlap use case, either by itself or in combination with
another use case.
Overlap comparisons can help buyers:
• Extend audience reach: Low overlap suggest your traits contain users the buyer has not seen before. As a result,
buyers may want these traits to add new users to their audience segments.
• Enhance existing audiences: High overlap suggests your traits contain users similar to those a buyer already
knows about. As a result, buyers may want these traits to help make targeted, incremental improvements to
developed audiences.
Price this use case as follows:
• Unit of Measure: Flat fee
• Price: Free ($0.00)
Modeling
A Modeling use case creates a plan that lets buyers compare your traits to theirs with algorithmic modeling. Buyers
look at the model results to find new audiences in your data that share similar conversion attributes to their own.
Price this use case as follows:
• Unit of Measure: Flat fee
• Price: Discounted or market rate price
Activation
An Activation use case lets buyers send data to adestination. With this use case, buyers cannot compare data with
an overlap report or in an algorithmic model. Price this use case as follows:
• Unit of Measure: CPM
• Price: CPM market rate
Features and Tools
44
Billing and Price Options
The billing and price options control how buyers pay for your data.
Option
Description
Billing Cycle
Monthly in Arrears is the only option. The billing cycle
ends on the 10th day of each month.
Unit of Measure
Charge data buyers on a CPM rate or flat fee.
• With CPM pricing, data buyers are required to self-report
usage.
• Wit flat fee pricing, data buyers do not report usage
because they're charged a fixed rate.
Price
The amount a seller charges the buyer as CPM rate or
flat fee price, in dollars.
Plan Notes
In the Additional Notes field, take some time to describe each data plan in a feed. A good, brief description helps
buyers understand the content or purpose of each plan in a data feed. Buyers can read data feed and plan descriptions
as they search for or evaluate new data sources.
Review, Approve, or Reject Private Feed Requests
Provider workflows for managing private feed requests from buyers.
To review, approve, or reject buyer requests, go to My Shared Data and:
1. Click the name of the private data feed.
2. Click Access Requests to review all the buyers who want access to your data feed.
3. In the Allow Access section of each request box, click the check mark to approve a request or the X to deny
access.
4. Confirm or cancel your selected action in the confirmation pop up.
Deactivate a Subscriber's Data Feed
As an Audience Marketplace Data Provider, you can revoke buyer access to a subscribed Data Feed. You may
want to remove a buyer from a feed for reasons such as late payment / non-payment of fees or if they use trait data
improperly.
To revoke a subscriber:
1. In My Shared Data, find the feed the subscriber is using.
Note: Data feeds with overdue accounts are flagged with a triangle/exclamation mark icon.
2. In the Subscribers column, click the blue number that counts subscribers for that feed.
This opens the subscription details page.
3. Move the Subscription slider to Off.
This opens a confirmation dialog window.
Features and Tools
45
4. In the Confirmation pop, click Yes to deactivate a subscription or Cancel to quit without making subscription
changes.
What Happens After You Deactivate a Subscriber
Revoking access to a Data Feed sends a notification email to all administrator users in the Data Buyer's account.
The email includes an attachment that lists revoked traits. This list helps subscribers find and remove deactivated
traits from their segments and models.
Billing and Feed Deactivation
After you remove access to a data feed, subscribers are responsible for fees for previous or current month, depending
on when you deactivated the feed.
Discounts for Data Providers
In Audience Marketplace, discounts let you reduce the published price of a data feed for individual subscribers.
You can offer discounts to subscribers who have submitted a subscription request or to subscribers who have
requested details about a data feed. Discounts apply to CPM and flat rate feeds. Discounts can be helpful when you
want to provide subscription incentives for new customers or to reward customer loyalty.
Apply Discounts to a Data Feed
To discount a feed, add a discount amount as a % to the discount field and confirm your changes. Data providers
can discount a data feeds in Audience Marketplace from either:
• My Shared Data > Potential Subscribers
• My Shared Data > Details Requests
In these examples, the seller has added 10% discount to the Software Audience data feed.
Features and Tools
46
Review Discounted Feeds
Data providers can see all of their subscribers and discounted feeds in Audience Marketplace > My Shared Data
> Current Subscribers.
Understanding the Data Provider Billing Report
Generate an Audience Marketplace billing report to view data feed usage for the previous month for each of your
subscribers. You can create a report for the previous month at any time. However, the report is more accurate when
you generate it on or after the 10th day of the current month.
Download a Billing Report
To download a report:
1. Go to Audience Marketplace > Receivables.
2. Click Generate Billing Report.
Features and Tools
47
Report Fields Defined
A billing report contains the following information.
Report Field
Description
Data Provider PID
Your Audience Manager data provider ID.
Data Provider Name
Your company or organization name.
Buyer PID
Buyer (subscriber) ID.
Buyer Name
The buyer's company or organization name.
Feed ID
The ID of the data feed
Feed Name
The name of the data feed.
Plan Use Cases
Use cases let sellers control how buyers use data. Options include:
• Segments and overlap
• Modeling
• Activation
See Plan Types for Data Feeds.
Unit of Measure
Indicates CPM or flat fee billing.
List Price
The subscription fee for each data feed.
Discounted Price
The subscription fee for a discounted data feed. See Discounts for Data Providers .
Units
Varies by feed price type:
• Flat fee data feeds: Returns 1 only.
• CPM data feeds: Returns the actual usage amount for CPM data feeds. If a subscriber
has not provided impression data for a CPM feed, the Units cell is empty and the
Flag cell is set to 1.
Total Cost
The amount Audience Manager bills a buyer.
Billing Period
In the report, this is the last day of the previous month.
Entry Date
The date a buyer entered subscription / usage information.
Subscription Start Date
The date a buyer started their data feed subscription.
Subscription End Date
The date a buyer ended their data feed subscription.
Features and Tools
48
Report Field
Description
Flag
For CPM feeds only. Flag options include:
• 0: Indicates a subscriber has reported usage information to Audience Manager.
• 1: Indicates a subscriber has not reported usage information to Audience Manager.
Audience Marketplace for Data Buyers
Overview and workflow for data buyers who want to purchase third-party data from within Audience Manager
Note: Role-based permissions control access to Audience Marketplace features.
The Marketplace: About
The Marketplace is an Audience Marketplace feature for data buyers that lists data feeds you can subscribe to. It
lists flat rate, CPM, or private data feeds. These feeds are provided by third-party vendors that use Audience Manager
to sell data. In the Marketplace, reporting tools let you track feed usage and the overlap between your traits and
those in a subscribed data feed. Finally, with Audience Marketplace, Adobe takes care of invoices and fee payments
(though you do have to self-report usage when subscribed to a CPM feed). These features let you find effective data
sources without wasting time looking for a data provider.
The Marketplace list contains information that you can sort and search to find the data feed that's right for you.
Items in the Marketplace buyer's list include:
• Search: Find data feeds by name or text description.
• Name: Name of the data feed.
• Description: Information about the contents of a data feed.
• Provider: Name of the data provider.
• Traits: The number of traits in a data feed.
• Unique Profiles per Month: The number of unique users seen in the last 30 days.
Features and Tools
49
• Overlapped Profiles per Month: The % of users in your segments that overlap with users in the provider's
segments.
• Private Feeds: See Private Data Feeds
• Currently Subscribed: The number of subscriptions you have with a data provider.
Private Data Feeds
In the Marketplace list, sometimes the provider's name and trait data are market as private. This indicates a private
data feed. A private data feed lets sellers limit buyer access to their data. Sellers can make feeds private when
they're offering special deals, discounts, or when privacy and access control are important to them. As a buyer, you
have to send a subscription request to the seller if you want access to a private feed. See Subscribe to a Private
Data Feed for details.
Understanding the Plan Details Page in Audience Marketplace
As an data buyer, you can click the name of a data plan in the Marketplace to see information about your subscription.
The details page shows you provider information, plan use cases, billing amounts, subscription controls, and a Venn
diagram with trait overlap data for the last 30-days.
Understanding Data Feed Use Cases
As an Audience Marketplace data buyer, you can purchase data for overlap, modeling, and activation use cases.
Each use case is designed for a specific purpose and limits what you can do with the data.These use case descriptions
can help you make the right decision about which type of data plan to buy.
Make Comparisons with Segments and Overlap Plans
Segments and Overlap
This use case lets you compare your traits with provider traits in atrait-to-trait overlap report. Also, you can create
or add provider traits to a segment and make additional comparisons with the segment-to-trait andsegment-to-segment
reports. Overlap comparisons can help you:
Features and Tools
50
• Extend audience reach: Low overlap suggests your traits contain users you have not seen before. You may want
these traits to try and reach new users.
• Enhance existing audiences: High overlap suggests your traits are similar to those owned by the data provider.
You may want these traits to help make targeted, incremental improvements to an already developed audience.
Algorithmic Models
This use case lets you evaluate supplier traits against your traits with algorithmic modeling. For example, our
algorithmic modeling system uses one of your traits as a basis for comparison against a supplier trait. When the
model runs, it can show if audiences in supplier traits share similar conversion attributes to your traits.
Activation
This use case lets you send data to a destination. In Audience Manager, a destination is any third-party system
(ad server, DSP, DMP, exchange, etc.) that you want to share data with. However, with an Activation use case,
you cannot run overlap reports or test the data in an algorithmic model.
Subscribe to a Public Data Feed
Buyers subscribe to public data feeds and plans in Audience Marketplace > Marketplace. You can also follow
these steps for a private data feed after you're approved by the seller.
To subscribe to a public data feed:
1.
2.
3.
4.
Click the data feed name in the Marketplace.
In the Use Case section find the plan you want to use and move the Subscription slider to On.
Click Review and Subscribe.
In the terms and conditions pop, click the check box and the click Ok.
Subscribe to a Private Data Feed
Buyers subscribe to private data feeds and plans in Audience Marketplace > Marketplace.
Tip: Sometimes data providers may offer a discount on a private data feed. You might want to ask about a
possible discount when submitting your subscription request.
To subscribe to a private data feed:
1. Click the data feed name in the Marketplace.
2. Click Request Access.
This opens the request dialog box.
3. In the request dialog box, write the provider a note expressing your interest in their data feed and click Send.
The seller will review your message and approve or reject your request. While waiting for approval, "Requested"
appears in the Marketplace list for that data feed.
•
•
Request approved: The status in the Marketplace list changes to "Access Granted" and you'll receive an
automated notification. At this point you can subscribe to the feed. See Subscribe to a Public Data Feed for
instructions.
Request denied: The "Requested" text is removed from the Marketplace list for the feed. You can try to
subscribe again or choose a different feed.
Unsubscribe from a Data Feed
Data buyers unsubscribe from data feeds and plans in Audience Marketplace > Marketplace.
Features and Tools
51
To unsubscribe from a data feed:
1. Click the data feed name in the Marketplace.
2. In the Use Case section find the plan you want to use and move the Subscription slider to Off.
What Happens After a Provider Deactivates My Data Feed
In Audience Marketplace, Data Providers can revoke access to the data feeds that you subscribe to. A Data Provider
may deactivate a feed for reasons such as late payment / non-payment of fees or if you use trait data improperly.
When a Data Provider revokes access to a Data Feed, this action sends a notification email to all administrator
users in the Data Buyer's account. The email includes an attachment that lists all of the revoked traits. As a Data
Buyer, you should review this attachment. It will help you find and remove revoked traits from your segments and
models.
Deactivated Trait List
The list that accompanies a deactivation email contains the fields shown in the table below.
Field
Description
Data Feed ID
ID of the deactivated data feed.
Data Feed Name
Name of the deactivated data feed.
Trait SID
Deactivated trait IDs.
Trait Name
Deactivated trait names.
Segment SID
ID of the segment that contains deactivated traits.
Segment Name
Name of the segment that contains deactivated traits.
Algo Model ID
The ID of the algorithmic model that contain deactivated traits.
Algo Model Name
The names of algorithmic models that contain deactivated traits.
Billing and Impression Allocation for CPM Data Feeds
In Audience Marketplace you must manually submit impression amounts each month. Also, if you build segments
from data feed traits, impressions must be allocated proportionally according to the qualification rules you apply to
those traits in Segment Builder.
Contents:
Billing Summary
Assign Impressions Based on Trait Qualification Rules or Type
Billing Examples
Features and Tools
52
Billing Summary
th
For a CPM data feed, you must submit impression amounts by the 5 day of each calendar month. To do this
properly, you must:
• Compile all advertising impressions delivered for each feed in the previous calendar month.
• Report CPM usage in Audience Marketplace > Payables. See How to Report CPM Usage for instructions.
After you report CPM number for the previous calendar month, Adobe will do the following:
• Create an invoice and bill you based on the CPM rate for each subscribed data feed.
• Pay data providers (sellers) fees owed based on your reported CPM use.
Important: As a buyer, all reported impression totals must be true and accurate. If you fail to report impression
th
totals by the 5 day of each month, you must include totals for the unreported month in the following month.
Assign Impressions Based on Trait Qualification Rules or Type
The Activation use case lets you use traits in the corresponding Data Feed to create segments in Segment Builder
and map those segments to a destination. The Boolean operators AND, OR, and NOT let you set the conditions for
trait and segment qualification. For billing purposes, you must allocate impression proportionally for segments that
use data feed traits. Proportional distribution depends on the Boolean operators you use to create qualification rules.
The following table lists how to properly allocate impressions by Boolean rule or trait type.
Rule Qualification
Logic or Type
Billing Distribution
AND
Apply 100% of the delivered impression totals to all the provider feeds in a rules-based
segment that uses a Boolean AND condition.
OR
Apply 75% of the delivered impression totals to all of the providers feeds in a rules-based
segment that uses a Boolean OR condition.
NOT
Apply 100% of the delivered impression totals to all the provider feeds in a rules-based
segment that uses a Boolean NOT condition.
Algorithmic segments Apply 100% of the delivered impression totals to all the provider feeds in an algorithmic
segment.
Billing Examples
These example can help you understand how to allocate impressions when you create segments from traits in a
data feed. For simplicity, each example assumes 100 impressions for a one month billing period.
Case 1: Segments With AND Qualification Rules
This segment contains 2 traits from separate data providers. Because segment qualification is based on an AND
condition, visitors have to realize the traits from both feeds to qualify for the segment.
Features and Tools
53
With an AND condition, you must assign 100% of the impressions received during the month to both data providers.
In the Audience MarketplacePayables section, you credit each provider with 100 impressions.
This example applies to segments that use Boolean NOT operators or for segments that contain algorithmic traits.
Case 2: Segments With OR Qualification Rules
This segment contains 2 traits from separate data providers. Because segment qualification is based on an OR
condition, visitors have to realize either Trait 1 or Trait 2 to qualify for the segment.
We cannot tell which trait is responsible for an impression because qualification is based on an OR condition. As a
result, in the Audience MarketplacePayables section you credit each provider with 75% of the total impressions.
Features and Tools
54
Case 3: Single Segment With Multiple Traits
In this example, we have a single segment that contains 2 traits from separate data providers. Segment qualification
in this case is based on an implied Boolean OR condition. The OR is not set explicitly by a menu option selection
when you create the segment. Because segment qualification is an implied OR condition, visitors have to realize
either Trait 1 or Trait 2 to qualify for the segment.
The bill result in this case is identical to example 2 above. We cannot tell which trait is responsible for an impression
because qualification is based on an implied OR condition. As a result, in the Audience MarketplacePayables
section you credit each provider with 75% of the total impressions.
Billing and Impression Allocation for Flat Fee Data Feeds
A flat fee data feed bills you a fixed amount each month, regardless of when the subscription starts or how many
impressions you use. Fees are not prorated for partial month usage or intervals. As with CPM billing, Adobe will
generate an invoice and bill you at the monthly, flat fee rate for your subscribed data feeds.
Features and Tools
55
For example, let's say you decided to turn on certain traits in a feed in the middle of the month. You will still be billed
at the full, monthly rate regardless of when you started the subscription or activated specific traits.
Discounts for Data Buyers
In Audience Marketplace, providers can offer buyers a discount on the published price of a CPM or flat rate data
feed. However, discount amounts aren't visible to buyers in the Marketplace feed list. But, you can also ask for a
discount when you subscribe to a private data feed or when requesting more information about a particular feed.
Request a Discount
Buyer Status
Description
Current Subscribers
If you're already subscribed to a private data feed and want to request a discount:
1. Unsubscribe from the data feed.
2. Contact the data provider and request a discounted price.
st
3. If the provider gives you a discount, re-subscribe to the feed on the 1 day of
the next month.
New Private Data Feed
Subscribers
Ask for a discount in your subscription request. See Subscribe to a Private Data
Feed.
Potential Subscribers
A potential subscriber is a data buyer who has requested access to a private data
feed, received seller approval, but has not subscribed to the feed. To request a
discount as a potential subscriber:
1. Go to Audience Marketplace > Marketplace.
2. Click the name of the feed you've been approved for.
3. Click Request More Details. Ask for a discount in your details request to the
seller.
Review Discounted Feeds
To review your discounted feeds:
1. Go to Audience Marketplace > Marketplace.
2. Click the name of a feed you're already subscribed to.
3. Look at the Price and Your Price columns in the Plan Details table. If the feed is discounted:
• The original price is marked with a red line.
• The fee in the Your Price column will be lower than the fee in the Price column.
In the example, the buyer gets a 10% discount on the Segments and Overlap plan in the Software Audience Feed.
Features and Tools
56
How to Report CPM Usage
Audience Marketplace data buyers agree to report all ad impressions served using traits contained in the data feed
th
priced on a cost per thousand ad impressions (CPM) basis. CPM usage is due on the 5 day of each calendar
month and includes data for previous month. Flat fee subscribers do not need to report usage.
To report CPM usage:
1. Go to Audience Marketplace > Payables.
2. Enter the CPM usage amount in the Usage column and click Submit.
3. Review the usage in the confirmation window and click Yes.
An Important Note About Entering CPM Usage
When entering ad impression totals in the Usage column (CPM plans only), please enter the total number of ad
impressions allocated for the Feed in units of one. Do not enter the total number of ad impressions allocated for the
Feed in units of a thousand (000). For example, if 1,234,567 ad impressions are allocated to this Feed then enter
1,234,567. Do not enter 1,234.6.
The totals required in the Usage column are advertising impressions delivered using Traits from the noted Feed as
a targeting criteria. Traits used to optimize your web or app content (Content Optimization) using tools such as
Adobe Target do not contribute to the Usage totals for CPM Plans. Data providers are typically compensated for
Content Optimization using flat fee plans.
See Billing and Impression Allocation for CPM Data Feeds for more information.
Private Data Feeds
A private data feed is an option that lets providers limit buyer access to their data. Data providers and buyers should
review this information before creating and subscribing to private data feeds.
Contents:
Private Data Feeds for Providers
Features and Tools
57
Private Data Feeds for Buyers
Private Data Feeds for Providers
As a provider, your data feeds can be public or private. A private data feed lets you limit buyer access to your data,
including the name of the data seller. You may want to create a private data feed to offer special deals, discounts,
or when privacy and access control are important. With a private data feed, you get to review and approve buyer
requests. After you approve a request, the feed looks just like a public data feed to the buyer. You can view and
manage all your feeds in Audience Marketplace > My Shared Data. As shown below, this type of feed is marked
"Private" in the status column.
Managing Feed Requests
Clicking the name of a private data feed from My Shared Data takes you to a page that contains several tabs. Click
a tab to manage your private data feed requests.
The following table defines the role or functions provided by each action tab.
Tab
Description
Current Subscribers
Lists approved buyers who have subscribed to a private data feed.
Potential Subscribers
Lists approved buyers who have not subscribed to a private data feed.
An approval lets buyers view a data feed as if it were public. This gives them a chance
to review and evaluate your feeds before subscribing. You can also offer discounts
on data feeds to buyers listed as potential subscribers. Once the buyer subscribes,
their profile moves to Current Subscribers.
Access Requests
Lists new subscription requests for a private data feed. Click this tab to review,
approve, or reject buyer requests.
• Approved buyers move to Potential Subscribers.
Features and Tools
Tab
58
Description
• Rejected buyers move to Denied Access.
Details Requests
Lists approved buyers who have not yet subscribed to a data feed and have requested
more information about your feeds.
An approval lets buyers view a data feed as if it were public. This gives them a chance
to review and evaluate your feeds before subscribing. You can also offer discounts
on data feeds to buyers requesting access. Responding to a details request removes
the buyer profile from this tab. If they haven't subscribed, the buyer profile is still in
Potential Subscribers.
Denied Access
Lists rejected subscription requests for a private data feed.
To re-approve denied buyers, change the Rejection Status to Allow. This moves
the buyer to Potential Subscribers.
Next Steps
The following documentation can help you get started with private data feeds.
• Create a Public or Private Data Feed
• Review, Approve, or Reject Private Feed Requests
• Private Data Feeds for Buyers
Private Data Feeds for Buyers
As a buyer, private data feeds appear in the Marketplace like any other offer. However, in this case, the feed list
does not show summary information for traits, unique users, and user overlap. Also, the data seller has an option
to show or hide their name in the Provider column of the Marketplace list. After the seller approves your subscription
request, all the data in a private feed becomes available to you (it works just like a public feed). The Marketplace
example below lists the 3 different feed types available to you as a buyer.
Feed types include:
The table describes how these different feed types show or hide data.
Features and Tools
59
Feed Type
Description
Public
The provider's name, trait, and unique data appears in the list.
Private Without Branding
The provider's name is set to "Private Seller," and you cannot see trait counts, unique
data, and trait overlap data.
Private With Branding
The provider's name appears in the list but you cannot see trait counts, unique data,
and trait overlap data.
Next Steps
See Subscribe to a Private Data Feed to request access.
Data Export Controls
Data Export Controls prevent you from sending data to destinations when this action violates data privacy or data
use agreements.
Contents:
Overview
Controls and labels defined
Classify data and match controls to block delivery
Workflow
Overview
Data Export Controls let you classify data sources and destinations. The classifications you apply determine when
data can or cannot be exported to a destination. This feature consists of:
• Data Export Controls : When set on a data source, these controls restrict how that data source and its traits can
be used.
• Data Export Labels : When set on a destination, these labels identify how the destination uses data.
Based on the classifications applied to a data source and destination, the export controls stop you from:
• Adding traits to a segment when that segment is blocked by an export control/export label combination.
• Sending any data to a destination if that destination is blocked by an export control/export label combination.
Data Export Controls are available automatically. However, you need administrator permissions to add export controls
to a data source. Adding export labels to a destination requires administrator permissions or sufficient privileges to
create or edit a destination.
Controls and labels defined
Data Export Control provide the following categories to help you classify data sources and destinations.
Features and Tools
60
Data Export Controls for a data
source
Data Export Labels for a
destination
Description
No restriction
n/a
By default, export restrictions are not
set on new data sources and
destinations.
Cannot be tied to personally
identifiable information (PII)
Contains personally identifiable
information (PII)
When selected, you cannot:
• Add traits to segments mapped to
destinations that use PII.
• Map segments to destinations that
use PII.
This is often required by third-party
data providers and when using data
sources that contain ad/media
tracking information.
Cannot be used for on site ad
targeting
Used for on site ad targeting
destinations that customize ad
delivery based on a visitor's
web-browsing history.
customize ad delivery based on a
visitor's web-browsing history.
Cannot be used for off site ad
targeting
Used for off site ad targeting
These restrictions are used generally
with When selected, you cannot:
destinations that re-target users on
other sites.
re-target users on other sites.
Often required when working with
data from social media platforms.
Cannot be used for on site
personalization
Used for on site personalization
destinations that customize content
based on user interests or
web-browsing history.
customize content based on user
interests or web-browsing history.
Features and Tools
61
Classify data and match controls to block delivery
To block data delivery, you must classify a data source with an export control and add an export label to a destination.
If you apply export controls to a data source or destination only, this feature will not restrict data delivery. When set
on both the data source and destination, the export controls will limit the traits you can add to a segment and prevent
the segment from sending data to a destination.
Additionally, at least one export label must match an export control before data delivery restrictions take effect. For
example, say you add the PII export control to a data source. Next, you add the on-site targeting label to a destination.
In this case, export controls will not limit data delivery because the settings do not match. However, if you add the
PII export label to the destination, the export controls will work.
The following illustration maps the relationship between the data export controls and the data export labels.
Workflow
To get started, review the data source and destination documentation. These articles provide instructions about how
to add export controls and labels to your data sources and destinations.
• Create a Data Source
• Add Data Export Labels to a Destination
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.
Features and Tools
62
• Create, edit, and delete data sources.
Create a Data Source
To create a new data source, go to Manage Data > Data Sources > Add New and complete the steps for each
section described here. You must have administrator permissions to create a data source.
Data Source Details
To complete the Data Source Details section:
1. Name the data source.
2. (Optional) Describe the data source.
A concise description helps you define the role or purpose of the data source.
3. Provide an integration code. Most of the time, integration codes are optional. They are required when you want
to:
• Create a cross-device data source.
• Use the Marketing Cloud ID service.
• Work with Profile Merge Rules.
4. Choose an ID type. Options include:
• Cookie: The cookie ID that identifies a device. You would select this when your data source is a web browser
or when working with anonymous data or data that cannot be associated with a single person.
• Device Advertising ID: The mobile device identifier. Select this when your data source is a mobile device or
Internet enabled device.
• Cross Device: A customer-provided, authenticated ID. Select this when you want to create a cross-device data
source and build a Profile Merge Rule.
Features and Tools
63
Note: Selecting Device Advertising ID or Cross Device limits the inbound ID options in the Data Source
Settings section to Customer ID only.
Data Export Controls
Data Export Controls are optional classification rules you can apply to a data source and destination. They prevent
you from sending data to a destination when that action violates a data privacy or use agreement. Skip this section
if you do not use Data Export Controls.
Important: Export restrictions will not work unless you set a matching export label on a destination.
Data export options include:
• No Restriction
• Cannot be tied to personally identifiable information
• Cannot be used for on-site ad targeting
• Cannot be used for off-site ad targeting
• Cannot be used for on-site personalization
See Data Export Controls for definitions and more information.
Data Source Settings
These settings determine how a data source is identified, used, and shared. You can also enable error reporting for
inbound data files. To complete the Data Source Settings section:
1. Select a Data Source Setting check box to apply an option to your data source. Options include:
• Inbound
• Enable file error sampling for 2 weeks
• Outbound
• Share Enabled
• Unique Trait Integration Code
• Share associated visitor or device IDs wiht all platform customers
See Data Source Settings Defined for descriptions of each control.
2. Click Save.
Delete a Data Source
Delete a data source that you no longer need.
Note: You cannot delete an Active Audience or Data Source Synced Trait.
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.
Features and Tools
64
Data Source Settings Defined
When you create a data source, the options in the Data Source Settings section determine how a data source is
identified, used, or shared. You can also enable error reporting for the Onboarding Status Report in this section.
The following table lists and describes the options available in the Data Source Settings section.
Setting
Select when
Enable file error sampling
You need to troubleshoot problems with inbound file processing. This feature
generates a report that shows you file format and syntax errors. Audience Manager
cannot process improperly formatted records in your data file.
You must activate this feature manually. It runs for 14-days from the day of
activation and turns itself off automatically. And, if you need to keep checking your
files, you can turn error sampling back on as needed.
You can activate error sampling when you create create an inbound data source,
or by checking the Error Sampling check box from the Data Source Settings
section of an existing inbound data source.
Inbound
Your data source is designed to receive inbound data.
If you choose this option, select an ID type. ID options include:
• Customer ID: Identifies inbound data with a customer ID.
• Audience Manager ID: Identifies inbound data with an Audience Manager ID.
• Marketing Cloud ID: Identifies inbound data with a Marketing Cloud ID. See
Cookies and the Marketing Cloud ID.
Outbound
Your data source sends data to a destination.
Share associated visitor or
device IDs with all platform
customers
Your data source contains visitor or device IDs that can be shared across other
Marketing Cloud solutions. For more information, see the Marketing Cloud ID
service.
Share Enabled
Your data source can be shared with other partners.
Unique Trait Integration Code Your data source requires a unique segment integration code.
Declared IDs
How declared IDs work, set up procedures, code examples, and variables.
Declared ID Targeting
Exchange and synchronize user IDs with Audience Manager from devices or browsers that do not use or accept
persistent storage mechanisms, such as third-party cookies.
Features and Tools
65
• Purpose of Declared ID Targeting
• 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 Manager uses DIL to let you pass in
declared IDs on an event call. Also, a declared ID can act as a universal ID that applies to the same user across all
the solutions in the Marketing Cloud. The following table describes the ID targeting/matching process:
Process
Event Call
Match ID
Description
To work, you need DIL and the Marketing Cloud ID service code on the page. DIL gets
declared IDs from the setVisitorID function provided by the Marketing Cloud ID
service and passes that on to Audience Manager.
Audience Manager attempts to match the client and visitor ID with a corresponding ID
in our system. If a matching ID does not exist, Audience Manager 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 Manager ID.
Return ID
Subsequent Event Calls
Audience Manager writes its synchronized ID to a first-party cookie (or other addressable
storage space) in the client domain or application.
Additional event calls read the Audience Manager ID from the client's domain and send
that to Audience Manager.
To get started, you need to configure the Marketing Cloud ID service and DIL across the pages on your site that
you want to use for data collection. See dil.create and Declared ID Variables.
Opt-out Calls
The declared ID process honors site visitor preferences to opt-out of Audience Manager targeting by your website.
When Audience Manager receives an opt-out request, the DCS returns an empty JSON object instead of the Audience
Manager user ID.
Audience Manager can pass in a declared ID opt-out alongside an Audience Manager 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 Manager opts the user out from that particular region on the edge
(the opt-out does not cross DCS regions).
Features and Tools
66
Declared ID Opt-Out Examples
You can make a declared ID opt-out requests with the d_cid and d_cid_ic key-value pairs. The legacy parameters
like d_dpid and d_dpuuid still work, but are considered deprecated. See CID Replaces DPID and DPUUID . In the
examples, italics indicates a variable placeholder.
Opt-Outs With CID and CID_IC
For a description and syntax, see URL Variables and Syntax for Declared IDs.
Opt-Out Using
Code Sample
A data provider ID and user ID.
http://domain name/demoptout.jpg?d_cid=123%01987...
An integration code and user ID.
http://domain name/demoptout?d_cid_ic=456%01321...
Multiple d_cid and d_cid_ic key-value http://domain
pairs.
name/demoptout?d_cid=123%01987&d_cid_ic=456%01321...
Opt-Outs With DPID, DPUUID, and UUID (Deprecated)
These methods still work but are considered deprecated. This information is provided for legacy purposes and
reference. Legacy opt-outs include:
• 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:///demoptout.jpg?d_dpuuid=user ID&d_dpid=data provider 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 Manager checks whether the request contains an AAM UUID in the
cookie, and if it does, uses that for storing the opt-out. Otherwise, Audience Manager 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=user ID&d_dpuuid=data provider's user ID&d_dpid=data provider
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).
URL Variables and Syntax for Declared IDs
Describes the variables and event call URLs that send IDs directly to Audience Manager.
Features and Tools
67
Variables and Syntax
The following table lists the key-value pairs that pass in your Audience Manager data provider ID and user IDs or
integration codes, if used. Note, italics indicates a variable placeholder. Spaces have been added to make these
easier to read.
In each key-value pair:
• The = symbol separates the key from its related values.
• The non-printing ASCII character %01 separates the values.
Variable
Description
d_cid = data provider ID %01 Contains a data provider ID and an associated unique user ID in a single
user ID
key-value pair. d_cid replaces d_dpid and d_dpuuid, which are considered
deprecated, but still supported. See CID Replaces DPID and DPUUID.
d_cid_ic = integration code Contains an integration code and an associated unique user ID in a single
%01 user ID
key-value pair. d_cid_ic replaces d_dpid and d_dpuuid, which are deprecated,
but still supported. See CID Replaces DPID and DPUUID.
Sample Event Calls
Given these key-value pairs and their required syntax, you would make event calls as shown below.
Event Call Includes
Code Sample
A data provider ID and user http://domain name/event?d_cid=123%01987...
ID.
An integration code and user http://domain name/event?d_cid_ic=456%01321...
ID.
Multiple d_cid and
d_cid_ic key-value pairs.
http://domain name/event?d_cid=123%01987&d_cid_ic=456%01321...
Declared ID Variables
Describes the configuration variables used to pass declared IDs through DIL to Audience Manager.
DIL Uses the Visitor ID Service to Pass Declared IDs
When used with the Visitor ID Service, you no longer need to pass in a declared IDs with the deprecated dpid and
dpuuid variables. Instead, the current versions of DIL rely on the visitorService function to get the declared IDs
from the setCustomerIDs function in the Visitor ID Service. For more information, see Customer IDs and
Authentication States. You would call visitorService in DIL.createas shown below.
var vDil = DIL.create({
partner:"partner name",
visitorService:{
namespace:"INSERT-MCORG-ID-HERE"
Features and Tools
68
}
});
In the namespace key-value pair, MCORG is your Marketing Cloud Organization ID. If you don't have this ID, you can
find it in the Administration section of the Marketing Cloud dashboard. You need administrator permissions to view
this dashboard. See Administration: Core Services.
Deprecated Functions
With the latest versions of DIL (6.2+), you don't need to use these key-value pairs to pass in declared IDs. That's
because DIL now relies on the visitorService function shown in the code sample above. This function gets
declared IDs from the Visitor ID Service. However, we're referencing these variables here for historical and legacy
purposes. See the code below for an example of how to configure DIL.create to get a declared ID from the Visitor
ID Service.
The following table describes the legacy variables used by the declaredId object:
Name
Type
dpid
String
dpuuid
String
Description
Data partner ID assigned by Audience Manager.
The data provider's unique ID for the user.
dpid and dpuuid
Audience Manager compares and matches the combined dpid and dpuuid to a corresponding user ID in our system.
If an ID does not exist, Audience Manager creates a new user ID and synchronizes it to the dpid/dpuuid combination.
Once Audience Manager 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.
Call this function when you're using DIL v6.1 or earlier. However, this function has been deprecated in favor of the
new version that gets delcared IDs from the Visitor ID Service.
DIL.create({
partner : "partner name",
declaredId : {
dpuuid : <dpuuid>,
dpid : <dpid>
}
});
Note: Note, you need to programmatically develop the code that supplies the ID values for the d_dpuuid and
d_dpid keys.
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();
Features and Tools
69
Request/Response Examples
The request sends a data provider and user ID to Audience Manager:
http://my_domain.net/event?d_rtbd=json&d_cb=myCallback&key=val&d_dpuuid=1234&d_dpid=5678
The response returns the Audience Manager ID (e.g., uuid) which is written to a first-party cookie in the page domain.
myCallback({
...
"uuid":"abc123"
})
Do Not Target and Opt-Out Calls
The declared ID process honors site visitor preferences to opt-out of Audience Manager targeting by your website.
When Audience Manager receives an opt-out request, the DCS returns an empty JSON object instead of the Audience
Manager user ID.
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 Manager, 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 Manager 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.
Features and Tools
70
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
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.
Destinations
In Audience Manager, a destination is any third-party system (ad server, DSP, ad network, etc.) that you want to
share data with. Destination Builder is the tool you used to create and manage cookie, URL, or server-to-server
destinations.
Purpose and Advantages
Destinations and Destination Builder lets you create destinations and send information about segmented users to
your data partner. This 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.
Related Topics
See the following sections for more information about Destination Builder, how to create destinations, and related
reference.
How to Choose a Destination Type
Describes technical and business reasons for choosing a URL, cookie, or server-to-server destination.
Features and Tools
71
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. For example:
• URLs and cookie-based destinations work almost synchronously with user actions on a page.
• Server-to-server methods are good for building deep audience segments over time.
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 visitors only.
or cookie destination to
• Visitors must be seen
qualify user and
again to qualify for the
immediately re-target.
segment.
• Immediate data transfer is
not required.
• Collecting data to build a
large audience pool of
qualified users.
Collecting data over time
(hours or days) to use it in
a campaign set to run at a
later date.
Cookie
Server-to-server
Considerations
• Transfers data about new
and previous site visitors.
• Visitors don't have to be
seen again to qualify for
other segments.
Destination Builder
Destination Builder lets you create cookie-based or URL destinations. You cannot create server-to-server (S2S)
destinations with Destination Builder, but you can manage their segment mappings. Contact your consultant to set
up a S2S destination. Destination Builder is located in Manage Data > Destinations.
Destination Builder Settings
Destination Builder consists of the following sections and settings:
Destination Builder Purpose
Section
Basic Information
Configuration
Used to name the destination, describe it, and select destination type (URL or cookie), and
platform (all, Android, browser, or iOS).
Includes controls for:
Features and Tools
72
Destination Builder Purpose
Section
• Passing in key-value data to URL destinations.You can send data as individual or serialized
key-value pairs. For details see, Destination Serialization and Standard and Serial Key-Value
Pairs.
• Elements of a cookie destination such as 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
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 How to Choose a Destination Type for more information.
Create a Cookie Destination
A cookie destination returns and writes data to a cookie in the user's browser. The cookie contains data that can be
read by other platforms that have access to the page. Follow these instructions to create a cookie destination with
Destination Builder.
To create a new cookie destination, go to Manage Data > Destinations > Create New Destination and complete
the sections as described below.
Basic Information
This section contains fields and options that start the cookie destination creation process. To complete this section:
1. Click Basic Information to expose the controls.
2. Name the destination. Avoid abbreviations and special characters.
3. (Optional) Describe the destination. A concise description is an effective way to define or provide more information
about a destination.
4. (Optional) In the Platform list, leave the default set to All. Currently, these options don't do anything. They're
designed to support features that may be added at a later date.
5. In the Type list, click Cookie.
6. (Optional) Select an Auto-fill Destination Mapping. Options include:
• Segment ID: Automatically adds and sends the segment ID to the destination.
• Integration Code Value: Automatically adds and sends the segment integration code to the destination mapping.
The integration code is a unique identifier created and used by the customer. It is limited to 255 characters,
maximum.
Features and Tools
73
7. Click Next to go to the Configuration settings or click Data Export Labels to apply export controls to the
destination.
Data Export Labels
This section contains options that apply data export controls to a cookie destination. Skip this step if you do not use
data export controls. To complete this section:
1. Click Data Export Labels to expose the controls.
2. Select a label that corresponds to data export control applied to the destination (see Add Export Labels to a
Destination for details).
3. Click Save.
Configuration
This section contains fields and options that let you set up the cookie for your destination.
Note: Audience Manager encodes data written to the destination cookie. For example, spaces are encoded
as %20 and semicolons are encoded as %3B. To complete this section:
1. Click Configuration to expose the controls
2. Name the cookie. Avoid abbreviations and special characters.
3. Choose a data format option. These options let you choose the delimiters and separators for the key-value pairs
that send segment data to a destination. Format options include:
• Single key: Lets you set the key in a key-value pair. You'll set the value after you select a segment in the
Segment Mappings section below.
• Multi key: Lets you set the key and value for a key-value pair. You'll create the key-value pair after you select
a segment in the Segment Mappings section below.
See Standard and Serial Key-Value Pairs for more information about these data elements.
4. Click Save.
All other settings are optional. For more information about the Cookie Domain and Publish data to settings, see
Optional Settings for Cookie Destinations.
Segment Mappings
This section lets you search for and add segments to your destination. To complete this section:
1. Click Segment Mappings to expose the controls.
2. In the Search and Add Segments box, start typing the name of a segment or click Browse All Segments to
browse a list of available segments.
3. Click Add Selected Segments when you find the segment you want to use. Adding a segment opens the Edit
Mapping window.
4. In the Edit Mapping pop:
• Mapping lets you set a value for the key specified in the Configuration section above.
• Publish from lets you set start and end date for the destination. If the end date is blank, the destination never
expires.
5. Click Save.
6. Click Done.
Features and Tools
74
Create a URL Destination
A URL destination makes pixel calls from a page to your destination. Follow these instructions to create a URL
destination with Destination Builder.
To create a new URL destination, go to Manage Data > Destinations > Create New Destination and complete
the sections as described below.
Basic Information
This section contains fields and options that start the URL destination creation process. To complete this section:
1. Click Basic Information to expose the controls.
2. Name the destination. Avoid abbreviations and special characters.
3. (Optional) Describe the destination. A concise description is an effective way to define or provide more information
about a destination.
4. (Optional) In the Platform list, leave the default set to All. Currently, these options don't do anything. They're
designed to support features that may be added at a later date.
5. In the Type list, click URL.
6. (Optional) Select an Auto-fill Destination Mapping. Options include:
• Segment ID: Automatically adds and sends the segment ID to the destination.
• Integration Code Value: Automatically adds and sends the segment integration code to the destination mapping.
The integration code is a unique identifier created and used by the customer. It is limited to 255 characters,
maximum.
7. Click Next to go to the Configuration settings or click Data Export Labels to apply export controls to the
destination.
Data Export Labels
This section contains options that apply data export controls to a URL destination. Skip this step if you do not use
data export controls. To complete this section:
1. Click Data Export Labels to expose the controls.
2. Select a label that corresponds to the data export control applied to the destination (see Add Export Labels to a
Destination for details).
3. Click Save.
Configuration
This section contains options that let you set a base URL and data delimiters passed in by the URL string. This
section is optional. To complete this section:
1. Click Configuration to expose the controls.
2. (Optional) Select the Serialize check box.
This lets you send segment to a destination sequentially rather than making separate calls for each segment.
Serialization helps make data transfers efficient. Selecting this check box exposes the URL and delimiter fields.
For more information, see Standard and Serial Key-Value Pairs.
3. If you select Serialize, then you must also configure the URL and delimiter fields described below.
Features and Tools
75
Field
Description
Base URL
The base part of a standard HTTP URL that does not change. Also, you need to
place the %ALIAS%placeholder macro in the base URL.
Example: http://www.myCompany.com/?%alias%...
Secure URL
The base part of a secure HTTPS URL that does not change. Also, you need to place
the %ALIAS%placeholder macro in the base URL.
Example: http://www.myCompany.com/?%alias%...
Delimiter
The symbol that separates the segment variables in the URL string. This is usually
a comma or semi-colon. Get this information from your destination partner.
Segment Mappings
This section lets you search for and add segments to your destination. To complete this section:
1. Click Segment Mappings to expose the controls.
2. In the Search and Add Segments box, start typing the name of a segment or click Browse All Segments
Mapping window.
4. In Edit Mapping:
• Mappings: Provide the key-value pairs used by the segment.
• Start Date and End Date: Choose a start and end date for the destination. If the end date is blank, the destination
never expires.
5. Click Done.
Optional Settings for Cookie Destinations
In Destination Builder, the Configuration section contains the Cookie Domain and Publish Data To settings.
These settings let you create rules to determine if a destination sets a cookie or returns a cookie. Cookie Domain
and Publish Data To work independently of each other. You can create a cookie destination without using either of
them.
Cookie Domain: Syntax and Examples
The Cookie Domain setting lets you set cookies on a specified domain or all domains. Set only one domain for
each cookie destination. The Cookie Domain field does not:
• Require or use wildcard characters.
• Accept multiple domains.
Syntax
To set cookie on all domains, leave this field blank. This is the default setting.
To set cookies on a specific domain and sub-domains:
• Type the name of the domain in the Cookie Domain field.
Features and Tools
76
• Start the domain name with a period. For example, .somedomain.com.
• The http://www prefix is not required.
Examples
As an example, let's say we have a fictitious site called sports.com. Sports.com has domains for golf, baseball, and
football. To set a cookie in all the sports domains, you would type that in the Cookie Domain box as shown below:
This tells Audience Manager to set a cookie in any domain that contains the pattern something.sports.com.
Next, let's take a look at how this works with a set of web pages and several different domain settings. The table
below shows you if Audience Manager will set a cookie based on how the Cookie Domain option is configured.
Website
sports.com
golf.sports.com
baseball.sports.com
sports.golf.com
Cookie Domain:
.sports.com
Cookie Domain:
.golf.sports.com
Cookie Domain: Blank
Cookie Set
Cookie Set
Yes
No
Yes
Yes
Yes
Yes
Yes
No
Yes
No
No
Yes
Cookie Set
Publish Data To
The Publish Data To settings return a cookie if the domain meets the criteria set by the options you select. Options
include:
• All of our domains:(Default) Returns a cookie for any domain.
• Only the selected domains: Returns a cookie only for the domains selected in the domains list.
• All of our domains except the selected domains: Prevents selected domains from receiving a cookie. All other
domains can receive a cookie.
Add or Edit Segments for Server-to-Server Destinations
You can only add or edit segments for a server-to-server (s2s) destination. You cannot create s2s destinations with
Destination Builder. Contact your consultant to set up s2s destinations. Follow these instructions to add or edit
segments for a s2s destination.
To add or edit segment mappings for an s2s destination:
1. Go to Manage Data > Destinations and find the s2s destination you want to work with.
2. In the Action column, click the pencil icon to edit the destination.
3. In the Search and Add Segments box, start typing the name of a segment or click Browse All Segments
Features and Tools
77
Mapping window.
5. In Edit Mapping:
•
•
Mappings: Set a value for the key-value pair used by this destination.
Start Date and End Date: Choose a start and end date for the destination. If the end date is blank, the
destination never expires.
6. Click Save and then click Done.
Add Data Export Labels to a Destination
Data Export Labels work with the Export Controls you set on a data source. Data Export Labels prevent you from
adding restricted traits to a segment and from sending segment data to a destination. You can set multiple export
labels to a new or existing cookie or URL destination.
Note: To add an export label, you need administrator permissions or sufficient privileges to create or edit a
destination.
To add export labels to a destination:
1. Click Manage Data:
•
•
For new destinations: Click Create New Destination. Complete the Basic Information section before you
select a data export label. See Create a Cookie Destination or Create a URL Destination for information.
For existing destinations: Use the Search box to find your destination or scroll through the list and click on
the destination name to open it.
2. Select a Data Export Label. Leave the check boxes blank if you don't want to set any export restrictions. Export
labels include the following options:
•
•
•
•
Contains personally identifiable information
Used for on-site ad targeting
Used for off-site ad targeting
Used for on-site personalization
Important: Export restrictions will not work unless you set a matching export control on a data source.
3. Click Save.
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. See Standard and Serial Key-Value Pairs for more information.
Supported Destinations
In Audience Manager, 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 the information about macro placement from your destination partner. See Destination Macros
Defined for more information.
Features and Tools
78
Standard and Serial Key-Value Pairs
A key-value pair consists of related 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). Destination
Builder sends data formatted as key-value pairs.
Basic Key-Value Pairs
Fully formed, a basic set of key-value pair could look like these:
• gender = male
• color = green
• price > 100
Standard and Serial Key-Value Pairs
Destinations accept key-value data in standard or serialized format.
• Standard key-value pairs: Formats destination data into separate key-value pairs. Each key is stated explicitly,
even when used again to define a different value.
• Serialized key-value pairs: Condenses multiple values into a single key-value pair. In a serialized key-value pair,
a special indicator separates the values within the key-value set.
Both 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-Value Pairs
Multiple 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
Delimiters and Separators
The characters that separate values within and between keys and values are known as delimiters and separators.
These become particularly important when you send segments to a destination in a serial format. Serialization lets
you pass in multiple values with a single key and combine key-value pairs. Delimiters and separators are defined
as follows:
• Key-value separator: Separates a key and value within a key-value pair.
• Key-value delimiter: Separates sets of key-value pairs.
• Serial separator: Separates multiple values within sets of serialized key-value pairs.
Examples
With Destination Builder you can format key-value data in several different ways. Let's take a look at some examples
of each type.
Key-Value Pair Examples
Example
Description
Standard single key
X = 1 & X = 2
A simple set of key-value pairs. The example
contains these elements:
Features and Tools
Key-Value Pair Examples
79
Example
Description
• Key: X
• Values: 1, 2
• Separator: =
• Key-value delimiter: &
Multiple key-value pairs
(non-serial)
X = 1 & X = 2 & Y = 3 &
Y = 4
A set of multiple key-value pairs that pass in values
with separate key-value sets.The example contains
these elements:
• Keys: X, Y
• Values: 1, 2, 3, 4
• Separator: =
• Key-value delimiter: &
Serial single key
X = 1 ; 2 ; 3
A key-value set that passes in multiple values with
a single key. Because this key has multiple values,
it is known as a serialized key-value pair. The
example contains these elements:
• Key: X
• Values: 1, 2, 3
• Separator: =
• Serial separator: semi-colon
Multiple key-value pairs
(serial)
X = 1 ; 2 & Y = 3 ; 4
A set of multiple key-value pairs that pass in
multiple values on separate keys. The example
contains these elements:
• Keys: X, Y
• Values: 1, 2, 3, 4
• Separator: =
• Delimiter: &
• Serial separator: semi-colon
Destination Macros Defined
Describes the macros you can add to a destination URL.
When creating a URL destination, you can insert the following macros into the URL string. Check with your
data/destination partner about proper macro placement within the destination URL.
Note: Macros are optional unless indicated otherwise. Italics indicates a variable placeholder.
Features and Tools
80
Macro
Explanation
%alias%
Required.
Defines the location of the mapped segment value in a destination URL. Usually this
is the Segment ID, but could also be the integration code.
%did%
Inserts the user's Audience Manager ID into the destination URL.
%dpid_data source id%
The data source id corresponds to the identifier for a data source passed in to the
macro.
Let's look at how this works in a simple example. In this case, we have an Audience
Manager partner with the following IDs and conditions:
• Data source ID: 1
• An internal customer ID: CustomerABC
• Declared ID: The partner wants to pass in these values as the declared ID
1:CustomerABC.
To do this with the %dpid_data source id%, the Audience Manager partner would
format the macro like this:
%dpid_1%
The macro will replace 1 with CustomerABC.
%http_proto%
Detects the protocol used in the parent webpage and inserts it into the destination
URL. For example:
• if the webpage is https://aam_client.com, this macro will be replaced with
https://url-destination.com
• if the webpage is http://aam_client.com, this macro will be replaced with
http://url-destination.com
%mcid%
Inserts the Marketing Cloud ID into the destination URL.
%region%
Inserts the Data Collection Server (DCS) region into the destination URL. In order to
minimize latency, when the visitor makes an HTTP call to Audience Manager, they
are being redirected to the closest DCS datacenter. This is achieved through DNS,
which is able to detect the visitor's location and direct them to the appropriate
datacenter.
%rnd%
Performs a cache busting function by inserting a random number into the destination
URL. This prevents browsers from serving cached content.
Features and Tools
81
Macro
Explanation
%timestamp%
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.
Cache Busting with %rnd% and %timestamp%
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 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 Manager 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.
get_aamCookie Code
Code required by DART Enterprise (and other destination types) to capture the Audience Manager unique user ID
(UUID) value.
Define this function at the top of the page, ideally within the <head> code block.
<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);
}
}
}
</script>
Features and Tools
82
Profile Link
Profile Link works with cross-device data sources to identify and collect traits for authenticated site visitors. It
includes the Profile Merge Rules feature. With Profile Merge Rules you get control over the data sets used for
segmentation and can target a person accurately across multiple devices.
Contents
• Data collection and targeting with anonymous and authenticated profiles
• Advantages
• Getting started
Data collection and targeting with anonymous and authenticated profiles
Typically, audience segmentation and targeting relies on data collected from all users on a device. Data collection
and targeting based on device-level data has some disadvantages. For example, you cannot distinguish between
multiple users who share a device or accurately target users across multiple devices. Device-centered data collection
is no longer sufficient for digital marketing campaigns or cross-device targeting.
Profile Link fundamentally changes how Audience Manager collects data and segments users for targeting. It lets
you work with 2 distinct types of profiles, a device profile and an authenticated profile.
Profile type
Device profile
Description
A device profile is tied to an ID for a given device such as a cookie ID or mobile device
ID. It includes:
• Rule-based traits realized when a user is not authenticated.
• Onboarded traits tied to a device ID such as cookie-based, third-party data.
Authenticated profile
The authenticated profile is tied to a user ID passed in when a person logs in to your
site. It includes
• Rule-based traits collected across devices when a user is authenticated.
• Onboarded traits in an offline file linked to the same user ID.
Features and Tools
83
These different profiles control the data you can use for segmentation. For example, with an authenticated profile,
you can build accurate segments based on data from multiple devices for a single person. This means you can to
deliver a consistent brand experience to customers across multiple devices. Additionally, cross-device authentication
allows Audience Manager to map the different platforms a person uses for their online activities. This called the
Profile Merge Device Graph.
Advantages
With Proflie link you can:
• Target users based on authenticated profiles, anonymous profiles, or combinations of both.
• Target a specific customer across their devices.
• Build a device graph based on deterministic data.
• Fine tune the data in your segments based on different profiles.
• Gain additional insight into your audience.
Getting started
See the following sections for more information about Profile Merge Rules.
Profile Merge Rules Dashboard
Create and manage all your merge rules from the dashboard.
The Profile Merge Rules dashboard provides a unified workspace that lets you create and work with all your trait
rules. The dashboard is located at Manage Data > Profile Merge Rules. Your rules dashboard could look similar
to the example shown below.
Features and Tools
84
In this example, the dashboard contains 3 rules. When working with the dashboard and merge rules you can:
• Create up to 3 rules, maximum from your cross-device data sources. See Create a Cross-Device Data Source.
• Designate a default merge rule. Segment Builder automatically applies the default rule to any new segments you
create.
• Apply Data Export Controls to a merge rule. Data Export Controls prevent you from sending data to destinations
when that would violate data privacy or use agreements.
• Track the average number of devices for each user.
• Work with basic controls to create, edit, and delete rules. Only administrators can manage rules, but other users
can view them and apply them to segments. SeeProfile Merge Rule Options Defined and Use Cases for Merge
Rules.
Getting Started With Profile Merge Rules
To create Profile Merge Rules review and complete the steps in each of the procedures described in this section.
Create a Cross-Device Data Source
You need to create a cross-device data source to build a Profile Merge Rule. Administrator permissions are required
to create, edit, or delete a data source. All users can view and use existing Profile Merge Rules. After you add a
data source, you can build profile merge rules.
See Create a Data Source.
Create a Profile Merge Rule
You can create merge rules after setting up a cross-device data source. Administrator permissions are required to
create, edit, or delete a rule. All users can view and use existing Profile Merge Rules. You can create a maximum
of 3 rules only.
Prerequisites: You must set up a profile merge rulebefore completing these procedures.
In Manage Data > Profile Merge, click Add New Rule and:
1. Name the merge rule.
2. Describe the merge rule.
A brief description can help explain why the rule was created and what it is designed to do.
Features and Tools
85
3. Select Set as default if you want to make this the default merge rule.
New segments are associated automatically with the default Profile Merge Rule.
4. In Profile Merge Rule Setup, select an authenticated profile and device option.
These options what data Audience Manager uses for segmentation. See Profile Merge Rule Options Defined.
Note: The current and last authenticated profile options need to be paired with a cross device data source.
To create a cross device data source for a profile rule, see Create a Cross-Device Data Source.
5. In Authenticated Profile Options, select a data source (up to 3, maximum).
A cross-device data source is required if you select Current Authenticated Profiles or Last Authenticated
Profiles in the previous step.
6. Choose a data export control.
Data Export Controls prevent you from sending data to destinations when this action violates data privacy or
data use agreements.
7. Review your settings and click Save.
Next Steps
Complete the procedures described in Configure Merge Rule Code.
Configure Merge Rule Code
Follow these instructions to set up the Visitor ID Service, DIL, and mobile SDK code to work with your merge rules.
Prerequisites: You must set up a cross-device data source and profile merge rulesbefore completing these
procedures.
Contents:
• For Visitor ID Service Customers
• Legacy DIL
• Configure SDKs
For Visitor ID Service Customers
The Visitor ID Service and the latest version of DIL are recommended when working with Profile Merge Rules.
However, you don't have to use the Visitor ID Service to work with this feature. If you're just using DIL, see the
legacy DIL section below.
Configure the Set Customer ID Function
When working with the Visitor ID Service, the setCustomerIDs function passes declared IDs to Audience Manager.
To use a profile merge rule, you must modify setCustomerIDs to use the integration code specified when you
created a cross-device data source. For example, say you've created a cross-device data source with the integration
code my_datasource_ic. To pass in a declared ID, you would add the integration code to the visitor ID function as
shown in the modified code sample below.
Generic code sample
Modified code sample
visitor.setCustomerIDs({
visitor.setCustomerIDs({
"userid":{
"my_datasource_ic":{
"id":"12345",
"id":"12345",
"authState":Visitor.AuthState.AUTHENTICATED
"authState":Visitor.AuthState.AUTHENTICATED
For more information, see Create a Cross-Device Data Source and Customer IDs and Authentication States.
Features and Tools
86
Configure DIL.create function
The latest versions of DIL now automatically pick up the declared ID from the visitorService function in DIL.create
(see Declared ID Variables). Check your DIL.create function to make sure this is set up properly as shown in the
code sample below.
partner:"parnter name",
visitorService:{
namespace:"INSERT-MCORG-ID-HERE"
}
});
In the namespace key-value pair, the MCORG variable is your Marketing Cloud Organization ID. If you don't have this
ID, you can find it in the Administration section of the Marketing Cloud dashboard.You need administrator permissions
to view this dashboard. See Administration: Core Services.
Configure SDKs
See the Configure SDKs section below.
Legacy DIL
If you're not using Visitor ID Service yet, you really ought to. But, we understand that moving to new code requires
careful thought and testing. In these cases, check your DIL.create function to make sure this is set up properly as
shown in the code sample below.
DIL.create({
partner:"partner name",
declaredId:{
dpuuid:dpuuid,
dpid:dpid
}
});
For more information, see the legacy DIL section in Declared ID Variables.
Configure SDKs
See the Configure SDKs section below.
Configure SDKs
Check the methods in your SDK code that let you pass declared IDs from Android and iOS mobile devices. The
variable names for the Android and iOS code libraries are the same:
• dpid: The cross-device data source ID.
• dpuuid: The declared ID (i.e., the user ID).
Device type
Method
Android
setDpidAndDpuuid
Syntax:
public static void setDpidAndDpuuid(String dpid, String dpuuid);
Example:
AudienceManager.setDpidAndDpuuid("myDpid","myDpuuid");
Features and Tools
87
Device type
Method
iOS
audienceSetDpid:dpuuid
Syntax:
+ (void) audienceSetDpid:(NSString *)dpid
dpuuid:(NSString *)dpuuid;
Example:
[ADBMobile audienceSetDpid:@"290"
dpuuid:@"99301393923940"];
See also, Audience Manager Methods for Android and Audience Manager Methods for iOS.
Profile Merge Rule Options Defined
The merge rule options let you control the type of data Audience Manager uses for segmentation. This includes your
own first-party data that links devices or the links provided by the Adobe Marketing Cloud Device Co-op, if you
participate in that program.
Profile Merge Rule provides 3 sets of options in the setup section.
Features and Tools
88
Authenticated Options
The Authenticated Options let you select un-authenticated and authenticated users and leverage their cross-device
profile for segmentation. These options help you identify and reach specific users on a shared device.
Authenticated Option
Description
No Authenticated Profile Tells Audience Manager not to use data collected from authenticated users.
Current Authenticated
Profile
Tells Audience Manager to read and write data to the authenticated profile if a visitor
has logged in to your site.
Last Authenticated
Profile
Tells Audience Manager to read data from the authenticated profile of the user who
last logged in on the device.
When selected, Audience Manager will not write new trait data to the authenticated
profile if the user is anonymous. Upon authentication, new trait data gets written to the
user's authenticated profile.
Authenticated Profile Options
The Authenticated Profile Options list your cross-device data sources. You can select up to 3 cross-device data
sources to use with each profile rule. The Authenticated Profile Options are available when you choose Current
Authenticated Profile or Last Authenticated Profile. See also, Create a Cross-Device Data Source.
Device Options
The Device Options let you select the type of device profile used by a Profile Merge Rule. A device profile is
composed of traits collected by users as they anonymously browse the web. At a minimum, a profile merge rule
includes an authenticated option and a device option.
Device Option
Description
No Device Profile
Tells Audience Manager not to use the traits contained in the anonymous profile for
segmentation.
Current Device Profile
Tells Audience Manager to use the anonymous device profile for segmentation.
Profile Link Device Graph Tells Audience Manager to read the profiles from the last 3 devices the user has
authenticated from. This option is available when you select Current Authenticated
Profile or Last Authenticated Profile.
Adobe Device Graph
Tells Audience Manager to merge device profiles using the links provide by the
Marketing Cloud Device Co-op.
The Device Co-op is a digital cooperative where participating customers share device
link information. The Device Co-op processes this data in a device graph. A device
graph links devices together form device clusters. These links are built from probabilistic
and deterministic data. The clusters represent a group of devices used by an unknown
Features and Tools
Device Option
89
Description
person. The Device Co-op shares these clusters among its members, which helps
them deliver valuable and consistent cross-device experiences to their customers.
For more information about the Device Co-op, see the:
• Device Co-op Overview
• Membership Requirements
• Device Graph: Internal Processes and Output
Use Cases for Merge Rules
Profile Merge Rules options that let you expand audience reach or focus on specific audiences based on targeting
or prospecting goals. This section covers how to work with these options and create merge rules for individual,
household, and cross-device targeting. Currently, Profile Merge Rules work with real-time destinations only.
Tip: For definitions and descriptions of these Merge Rule settings, see Profile Merge Rule Options Defined.
Features and Tools
90
Options that focus targeting
User authentication to a website should trigger a declared ID call to Audience Manager. After this event, Audience
Manager writes trait data to (and reads from) an authenticated profile. The authenticated profile lets Audience
Manager:
• Write traits to the authenticated profile specific to a particular user.
• Identify and differentiate between multiple device users for segmentation.
Reach authenticated users
The authenticated profile options create rules let you reach users who are logged on to a website or app. For example,
a financial services company would use this option to target authenticated users with credit card upgrade offers or
specialized service offers based on income or account activity. Another example would be an airline targeting
authenticated frequent fliers with deals based on accrued mileage.
To create a rule that reaches authenticated users, select Current Authenticated Profile + No Device Profile.
These options tell your rule to use an authenticated profile only. This rule will ignore data in the anonymous device
profile.
Reach users based on previous authentication state
These options reach specific users when they're browsing but not logged on. You can do this with options that rely
on inferred user-level targeting. Inferred targeting helps you reach people who are not explicitly authenticated to
your site but may be browsing online. It works by reading (but not writing) data from the last authenticated profile.
And, to help keep the authenticated profile clean, Audience Manager writes new trait qualifications to the device
profile instead of the authenticated profile. For example, say you're a marketer that wants to test different offers with
existing customers who are not logged on to your site or app. As a marketer, you can test these ads with current,
un-authenticated customers to see which offers get the most response.
Rules that reach users based on previous authentication include:
• Last Authenticated Profiles + Current Device Profile
• Last Authenticated Profiles + Profile Merge Device Graph
Options that expand targeting
Along with rules that help reach specific customers, marketers also need rules that increase the size of data sets
available for targeting. Profile Merge lets you do this with the device profile options. The device options expand the
data set eligible for segmentation because they draw on traits realized while a user was in an unauthenticated state
on the device. For example, this could be useful when you're trying to reach everyone in a household (household-level
targeting) or all the users who share a device. A use case for these options could include advertising a family vacation
offer. In this case, you'll want to reach everyone using a device or in a household.
To create a rule that expands the targeting data set, select Current Authenticated Profiles + Current Device
Profile.
Rules that use the device graph option extend your data set even further. With the device graph option, Audience
Manager relies on the device profiles aggregated from the last 3 devices that a visitor used for authentication to your
site. The device graph rules include:
• Current Authenticated Profiles + Profile Merge Device Graph
• Last Authenticated Profiles + Profile Merge Device Graph
Tip: Create a simple rule with No Authenticated Profile + Current Device Profile when you're still developing
a strategy and are unsure about which options to choose or if your site doesn't use authentication.
Features and Tools
91
Report Metrics for Profile Merge Rules
Profile Link metrics provide data about people and devices that authenticate to your site. Reports return totals and
averages for visitor and devices. Report graphs help you visualize and compare trends. Data and graphs update
dynamically as you create a merge rule or when you click an existing rule from the Profile Merge Rules dashboard.
For members of the Adobe Marketing Cloud Device Co-op, these metrics can include Device Graph data.
Contents:
Metric Definitions
Sample Reports
Profile Link Trend Graphs
Metric Definitions
Metric
Description
Authenticated Activity Shows:
• Active people: The number of people who have authenticated to your site for the last
60-days.
• Total lifetime people: The total number of people stored in the selected authenticated
profile.
• % Active People: Shows Active People as a %.
Authenticated Activity lets you compare data sources by activity, volume, and percent.
It can help you find a data source that has a lot of people and a high percentage of active
users. Or, you may find value in comparing data sources with high proportion of active
users compared to the total audience size. For example, sometimes a data source with
low total lifetime numbers and high activity are more valuable than those with high lifetime
results and low activity numbers.
Note: The Authenticated Activity metrics contain Profile Link data only. This
report does not include Device Graph data.
Average Devices per
Person
Shows the average number of devices that are used by visitors who have authenticated
to your site for the selected data source.
Total Devices
Shows the total number of devices people have used to authenticate to your site for the
selected data source.
Total People
Shows the total number of people who have been identified deterministically for the
selected data source.
Note: Reports return data in side-by-side bar graphs when your merge rules use data from the Marketing
Cloud Device Co-op. This lets you compare your authenticated, first-party data with cross-device data provided
by the Device Co-op. Available to members of the Device Co-op only.
Features and Tools
92
Sample Reports
Standard Profile Link Report
A standard Profile Link report looks like the following example. Merge rules that use multiple data sources (up to
3, maximum) show graphs in separate tabs for each data source. This merge rule does not include Device Co-op
data.
Profile Link Report With Device Graph Data
A Profile Link report that includes Device Co-op data shows Profile Link and Device Graph data with side-by-side
bar graphs. Placing these graphs adjacent to each other lets you evaluate the benefits of using the Device Graph
compared to Profile Link by itself. Merge rules that use multiple data sources (up to 3, maximum) show graphs in
separate tabs for each data source. As a reminder, the Authenticated Activity graph and metrics do not contain
Device Graph data.
Profile Link Trend Graphs
In addition to the other data visualizations, Profile Link reports include a line graph. The line graph is designed to
show you trends over time for your profile rules. Trend graphs (and the other reports) are available when you click
a rule from the Profile Merge Rules landing page (Manage Data > Profile Merge Rules). These graphs include
Device Graph data if you're a Device Co-op member and have created a rule that uses this data. Click on a trend
line to see underlying data.
Features and Tools
93
Reports
Use the options under the Analytics menu to view the dashboard and various reports.
Individual sections describe available reports, their purposes, and typical uses. All reports are available from the
Analytics dashboard.
For information describing the time frames when Audience Manager receives information to populate reports, see
Reporting and File Transfer Time-Frame Guidelines.
Advertiser Analytics Reports
The Advertiser Analytics reports use data visualization methods to return information on the destinations in your
Audience Manager account. In each report, you can click on almost any data point to return detailed information
about that item. These reports are not available by default. Contact your Audience Manager consultant to get started.
Additional Requirements
To use the Advertiser Analytics reports, your event calls must include all of the parameters listed in the Overview
and Mappings for Metadata Files documentation. To pass the required metadata parameters to Audience Manager
see Capturing Campaign Click Data via Pixel Calls and Capturing Campaign Impression Data via Pixel Calls.
Also, if you want to use these reports to analyze your own data or data from a source that is not integrated with
Audience Manager, you need to create and upload data and metadata files for that data. For more information, see
Data Files for Advertiser Analytics Reports and Data and Metadata Files for Advertising Analytics Reports.
Role-Based Access Control (RBAC)
The type of reports which users can view depend on the RBAC group the users are assigned to. See Administration
and Create a Group for more information.
Features and Tools
94
RBAC groups must have some data sources set up in
order to view the Advertiser Analytics Reports. Your Audience Manager consultant will set up these data sources
for you. The more data sources in each RBAC user group, the more data the users will have access to. There are
three data sources your consultant will set up:
• At least one advertiser data source
• At least one brand data source
• At least one platform data source
Users that belong to more than one RBAC user group can switch between each group's view. The displayed data
will update to respect the selected group. If your company does not use RBAC, all users will have admin privileges
and access to all the data sources (conversion groups).
Conversion Groups
In the Advertiser Analytics reports, Conversion Groups are synonymous with data sources that contain at least
one conversion trait. Data sources which do not contain at least one conversion trait do not appear in the Advertiser
Analytics reports. You can view the conversion traits for conversion groups in the Reported Conversion Traits
report.
Available Reports
The available Advertiser Analytics reports are listed below:
Segment Performance
The Segment Performance report returns data in a scatter plot that shows the relationship between impressions
and clicks for your segments. Use this report to evaluate segment performance by impressions and clicks and quickly
find high performing segments in your account.
Filters and Options Narrow Scope
By default, the Segment Performance report returns data for all your segments. Sometimes the default view
generates a graph with segments crowded together in an undifferentiated mass. When segments cluster and overlap
it's hard to derive meaningful information from the results. This can happen if you have a lot of data or segments
with low impression counts and few clicks. To help you avoid this, the report includes options and a minium impression
Features and Tools
95
slider that narrow the scope of your results. These options help you reduce clutter and find high performing segments
that you might otherwise miss in a large, aggregated data set.
Tip: After you've identified high performing or other interesting segments, select those same segments in the
Segment Dashboard report for further analysis.
Drill Down into Segment-Level Data
From the default view or after filtering the results, you can click any segment to view the underlying data. This action
displays metrics that include:
• Clicks
• Impressions
• Click-through rate
• Conversions
• Conversion rate
Colors and Shapes
The Segment Performance report relies on data visualization techniques to display information.
• Color: Each segment is a shade of green from light to dark. Light green identifies segments with low conversion
rates. Dark green identifies segments with high conversion rates.
• Shape: The report displays each segment with a unique shape when you select multiple brands from the Brands
option menu.
Sample Report
Your Segment Performance report could look similar to the one below.
Features and Tools
96
Segment Dashboard
The Segment Dashboard contains the Trend Analysis, Dimension Analysis, and Scatterplot Analysis reports.
It provides an at-a-glance view of segment performance without having to switch between multiple, related reports.
It's also a powerful tool because it lets you compare specific metrics (impressions, clicks, conversions, etc.) against
other dimensions and filters. This helps provide deep insight into those combinations of brands, sites, creatives,
segments, and other elements that drive performance in your account.
Tip:
• Use the slider to filter by time interval and select other options to narrow or refine the scope of the report.
• After you've identified high performing or other interesting segments in the Segment Performance report,
evaluate them against the other metrics in the Segment Dashboard.
Sample Report
Your Segment Dashboard could look similar to the one below. Click on a data point in any of the reports to view
the underlying data.
Features and Tools
97
Optimal Frequency Report
The Optimal Frequency Report helps you discover the optimal balance between the number of served impressions
and conversions. It allows you to adjust the number of impressions you would want to display before starting to see
diminishing returns.
Conversion volume typically decreases with higher impression frequency buckets. Fewer users see the higher
number of impressions. This means those higher frequency buckets have fewer conversions. However, the overall
conversion % increases with each impression frequency bucket. More conversions are generated with each bucket,
so the sum of conversions (the numerator) approaches the total number of possible conversions (the denominator)
and therefore the % increases. The intersection of the 2 line plots provides a guide to the "optimal" impression
frequency, i.e. the optimal number of impressions that need to be served, before the customer starts to see diminishing
returns.
Sample Report
In this example, the optimal frequency is between 6 to 7 impressions, which gives you a total conversion % just
above 70%.
Features and Tools
98
Unique User Reach
The Unique User Reach report returns data in a bubble chart. Each bubble is sized in direct proportion to the number
of unique users for your selected dimension. A larger bubble indicates greater reach than a smaller bubble. The
Unique User Reach report helps you find the advertiser, brand, campaign, creative, placement, or site that provides
the broadest reach against your targeted users.
Sample Report
Your Unique User Reach report could look similar to the one below. In your report, click on a bubble to view the
underlying data.
Features and Tools
99
Reported Conversion Traits
This report shows you all the traits labeled as conversion traits for a conversion group at a certain date. Conversion
traits for conversion groups can change from reporting run to reporting run. The report displays conversion traits by
conversion group for the selected reporting date.
Sample Report
Your Reported Conversion Traits report could look similar to the one below:
Features and Tools
100
Cross Channel Conversion
The Cross Channel Conversion option in the Advertiser Analytics reports allows you to attribute offline conversions
to served online impressions or clicks.
The Cross Channel Conversion reports combine results from the DoubleClick Campaign Manager (DCM) platform
with Audience Manager conversion traits. This lets you link offline conversions to online impressions or clicks. You
can use the Cross Channel Conversion for the following reports:
• Segment Performance
• Segment Dashboard
• Optimal Frequency
To view the Cross Channel Conversion reports, select the AAM+DCM item in the Platform drop-down list.
The following table lists important considerations when setting up Cross Channel Conversion
Consideration
Description
Minimum number of
conversion traits
At least one conversion trait must be assigned to a data source
in order for the Cross Channel Conversion reports to run. See
Basic Information for Traits for more information on traits.
Features and Tools
101
Consideration
Description
Maximum number of
conversion traits
The reports pull in a maximum of 50 conversion traits from the
user. If you reach the maximum, the reports use the first 50
conversion traits based on trait ID, in ascending order.
Attribution window
The AAM+DCM attribution window is 14 days, meaning that
only conversion traits exhibited in the last two weeks are
considered.
Last-touch methodology The creative that the user has seen last before converting is the
one awarded the conversion.
Clicks versus
impressions
A click takes precedence over an impression when deciding
attribution if they occur at the exact same time. For example,
on a page where multiple creatives are displayed, the one being
clicked on is awarded the conversion.
Data recency
The reports are always calculated for data available the previous
day.
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 Manager. 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.
General Reports
A General report returns performance data on traits, segments, and destinations.
Audience Manager 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.
Features and Tools
102
The following illustration provides a high-level overview of key elements in the General report.
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.
General Reports Results Explained
The numbers in the General Reports are generated directly from our User Profile Store. The results reflect the
number of users that Audience Manager contained in the backend at the time these reporting numbers were
generated.
Features and Tools
103
• These numbers do not include visitor IDs with excessive traffic. Traffic from bots is filtered prior to reaching our
backend system. Also, some bot traffic is discarded during a weekly cleanup job run in the backend.
• If you onboard data via inbound processing keyed off the Audience Manager UUID, and these IDs include users
that are no longer active in our system, these inactive Audience Manager UUIDs never reach the User Profile Store
and are not reported.
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
• 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.
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.
Features and Tools
104
• 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.
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.
Segment Name
Name of the segment.
Clicks
Number of clicks recorded for that segment.
Features and Tools
105
Metric
Description
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.
Why don't the numbers match up between Adobe Audience Manager and Adobe Media Optimizer?
Reasons for number discrepancies include the following:
Features and Tools
106
• 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.
Features and Tools
107
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
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).
Features and Tools
108
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.
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.
Features and Tools
109
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:
Features and Tools
110
• 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)
Segment-to-Trait Data Pop Fields Defined
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:
Features and Tools
111
• 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.
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
Manager.
Unused Signals Report
Features and Tools
112
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 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
Review the report to account for different value variations for a particular signal.
Related Values to a Single Key
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 replace 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.
Note: When searching for unused values in the report, please consider the following particularity. There is a
difference in expression between the two examples below:
• T(v=1 AND NOT (a=23))
• T(v=1 AND (a!=23))
• Both examples show a trait which contains two key-value pairs v and a. The first expression translates into: the
trait contains key v with the value 1 AND NOT the key a with the value 23. The second expression contains key v
with the value 1 AND the key a with the value NOT EQUAL 23.
Features and Tools
113
• Considering the two different expressions above, let's say you search in the Unused Signals Report for the values
that get passed on key a with any value different than 23, you'll only obtain results in the first case because values
for key were not sent AT ALL. In the second case, values different than 23 were sent so key a is not unused.
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.
Daily Trait Variation Report
This report returns a list of traits with a standard deviation greater than 1.7 in either direction over the past 30 days,
and has a unique user base greater than 10,000 users. This report lets you evaluate how the number of impressions
from unique users in a trait fluctuate over time.
Standard deviation measures the amount of variation or dispersion from the mean (or average/expected value). A
low standard deviation indicates that the data points tend to be very close to the mean. A high standard deviation
indicates that the data points are spread out over a large range of values.
From the Date list, select one or more dates for your report. A color-coded bar chart displays at the bottom of the
list that provides a visual representative of the range of standard deviation for all traits across all selected dates.
The black vertical line indicates the mean.
The middle column contains a list of traits, identified by Trait ID and Trait Name. Click any trait to access a pop-up
dialog box that lets you select from the following options:
• Keep Only: Removes all other traits from the report and displays data for this trait only.
• Exclude: Removes this trait from the report and displays data for all other traits. You can exclude multiple traits.
• View Data: Lets you display data for that row. You can also download all rows as a text file.
The Standard Deviation column displays color-coded bar charts that display the standard deviation for each trait.
Red bars indicate traits with a negative standard deviation (data points tend to be below the mean). Green bars
Features and Tools
114
indicate traits with a positive standard deviation (data points tend to be above the mean). Mouse over any bar to
display a pop-up dialog box with more information and options to keep or exclude that trait and view more information.
Icons display at the bottom of the report that let you export data in various formats, revert any changes you might
have made to the report (such as excluding traits), enable or disable automatic updates, and refresh the report's
data. See Report Icons and Tools Explained.
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.
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.
Features and Tools
115
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:
• Reduce the overall amount of data returned by the reports.
• Focus on traits or segments that fall within a particular size range.
Overlap Reports: Update Schedule and Minimum Segment Size
Describes the segment size and creation time requirements required by the Overlap report update process.
Update Schedule and Requirements
Overlap reports update weekly on Sunday. 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 real-time 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).
Segment Size and/or Creation Time Affects Reporting
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.
Use Case
Description
Segment Size Too
Small
Let's say you create a segment on (or before) Thursday, but it contains less than 70,000
total real-time 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.
Segment Created Too Let's say you create a segment on Friday and it contains more than 70,000 total real-time
Late
users. This segment won't appear in the overlap reports for the next week because it was
Features and Tools
Use Case
116
Description
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.
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.
Features and Tools
117
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.
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 Manager 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
Features and Tools
118
Report data is updated weekly each Sunday. The update processes data from Saturday (the day before) back to
the previous Sunday.
Onboarding Status Report: About
The Onboarding Status Report checks success and failure rates for processing records in your inbound data
source files. This report displays data in an interactive bar chart and provides summary metrics in tabular form. And,
it includes an option that samples files for a fixed time interval and displays the most common errors for each error
type. You can find this report in Analytics > Onboarding Status Report. This report is also available when you
create an inbound data source.
Contents:
Error Reporting and Error Sampling
Error Report Bar Chart
Error Report Tables
14-Day Error Sampling Report
Related Content
Error Reporting and Error Sampling
Error reporting and error sampling are 2 separate features of the Onboarding Status report.
Feature
Description
Error Reporting Error reporting shows you the success and failure rates for the number of records processed in
an inbound data source. It returns data in an interactive, stacked bar graph and as summary
metrics in tables below the graph.
Error reporting is automatic. It runs continuously for all of your inbound data sources. It returns
data based on range of preset time intervals or a customized time interval that you set with a
calendar widget.
Error Sampling
Error sampling parses the contents of your data files and returns the 10 most common errors
for each error type. The errors in your inbound data files prevent individual records from being
processed. Use this report as a troubleshooting tool to help reduce the number of file errors and
improve processing rates.
You must activate error sampling manually. It runs for 14-days from the day of activation and
then turns itself off. You can turn error sampling back on after the 14-day interval expires. You
activate error sampling when you create an inbound data source or by checking the Error
Sampling check box from the Data Source Settings section of an existing inbound data source.
Error sampling is a computationally demanding process. As a result, it only returns first 10 errors
for each error category. It is not designed to return every error contained in an inbound data
source. These errors are a representative sample of a potentially larger group of similar errors.
Review your entire file for the types of errors this report flags, reformat the file, and send it in
again.
See Inbound Data File Contents: Syntax, Invalid Characters, Variables, and Examples for more
information about how to properly format an data file for an inbound data source.
Features and Tools
119
Error Report Bar Chart
The error report graphs the success and failure rates for record processing in a stacked bar graph as shown in the
following example. The graph is interactive. Clicking on a bar shows summary metrics for that day in a table below
the graph.
Error Report Tables
The error report displays tabular data below the bar graph. The table shows success and failure rates along with
totals and percentages.
Successful and Failed Records
This default view shows you a frequency count of the total records in your report and includes a breakdown of the
errors by error type.
Features and Tools
120
Totals & Percentages
Click Totals & Percentages to see what % of your files were processed successfully.
14-Day Error Sampling Report
With error sampling active, the report will show you the top 10 errors for each error type. Click on an error type button
at the top of the report to see each set of sampled data.
Note: The report does not highlight record errors with this current release. To find and fix file errors, you
should review the results and compare those to the specifications in the Inbound Data File Contents
documentation.
Features and Tools
121
Related Content
Create an Onboarding Status Report
A Sample Error Report returns the number records in a data source were processed successfully and how many
failed. Follow these steps to generate a Sample Error Report.
1. Go to Analytics > Onboarding Status Report. Search for a data source or choose one from the list.
2. Select a date range. Options include:
•
•
A set of fixed report intervals.
Calendar widgets that let you create a custom date range.
3. Click OK.
Onboarding Status Report Terms and Definitions
A reference guide for the labels and terms used in this report.
Term
Definition
Data Sync File Name Lists files that Audience Manager received and processed from you selected inbound data
source.
File processing will fail if the file name is formatted improperly. File name requirements vary
depending on how you send this data to Audience Manager. Delivery methods include
Amazon S3 and FTP. For instructions on how to name your files, see:
• Amazon S3 Name and File Size Requirements for Inbound Data Files
• FTP Name and File Size Requirements for Inbound Data Files
Features and Tools
122
Term
Definition
Format Errors
Lists the number of records that failed processing because they did not match the syntax
or formatting requirements. See Inbound Data File Contents: Syntax, Invalid Characters,
Variables, and Examples for information on how to format your data.
Invalid AAM ID
Lists the number of improperly formatted Audience Manager user IDs (UUID). Usually, this
indicates the IDs:
• Did not match the expected 38-digit format.
• Contain alphabetical characters. IDs should be numbers only.
No Matching AAM ID These are onboarded IDs Audience Manager cannot match to an existing ID. Onboarded
IDs can have this status when Audience Manager has not yet performed an ID sync or it
still can't match the ID even after a synch.
In the case of unmatched mobile IDs, Audience Manager will:
• Continue to store and try to synch this ID.
• Record it as a Stored Record in the report if the ID cannot be synched.
If your onboarded file contains mobile IDs, then you can treat these numbers a bit more
lightly than the other metrics. They will not affect the success and match rates for subsequent
files.
No Trait Realized
Lists traits that Audience Manager cannot match to an onboarded trait. This could be the
result of:
• Improperly formatted traits in your inbound data file. For on how to format your data file,
see Inbound Data File Contents: Syntax, Invalid Characters, Variables, and Examples.
• Traits that have not yet been defined in Audience Manager.
Percent Success
The percentage of records in your file that were stored successfully. Percent success =
records processed / number of records in a file.
Records Received
The total number of records received. In most cases, this number should match the total
number of records (lines) in your inbound data file.
Stored Records
Number of records stored successfully. However, because of file format errors, some of
these records may not be stored by Audience Manager. The number of stored records can
be less than the number of records received.
Total Realized Traits The number of traits for all users across all inbound files that get stored in the Audience
Manager platform.
Total Unused
Signals
Total number of unused signals received in the report. This total is based on the total number
of successfully stored records.
See Unused Signals Report for more information.
Features and Tools
123
Outbound History Report
View outbound batch job history information for a specified destination and time period.
1. Click Analytics > Outbound History.
2. In the Search for a Destination box, start typing and select the desired destination.
3. In the Select a Date Range box, specify the start and end dates for your report, then click Apply Date Filter.
Features and Tools
124
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 Manager 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.
Trend Reports
A Trend report returns trend data on traits and segments.
Audience Manager 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.
Features and Tools
125
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.
Features and Tools
126
3. Click the date boxes to display a calendar, then select the starting and ending dates for your report.
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 Manager 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:
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.
Features and Tools
127
• 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 Dashboard
Use the Dashboard to view information about your partners' unique visitor counts broken down by trait types and
segments for a specified time frame.
Audience Manager uses Role Based Access Control (RBAC) to extend user-group permissions to the Dashboard.
Users can see only information on the dashboard 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.
This dashboard can be used to troubleshoot data-delivery issues. For example, if you notice a dip or spike in total
unique users with the breakdown of type of unique user (rule-based vs. onboarded), you have a better starting point
to track down a potential data-delivery problem. If you notice a dip in total unique users and in onboarded unique
users, you can go to the Onboarding Status report to see if there was an issue with an inbound file.
To access the Dashboard:
1. In the Analytics menu, click Dashboard.
2. (Optional) Select the desired time frame from the last reporting date from the drop-down list (7 Days, 14 Days
(the default), 30 Day, or 60 Days).
Depending on the period selected, the delta change in the Largest Traits/Most Changed Traits and Largest
Segments/Most Changed Segments panels displays the change in unique visitors in the audience over the period
ending today vs. the prior period of the same length. For example, if you select 7 Days, the delta compares the
unique visitors over the prior seven days ending today against the unique visitors for the seven days ending
seven days ago.
Note: You can investigate a delta change that seems out of the ordinary by running a Trend report. For
example, if you see an unusually large delta change during the last seven days, you could run a Trend
report for the last 14 days (2 x 7) to better understand the numbers.
Depending on the logged-in user's permissions, the following panels display:
• Partner Uniques
• Largest Traits/Most Changed Traits
• Largest Segments/Most Changed Segments
3. (Optional) Click Normalize above any graph to show all of the data on the same scale. You can also mouse over
any data point to see more information.
Partner Uniques
Permission Required to View: View All Traits.
Features and Tools
128
This panel displays the number of unique visitors during the specified time frame. Individual, color-coded lines
represent the total number of unique visitors and the number of unique visitors captured using algorithmic, rule-based,
and onboarded traits.
Note: The total number of unique visitors represents visitors captured via rule-based or onboarded traits.
However, the total number of unique visitors does not equal the sum of unique visitors captured using the
rule-based and onboarded traits. The same unique user might be represented in either of these two trait types.
Largest Traits/Most Changed Traits
Permission Required to View: View Traits.
This panel displays the number of unique visitors captured by various traits.
Use the Show drop-down list to display information about different types of traits: All Traits, Algorithmic, Onboarded,
or Rule-Based.
This panel contains the following tabs:
Tab
Description
Largest Traits
Displays information about the number of unique visitors sorted by number (highest to
lowest) and also lists the delta change of unique visitors during the specified time frame.
Features and Tools
129
Tab
Description
Most Changed Traits
Displays information about the number of unique visitors sorted by the delta change.
Largest Segments/Most Changed Segments
Permission Required to View: View Segments.
This panel displays the number of unique visitors captured by various segments in real-time.
This panel contains the following tabs:
Tab
Description
Largest Segments
Displays information about the number of unique visitors and the delta change of unique
visitors during the specified time frame.
Most Changed
Segments
Displays information about the number of unique visitors sorted by the delta change.
Reports and Data Sampling Methodologies
Lists reports that use sampled and total data to generate results.
Reports That Use Sampled Data
The Overlap reports return data that consists of a statistically significant random sample of all available data. The
Overlap reports include:
• 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.
Features and Tools
130
• Segments: 70,000 or more real-time users over a 14-day period.
Reports That Use All Data
These report return results based on all available data. They do not contain sampled data.
• Delivery reports
• General reports for traits
• Segment Builder trend report
• Segment Builder - Total Segment Population
• Trend reports for traits
• Trait Builder Trend report
• Unused Signals report
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 Manager, 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 Manager 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.
• Monitor performance with Audience Manager reports.
Features and Tools
131
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.
Retrieving Segment Metadata
When Audience Manager sends segment information to a data partner, it identifies these objects with numeric IDs.
As a data partner, when you share this information with your customers (or work with it yourself), an actual name
and description provide a better experience for customers in reports, dashboards, or other user interfaces (UI). Data
partners can make these friendly names available to their customers with either the manual or automated methods
described in this section.
Manual method
As a data partner, you're probably used to getting audience metadata from your customers through manual processes.
This could include files attached to emails or from customers adding that data through a UI you've built and maintained
for this purpose. These process work, but they're often cumbersome, time consuming, and may require manual data
entry work. These methods are often used to help get an integration up and running quickly, but they do not provide
the best customer experience in the long run. As an alternative, you can use the Audience Manager API to get
segment metadata automatically.
Automated method
Audience Manager provides a set of REST APIs that let you retrieve segment metadata automatically. With the API,
you can create jobs that retrieve segment metadata at scheduled intervals or automatically, whenever you process
Audience Manager data and find a new segment ID. See the steps below for more information.
Step 1: Review the Audience Manager APIs
Features and Tools
132
The Getting Started section contains information about general requirements, authentication, available methods,
etc. This is a good place to begin if you haven't worked with the Audience Manager API before.
Step 2: Request OAuth2 access credentials
You need a client ID and secret to make API calls. You can obtain a client ID and secret from your integration
specialist during the integration set up process.You can also send an email request to Audience Manager Customer
Care at [email protected].
Step 3: Collect customer-specific information from each integrated customer
Request the following from each integrated customer:
• Username: This is for a restricted user that has read-only permissions for the destination associated with a specific
integration.
• Password: The user password.
• Destination ID: This is the ID (an integer) associated with the destination created for the specific server-to-server
integration.
Step 4: Retrieve segment metadata with an API call
After completing the previous steps, you can use a GET method to retrieve segment metadata. For a sample request
and response, see Return Destination Mappings. This call returns segment data formatted as key-value pairs in a
JSON object. Some of the important segment attributes returned in the response are listed in the following table.
Parameter
Description
destinationMappingId
The Audience Manager segment ID.
elementName
The segment name.
elementDescription
Some text that briefly describes the segment.
elementStatus
The current status of the segment mapping. Returned status options include:
• active
• inactive
• deleted
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.
Features and Tools
133
• 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.
• Hover over the clock icon to add recency and frequency rules to the trait.
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.
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.
Features and Tools
Field
134
Description
• 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).
• Contain many trait groups.
• Have complex qualification requirements.
Search
Estimated Historic Segment Size
Finds traits to add to a segment.
See Trait and Segment Size Data in Segment Builder.
Total Segment Population
Trait and Segment Size Data in Segment Builder
Segment Builder shows you the number of unique users in the traits that compose a segment and for the segment
itself. Segment Builder displays this information when you expand the Traits panel.
Features and Tools
135
Trait Data
Metric
Description
Last 30 Days
The number of unique users who qualified for (realized) the trait during the last 30-days.
Note: In Trait Builder, the last 30-day size/population totals can be different for
traits and real-time segments.
• For traits (as indicated above), the last 30-days metric counts the number of unique
users who qualified for that trait during the last 30-days.
• For real-time segments, the last 30-days metric counts the number of users who
have qualified for a trait at some point in the past and have been seen again by
Audience Manager within the last 30-days. For example, say you have a user who
qualified for a trait 200 days ago, but has only been seen again 10 days ago. In the
Segment Builder data, this user won't be added to the trait count because they
first qualified for the trait more than 30-days ago. However, they will be included in
the last 30-day count for the real-time segment results because they've qualified
for the segment within that time interval.
Segment Data
Metric
Description
Estimated Historic
Segment Size
The estimated number of unique users in a segment. You can use it to:
• See how many people a new or revised segment might reach over time.
• Tune the segment depending on your goals. For example, large segments are useful for
brand-awareness campaigns and smaller segments are useful for focused targeting or
re-targeting campaigns.
Real-time Segment
Population
A count of unique visitors seen in real-time for the specified time range and who were
qualified for the segment at the moment we saw them.
Note: Note, in Trait Builder, the last 30-day size/population totals can be different
for traits and real-time segments.
• For traits, the last 30-days metric counts the number of unique users who qualified
for that trait during the last 30-days.
• For real-time segments, the last 30-days metric counts the number of users who
have qualified for a trait at some point in the past and have been seen again by
Audience Manager within the last 30-days. For example, say you have a user who
qualified for a trait 200 days ago, but has only been seen again 10 days ago. In the
Segment Builder data, this user won't be added to the trait count because they
first qualified for the trait more than 30-days ago. However, they will be included in
the last 30-day count for the real-time segment results because they've qualified for
the segment within that time interval.
Features and Tools
136
Metric
Description
Total Segment
Population
A count of unique visitors who were qualified for the segment in the specified time range.
Note: The weekly data cleanup process removes inactive users from the segment.
This will cause a small reduction in the Total Segment Population metric. See Data
Retention.
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
Features and Tools
137
In the URL and Secure URL fields, specify the complete standard or secure address used to send data to the
destination.
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].
Features and Tools
138
Name or Variable
Description
<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.
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 Manager 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.
• You can configure frequency requirements without configuring recency requirements by leaving recency blank.
• Frequency-capping expressions include all the users whose number of trait realizations is below a desired value.
For example:
frequency([1000T]) <= 5
This expression includes all users that have realized the trait with the ID "1000" fewer than five times, including
users who have not realized the trait.
• 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.
Features and Tools
139
Using the above example, frequency([1000T]) <= 5, the expression becomes valid when joined with another
trait.
For example:
frequency([1000T]) <= 5 AND isSiteVisitorTrait
• For advertising frequency-capping use cases, you could create a segment rule similar to the following:
(frequency([1000T] <= 2D) >= 5)?
This expression includes all users that have realized the trait with the ID "1000" in the last 2 days more than five
times.
You can achieve the capping by sending this segment to the ad server and then include a NOT on the segment
in the ad server. This approach achieves greater performance in Audience Manager, while still serving the same
purpose for frequency capping.
• 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 Manager 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.
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.
Features and Tools
140
• 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 using an API method. For more information, see REST APIs.
Tags
Tag Insertion Manager (TIM) was used to create and manage data collection code. This feature is deprecated and
has been replaced by the Adobe Dynamic Tag Manager.
For more information, see Dynamic Tag Management.
Traits
Manage data collection and audience creation with rules-based, onboarded, or algorithmic traits.
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 columns you can sort.
2. Review and work with Active Audience Traits and Data Source Synced Traits.
3. Create, edit, and delete traits.
4. View and manage trait storage folders.
5. Search for traits by name, ID, or other associated elements.
Features and Tools
141
Active Audience Traits and Data Source Synced Traits
These are special traits used by Addressable Audiences. Active Audience and Data Source Synced Traits are
located in Manage Data > Traits > Audience Traits.
Note: Access requires administrator permissions.
Active Audience Traits
An Active Audience trait contains all of the devices under management in your Audience Manager account. You
can use an Active Audience Trait like other traits when you build or edit segments. Also, Addressable Audiences
requires this trait to generate overlap data. All accounts have an Active Audience trait by default. This trait cannot
be deleted.
Data Source Synced Traits
Data Source Synced Traits appear in the Audience Traits folder when you create or edit a datasource and apply
either of these settings:
Features and Tools
142
Data Source Synced Traits track all of the users associated with a data source. You can use a Data Source
Synched Trait like other traits when you build or edit segments. When you create a Data Source Synced Trait,
the trait name matches the name used by your data source. Edit the data source to change the trait name. These
traits cannot be deleted.
Tip: Data Source Synced Traits are useful for troubleshooting. Click a trait name to check the metrics on
the trait summary page. If your selected trait returns data, that indicates the ID synchronization process is set
up properly and pushing data to Audience Manager.
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:
• Basic Information: Shows required and optional details specified when the trait was created.
• Trait Graph: Shows trait qualifications for the last 90-days.
• For rule-based traits, trait qualification happens in real-time, as users qualify for a trait in their browser.
• For onboarded traits, trait qualification happens after an inbound file is processed.
• Trait Expression: Shows the various rules for the trait. Clicking "Edit Signal Rules" lets you manage the various
rules that the trait consists of.
• Segments with this Trait: Shows you what segments the trait belongs to.
Features and Tools
143
Trait Builder
Describes how to create rules-based, onboarded 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:
• 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 Audience Manager reports.
Create Rules-Based, Onboarded 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. The Basic Information
settings are the same for rules-based, onboarded and algorithmic traits. To create a new trait, provide a name (avoid
special characters), a data source, and select a storage folder. Other Basic Information fields are optional.
Basic Information Fields Defined
Features and Tools
144
Interface Element
Explanation
Name
The trait name. Required.
Note: When naming traits, avoid these special characters:
• Commas
• Dashes
• Hyphens
• Tabs
• Vertical bar or pipe symbol
This helps reduce processing errors when you set up an inbound data file transfer.
Description
A few words to help describe the trait's purpose or function. Optional.
Event Type
Assigns the trait to a type or category, usually according to function (e.g. conversion, 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.
Note: Traits belong to a single category only. Optional.
Create Rules-Based or Onboarded Traits
Describes set up steps and features specific to the rules-based and onboarded 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
Features and Tools
145
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 drop-down 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.
3. The test fields let you validate combinations of signal rules or the URLs that you want to use when sending data
to Audience Manager.
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 Trait Expression 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 Manager using that syntax.
2. Select a comparison operator from the Operator dropdown.
The comparison operator evaluates the relationship between the elements in a signal.
Note: The Boolean OR operator establishes the relationship between multiple signals within a group and
cannot be changed.
3. Click Add Rule.
The saved rule appears in the traits workspace above the data entry fields.
Features and Tools
146
Example
In the example below, a user has created a new trait rule based on the product ID. To build this rule, the user provided
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.
Create a New Rule Group
This procedure describes how to create a new rule group.
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 edit.
Features and Tools
147
This brings up the trait management icons.
2. Click the pencil to edit the trait.
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 Trait Builder, the Advanced Options lets you set a time-to-live (TTL) interval for a trait. TTL defines how many
days a qualified visitor remains in a trait (120 days is default). When set to 0, 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.
•
•
•
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.
Features and Tools
148
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:
• 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.
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.
Features and Tools
149
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.
Accuracy vs Reach: About
Features and Tools
150
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.
Features and Tools
151
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.
Matchesword
The values in a key-value pair match the pattern specified
by this operator.
Features and Tools
152
Operator
Evaluates to True When
Startswith
The value in a key-value pair starts with characters
specified by a regular expression.
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 with a common taxonomy.
The Audience Manager Taxonomy
The Audience Manager taxonomy is an optional feature that classifies traits using uniform, logical, and commonly
understood naming conventions. It operates at the platform level to help ensure naming consistency throughout the
Audience Manager 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 Manager 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 Manager 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 Manager 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 Data Categories
You assign taxonomic classifications when creating or editing traits in the Add New Trait Wizard (located in Manage
Data > Traits). Refer to the documentation on creating traits 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).
Features and Tools
153
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.
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.
Segment Time to Live Explained
How trait time-to-live (TTL) interval affects segment membership.
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 default TTL for new traits is 120-days. When set to 0-days, the trait never expires. 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.
Features and Tools
154
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 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 Manager TTLs are Independent of Third-Party TTL Settings
Remember, the TTL set on your Audience Manager 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 Manager. 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.
Features and Tools
155
Key variable prefix
Identifies the variable
d_
At the Audience Manager level. This data is uniform across the Audience Manager
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.
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 Manager 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 Manager 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
d_area_code
For Targeting
North America area codes.
For example:
Trait: d_area_code=801
Trait Name: Utah
Features and Tools
Key
d_city
156
For Targeting
Cities and towns. Download the City List.
For example:
Trait: d_city=bonn
Trait Name: Bonn
d_country
Values correspond to ISO country codes. For a searchable list of codes, see the ISO Online
Browsing Platform.
Targeting for the United Kingdom is the only special case that does not obey ISO 3166.
You should use "UK" instead of "GB" for targeting in the United Kingdom.
To target the Netherlands Antilles, the code "AN" has been deprecated since 2010. The
area has been dissolved into five separate territorial units. The implication is that for targeting
in the Netherlands Antilles, you should not use "AN," but a combination of the country codes
for "CW," "SX," and "BQ."
For example:
Trait: d_country=CZ
Trait Name: Czech Republic
Trait: d_country=UK
Trait Name: United Kingdom
Trait: d_country=CW OR d_country=SX OR d_country=BQ
Trait Name: Netherlands Antilles
d_dma_code
Metropolitan area DMA codes. Download the DMA region list (.csv format).
For example:
Trait: d_dma_code=807
Trait Name: San Francisco
d_lat
d_long
d_postal_code
Latitude (e.g. d_lat=40.75). Download the latitudes list.
Longitude (e.g. d_long=73.98). Download the longitudes list.
ZIP codes (exclude the extended +4 code). Download the postal codes list.
For example:
Trait: d_postal_code=84004
Trait Name: Alpine
d_state
2-character abbreviation for a US state. Download the states codes list.
Features and Tools
Key
157
For Targeting
For example:
Trait:d_state=NY
Trait Name: New York
d_region
d_isp
Regional alphanumeric IDs. Download the region list.
ISP/organization. Download the ISP List.
The list of all location-based signals comprises all the signals above, in the following order:
d_country,d_city,d_region,d_state,d_dma_code,d_postal_code,d_area_code,d_lat,d_long
Device Targeting With Platform-level Keys
Describes the common platform-level key-value pairs you can use to target users with device-related variables
across all properties in your Audience Manager account.
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 Manager account. These variables are formed by key-value pairs with the key
prefixed by d_ as shown below.
Platform-level Keys Defined by User Agent
The Data Collection Servers extract the values for these keys from the user agent header in HTTP requests. The
values represent device-level information from the Device Atlas database. The signals in the table below are available,
as extracted from the user agent example. Download a list of the most common keys, according to Device Atlas
measurements.
Signal
Type
Example
d_device_vendor
VENDOR
apple
d_device_hardware_type
HARDWARE
mobile phone
d_device_os_version
OS VERSION
5_0
d_device_os_name
OS NAME
ios
d_device_model
MODEL
iphone
d_device_marketing_name
MARKETING NAME
iphone
d_device_manufacturer
MANUFACTURER
apple
Mozilla/5.0 (iPhone; CPU iPhone OS 5_0 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko)
Version/5.1 Mobile/9A334 Safari/7534.48.3
Note: Even if one or more signals cannot be retrieved from the user agent header, the other signals will still
be passed to the Data Collection Servers.
Features and Tools
158
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
This rule establishes trait qualification requirements using Boolean OR and AND operators.
Sample code
(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
(price>== “1.00” OR price<== “100.00”)
Meet any price condition between 1.00 and 100.00.
Comparison Operators
Accepted Regular Expression Constructs
This document addresses the basic and advanced regular expressions that are supported in the Audience Manager
trait builder.
Regular Expressions
You can create your own trait rules with the Expression Builder code editor. Find the code editor in Traits > Add
New > Rule-based > Trait Expression and switch to Code View. Audience Manager supports all the available
regular expression constructs referenced in the Java Regular Expression Class Pattern. You can validate any of
the regular expressions directly in the Expression Builder.
Features and Tools
159
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. For each trait, you can view its SID, name, details about how visitor traits were realized (first- or
third-party), the realization date, and the frequency of realizations. For each segment, you can view its SID, name,
and the segment membership date. You can also view the visitor profile for another Audience Manager profile ID
(UUID). The Visitor Profile Viewer is helpful for troubleshooting purposes.
Note:
• Access requires Administrator permissions.
• There is a 12-hour delay before information about realized segments and onboarded traits appears in the
user interface.
• Traits that are not part of a segment will not appear in theVisitor Profile Viewer.
1. Click Tools > Visitor Profile Viewer.
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 Manager profile ID, then click Refresh to view the traits
and segments for that user.
API and SDK Code
160
API and SDK Code
APIs and toolkits that let you work programmatically with Audience Manager.
Note: These features are not supported by our APIs:
• General, Trend, and Interactive reports.
• Deprecated Tag Insertion Manager (TIM) functionality.
API Code Migration
API code documentation is moving to a new location. Changes apply to new and existing methods. Review this
section for more information.
Moving On Up
Here at Audience Manager, we're engineers, developers, and code ninjas just like you. And, like you, we want to
work with reliable, accurate API documentation. As a result, we're re-writing our API content and moving it to a new
Audience Manager API docs site. We think this change will help improve your experience with our code. However,
this migration is an incremental process so just a few of our REST APIs are available in the new space. You'll have
to check in both the new site and the REST APIs to find all of the available methods. Eventually, all our code will be
in one place, the Audience Manager API docs site.
What's Changed
The new documentation site contains the REST APIs listed below.
API Type
Available Methods
The Audience Marketplace APIs include methods for managing data feeds.
• Data Feed API
• Data Feed Request
• Data Feed Finance
• Data Feed Plans
• Data Feed Subscription API
Data Source
Data Source API
Reporting
Reporting API
Segments
Segment API
Segment Test Group
• Segment Test Group API
• Segment Test Group Draft API
API and SDK Code
161
Data Integration Library (DIL) API
The Audience Manager DIL API.
Understanding the Data Integration Library (DIL)
An overview of DIL and how it works.
Purpose of DIL
DIL is an API library.You can think it as a body of helper code for Adobe Audience Manager (AAM). It is not required
to use AAM, but the methods and functions DIL provides means you don't have to develop your own code to send
data to AAM. Also, DIL is different than the API provided by the Marketing Cloud ID service. That service is designed
to manage visitor identity across different Marketing Cloud solutions. By contrast, DIL is designed to:
• Make event calls and send data to the Data Collection Server.
• Send data to destinations.
Getting and Implementing DIL Code
DIL code isn't available for download. Contact your consultant to get the latest version.
Rather than work with DIL and set up AAM manually, we recommend that you use Adobe Dynamic Tag Manager
(DTM) instead. DTM is the recommended implementation tool because it simplifies code deployment, placement,
and version management.
Sample Call
DIL sends data to AAM in an event call. An event call is an XML HTTP request from your page. It uses a POST
method to send data in the body of the request.
Event Call Element Description
URL
DIL event calls use the following syntax: http://adobe.demdex.net/event?_ts = UNIX
UTC timestamp
Body
As shown in sample below, DIL passes data as key-value pairs. Special prefix characters
identify the key-value pairs as Audience Manager or partner variables.
d_dst=1
d_jsonv=1
d_ld=_ts=1473693143821
d_mid=54192285857942994142875423154873503351
d_nsid=0
d_rtbd=json
See also:
• Prefix Requirements for Key Variables
• Supported Variables
API and SDK Code
162
Class-level DIL Methods
The class-level DIL APIs let you programmatically create and work with Audience Manager 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 Manager 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.
DIL create
Creates a partner-specific DIL instance.
Function Signature: DIL.create: function (initConfig) {}
initConfig Elements
Important: The visitorService property is always required. Other properties listed here are optional, unless
indicated otherwise.
initConfig accepts the following elements:
Name
containerNSID
declaredId
Type
Description
Integer
Customer NSID. Default is 0.
Object
delcaredId is used to pass in either the:
• dpid: Data partner ID assigned to you by Audience Manager.
• dpuuid: Your unique ID for a user.
Important: Only use un-encoded values for your IDs. Encoding
will create double-encoded identifiers.
Note: If you use the Visitor ID Service, set customer IDs with
the setCustomerIDs method instead of DIL. See Customer IDs
and Authentication States.
delayAllUntilWindowLoad
Boolean
If true, defers all requests (IFRAME, event calls, ID sync, and
destinationing) from executing until the Page Load event fires. Default
is false.
API and SDK Code
Name
disableDeclaredUUIDCookie
disableDestinationPublishingIframe
disableIDSyncs
enableErrorReporting
iframeAkamaiHTTPS
mappings
partner
163
Type
Description
Boolean
False by default, which means Audience Management sets a cookie
in the partner's domain (sets a first party cookie).
Boolean
If true, will not attach the destination publishing IFRAME to the DOM
or fire destinations. Default is false.
Boolean
Disables ID synchronization. You must disable ID syncs when using
DIL v6.2+ and the Visitor ID Service. The visitorService function
(see sample code below) takes care of this operation.
Boolean
Set to true to enable error reporting for all DIL instances on the page.
Works with Boolean true only.
Boolean
Specifies if the destination publishing template should use Akamai
for HTTPS connections. Enabled on a per-partner basis.
Object
Associates the value from one key-value pair to another. See Map
Key Values to Other Keys. Released with v2.4.
String
Required.
Partner name as provided by Audience Management.
removeFinishedScriptsAndCallbacks
uuidCookie
visitorService
Boolean
Removes scripts and callbacks. Default is False. Applies to the
current DIL instance only. Released with v3.3.
Object
Sets a cookie with the unique user ID returned from Audience
Management. See uuidCookie Properties.
Object
Required with DIL 6.2 or greater.
DIL relies on the setCustomerIDs function in the Visitor ID Service
to pass declared IDs into Audience Manager. See Customer IDs and
Authentication States for more information.
Sample Code
In the sample code, the namespace key-value pair contains is your Marketing Cloud Organization ID (MCORG). If you
don't have this ID, you can find it in the Administration section of the Marketing Cloud dashboard. You need
administrator permissions to view this dashboard. See Administration: Core Services.
var partnerObject1 = DIL.create({
partner: "partner name",
visitorService:{
namespace: "INSERT-MCORG-ID-HERE"
},
containerNSID: 3,
API and SDK Code
164
uuidCookie:{
name:'ad_uuid',
days:200,
path:'/test',
domain:'adobe.com',
secure:true
}
});
var partnerObject2 = DIL.create({
partner: "partner name",
visitorService:{
},
containerNSID: 3,
disableDestinationPublishingIframe: true
});
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.
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.
Code Sample:
partner: 'demofirst',
visitorService: {
}
});
API and SDK Code
165
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.
Function Signature: isAddedPostWindowLoad: function()
Sample Code
DIL.isAddedPostWindowLoad();
API and SDK Code
166
Instance-level DIL Methods
The instance-level DIL APIs let you programmatically create and work with Audience Manager 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 Manager 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 and SDK Code
167
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
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
Sample Code
partner: 'partner',
containerNSID: NSID
});
partnerObject.api.logs({
file: 'dil.js',
API and SDK Code
168
message: 'This is the first request'
});
submit
Submits all pending data to Audience Manager 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
Sample Code
partner: 'partnerName',
});
dataLib.api.traits([123,456, 789]).logs({
file: 'dil.js',
}).signals({
c_zdid: 1111
d_dma: 'default'
}).submit();
afterResult
A function that executes after the default destination publishing callback.
Function Signature: afterResult: function (fn) {}
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
});
dataLib.api.signals({
c_zdid: 54321
d_dma: 'default'
}).afterResult(function(json){
API and SDK Code
169
//Do something with the JSON data returned from the server.
}).submit();
clearData
Clears all data in a pending request.
Function Signature: clearData: function () {}
Response
Sample Code
});
dataLib.api.traits([123,456, 789]).logs({
file: 'dil.js'
}).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) {}
Reserved Request Keys
The following request keys are reserved and cannot be overwritten by this method:
• sids
• pdata
• logdata
• callback
• postCallbackFn
• useImageRequest
Response
Sample Code
partner: 'partner',
containerNSID: NSID
API and SDK Code
});
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
});
//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
});
dataLib.api.traits([123, 456, 789]).logs({
file: 'dil.js',
});.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
partner: 'partnerName'
});
//Verify the partner name
var partner = dataLib.api.getPartner();
170
API and SDK Code
171
getState
Returns the state of the current DIL instance. Useful for debugging and troubleshooting.
Function Signature: dil.api.getState: function () {}
Sample Code
});
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
Manager.
API and SDK Code
172
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 Manager. For
example, partner x would use this to synchronize a user ID
with partner y and then send that to Audience Manager.
dil.Instance.api.aamIdSync(initConfig)
When you already know the user ID and want to send it to
Audience Manager.
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 Manager.
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 Manager 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({
API and SDK Code
173
dpid: '23', // must be a string
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.
Parameters
Name
Type
Description
callback
Function
JavaScript function executed by the JSONP callback.
Response
Sample Code
});
dataLib.api.traits([123, 456, 789]).result(function(json){
//Do something, possibly with the JSON data returned from the server.
});.submit();
secureDataCollection
secureDataCollection is a boolean parameter that controls how DIL makes calls to the Data Collection Servers
(DCS) and Akamai.
• When secureDataCollection= true (default), DIL always makes secure, HTTPS calls.
• When secureDataCollection= false, DIL makes either HTTP or HTTPS calls by following the security protocol
set by the page.
Important: Set secureDataCollection= false if you use visitorAPI.js and DIL on the same page. See the
code sample below.
var dilInstance = DIL.create({
...
secureDataCollection: false
});
useCorsOnly
useCorsOnly is a boolean true/false parameter that controls how the browser requests resources from other domains.
Overview
API and SDK Code
174
useCorsOnly is false by default. False means the browser can perform resource checks with CORS or JSONP.
However, DIL always tries to request resources with CORS first. It reverts to JSONP on older browsers that do not
support CORS. If you need to force the browser to use CORS only, such as with sites that have high-security
requirements, set useCorsOnly:true.
Code Sample
...
useCorsOnly: true
});
Important:
• We recommend that you set useCorsOnly: true only when you're sure that your site visitors have browsers
that support this feature.
• When useCorsOnly: true, DIL will not make ID calls from Internet Explorer version 9 or older.
useImageRequest
Changes the request type to image <img> from script <src>.
Function Signature: useImageRequest: function () {}
Response
Returns an API object of the current DIL instance.
Sample Code
partner:'partnerName',
});
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 Manager objects.
siteCatalyst.init
Works with DIL to send Analytics tag elements (variables, props, eVars, etc.) to Audience Manager. 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
API and SDK Code
175
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 or
later.
• filterFromContextVariables
For example, filterFromContextVariables:
['email', 'zip', 'accountNumber'] would result
in the array of strings being filtered from the data
collection of context data. This option excludes
Personally Identifiable Information (PII).
Data Captured by siteCatalyst.init
This function returns details on the following Analytics properties:
• pageName
• channel
• campaign
• products
• events
API and SDK Code
176
• 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
The GA.init() function sends data from Google Analytics to Audience Manager.
Important: GA.init() only works with Google's legacy analytics tracking code, ga.js or dc.js. You cannot
invoke this DIL function if you use analytics.js, which is the latest code library for Google Analytics.
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
API and SDK Code
177
By default, GA.init captures data from the following functions:
• _setCustomVar
• _addItem
• _addTrans
• _setAccount
• _trackSocial
DIL Creates Keys for GA Data
Audience Manager 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
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
API and SDK Code
178
'Olive Medium', // category or variation
'11.99',
// unit price - required
'1'
// quantity - required
]);
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 Manager 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 and SDK Code
179
Search Type
Description
Code Sample
Default Search
Returns keyword search terms used var results =
by the AOL, Ask, Bing, Google, and DIL.tools.getSearchReferrer();
Yahoo search engines.
Pass in a Custom
URL
Returns the search referrer based on var results =
DIL.tools.getSearchReferrer("http://www.ehow.com/
a custom URL.
Match URL
Hostname with a
Custom Regex
Pass in a custom regex to match the var results =
host name of the referring URL.
Match Search
Patterns with a
Custom Regex
Pass in a custom regex to perform a var results =
custom search.
search.aspx?q=adobe+rules");
search.aspx?q=adobe+rules",{
hostPattern:/ehow\./,
queryParam:"p"
});
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 and SDK Code
180
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
});
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 Manager with DIL
Create an object variable that sends information about page elements to Audience Manager. 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 Manager 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 Manager 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 Manager. 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"
};
API and SDK Code
181
var sample_dil = DIL.create({ partner : "partner name" });
//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 Manager.
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 Manager.
Supported Search Engines
By default, DIL.getSearchReferrer recognizes searches from these search engines (including international
variations):
• AOL
• Ask
• Bing
• Google
• Yahoo!
Description
API and SDK Code
182
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 Manager.
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 Manager.
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
Manager. 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 Manager 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 Manager
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 and SDK Code
183
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 Manager 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 Manager.
Flash DIL is an ActionScript code library that lets you work with video playback data in Audience Manager. 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 Manager.
Analytics data (Props, eVars, events, etc.) captured from the FLA file is available in Audience Manager 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.
• 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 and SDK Code
184
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.
API and SDK Code
185
Flash DIL Data in Audience Manager
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).
Match Audience Manager Traits to Analytics Variables
To use the Analytics data passed by Flash DIL, you should create Audience Manager 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 Manager 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 Manager 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 Manager 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, defaults to 0
s.loadModule(d);
Tag Manager Integration
Steps to integrate Tag Manager and Audience Manager.
1. (Conditional) Contact your Adobe Account Manager to set up an Audience Manager account, if necessary.
You must be an Audience Manager customer and have an Audience Management account to use this integration.
API and SDK Code
186
2. When you add Audience Manager, 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
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 Manager event call on your web page:
// Example: partner_name=adobe
[http|https]://adobe.demdex.com/event?...
REST APIs
RESTful APIs let you work programmatically with Audience Management.
The Audience Manager 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 Manager 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.
• We recommend you create a separate user account for working with the Audience Manager APIs that is not tied
to an end user. See here how to create a user in the Audience Manager UI.
API and SDK Code
187
OAuth Authentication
The Audience Manager REST API follows OAuth 2.0 standards for token authentication and renewal.
Contents:
Password Authentication Workflow
Refresh Token
Authorization Code and Implicit Authentication
Password Authentication Workflow
Password authentication secure access our REST API. The following table outlines the workflow for password
authentication from a JSON client in your browser.
Tip: Encrypt access and refresh tokens if you store them in a database.
Process Step
Request API
Access
Description
Contact your Partner Solutions manager. They 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"
}
API and SDK Code
Process Step
188
Description
The "expires_in" key 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 exposed.
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.
Process Step
Request the New Token
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"
}
API and SDK Code
189
Authorization Code and Implicit Authentication
The Audience Manager REST API supports authorization code and implicit authentication. To use these access
methods, your users need to log in to https://api.demdex.com/oauth/authorize to get access and refresh
tokens.
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).
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
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.
API and SDK Code
Parameter
190
Description
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.
• Request URLS
• Environments
• Versions
Request URLS
The following table lists the request URLs used to pass in API requests, by method.
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/
API and SDK Code
191
Environments
The Audience Manager 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/...
Beta
https://api-beta.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.
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.
API and SDK Code
192
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,
"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,
API and SDK Code
193
"pid": 1,
"name": "New name",
"description": "Revised description",
"algoTypeId": 1,
"crUID": 3,
"upUID": 3,
"status": 1,
"createTime": 1346092322000,
"dataSources": [size(2)
3,
4
],
"sid": 8,
"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.
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/
API and SDK Code
194
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.
Request
GET https://api.demdex.com/v1/models/
in the request string when passing that query in to the API. See Optional Parameters.
Parameter
Description
page
pageSize
sortBy
descending
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:
API and SDK Code
195
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":"Test model",
"description":"For testing",
"algoTypeId":1,
"intervalSeconds":604800,
"lookBackPeriod":30,
"crUID":833,
"upUID":833,
"status":"INACTIVE",
"lastRunStatus":null,
"createTime":1427474087000,
"algoModelVersion":0,
"sid":1784945,
"lastRunTimestamp":null,
"baselineTraitType":"SEGMENT",
"lastSuccessfulRunTimestamp":null,
"updateTime":1427474947000
},
{
"algoModelId":738,
"pid":1234,
"name":"Another Test Model",
"description":"For testing",
"algoTypeId":1,
"intervalSeconds":604800,
"lookBackPeriod":30,
"crUID":833,
"upUID":833,
"status":"ACTIVE",
"lastRunStatus":2,
"createTime":1422494342000,
"algoModelVersion":0,
"sid":916388,
"lastRunTimestamp":1431445691000,
"baselineTraitType":"SEGMENT",
"lastSuccessfulRunTimestamp":1431445691000,
"updateTime":1429133721000
}
]
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,
API and SDK Code
196
"name": "newmodel78",
"description": "descriptions is in the name",
"algoTypeId": 1,
"crUID": 3,
"upUID": 3,
"status": 1,
"createTime": 1344969143000,
"dataSources": [
4
],
"sid": 8,
"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/
in the request string when passing that query in to the API. See also Optional Parameters.
Parameter
Description
page
pageSize
sortBy
descending
search
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:
folderId
Sample Response
{
"total": 2,
"page": 0,
"pageSize": 10,
"list": [
{
Returns all the IDs for traits inside the specified folder. Not available to all methods.
API and SDK Code
"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,
"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,
"crUID": 3,
"upUID": 3,
"createTime": 1344277873000,
"updateTime": 1344277873000,
"type": 1,
"dataSourceId": 1,
"folderId": 10,
"traitType": 3,
"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
[
{
197
API and SDK Code
198
"AccuracyValue": 0.12,
"ReachValue": 0
},
{
"ReachValue": 0
},
{
"ReachValue": 23232
},
{
"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
]
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,
API and SDK Code
"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": {
"type": "object",
"id": "initConfig",
"required": true,
"properties": {
"declaredId": {
"id": "declaredId",
"required": false,
"type": "object",
"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",
199
API and SDK Code
200
"required": false
},
"mappings": {
"type": "object",
"id": "mappings",
"required": false,
"additionalProperties": {
"type": "string"
}
},
"removeFinishedScriptsAndCallbacks": {
"type": "boolean",
"id": "removeFinishedScriptsAndCallbacks",
"required": false
},
"uuidCookie": {
"type": "object",
"id": "uuidCookie",
"required": false,
"properties": {
"days": {
"type": "number",
"id": "days",
"required": false
},
"domain": {
"type": "string",
"id": "domain",
"required": false
},
"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",
API and SDK Code
"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,
"properties": {
"GoogleAnalytics": {
"type": "object",
"id": "GoogleAnalytics",
"required": false,
"properties": {
"code": {
"id": "code",
"type": "boolean",
"required": true
}
}
},
"Peer39": {
"type": "object",
"id": "Peer39",
"required": false,
"properties": {
"code": {
"id": "code",
"type": "boolean",
"required": true
}
}
},
"SiteCatalyst": {
"type": "object",
"id": "SiteCatalyst",
"required": false,
"properties": {
"code": {
"type": "boolean",
"id": "code",
"required": true
},
"init": {
"type": "object",
"id": "init",
"required": false,
"properties": {
"siteCatalystInstance": {
"type": "string",
"id": "siteCatalystInstance",
"required": true
},
"dilInstance": {
"type": "string",
"id": "dilInstance",
201
API and SDK Code
202
"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",
"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",
API and SDK Code
203
"required": false
}
]
}
}
}
}
}
}
}
}
},
"tools": {
"type": "object",
"id": "tools",
"required": false,
"properties": {
"getMetaTags": {
"type": "boolean",
"id": "getMetaTags",
"required": false
},
"getSearchReferrer": {
"type": "boolean",
"id": "getSearchReferrer",
"required": false
},
"decomposeURI": {
"type": "boolean",
"id": "decomposeURI",
"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',
API and SDK Code
204
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',
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
}
}
}
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.
The Data Source API methods have moved. See the Adobe Audience Manager API Docs.
API and SDK Code
205
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
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.
API and SDK Code
206
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.
{
"targetKey": "targetKey",
"sourceKey": "sourceKey",
"targetValue": "targetValue",
"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/
Parameter
Description
page
pageSize
sortBy
descending
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:
Sample Response
API and SDK Code
207
A successful update returns response code 200 OK and data (in an array) as shown below. All request values are
required unless otherwise indicated.
[
{
"pid": 1099,
"updateTime": 1319746748000,
"version": 0,
"upUID": 507,
"crUID": 507,
"sourceValue": "sourceValue",
"createTime": 1319746748000
},
{
"DerivedSignalId": 2,
"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 Manager, 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.
API and SDK Code
208
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
A successful request returns 201 created and the destination.
{
"destinationId":4033,
"dataSourceId":null,
"pid":1099,
"name":"Sample URL Destination (not serialized)",
"description":"",
"startDate":null,
"endDate":null,
"status":"ACTIVE",
"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
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":"",
"serializationEnabled":true,
"urlFormatString":"http://www.adobe.com/send?data=%ALIAS%",
API and SDK Code
209
"secureUrlFormatString":"https://www.adobe.com/%ALIAS%",
"delimiter":","
}
Sample Response
A successful update returns response code 201 created and the destination.
{
"pid":1099,
"name":"Sample URL Destination (Serialized)",
"description":"",
"startDate":null,
"endDate":null,
"status":"active",
"createTime":1338937420000,
"updateTime":1338937420000,
"crUID":694,
"upUID":694,
"tagType":0,
"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
Sample Request
{
"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":",",
}
Sample Response
{
API and SDK Code
210
"pid":1099,
"name":"Cookie Destination Single Key Not Serialized",
"status":"active",
"createTime":1338937984000,
"updateTime":1338937984000,
"crUID":694,
"upUID":694,
"domainRestrictions":"inclusion",
"singleKey":"key",
"keySeparator":"=",
"transferMethod":0,
"maxSize":2048,
"ttl":0,
"siteIDs":[
312
],
"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
Sample Request
{
"name":"Cookie Destination Single Key Serialized",
"adServerTypeID":1,
"maxSize":"2048",
"ttl":"0",
"siteIDs":[
],
"singleKey":"k",
"keySeparator":"=",
"serializationSeparator":"#"
}
Sample Response
{
"pid":1099,
"name":"Cookie Destination Single Key Serialized",
"status":"active",
API and SDK Code
"createTime":1338938329000,
"updateTime":1338938329000,
"crUID":694,
"upUID":694,
"singleKey":"k",
"keySeparator":"=",
"transferMethod":0,
"serializationSeparator":"#",
"maxSize":2048,
"ttl":0,
"siteIDs":[
],
}
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
Sample Request
{
"name":"Ad Server Multi-Key Not Serialized",
"adServerTypeID":1,
"maxSize":"2048",
"ttl":"0",
"siteIDs":[
],
"formatType":"key_value",
"keySeparator":"=",
}
Sample Response
{
"pid":1099,
"name":"Ad Server Multi-Key Not Serialized",
"status":1,
"createTime":1338938666000,
"updateTime":1338938666000,
"crUID":694,
"upUID":694,
211
API and SDK Code
212
"keySeparator":"=",
"transferMethod":0,
"maxSize":2048,
"ttl":0,
"siteIDs":[
],
}
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
Sample Request
{
"name":"Cookie Destination Multi-Key Serialized",
"adServerTypeID":1,
"maxSize":"2048",
"ttl":"0",
"siteIDs":[
],
"keySeparator":"=",
"serializationSeparator":"#"
}
Sample Response
{
"pid":1099,
"name":"Ad Server Multi-Key Serialized",
"status":"active",
"createTime":1338938872000,
"updateTime":1338938872000,
"crUID":694,
"upUID":694,
"keySeparator":"=",
API and SDK Code
213
"transferMethod":0,
"serializationSeparator":"#",
"maxSize":2048,
"ttl":0,
"siteIDs":[
],
}
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.
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
{
"sid":87723,
"traitType":"SEGMENT",
"url":"http://adobe.com",
"startDate":"2012-07-04"
}
Sample Response
{
"mappingId":65334,
"traitValue":0,
"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,
"secureUrl":null,
"tagCode":null,
"secureTagCode":null,
"traitAlias":null
}
API and SDK Code
214
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,
"startDate":"2012-07-04",
"traitAlias":"123"
}
Sample Response
{
"mappingId":65335,
"traitValue":0,
"elementName":"Sample Games",
"elementDescription":"Migration of Sample Games Pixel",
"createTime":1338940401000,
"updateTime":1338940401000,
"crUID":694,
"upUID":694,
"sid":87723,
"startDate":"2012-07-03",
"endDate":null,
"priority":null,
"url":"123",
"secureUrl":"123",
"tagCode":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
Sample Request
In the request, the valueAlias corresponds to the value in a key-value pair. All request values are required unless
{
"sid":87723,
"startDate":"2012-07-04",
"valueAlias":"123"
}
Sample Response
{
"destinationMappingId":65336,
API and SDK Code
215
"traitValue":0,
"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
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,
"startDate":"2012-07-04",
"traitAlias":"type",
"valueAlias":"123"
}
Sample Response
{
"mappingId":65338,
"traitValue":0,
"createTime":1338941092000,
"updateTime":1338941092000,
"crUID":694,
"upUID":694,
"sid":87723,
"startDate":"2012-07-03",
"endDate":null,
"priority":1,
"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
API and SDK Code
216
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,
"startDate":"2012-07-04",
"valueAlias":"123"
}
Sample Response
{
"traitValue":0,
"createTime":1338941273000,
"updateTime":1338941273000,
"crUID":694,
"upUID":694,
"sid":87723,
"startDate":"2012-07-03",
"endDate":null,
"priority":2,
"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
Sample Request
In the request, the traitAlias corresponds to the key in a key-value pair. All request values are required unless
{
"sid":87723,
"startDate":"2012-07-04",
"traitAlias":"123"
}
Sample Response
{
"traitValue":0,
"elementName":"Sample",
"elementDescription":"",
"createTime":1338942118000,
"updateTime":1338942118000,
"crUID":308,
API and SDK Code
"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
[
{
"sid": 105123,
"startDate":"2012-11-20"
},
{
"sid": 121070,
"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
},
{
"traitValue": 0,
"orderId": 780,
"elementName": "Test Trait",
"elementDescription": "This trait",
"elementStatus": 1,
217
API and SDK Code
218
"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,
"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.
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/
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>
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,
"startDate":"2012-11-20"
},
{
API and SDK Code
"sid": 121070,
"url":"http://my.adobeconnect.com",
"startDate":"2012-11-21"
}
]
Sample Response
Returns an array of created mappings.
[
{
"destinationMappingId": 103454,
"traitValue": 0,
"elementName": "Case of the Mondays",
"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,
"traitAlias": null
},
{
"traitToDataOrderId": 103455,
"traitValue": 0,
"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,
"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
219
API and SDK Code
{
"name":"Updated URL Destination (not serialized)",
"description":"new description",
}
Sample Response
{
"destinationType": "PUSH",
"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,
"tagType": 0,
"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
{
"sid": 105123,
"startDate":"2012-11-20"
}
Sample Response
{
"traitValue": 0,
"elementName": "sample",
"createTime": 1353373005000,
"updateTime": 1353373005000,
"crUID": 1065,
"upUID": 1065,
"sid": 105123,
"startDate": "2012-11-19",
220
API and SDK Code
221
"endDate": null,
"priority": null,
"url": "http://www.adobe.com/send?%ALIAS%",
"secureUrl": null,
"tagCode": 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
{
"pid":1099,
"name":"sample destination",
"description":"Turn",
"startDate":null,
"endDate":null,
"status":"active",
"createTime":1281997484000,
"updateTime":1300752888000,
"crUID":224,
"upUID":308,
"domainRestrictions":"ALL_DOMAINS",
"tagType":0,
"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.
API and SDK Code
222
Parameter
Description
page
pageSize
sortBy
descending
search
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:
Sample Response
[
{
"pid":1099,
"name":"Test",
"description":"",
"status":"active",
"createTime":1291345192000,
"updateTime":1291347561000,
"crUID":262,
"upUID":262,
"domainRestrictions":"all_domains"
},
{
"pid":1099,
"name":"sample destination",
"status":"active",
"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,
API and SDK Code
"traitValue": 0,
"elementName": "sample",
"elementDescription": "Migration Pixel",
"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,
"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
GET https://api.demdex.com/v1/destinations/<destinationId>/mappings
Note: Supports paging parameters.
Sample Response
{
"total":354,
"page":0,
"pageSize":2,
"list":[
{
"traitValue":0,
"elementName":"sample pixel",
"elementDescription":"Migration Pixel",
"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,
"traitAlias":null
}
{
"traitValue":0,
223
API and SDK Code
224
"elementName":"sample pixel",
"elementDescription":"Migration Pixel",
"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,
"traitAlias":null
}
]
{
Return All Available Destination Platforms
A GET method that returns all available device platforms for destinations.
Request
GET /destinations/configurations/available-platforms/
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,
API and SDK Code
225
"syncType":1,
"successRecords":1,
"startTime":1337346397000,
"endTime":1337346397000,
"success":true
},
{
"pushID":34124,
"orderID":655,
"syncType":1,
"successRecords":1,
"startTime":1337396811000,
"endTime":1337396812000,
"success":true
}
]
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.
API and SDK Code
226
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,
}
Return Properties for all Domains
A GET method that returns information about all your domains (for cookie destinations only).
Request
GET https://api.demdex.com/v1/partner-sites/
Parameter
Description
page
pageSize
sortBy
descending
search
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:
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,
},
{
API and SDK Code
227
"pid": 2222,
"siteId": 222,
},
{
"pid": 3333,
"siteId": 333,
}
]
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/
Sample Request
{
"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,
"status":"ACTIVE",
"startTime":1334183314000,
"createTime":1335901700000,
"updateTime":1335901700000,
"crUId":507,
"upUId":507,
"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)
API and SDK Code
228
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
{
"dataSourceId":281,
"integrationCode":0,
"status":"active",
"folderId":13247
}
Sample Response
A successful response returns 200 OK. An unsuccessful response returns error code 4xx.
{
"pid":1099,
"legacyId":15693,
"sid":64821,
"dataSourceId":265,
"status":"ACTIVE",
"startTime":1334183314000,
"createTime":1335901700000,
"updateTime":1335901700000,
"crUId":507,
"upUId":507,
"folderId":13247
}
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>
Sample Response
API and SDK Code
229
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,
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>
• 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,
"status":"ACTIVE",
"startTime":1334183314000,
"createTime":1335901700000,
"updateTime":1335901700000,
API and SDK Code
230
"crUId":507,
"upUId":507,
"permissions: ["READ", "WRITE", "CREATE", "DELETE"],
"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.
Return Properties for all Segments
A GET method that returns details about all your segments.
Request
GET https://api.demdex.com/v1/segments/
Parameter
Description
page
pageSize
sortBy
descending
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
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.
API and SDK Code
Parameter
231
Description
• 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
GET
https://api.demdex.com/v1/segments/?page=1&pageSize=1&sortBy=Name&descending=true
Sample Response
{
"total":3844,
"page":0,
"pageSize":5,
"list":[
{
"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"],
"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,
API and SDK Code
232
"segmentRule":"(13212T)",
"permissions": ["READ", "WRITE", "CREATE", "DELETE", "ADMINISTRATION"],
"folderId":13350
}
]
}
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":[
{
"timeWindow":"DAYS7",
"confidenceInterval":{
"high":15,
"low":0
},
"size":0
},
{
"high":15,
"low":0
},
"size":0
},
{
"high":15,
"low":0
},
"size":0
}
],
"lastUpdate":"2012-05-15 23:52:01",
"segment":"2434T AND 3434T"
}
API and SDK Code
233
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." 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
API and SDK Code
234
• 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 Manager common taxonomy. This optional classification scheme organizes
traits into industry standard categories.
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,
"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,
},
{
"crUID": 158,
"name": "Automotive",
"upUID": 158,
"description": "Automotive",
API and SDK Code
235
"categoryID": 2,
},
{
"crUID": 158,
"name": "Business",
"upUID": 158,
"description": "Business",
"categoryID": 3,
}
]
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,
},
{
"crUID": 158,
"name": "Celebrity Fan/Gossip",
"upUID": 158,
"description": "Celebrity Fan/Gossip",
"categoryID": 49,
},
{
"crUID": 158,
"name": "Fine Art",
"upUID": 158,
"description": "Fine Art",
"categoryID": 72,
}
]
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/
API and SDK Code
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.
{
"sid":241161,
"pid":1111,
"folderId":425,
"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 Onboarded Trait
A POST method that creates a new onboarded trait (a trait from another system's database that is imported into
Audience Manager).
Request
Sample Request Body
The JSON request requires a trait name and folder ID. All other parameters are optional.
{
"traitType":"ON_BOARDED_TRAIT",
236
API and SDK Code
237
"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.
{
"sid":241161,
"pid":1111,
"folderId":425,
"ttl":30,
"crUID":839,
"upUID":839,
"createTime":1354822051000,
"updateTime":1354822051000,
"permissions":[
"READ",
"WRITE",
"CREATE",
"DELETE"
],
"dataSourceId":452,
"categoryId":1234
}
Create a New Algorithmic Trait
A POST method that creates a new algorithmic trait.
Request
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",
API and SDK Code
238
"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>
Sample Request Body
The JSON request body could look similar to the following example.
{
"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
}
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.
{
"sid":241161,
"pid":1111,
"ttl":90,
"crUID":839,
"upUID":839,
API and SDK Code
239
"createTime":1354822051000,
"updateTime":1354822612000,
"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
Sample Request Body
The JSON request body could look similar to the following example.
{
"ttl":90,
"dataSourceId":159,
"folderId":362
"categoryId:0
}
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.
{
"sid":241161,
"pid":1111,
"ttl":90,
"crUID":839,
API and SDK Code
240
"upUID":839,
"createTime":1354822051000,
"updateTime":1354822612000,
"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
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.
{
"sid": 778769,
"status": 1,
"algoModelId": 175,
"accuracy": 0.95,
"folderId": 3143,
"categoryId": 0
}
Delete a Trait
A DELETE method that removes an individual trait from your collection.
API and SDK Code
241
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>
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.
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>
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.
{
API and SDK Code
242
"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>
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.
{
"sid": 778770,
"status": 1,
"algoModelId": 175,
"accuracy": 0.95,
"folderId": 3143,
"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/
Parameter
Description
page
API and SDK Code
243
Parameter
Description
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:
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,
"name":"Trait 1",
"description":"Trait 1 description",
"status":"ACTIVE",
"dataSourceId":159,
"folderId":362
},
{
"sid":1158,
"name":"Trait 2",
"status":"ACTIVE",
"dataSourceId":159,
"folderId":362
},
{
"sid":6412,
"name":Trait 3",
"status":"ACTIVE",
"dataSourceId":159,
"folderId":362
API and SDK Code
244
}
]
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
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
}
API and SDK Code
245
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
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
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.
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"},
API and SDK Code
246
"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 Type Methods
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.
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,
API and SDK Code
"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,
"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
}
]
247
API and SDK Code
248
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>,
"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.
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
{
API and SDK Code
249
"groups" : [<group_1_id>, ...]
}
Sample Response
{
"pid" : <integer>,
}
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
{
"phoneNumber" : <string_may_be_null>
}
Sample Response
{
"userId": <integer>,,
"emailAddress" : <string>
"phoneNumber" : <string_may_be_null>
}
Update Logged-In User Password
A PUT method to update the currently logged-in user.
users.
Request
API and SDK Code
250
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.
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>,
"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.
users.
Request
GET /api/v1/users/self
Sample Response
{
"pid" : <integer>,
API and SDK Code
"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>,
}
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>, ...]}
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
251
API and SDK Code
POST /api/v1/groups/
Sample Request Body
{
"name" : <string>,
"description" : <string_may_be_null>,
}
Sample Response
{
"groupId" : <integer>,
"pid" : <integer>,
"name" : <string>,
"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>,
}
Sample Response
{
"pid" : <integer>,
"name" : <string>,
}
List Groups
A GET method to list user groups.
Request
GET /api/v1/groups/
Sample Response
[
{
"pid" : <integer>,
"name" : <string>,
}, ...
]
252
API and SDK Code
253
Delete a Group
A DELETE method to delete a user group and remove all members from that group.
Request
DELETE /api/v1/groups/<groupId>
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
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/
Sample Response
[
{ "objectType" : "SEGMENT",
"objectId" : 563,
"permissions" : [ "READ", "WRITE"]
},
{ "objectType" : "SEGMENT",
"objectId" : 2363,
"permissions" : [ "CREATE", "WRITE"]
},
{ "objectType" : "TRAIT",
API and SDK Code
254
"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.
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/
API and SDK Code
255
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
{
"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.
Request
DELETE https://api.demdex.com/v1/folders/traits/<folderId>
Sample Response
API and SDK Code
256
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/
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":[
{
"pid":1099,
"folderId":399,
"name":"folder 1",
"parentFolderId":0,
"subFolders":[
]
},
{
"pid":1099,
"folderId":317,
"name":"folder 2",
"parentFolderId":0,
API and SDK Code
257
"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
{
"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
{
"name":"Sample Updated",
"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 Segments/Sample",
API and SDK Code
258
"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/
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.
[
{
"path":"/All Segments",
"pid":1099,
API and SDK Code
259
"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 Manager 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 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>
}
List DCS Regions
A GET method to list DCS regions.
API and SDK Code
260
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>
},
...
]
SDK Code
Audience Manager provides software development kits (SDKs) for Android and iOS.
For SDK code libraries, see:
• Android SDK
• iOS SDK
Implementation and Integration Guides
261
Work with data from Marketing Cloud solutions or other external systems in Audience Manager.
Adobe data partners who want to receive audiences through a server-to-server integration should see Audience
Manager Targeting Integration to get started.
Ad Server Integration
Integrate Audience Manager with popular ad servers.
DART Enterprise as an Audience Manager Destination
Set up DART Enterprise as a destination and send Audience Management segment data to that platform. Once
configured, Audience Manager 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 Manager segment data.
• get_aamCookie Function: Code that captures the Audience Manager 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 Manager) that loads an Iframe on the
page. The Iframe contains Audience Manager cookie information that can be read by DART.
• Send Delivery Logs to Audience Manager: If you want a segment delivery report (optional), provide Audience
Manager 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 Manager UUID. Audience Manager can pick up or receive these via FTP.
Cookie Format and Key-Value Data
Audience Manager 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.
262
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 Manager - 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.
• 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 Manager, 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 Manager, 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 Manager 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:
263
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 Manager cookie configuration screen. See the DART documentation for more information about
campaign management.
GPT as an Audience Manager Destination
Set up Google Publisher Tags (GPT) as a destination to send Audience Manager segment data to DFP.
GPT Destination Requirements
Requirements and related information about setting up Google Publisher Tags (GPT) as an Audience Manager
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
Manager 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 Manager 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 Manager cookie data.
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,
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
264
Create a GPT Destination
Create a cookie-based destination for Google Publisher Tags in Audience Manager.
Destinations
Basic Information
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):
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
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.
3. Click Done.
Modify the GPT setTargeting API Call
Add an if statement to check for Audience Manager cookies before calling the Google Publisher Tag .setTargeting
method.
Check for Audience Manager 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.
265
IF Statement Code Sample
In this example, the Audience Manager destination cookie name is Sample. You set this name when you create the
destination cookie in the Audience Manager 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.
AamGpt.getValues
Array of strings
Returns values in an array, e.g., ["value1","value2"].
AamGpt.getCookie
Int
Returns the Audience Manager user ID, e.g., 12345.
AamGpt Code
A JavaScript function that reads Audience Manager 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 Manager 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");
266
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;
}
}
};
DFP as an Audience Manager Destination
Set up DFP as a destination and send Audience Manager 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
• 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 Manager user ID and cookie data. Place this code
on the top of the page or inside the <head> codeblock.
• A standard value delimiter separates individual key-value pairs.
Only Qualified Segments are Sent to DFP
267
The amount data passed in to DFP depends on how many segments a particular user qualifies for. For example,
segments get sent to DFP (not all 100).
Create a DFP Destination
Create a cookie-based destination for DFP in Audience Manager.
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.
3. Click Done.
DFP Setup
Modify DFP settings to work with Audience Manager segment data.
To set up DFP
• Install DIL code across your site.
• Create DFP as a cookie destination in Audience Manager.
268
• 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 Manager Destination
Set up OAS as a destination and send Audience Manager 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.
• 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.
• 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,
segments get sent to OAS (not all 100).
Create an OAS Destination
Create a cookie-based destination for OAS in Audience Manager.
269
segment:
3. Click Done.
OAS Setup
Modify OAS settings to work with Audience Manager segment data.
To set up OAS
• Create OAS as a cookie destination in Audience Manager.
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.
“&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 Manager Destination
Set up OpenX as a destination and send Audience Manager segment data to that platform.
Note: For onsite ad server targeting only.
270
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 Manager 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.
Key-Value Data: Format Requirements
Audience Manager 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.
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,
segments get sent to OpenX (not all 100).
Create an OpenX Destination
Create a cookie-based destination for OpenX in Audience Management.
271
segment:
3. Click Done.
OpenX Setup
Modify OpenX settings to work with Audience Manager segment data.
To set up OpenX
• Create OpenX as a cookie destination in Audience Manager.
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.
“&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
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 Impression Data via Pixel Calls
One approach for sending media data to Audience Manager uses ad server macros (such as DFA or Pointroll) to
send campaign attributes to Audience Manager.
This methodology is often referred to as "pixeling the creative." Those data points are dynamically inserted into the
Audience Manager 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
272
campaign performance, helps identify custom conversion paths, and helps customers improve the sequence of ad
server events that lead to conversions.
Contents:
Event Call Syntax
Supported Key-Value Pairs
Note: The text styles (monospaced text, italics, brackets [ ] ( ), etc.) indicate code elements and options.
See Style Conventions for Code and Text Elements for more information.
Event Call Syntax
The event call collects impression and conversion data and sends it to the Audience Managerdata 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.
Event calls consist of key-value pairs that use the following syntax:
http://clientname.demdex.net/event?d_event=imp&d_src=datasource_id&d_site=siteID&
d_creative=creative_id&d_adgroup=adgroup_id&d_placement=placement_id
&d_campaign=campaign_id[&d_cid=(GAID|IDFA)%01 DPUUID]&d_bust=cache buster value
In the key-value pair, the value variable is an ID or macro inserted by the ad server. When the ad tag loads, that
%macro% gets replaced with the required, corresponding values. This call does not return a response.
Supported Key-Value Pairs
Impression event calls accept data formed into key-value pairs. The following table lists an describes the keys used
to hold these variables. Many of these are required if you want to capture and analyze data in the Advertiser Analytics
Reports.
Key
d_adgroup
Description
Numeric ad group ID from the ad server.
Optional.
d_adsrc
Data source ID or integration code for your advertiser.
Required for Advertising Analytics reports.
d_bu
Data source ID or integration code for your business unit.
d_bust
Cache-busting value. Audience Manager 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.
Optional.
Key
d_campaign
273
Description
Numeric campaign ID from the ad server.
d_cid
In this context, d_cid instantiates a key-value pair that lets you associate a mobile
device type to a unique user ID (DPUUID). A fixed ID determines the mobile device
type. The value, which is the user ID, can vary. Separate the key-value pair with %01,
which is a non-printing control character. This parameter accepts the following keys:
• 20914: Identifies an Android (GAID) device. For example, d_cid = 20914 %01
1234 says that user 1234 is associated with an Android device.
• 20915: Identifies an iOS (IDFA) device. For example, d_cid = 20915 %01 5678
says that user 5678 is associated with an iOS device.
Optional.
d_creative
Numeric creative ID from the ad server.
d_event=imp
Identifies an event call as an impression event.
Required.
d_exch
Source ID for the inventory exchange that served the ad (e.g., Appnexus, Right Media,
Openx, etc.).
Optional.
d_io
Insertion order ID.
Optional.
d_placement
Numeric placement ID from the ad server.
Optional.
d_site
Numeric site ID from the ad server.
d_src
Data source ID or integration code of the platform providing the metadata (e.g., DFA,
Atlas, GBM, Media Math, etc.).
d_tactic
A tactic ID.
Optional.
Key
274
Description
d_vert
ID for an industry vertical or category.
Optional.
Note: Please contact your Adobe Audience Manager 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 Manager data
collection servers (DCS) for processing. The visitor is then redirected to the intended web address.
Requirements
Click tracking calls require that the following parameters:
• d_event=click: A key-value pair that identifies an event call as a click event.
• d_rd=redirect URL: A key-value pair that contains an encoded redirect URL.
In addition, the call can contain key-value pairs that can be used for trait qualification or to provide data and metadata
for other reports.
Request Sample
http://client.demdex.net/event?d_event=click&d_creative=123&d_rd=http%3A%2F%2Fadobe.com%2Fcallback%3Fcreative%3D%25d_creative%25
Response
The response redirects the browser to the URL specified in the d_rd parameter. The response string can include
values generated by any of the supported macros listed below.
Based on the above example, the browser is redirected to the following URL:
http://adobe.com/callback?creative=123
Supported Macros
Click events support the macros listed in the following table. A macro is a small unit of self contained code that
activates 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%. Some keys do not have macros and accept a
hard coded ID value instead. Keys that accept hard coded values are required if you want to analyze data in the
Advertiser Analytics Reports.
Key
Macro
Description
d_adgroup
%d_adroup%
Numeric ad group ID from the ad server.
Required.
d_adsrc
No macro.
Data source ID or integration code for your advertiser.
for Advertising Analytics reports.
Key
Macro
275
Description
Accepts a hard coded ID
value.
d_bu
%d_bu%
Numeric ID for the business unit.
d_campaign
%d_campaign%
Numeric campaign ID from the ad server.
d_creative
%d_creative%
Numeric creative ID from the ad server.
Required.
d_dpid
%d_id%
Data provider ID.
Often used with d_dpuuid to link a data provider ID to a user ID.
Optional.
d_dpuuid
%d_dpuuid%
Unique user ID supplied by the data provider.
Often used with d_dpid to link a user ID to a data provider ID.
d_exch
No macro.
Source ID for the inventory exchange that served the ad (e.g.,
Appnexus, Right Media, Openx, etc.).
Accepts a hard coded ID
value.
Optional.
d_io
No macro.
Insertion order ID.
Accepts a hard coded ID Required for Advertising Analytics reports.
value.
Optional.
d_mid
%d_mid%
Marketing Cloud ID (MID). For more information about the MID, see
Cookies and the Marketing Cloud ID.
Optional.
d_placement
%d_placement%
Optional.
d_region
%d_region%
The numeric region ID for the DCS cluster that services a request.
For more information about the DCS, see Data Collection
Components.
Key
Macro
276
Description
Optional.
r_rand
%r_rand%
Random number used for cache busting.
Optional.
d_site
%d_site%
Numeric site ID from the ad server.
Optional.
d_src
%d_src%
DPID of the source from where Audience Manager pulls the
metadata.
Required.
d_tactic
No macro.
A tactic ID.
Accepts a hard coded ID Optional.
value.
d_uuid
%d_uuid%
Specify the ID of the visitor directly in the URL instead of relying on
Demdex cookie.
Optional.
d_vert
No macro.
Accepts a hard coded ID Required for Advertising Analytics reports.
value.
Optional.
Macros Example
This example demonstrates passing the creative, adgroup, and placement macros. It assumes the 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%25
d_adgroup%25%26d_placement%3D%25placement%25%26src%3D%25d_src%25
Response
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
277
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.
• 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 Manager 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 Amazon S3: About.
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:
• 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
Recommendation
278
Description
• 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 Manager 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 Manager 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.
• No special characters in fields (newline, etc.).
• No delimiter characters in the fields.
File Size
Send Compressed Files
Use AAM UUID
Send Incremental Data
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 with Amazon S3. We recommend using gzip.
Use the 38-digit AAM UUID as the join ID.
Send incremental data only, ideally one set of files per hour.
Audience Manager will only begin processing one day's data when the first hour
of the next day's data has been delivered.
Audience Manager cannot begin populating files for a new day until the previous
day's files have been processed.
Recommendation
279
Description
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 Fitness
a particular size.
Campaign
A set of related ads that are served
during a specified flight.
Teen Party Season 3 Premiere
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.
Strategy
Creative
Wrestling_Weekly_Tomorrow_7.25
The image file or assets that are
displayed to the user.
Keyval
Placement
Comedy Mobile (comedy.mb)
Bio.Broadcast(Homepage)-160x600
video_id=294869
Creative size and delivery scope.
Core_Travel_HotelChecker_ROS__728x90
DFP Premium
Information that you need to provide to Adobe when using DoubleClick for Publishers Premium and Audience
Manager.
• 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
280
• 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 Manager 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
DFP
Information that you need to provide to Adobe when using DoubleClick for Publishers and Audience Manager.
Note: We strongly recommend that you useDFP Premium rather than DFP, described below.
• UserID Values
• The hostname of the FTP server
• Your FTP username and password
281
• 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
DFA
Information that you need to provide to Adobe when using DoubleClick for Advertisers and Audience Manager.
• 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
282
Dimension
DFA Service
DFA Object
DFA Field Name
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 Manager.
• UserID Values
MediaMath will contact Adobe for the appropriate access to the appropriate Amazon S3 bucket.
Default Dimensions
• Advertiser
• Campaign
• Strategy
dimension names.
UserID Values
24/7 Open AdStream
Information that you need to provide to Adobe when using 24/7 Open AdSteam and Audience Manager.
• UserID Values
• Event Type Definitions
283
• The filenames of the different logs files you will be sending to Adobe
Default Dimensions
• Advertiser
• Campaign
• Creative
dimension names.
UserID Values
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
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 Manager.
284
• UserID Values
Default Dimensions
• Advertiser
• Ad
• Campaign
• Creative
• Order
• PO Number
• Site
dimension names.
UserID Values
Pre-Submission Data Integration Checklist
Information that you should gather before requesting report setup from your Audience Manager 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.
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
285
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:
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)
286
Sends
Opens
Clicks
Conversions
UserID Type: Specify the UserID type:
Audience Manager 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:
Customer Data Feed Overview
Information about working with customer data feeds, including input/output, fields, filtering, and notifications.
Audience Manager delivers files every hour using Amazon S3. You should use the HTTPS option to ensure that
data is encrypted during transit. Audience Manager does not currently encrypt the data.
Using Amazon S3 lets Audience Manager use its distributed environment to deliver files in a timely manner. Audience
Manager 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 Amazon S3: About.
Note: Audience Manager does not allow the use of FTP, SFTP, or SCP to obtain customer data feed log files.
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.
287
C++: Access S3 using the libs3 library.
Customer Data Feeds Implementation
For any new integration, please consult with you Audience Management Account Manager.
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
2013-10-01 19:27
2726614
2013-10-01 19:27
2758371
2013-10-01 19:27
2915035
2013-10-01 19:27
2874818
2013-10-01 19:27
2822752
2013-10-01 19:27
2931709
2013-10-01 19:28
2873344
2013-10-01 19:28
2846825
2013-10-01 19:28
2896432
2013-10-01 19:28
2838296
2013-10-01 19:28
2867915
2013-10-01 19:28
2883941
2013-10-01 19:28
2927182
2013-10-01 19:28
2978566
2013-10-01 19:28
2922342
2013-10-01 19:28
2955889
2013-10-01 19:28
2694690
2013-10-01 19:28
2976889
2013-10-01 19:28
2928639
2013-10-01 19:28
2868285
2013-10-01 19:28
2756921
2013-10-01 19:28
2834288
2013-10-01 19:28
2807185
2013-10-01 19:28
2851014
2013-10-01 19:28
3055701
2013-10-01 19:28
2684026
2013-10-01 19:28
2857990
2013-10-01 19:28
2646229
2013-10-01 19:28
2948097
2013-10-01 19:28
2746211
2013-10-01 19:28
2858033
2013-10-01 19:28
2718488
2013-10-01 19:28
2825010
2013-10-01 19:28
2747415
2013-10-01 19:28
2971541
2013-10-01 19:28
2892273
2013-10-01 19:28
2873868
2013-10-01 19:28
2895880
2013-10-01 19:28
2975552
2013-10-01 19:28
2941391
2013-10-01 19:28
3042072
2013-10-01 19:28
2979775
2013-10-01 19:28
2873350
2013-10-01 19:28
2869144
2013-10-01 19:28
2824391
2013-10-01 19:28
3058264
2013-10-01 19:28
2841097
2013-10-01 19:28
2817626
2013-10-01 19:28
2906812
2013-10-01 19:28
2937478
2013-10-01 19:28
2953161
2013-10-01 19:28
3055322
2013-10-01 19:28
2974555
2013-10-01 19:28
2836694
2013-10-01 19:28
2787243
2013-10-01 19:29
2796356
2013-10-01 19:29
2801108
2013-10-01 19:29
2895750
2013-10-01 19:29
2784504
2013-10-01 19:29
3125536
2013-10-01 19:29
2885012
288
289
2013-10-01 19:29
2767172
2013-10-01 19:29
2803890
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
[1 of 66]
14328 of 14328
100% in
0s
217.98 kB/s done
2791012 of 2791012
100% in
0s
6.40 MB/s done
2869216 of 2869216
100% in
0s
4.39 MB/s done
2726614 of 2726614
100% in
0s
7.89 MB/s done
2758371 of 2758371
100% in
0s
9.40 MB/s done
2915035 of 2915035
100% in
0s
10.06 MB/s done
2874818 of 2874818
100% in
0s
7.94 MB/s done
2822752 of 2822752
100% in
0s
9.67 MB/s done
2931709 of 2931709
100% in
0s
9.59 MB/s done
2873344 of 2873344
100% in
0s
6.01 MB/s done
2846825 of 2846825
100% in
0s
5.99 MB/s done
2896432 of 2896432
100% in
0s
4.23 MB/s done
2838296 of 2838296
100% in
0s
6.18 MB/s done
2867915 of 2867915
100% in
1s
2.55 MB/s done
/path/to/dirt/AAM_CDF_1234_000013_0.gz [15 of 66]
2883941 of 2883941
100% in
0s
4.86 MB/s done
2927182 of 2927182
100% in
0s
4.87 MB/s done
2978566 of 2978566
100% in
0s
9.29 MB/s done
2922342 of 2922342
100% in
0s
6.48 MB/s done
2955889 of 2955889
100% in
0s
4.66 MB/s done
2694690 of 2694690
100% in
0s
3.79 MB/s done
2976889 of 2976889
100% in
0s
5.59 MB/s done
2928639 of 2928639
100% in
0s
6.78 MB/s done
2868285 of 2868285
100% in
1s
2.50 MB/s done
2756921 of 2756921
100% in
0s
6.78 MB/s done
2834288 of 2834288
100% in
0s
7.34 MB/s done
2807185 of 2807185
100% in
0s
7.95 MB/s done
2851014 of 2851014
100% in
0s
6.72 MB/s done
3055701 of 3055701
100% in
0s
12.30 MB/s done
2684026 of 2684026
100% in
0s
5.88 MB/s done
2857990 of 2857990
100% in
0s
11.65 MB/s done
2646229 of 2646229
100% in
0s
6.26 MB/s done
2948097 of 2948097
100% in
0s
6.40 MB/s done
2746211 of 2746211
100% in
0s
6.31 MB/s done
2858033 of 2858033
100% in
0s
11.56 MB/s done
2718488 of 2718488
100% in
0s
6.79 MB/s done
2825010 of 2825010
100% in
0s
4.98 MB/s done
2747415 of 2747415
100% in
0s
9.72 MB/s done
290
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
2971541 of 2971541
100% in
0s
7.54 MB/s done
2892273 of 2892273
100% in
0s
9.25 MB/s done
2873868 of 2873868
100% in
0s
14.11 MB/s done
2895880 of 2895880
100% in
0s
7.33 MB/s done
2975552 of 2975552
100% in
0s
4.08 MB/s done
2941391 of 2941391
100% in
0s
9.10 MB/s done
3042072 of 3042072
100% in
0s
17.49 MB/s done
2979775 of 2979775
100% in
0s
5.70 MB/s done
2873350 of 2873350
100% in
0s
9.12 MB/s done
2869144 of 2869144
100% in
0s
6.66 MB/s done
2824391 of 2824391
100% in
0s
7.28 MB/s done
3058264 of 3058264
100% in
0s
6.14 MB/s done
2841097 of 2841097
100% in
0s
8.21 MB/s done
2817626 of 2817626
100% in
0s
8.89 MB/s done
2906812 of 2906812
100% in
0s
9.44 MB/s done
2937478 of 2937478
100% in
0s
12.87 MB/s done
2953161 of 2953161
100% in
0s
7.66 MB/s done
3055322 of 3055322
100% in
0s
9.75 MB/s done
2974555 of 2974555
100% in
0s
8.12 MB/s done
2836694 of 2836694
100% in
0s
7.59 MB/s done
2787243 of 2787243
100% in
0s
10.29 MB/s done
2796356 of 2796356
100% in
0s
7.83 MB/s done
2801108 of 2801108
100% in
0s
8.47 MB/s done
291
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
->
2895750 of 2895750
100% in
0s
11.84 MB/s done
2784504 of 2784504
100% in
0s
6.44 MB/s done
3125536 of 3125536
100% in
0s
7.94 MB/s done
2885012 of 2885012
100% in
0s
8.63 MB/s done
2767172 of 2767172
100% in
0s
8.24 MB/s done
2803890 of 2803890
100% in
0s
8.33 MB/s done
Done. Downloaded 186666515 bytes in 26.5 seconds, 6.72 MB/s
292
->
->
->
->
->
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
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.
Input/Output
Information about the input/output that Audience Manager performs on customer data feeds.
Input
The input to this hourly process is data from the raw DCS logs. Audience Manager starts processing this data as
soon as a full hour has passed since the last process finished.
Output
Consider the following when working with the output log files:
• Customer Data Feed files can only be generated from the day requested. They cannot be generated retroactively.
• You can have the data delivered to one or to multiple S3 buckets. By default, Audience Manager delivers data to
the bucket mentioned in the next bullet.
• The default bucket is owned by Audience Manager 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 Manager 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.
293
• 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").
• Data is compressed with the gzip compression codec by default.
• 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 Manager
Account Manager.
• It is difficult to estimate file sizes. Also, the files won't always be the same size. Generally, sizes ranges from 800
MB to 950 MB per million records (uncompressed). Your file sizes may be different.
• If there was no data for a particular hour, or if data processing was delayed, the directory contains a .info file and
(eventually) an empty gzip-compressed file.
• A missing hourly directory means that something is wrong on the Audience Manager side, but this directory will
reappear eventually. Under normal conditions, you should always have a directory, even if that directory is empty.
• 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 from the S3 buckets controlled by Audience Manager.
• With data processing delays, hourly directory will only contain a .info file and eventually an empty gzip-compressed
file. But no data is lost, and the next available hour will contain all the data that has not been delivered for the
previous hour, there should be no data loss under any circumstances.
Fields in the Customer Data Feed
List of standard fields used in customer data fields.
Field
EventTime
Uuid
SiteId
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 Manager User ID is represented by
a 38-digit string.
18
ID for the deployed TIM container. Note, TIM tags
and containers are deprecated and no longer used.
SeeTags.
Field
RealizedTraits
Reazil edSegments
RequestParameters
294
Value/Example
Description
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 Manager Account Manager.
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 Manager filters customer data feeds.
295
Audience Manager 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 Manager Account Manager.
Notifications
Information about notifications that Audience Manager provides to let you know if a process is complete.
Even though Audience Manager 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 Manager 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
},
{
"FileChecksumMD5": "7b469485d60274b6991acd0817855840",
},
...
{
"FileChecksumMD5": "348a7170f0d1a6199550cfa5c00b725b",
},
296
{
"FileChecksumMD5": "c6f8bd48b950813aa87e6f84f287f449",
}
],
"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
Data Integration Methods
A high-level overview of how Audience Manager 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 Manager exchanges information with other data providers and systems.
Supported Data Integration Methods: Real-Time and Batch (Server-to-Server)
Audience Manager 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
Manager can send/receive data in real-time from the browser or by batch updates through offline, server-to-server
communication processes.
297
• 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 Manager 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 Manager 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 Manager. Furthermore, 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 Manager 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 Manager uses real-time calls to integrate with Target, Adobe Auditude/Primetime, and other content
management systems.
298
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 Manager 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 Manager 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 Manager 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.
Disadvantages:
• 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 Manager 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
299
Category
Trait ID
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
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 Manager. 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 Manager
Mail your taxonomy (and any updates) to DL-Data-Partners-AAM <[email protected]>.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 Manager 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
300
The real-time data integration process works as follows:
1. A user visits a customer's site that contains Audience Manager code.
2. Audience Manager 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 Manager.
5. Audience Manager ingests segment information and makes it available for targeting.
Batch Data Transfer Process
A general overview of how Audience Manager 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.
1.
2.
3.
4.
A user visits a customer site.
Audience Manager and the third-party data provider assign the visitor a unique ID (usually with a cookie).
Audience Manager calls the third-party data provider to match visitor IDs.
A scheduled request, usually on a daily interval, exchanges visitor segment data between Audience Manager
and your third-party data provider.
301
For information describing the time frames when Audience Manager processes inbound and outbound Server-to-Server
(S2S) file transfers, see Reporting and File Transfer Time-Frame Guidelines.
Data and Metadata Files for Advertiser Analytics Reports
A data file contains impression, click, or conversion data that you can import into the Advertising Analytics reports.
A metadata file contains human-readable names that correspond to various report options and menu items. Format
your data and metadata files according to the specifications in this section.
Important: To use metadata files, your event calls must include all of the parameters listed in the overview
and mappings section.
Data Files for Advertiser Analytics Reports
A data file contains impression, click, or conversion data. When formatted properly, you can import this data into
Audience Manager and view it in the Advertiser Analytics Reports. Format your data files according to these
specifications in this section.
Contents:
Overview
Naming Conventions for Data Files
Content Format for Data Files
Delivery Methods for Data Files
302
Overview
A properly named and formatted data file lets you import impression, click, or conversion data into the Advertiser
Analytics Reports. This is useful when working with partner who is not integrated with Audience Manager and you
want to work with their data in that report suite. This process requires separate files for impression, click, and
conversion data. Do not mix these events in a single file.
A data file must be accompanied by a metadata file. The metadata file contents match data file information to related,
human-readable labels in the report menus. For more information, see Overview and Mappings for Metadata Files.
Naming Conventions for Data Files
The following syntax defines the structure of a well-formed data file name. Note, italics indicates a variable placeholder
that changes depending on the file contents.
Syntax: event type_yyyymmdd
In a file name:
• The event type indicates the file contains impressions, clicks, or conversions. Create a separate file for each event
type.
• A hyphen separates the event type and a year-month-date timestamp.
Given these requirements, name your data files based on their contents like this:
• Impression data: impressions_yyyymmdd
• Click data: clicks_yyyymmdd
• Conversion data: conversions_yyyymmdd
Content Format for Data Files
The following syntax defines the content structure in well-formed data file. Note, italics indicates a variable placeholder
and is replaced with an label in an actual data file.
Syntax: header label 1 | header label 2 ... header label n | version
In the file contents:
• The header labels must appear in the order as shown in the table below. Impressions and clicks use the same
labels. Conversion files contain extra headers.
• If you don't have data for a particular column, populate that field with a NULL object or -1.
• Files must end with a version number. The current version is 1.1.
• Separate file headers and contents with the non-printing ASCII 001 character. If you cannot use ASCII 001, then
separate the headers and data with a tab delimiter. As these are non-printing characters, the syntax example above
shows a pipe "|" for display purposes only.
Field Labels
The table below lists and describes the column headers for your data file. Headers are case-sensitive and must
appear as ordered in the table. All data types are integers (INT) unless indicated otherwise.
Label
Description
Time-Stamp
A UTC date and time for the impression, click, or conversion event. Use the yyyy-dd-mm
hh:mm:ss format.
User-ID
Your ID for a site visitor, also known as the data provider unique user ID or DPUUID.
Label
Description
Advertiser-ID
The data source ID or integration code for your advertiser.
BU-ID
Business unit ID.
Campaign-ID
Campaign ID.
Creative-ID
Creative ID.
Site-ID
Site ID.
Placement-ID
Insertion-Order-ID
Insertion Order ID.
Tactic-ID
Tactic ID.
Vertical-ID
Quantity
The number of items sold in a conversion event.
303
For conversion data files only.
Revenue
Purchase or other conversion amount. Data type: Float.
Other-Data
URL of the conversion landing page. Data type: String.
Event-Type
Conversion type. Indicates whether a conversion is matched or not. Options include:
• 0: Impression
• 1: Click
• -1: Unattributed or unknown
Version
A required version number that appears at the end of every row in an impression, click,
or conversion data file. The current version is 1.1.
Delivery Methods for Data Files
Upload your impression, click, or conversion data files to an Amazon S3 directory for your Audience Manager
account. Refer to this section for information about delivery/directory paths, file processing times, and updates.
Delivery Path Syntax and Examples
304
Data is stored in a separate namespace for each customer in an Amazon S3 directory. The file path follows the
syntax shown below. Note, italics indicates a variable placeholder. Other elements are constants or keys and do
not change.
Syntax: .../log_ingestion/pid=AAM ID/dpid=d_src/logs/file type_yyyymmdd
The following table defines each of these elements in a file delivery path.
File Parameter
Description
.../log_ingestion/
This is the start of the directory storage path. You'll receive the full path when
everything is set up.
pid=AAM ID
This key-value pair that contains your Audience Manager customer ID.
dpid=d_src
This key-value pair contains the data source ID passed in on an event call. It
identifies the agency the data comes from and ties that data to a supporting
metadata file.
logs
A higher level directory for data files.
file type_yyyymmdd
A file type name that indicates what sort of data it contains and a delivery
timestamp.
Sample Upload Path and File Name
When you upload a file, the path will look similar to this:
.../log_ingestion/pid=1234/dpid=567/logs/impressions_20150902
File Processing Times and Updates
Data files are processed twice daily, at 04:30 UTC and 17:30 UTC. If you miss these deadlines, your file will be
processed the next day.
To update your data, send in a file that contains all of the impressions, clicks, or conversions for a particular day. In
this case, a day is the 24-hour period from one midnight to the next. As a best practice, you may want to use UTC
time to define your day interval.
Next Steps
Review the requirements for naming and creating metadata files. To get started, see Overview and Mappings for
Metadata Files
Overview and Mappings for Metadata Files
A metadata file links numeric IDs with names you can read and understand. The Advertiser Analytics reports
display readable names in the various report options menus.
Contents:
• Overview
• File Mappings
305
• How Event Call IDs Shape File Names, Contents, and Delivery Paths
Overview
A review of metadata and how it's used. A metadata file must be accompanied by a data file. The metadata file
contents match data file information to related, human-readable labels in the report menus. For more information,
see Data Files for Advertiser Analytics Reports.
Metadata Files Contain Data About Other Data
A metadata file contains information about other types of data. To help you understand how this works, let’s review
how Audience Manager receives data. During an impression or click event, Audience Manager receives data in an
URL string known as an event call. The event call organizes information into sets of defined key-value pairs. The
values in a key-value pair contain of numeric data. The metadata file contains names and other readable information
corresponding to the ID in each key-value pair.
Metadata Links IDs to Readable Names
The metadata file is required to tie a numeric ID to a readable name. As an example, say an event call contains a
creative ID in a key-value pair like this: d_creative:1234. Without a metadata file, this creative would show up as
1234 in an options menu. However, a properly formatted metadata file can tie this creative to back to a real name
like “Advertiser Creative A,” which is a name you can read and recognize in a report.
When Do You Need a Metadata File
First, a metadata file, and all of the parameters listed below, are required in an event call when you want to use the
Advertiser Analytics Reports.
Second, you need a metadata file if you’re sending your own data to Audience Manager or if you want to see data
in the reports from other providers we’re not integrated with. For example, Audience Manager has an integration
with Google’s Double-click Campaign Manager (DCM). Because of this relationship, Audience Manager can associate
IDs with names and descriptions used by the report options. Without an integration, we can still ingest data, but the
report options will show numeric IDs instead of descriptive name.
306
File Mappings
The following table lists the key-value pairs that hold data used by the Advertising Analytics reports. If you need
to use a metadata file, it would contain human-readable information that corresponds to the values in these key-value
pairs. The values for these keys accept integers only (data type INT). Note, italics indicates a variable placeholder.
Other elements are constants or keys and do not change.
Important: If you're using the Advertising Analytics reports, all of these values are required in the event
call.
Report Option
Metadata Key-Value Pairs
Advertiser
d_adsrc = data source ID or integration code
This is the advertiser's data source ID or integration code provided when creating
a data source. See Create a Data Source.
Business Unit (BU)
d_bu = business unit ID
Campaign
d_campaign = campaign ID
307
Report Option
Metadata Key-Value Pairs
Creative
d_creative = creative ID
Exchange
Accepts 2 different key-value pairs:
• d_exchange = ID for the exchange that served the ad
• d_site = ID for the site an ad served on
Insertion Order (IO)
d_io = insertion order ID
Platform
d_src = data source ID
This is the data source ID for the platform providing metadata information (e.g.,
DFA, Atlas, GBM, MediaMath, etc.).
Tactic
d_tactic = tactic ID
Vertical
d_vert = vertical ID
How Event Call IDs Shape File Names, Contents, and Delivery Paths
The IDs passed in by these key-value pairs help create the metadata file name and its contents. The following
sections and illustrations demonstrate how this works. These examples build a file that contains the name of a
creative in a campaign, but other combinations are possible.
Event Call
In this example we'll create a metadata file that brings creative names in to an Advertiser Analytics report. To do
this, we need to extract creative, campaign, and data source IDs from an event call.
File Name
308
The file name is based on the creative, campaign, and data source IDs. In this case, compare the differences here
between the key-value data in an event call and how it's used in a file name.
In a file name:
• The data source key changes to dpid from d_src.
• The creative and campaign IDs represent a category rather than an actual identifier.
See Naming Conventions for Metadata Files.
File Contents
In this example, the file contents reflect the creative and campaign IDs passed in on the event call. The new element
here is a readable name. Once processed, the name in this file will appear as an option in the Creative menu of an
Advertiser Analytics report.
See Content Format for Metadata Files.
File Delivery
309
After you name and add data to a file, you send it to an Amazon S3 storage directory provided by Audience Manager.
See Delivery Methods for Metadata Files and Status Updates for Metadata Files.
Naming Conventions for Metadata Files
Name your Advertising Analytics metadata file according to these specifications.
Syntax and ID Categories
The following syntax defines the structure of a well-formed metadata file name. Note, italics indicates a variable
placeholder. The other elements are constants and do not change.
Syntax: yyyymmdd_parentID_childID
In the name syntax, you'll notice a parent ID variable. Don't confuse it with the parent ID used in the metadata file
contents. These 2 variables seem similar, but they represent different things:
• In the file name, the parent ID corresponds to a category like "campaign" (ID 1), "placement" (ID 3), or "tactic" (ID
9), etc.
• In the file body, the parent ID is the actual ID of the object that the contents belong to. For example, if your file
contains creatives that are part of a campaign, the parent ID is the actual ID of the campaigns these creatives
belong to.
Metadata File ID and Categories
In the metadata file name, the parent and child IDs are identifiers that classify the type of data in a file and place it
into a hierarchy. You can tag the parent and child elements in file name with the following category IDs:
• 0: No parent
• 1: Campaign
• 2: Creative
• 3: Placement
• 4: Exchange
• 5: Site
• 6: Advertiser (if using integration codes in a data source)
• 7: Insertion Order (IO)
• 8: Vertical (i.e., a specific industry or business category like "computers," "automobiles," "real estate," etc.)
• 9: Tactic
• 10: Business unit or brand
Example
Let's take a look at how you would use these IDs in a metadata file name. As an example, say your data file consists
of campaign creatives. In this case, the campaign is a parent object and the creatives are child objects because
they belong to, or are contained by, the campaign. As a result, you'd choose the following IDs for the metadata file
name:
• Parent ID: 1
• Child ID: 2
Your metadata file name would look like this: 20150827_1_2
Sometimes, you might have data that does not belong to a parent object. Whenever this is the case, select ID 0 for
the parent ID. In this case, your file title would look like this: 20150827_0_2.
310
Content Format for Metadata Files
Format the contents of your Advertising Analytics metadata file according to these specifications.
Syntax
The following syntax defines the structure of well-formed contents in a metadata file. Note, italics indicates a variable
placeholder.
Syntax: content ID | name | parent ID
In the contents syntax, you'll notice a parent ID variable. Don't confuse it with the parent ID used in the metadata
file name. These 2 variables seem similar, but they represent different things. In the file name, the parent ID
corresponds to a category like "campaign" (ID 1), "placement" (ID 3), or "tactic" (ID 9), etc. In the file body:
• The parent ID is the numeric ID of the object that the file contents belong to. For example, if your file contains
creatives in a campaign, this value is the campaign ID.
• If your file content does not have a parent ID, then use the NULL object (i.e., the non-printing programming object)
or -1. You would use NULL or -1 when the parent ID in the file name is set to ID 0.
Separate File Entries With ASCII 001 or Tab
The non-printing ASCII 001 character is the preferred delimiter for separating contents in your file. If you cannot use
ASCII 001, then separate file contents with a tab delimiter. As these are non-printing characters, the syntax example
above shows a pipe "|" for display purposes only.
Examples
Let's take a look at how you would structure content in a metadata file. Part of this structure depends on the type of
information categorized by the parent ID the file title.
With a Parent Object
Let's say you want to populate the creative drop down menu with creative names from a particular campaign. In this
case, your metadata file name would include ID 1 (campaign) and ID 2 (creative). Following the content syntax, your
metadata file would contain the creative ID, creative name, and actual campaign ID.
//file title
20150827_1_2
//creative IDs, names, and campaign IDs
111 Creative A 456
222 Creative B 456
333 Creative C 987
Without a Parent Object
Sometimes, the content in a metadata file does not have a parent object. In these cases, the:
• File name parent ID is 0.
• File content parent ID is the non-printing NULL object (preferred) or -1.
//file title
20150827_0_2
//file contents: creative IDs, names, and campaign IDs
888 Creative X NULL
777 Creative Y NULL
666 Creative Z NULL
311
Delivery Methods for Metadata Files
Send or update metadata files by sending them to a special Amazon S3 directory for your Audience Manager account.
Refer to this section for information about delivery/directory paths, file processing times, and updates.
Delivery Path Syntax and Examples
Data is stored in separate namespace for each customer in an Amazon S3 directory. The file path follows the syntax
shown below. Note, italics indicates a variable placeholder. Brackets [ ] indicate optional parameters. The other
elements are constants and do not change.
Syntax: .../log_ingestion/pid=AAM ID/dpid=d_src/[meta|status]/yyyymmdd_parent ID_child ID
The following table defines each of these elements in a file delivery path.
File Parameter
Description
.../log_ingestion/
This is the start of the directory storage path. You'll receive the full path when
everything is set up.
pid=AAM ID
This key-value pair that contains your Audience Manager customer ID.
dpid=d_src
This key-value pair contains the data source ID passed in on an event call. The
data source ID is the value that ties all the contents in your file to the actual
data it belongs to.
For example, say you have a creative with the ID 123 and the name "Advertiser
Creative A." As an event call only passes in the ID you need to include
"Advertiser Creative A" in the metadata file. The campaign and creative belong
to a data source. The data source ID is what ties these together and lets us
accurately associate file contents to an ID sent in on an event call. See How
Event Call IDs Shape File Names, Contents, and Delivery Paths.
• meta
• meta is a file upload/storage directory.
• status
• status is a path to a directory that holds success or failure information about
your processed files. After your file is processed, you'll see a .info file with
yyyymmdd timestamp title. Status files contain data in a JSON object. See
Status Updates for Metadata Files.
yyyymmdd_parent ID_child ID
This is the file name. See Naming Conventions for Metadata Files.
Sample Upload and Status Paths
To upload a metadata file or to check its status, the file paths will look similar to these:
• Upload path: /log_ingestion/pid=1234/dpid=567/meta/20150827_1_2
• Processing status path: /log_ingestion/pid=1234/dpid=567/status/20150827.info.
312
File Processing Times and Updates
Metadata files are processed twice daily, at 04:30 UTC and 17:30 UTC. If you miss these deadlines, your file will
be processed the next day.
To update your metadata records, just send a file that contains new information. You don't need to send full updates
each time.
Status Updates for Metadata Files
The S3 status directory holds a .info file with success and failure information about your uploaded files. The file
contains JSON-formatted data with status results in an array.
The contents of your .info fill will look similar to this example.
//sample file path
/log_ingestion/pid=1234/dpid=567/status/20150827.info
//sample contents
{
"Files": [
{
"FileChecksumMD5": "94b821082daff242e452c0d8796b08f0",
"FileName": "20141112_4_2",
"MetadataType": "Creative",
"Parent": "Site",
"Status": "SUCCESS",
"Description": ""
},
{
"FileChecksumMD5": "db79f148e6a635629701c13a7bcc8db0",
"FileName": "20141112_0_4",
"MetadataType": "Site",
"Parent": "None",
"Status": "FAILURE",
"Description": "Invalid format."
}
],
"Summary": {
"Day": "2014-11-12",
"ProcessingTimeRFC2822": "Wed, 10 Dec 2014 21:07:58 -0000",
"ProcessingTimestampPOSIX": 1418263678,
"TotalByteSize": 547712,
"TotalNumberFiles": 2,
"NumberSuccess": 1,
"NumberFailure": 1,
"GlobalStatus": "FAILURE"
}
}
Metadata Key-Value Pairs Defined
The following tables lists and defines the keys in the Files and Summary sections of a metadata status file.
Keys in the Files Array
Key
Description
Description
Contains a brief description of why processing failed. This
field is empty when processing is successful.
313
Key
Description
FileByteSize
File size in bytes.
FileChecksumMD5
The MD 5 checksum for the metadata file uploaded to your
meta directory.
FileName
The name of the metadata file uploaded to your meta directory.
MetadataType
The human-readable name for the type of data your file
contains. It is based on the child ID in your file name.
Parent
The human-readable name for the type of data your file
contains. It is based on the parent ID in your file name.
Status
Returns 2 text values that describe the processing status of
your metadata file:
• SUCCESS
• FAILURE
Keys in the Summary Object
Key
Description
Day
File processing date in yyyy-mm-dd format.
GlobalStatus
Returns 2 text values that describe the processing status for all your
files for an entire day:
• SUCCESS
• FAILURE
NumberFailure
The number of files that were processed unsuccessfully.
NumberSuccess
The number of files processed successfully.
ProcessingTimeRFC2822
Returns a human-readable time stamp for processing start times.
ProcessingTimePOSIX
A UNIX time stamp for processing start times.
TotalByteSize
Total number of bytes for all your metadata files for the day.
314
Key
Description
TotalNumberFiles
Total number of all your files processed for the day.
DCS Integration
This material describes the attributes and syntax used to send data to the Audience Manager 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 Manager user interface.
Variable Prefix Requirements
Defines the variable prefixes that identify the type of data passed in to the DCS.
Identifying Audience Manager 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.
d_
A system variable used by Audience Management.
h_
An HTTP header variable.
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_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 Manager variables. In most cases, none of these are required.
Variable
Definition
d_cb
Encloses the JSON response in a callback wrapper.
d_cid
Contains a data provider ID assigned by Audience Manager and an associated unique user
ID in a single key-value pair. d_cid replaces d_dpid and d_dpuuid, which are considered
deprecated, but still supported. See CID Replaces DPID and DPUUID.
315
Variable
Definition
d_cid_ic
Contains an integration code and an associated unique user ID in a single key-value pair.
d_cid_ic replaces d_dpid and d_dpuuid, which are deprecated, but still supported. See CID
Replaces DPID and DPUUID.
d_dpid
Deprecated. See d_cid and d_cid_ic.
d_dpuuid
Deprecated. See d_cid and d_cid_ic.
d_dst=1
Prompts the DCS to return destination inside the JSON response.
d_mid
Specifies the unique, persistent visitor identifier returned by the Marketing Cloud ID service.
For more information about the MID, see Cookies and the Marketing Cloud ID.
d_ptfm
Allows Audience Manager to distinguish mobile requests from desktop requests. Supported
values include:
• ios
• 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 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 alias.demdex.net/event?key1=val1[,val2][&key2=val2]...
Note: In key-value pairs, enclose the string values in double quotes (e.g., age="41 to 55"). For more
information, see Key-Value Pairs Explained.
Parameters
Input
Italics indicate a variable placeholder. You would substitute that with a real value when making an actual call.
316
Field Name
Description
domain
Domain alias assigned by Audience Manager (e.g., my_domain.demdex.net).
alias.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
Manager or customer attribute.
val
A variable value that belongs to a set defined by the key in a key-value pair.
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_interests=photography&c_camera=canon&
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.
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
An ID (integer) that identifies the geographic region of the Data Collection
Server (DCS). Region IDs include:
• 3: Southeast Asia (Singapore)
Parameter
317
Description
• 4: South America (São Paulo, Brazil)
• 6: Europe (Dublin, Ireland)
• 7: US East Coast (Virginia, USA)
• 8: South Pacific / Oceana (Sydney, Australia)
• 9: US West Coast (Oregon, USA)
• 10: US Central (Texas, USA)
• 11: Asia (Tokyo, Japan)
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.
ts:
Timestamp in Unix seconds (UTC).
u: and UUID:
Unique user ID assigned by Audience Manager (long integer).
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.
Format Type
Definition
Example
Standard
Organizes data into separate key-value pairs. Each key1=val1&key1=val2& key2=val2
key 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 values with a specific indicator.
key1=val1,val2,val3
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 Manager requires the following delimiters and separators:
318
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
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
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.
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
319
DMA ID
Marketing Area
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
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
320
DMA ID
Marketing Area
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
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
321
DMA ID
Marketing Area
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)
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
322
DMA ID
Marketing Area
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
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
323
DMA ID
Marketing Area
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
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
324
DMA ID
Marketing Area
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
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
325
DMA ID
Marketing Area
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
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 Manager 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.
Race Conditions and Error Handling
Describes how to prevent race conditions and DCS error handling.
Preventing Race Conditions
326
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 Manager or partner level.
• Comes from an invalid/unselected geographic region.
• Disables browser cookies (either all or third-party).
DCS Error Codes, Messages, and Examples
A list and examples of error codes and messages generated by the Data Collection Servers (DCS).
Contents
DCS Error Codes
Sample Error Messages
DCS Error Codes
System Errors
Code Error Message
Description
0
This is a catch-all error that handles events that is not covered by the
other error handlers. Troubleshooting this error is difficult. It can be
caused by a variety of unknown actions or events.
Unspecified error
If you receive this error, try your DCS request again. Contact your
Adobe representative if the problem persists.
1
Could not find config hostname:
hostname here
2
Invalid d_orgid value (could not find The Organization ID is incorrect.
a config for this org id)
Check your ID and try the request again. If you do not know or have
your Organization ID, see the "Administration Page" section in
Marketing Cloud Administration for information about how to find it.
Integration Errors
The host name sent in the request has not been set up by our partner
provisioning team. Contact your Adobe representative if you see this
error message.
327
Code
Message
100
Could not retrieve host name An API call did not send the host HTTP header in the request.
for the request
Add host header to the call and try again. Note, most browsers and API
clients do this automatically.
101
Invalid marketing cloud id
passed in
The DCS call contains an invalid Marketing Cloud ID.
Invalid aam id passed in
request
The DCS call contains an invalid Audience Manager ID.
All customer ids are invalid
All of the customer IDs in your call are invalid. Check your IDs and try again.
102
104
Description
Check the d_mid= key-value pair in the header string. Make sure you're
passing in the correct Marketing Cloud ID and try the request again.
Check the d_uuid= key-value pair in the header string. Make sure you're
passing in the correct Audience Manager ID and try the request again.
Opt Out Errors
Code
Message
Description
171
Encountered opt out tag
for id
A customer has opted-out from receiving interest-based advertising.
172
Blocked cookies
Returned when the user's browser blocks third-party cookies.
173
Encountered trust
relationship via NAI
The user has initiated an opt-out process through NAI.
199
Requests from this country Based on the IP address, the DCS blocks requests from the following
are not allowed
countries:
• Cuba (CU)
• Iran (IR)
• North Korea (KP)
• Sudan (SD)
• Syria (SY)
Sample Error Messages
The DCS returns error codes and messages in a JSON object or in an X-Error returned in the header of an HTTP
response.
JSON Error
{
"errors":[
{
"code":101,
"msg":"Invalid marketing cloud id passed in"
328
},
{
"code":102,
"msg":"Invalid aam id passed in request"
}
]
}
X-Error
Error codes appear in the X-Error header like this, X-Error: 101,102.
Implementing Audience Manager
This section outlines and explains the processes related to getting started with the Audience Manager data
management platform (DMP). This section is designed to help business teams, project managers, and technology
managers understand the Audience Manager implementation process.
Implementation Overview
Getting started with Audience Manager 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 Manager
Our Partner Solutions and Account Management teams will work closely with you before, during, and after the
implementation process.
Audience Manager 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
Activity
329
Purpose/Description
Status reports and project team Establish and maintain clear communication
calls
about 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
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.
Activity
Purpose/Description
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 Business and technical teams
of that data
• Discover sources of your first-party, second-party,
and third-party data
Find destinations
Discover if the client sends data to other ad servers, Business teams
DSPs, networks, or exchanges
Breakout sessions
Refine business requirements and needs
Business teams
Follow-up communication
Regular communication for follow-up and
development purposes
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.
330
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.
Activity
Purpose/Description
Participants
Prepare a data collection
strategy
Work with Adobe technical teams to build a
data-collection 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
Verify functionality and
resolve bugs
Examine and communicate results, resolve bugs, and Technical teams
re-test
User training
Provide education and understanding about Audience Business teams
Manager features, tools, and reports
Deliverables for this phase can include:
• A completed and accepted data-collection plan
• End-to-end QA testing
• Basic instruction on Audience Manager 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.
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 features, tools, and reports
Follow-up
communications
Regularly scheduled communication to keep abreast of Business and technical teams
your user experience with Audience Manager
Tasks for this phase can include:
Business teams
331
• 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 Manager 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
The Audience Manager 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 Manager.
Contact us here for more information and to get started with Audience Manager.
Import DCM Data Files Into Audience Manager
Set up a Google group to bring your DoubleClick Campaign Manager (DCM) data files into Audience Manager. The
content in this section summarizes the integration process and provides you with links to DCM resources to help
you get started.
Integration summary
DCM is Google's replacement for DoubleClick for Advertisers (DFA). Similar to DFA, DCM customers can import,
view, and work with their data in Audience Manager. But, Audience Manager cannot directly access and import your
Data Transfer and Match Table files. To import these files, the burden of effort lies with the customer. However,
the set up procedure is well documented in the DoubleClick Campaign Manager Help. Also, you can review the
steps listed below to get started.
Caution: DCM data files contain data for all your advertisers or clients. If you need to omit specific clients,
then you must edit the files before making them available to Audience Manager.
Data transfer frequency and availability
Audience Manager checks for and transfers data once each day. Data is usually available in Audience Manager
after 24-hours.
332
Steps
1. Create a group.
Groups control access to your DCM data. Eventually, you'll invite and add Audience Manager to this group.
2. Verify your Google Cloud Storage status.
Google Cloud Storage contains the data bucket that holds your Data Transfer and Match Tables. You'll need
to setup a bucket or make sure your new group has access to an existing data storage bucket.
3. Get a data file URL.
Work with your DCM Account Manager or Platform Solutions Consultant. They will provide you with a URL to
your data files. And, Google might change the format for bucket and file names in future releases. Again, work
with your DCM Account Manager to make sure you're using the right formats.
4. Set bucket permissions.
The Cloud Storage Manager lets you control data sharing and bucket access. Give your group read access to
the bucket that contains your Data Transfer and Match Table files.
5. Set up data sharing.
Shared DCM user IDs are encrypted to protect privacy. Encryption adds 2 columns to the end of your Data
Transfer file, PartnerId1 and PartnerId2. These columns contain encoded user IDs specific to each company
that receives these files. As an authorized third-party, Audience Manager can receive DCM data, but cannot
decode the IDs. However, on the Audience Manager side, we know how the encoded IDs match our IDs. This
means we can match and synchronize users with confidence and accuracy. Note, you cannot import DCM files
into Audience Manager if you're already sharing data with 2 other third-party partners.
6. Invite Audience Manager to join the group.
After you create a group and give it access to a data bucket, invite Audience Manager to join the group. Send
an invitation email to [email protected]. Be sure to include the data file URL from step 3. Our internal teams
will work with you to verify access after accepting the invitation.
Real-Time Data Transfers With the DCS API
The Data Collection Server (DCS) is designed to receive raw data and signals about website visitors. It accepts
and returns data in sets of key-value pairs. With the right information, you can use DCS code as an API to send and
receive user data in real-time. This guide provides instructions on how to use the DCS for real-time data transfers.
Common uses for DCS data
Real-time data transfers can help you customize landing pages or other interactions based on visitor interests. Some
common use cases include:
• On-site personalization: Tailor a visitor’s experience on your site by dynamically adding relevant content and calls
to action based on the segments they belong to.
• Improve customer service: Import Audience Manager segments into a CRM or other system through a
server-to-server data transfer. This data can provide call service or on-line chat operators with relevant, personalized
information about a customer.
Requirements: User IDs, region IDs
The DCS requires user IDs and region IDs to make real-time data transfers.
• The user ID is required because you need to associate data with a particular visitor.
• The region ID is required because user data is stored in data centers that are geographically closest to site visitors.
This strategy helps improve response times because your query goes directly to a data center that contains
information about that visitor. Other data centers may not have any information about a particular site visitor.
333
Currently, this guide covers How to recover the user and region IDs if you use the Visitor ID Service or from DCS
files you already receive as an Audience Manager customer.
We'll add new methods as they become available. Refer to the following sections to get started.
Get User IDs and Regions Through the Marketing Cloud ID Service
This section describes how to get started with the Marketing Cloud ID service, read the visitor cookie for the IDs
required to make real-time calls to the Data Collection Servers (DCS), and use an optional function to return the
visitor ID.
Contents:
Read the ID Service Cookie
Get the Marketing Cloud Visitor ID With getMarketingCloudVisitorID
Next Steps
Read the ID Service Cookie
The Marketing Cloud ID service assigns visitor and region IDs to users who come to your website. These IDs identify
users across all the solutions in the Marketing Cloud. They are required to make real-time calls to the DCS. If you're
using the ID service, you can extract this information from a cookie or by calling a function. Regardless of your status
as an ID Service customer, the steps in the table below will help you get started.
Task
Description
Check your Marketing Cloud
status
To use the ID service you need to have a Marketing Cloud account. If you have
a Marketing Cloud account, great!
If you're not part of the Marketing Cloud, then sign up. We'd love to have you
and there's always room for more. For instructions on how to set up an account,
see Core Services - Enabling Your Solutions.
Set up the ID service
The ID service consists of JavaScript code that gets put on each page you
want to use for data collection. See Standard Implementation Guide for more
information.
Read the ID service cookie
The ID service uses JavaScript to store the user and region ID in a cookie.You
can get the required user and region ID by reading the AMCV_###@AdobeOrg
cookie. The ### elements are placeholders. See the Cookies and the Marketing
Cloud ID for details. In the cookie, your code or app should look for these
key-value pairs:
• mid=user ID: This key-value pair holds the Marketing Cloud user ID.
• aamlh=region ID: This key-value pair holds the region ID (sometimes called
a location hint). See the region ID and host name table for a complete list of
regional IDs and server host names.
With this information, you can make real-time calls with the DCS API.
334
Task
Description
Return the Marketing Cloud ID
with a function
The function getMarketingCloudVisitorID returns the Marketing Cloud visitor
ID. It is used by customized solutions that require this information.
Get the Marketing Cloud Visitor ID With getMarketingCloudVisitorID
Another way to get the visitor ID is with the function, getMarketingCloudVisitorID. When invoked,
getMarketingCloudVisitorID queries the ID service and returns an ID. getMarketingCloudVisitorID accepts
the optional callback argument as shown:
var analyticsID = visitor.getAnalyticsVisitorID(callback)
How to use callback
callback is optional. This function works without it, but returns an ID only when a visitor has a Marketing Cloud
cookie in their browser. If the visitor cookie is missing or a visitor doesn't have an ID, the function returns an empty
() object. This can happen even after the page loads and the visitor receives a new ID. To avoid this, callback
forces this function to check for a visitor ID after the code loads. Without callback, the visitor ID function won't
return an ID even if it's written to the user's browser later.
Next Steps
Once you have the user and region ID, you can start sending and receiving DCS data. To get started, see Making
DCS API Calls.
Get User IDs and Regions From a DCS Response
As an Audience Manager or Marketing Cloud customer, you're probably receiving DCS log files.This section describes
how to parse the DCS file for the visitor and region IDs required to make real-time calls to the DCS.
The DCS log files contain extensive data about your site visitors. When parsing these files for the visitor and region
ID, look for the uuid and dcs_region parameters. The user ID is required to identify and associate data with a
particular visitor. The region ID is required because user information is stored in data centers that are geographically
closest to site visitors. This strategy helps improve response times because your query goes directly to a data center
that contains information about that visitor. Other data centers may not have any information about a particular site
visitor. These appear near the end of the fille and store data in the form of key-value pairs.
Parameter
Data type
"uuid":user ID
String
"dcs_region":region ID
Int
Example
"uuid":"123456789"
"dcs_region":9
See the DCS region ID and host name table for
a complete list.
335
As shown in the following example, you can find the user and region IDs at the end of the file. Note, this is sample
data only. It has been truncated for brevity and JSON-formatted for clarity.Your actual log files will arrive unformatted
and will contain different information. See the UUID and the region ID at the end of the file.
{
"stuff":[
],
"ibs":[
{
"id":"269",
"ttl":10080,
"tag":"img",
"url":[
"//sync.mathtag.com/sync/img?mt_exid=10004&
mt_exuid=70208690515112302850772373915999266508&redir=
http%3A%2F%2Fdpm.demdex.net%2Fibs%3Adpid%3D269%26dpuuid%3D[MM_UUID]
%26ddsuuid%3d70208690515112302850772373915999266508"
]
},
{
"id":"771",
"ttl":20160,
"tag":"img",
"url":[
"//cm.g.doubleclick.net/pixel?google_nid=adobe_dmp&google_cm"
]
}
],
"dpcalls":[
{
"id":"21",
"ttl":14400,
"tag":"js",
"url":[
"//adadvisor.net/adscores/g.json?sid=9233633946"
],
"callback":{
"obj":"Targus",
"fn":"parseInfo",
"key":"targus",
"tag":"img",
"url":"//dpm.demdex.net/demdot.jpg?et:dpm|dpid:21|data:"
}
},
{
"id":"22",
"ttl":14400,
"tag":"js",
"url":[
"//api.bizographics.com/v1/profile.json?api_key=6332f8b7316a4d1284e9c1217a367347&callback=Demdex.parseBizo"
],
"callback":{
"obj":"Demdex",
"fn":"parseBizo",
"key":"bizographics",
"tag":"img",
"url":"//dpm.demdex.net/demdot.jpg?et:dpm|dpid:22|data:"
}
}
],
"uuid":"70208690515112302850772373915999266508",
"dcs_region":9
}
336
DCS prefixes and variables
Many of the variables, keys, and parameters used by the DCS are prefixed by a special character. The DCS uses
these prefixes to identify the type of data passed in on a request. For more information about variable prefixes, see
Variable Prefix Requirements.
The DCS also supports unique variables you can add to a query. They help with formatting or hold special IDs. For
a complete list of DCS variables, see Supported Variables.
Next Steps
Once you have the user and region ID, you can start sending and receiving DCS data. To get started, see Making
DCS API Calls.
Making DCS API Calls
Once you have user and region IDs, you can make real-time calls to the DCS. Refer to this section for syntax and
examples.
Requesting data: Syntax and examples
The following syntax defines the structure of a well-formed DCS request. Note, italics indicate a variable placeholder.
You would substitute that with a real value when making an actual call. Other elements are constants and do not
change.
Note: Syntax and sample code may include artificial line breaks to help make long strings easier to read.
Syntax
"Host:domain_alias.demdex.net" "https://DCS host name.demdex.net/event?d_rtbd=json&d_jsonv=1&
d_uuid=user ID"
Example
"Host:foo.demdex.net" "https://usw2.demdex.net/event?d_rtbd=json&d_jsonv=1&
d_uuid=123456789"
See the DCS response for an example.
Request parameters
Parameter
Description
domain_alias.demdex.net
This is the host header element. It contains the domain
alias assigned to your company by Audience Manager.
DCS host name.demdex.net
The regional address of the DCS server. See the region
ID and host name table below.
event
Defines the start of a URL string that contains query
parameters or data passed in as key-value pairs.
d_rtbd=json
A request that returns data in JSON. Required.
337
Parameter
Description
d_jsonv=1
Returns data in the JSON v1 format.
d_uuid=Audience Manager user ID
This is the unique user ID key that holds the Audience
Manager user ID value in a key-value pair.
Use d_uuid if you're passing in the Audience Manager
user ID.
This is the unique user ID key that holds the Marketing
Cloud user ID value in a key-value pair.
d_mid=Marketing Cloud user ID
Use d_mid if you're passing in a Marketing Cloud ID
captured from the Visitor ID Service. For more information
about the MID, see Cookies and the Marketing Cloud ID.
DCS region IDs, locations, and host names
The regional host name is required because the DCS stores information in data centers that are geographically
closest to site visitors. Other DCS servers may not have data about a particular user. Sending a request to the wrong
DCS is inefficient and can delay your response. To make a DCS request, match the region ID to its corresponding
regional host name and form your query with the proper host name. You can capture the region ID from the Visitor
ID Service or a DCS response. The following table lists the available host names by DCS region ID.
Region ID (dcs_region)
Location
Host name
3
Singapore
apse.demdex.net
4
São Paulo, Brazil
sae.demdex.net
6
Dublin, Ireland
irl1.demdex.net
7
Virginia, USA
use.demdex.net
8
Sydney, Australia
apse2.demdex.net
9
Oregon, USA
usw2.demdex.net
11
Tokyo, Japan
tyo3.demdex.net
Sending data: Syntax and examples
See URL format for Passing Data to the DCS.
DCS prefixes and variables
Many of the variables, keys, and parameters used by the DCS are prefixed by a special character. The DCS uses
these prefixes to identify the type of data passed in on a request. For more information about variable prefixes, see
Variable Prefix Requirements.
The DCS also supports unique variables you can add to a query. They help with formatting or hold special IDs. For
a complete list of DCS variables, see Supported Variables.
338
Receiving Audience Data
Receive audience data from Audience Manager.
ID Synchronization for Outbound Data Transfers
Describes the syntax and parameters used in the initial HTTP call to synchronize user IDs between a Audience
Manager and a third-party data provider. ID synchronization can begin after you send your data taxonomy to Audience
Manager.
Purpose of ID Synchronization
ID synchronization is the first step in the outbound, asynchronous data transfer process. In this step, Audience
Manager 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 Manager 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 Manager).
<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:
• Accepts data in JSON format.
• Provides a URL that can be used by the POST call to return data.
• Accept secure HTTPS data transfers. Audience Manager will not send this file with the unsecure HTTP protocol.
339
Frequency
This data transfer method can send data in near real-time as users qualify for segments. Additionally, this method
can send batches of offline or onboarded data as frequently as every 12-hours.
Required Responses
By default, the recipient server must return the 200 OK code to indicate successful receipt. Other codes will be
interpreted as failures. This response is expected within 3000 milliseconds. In response to a failure, Audience
Manager will make 1 retry attempt only.
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.
User_DPID
Integer
An ID that indicates if the file contains Android or iOS IDs. Uses the
following ID values:
• Android IDs (GAID): 20914
• iOS IDs (IDFA): 20915
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 Manager UUID.
DataPartner_UUID
String
Data partner UUID. Leave blank if your data partner does not have a
UUID.
AAM_Regions
Array
The Audience Manager region ID where we've seen this device. For
instance, if the device had some activity in Paris (Europe), the region ID
would be [6]. Please also refer to the index of all Audience Manager region
IDs.
Segments
Array
An array of segment objects.
Segment_ID
Integer
The Audience Manager segment ID.
Status
Integer
Defines the status of a user in the segment. Accepts the following:
• 1: Active (default)
Parameter
Data Type
340
Description
• 0: Inactive, opted-out, or unsegmented.
Users are unsegmented when they are:
• Removed from a segment based on the segment rule.
• Removed from a segment based on the segment's time-to-live interval.
• Moved to an inactive state if they have not been seen for the last
120-days.
All partner IDs that are synced to an Audience Manager ID will receive
the "Status":"0" flag when a user is unsegmented.
DateTime
DateTime
Time that a site visitor qualified for the trait.
Security
You can secure your real-time outbound data transfer process by encrypting HTTP requests with private keys or by
having Audience Manager authenticate through the OAuth 2.0 protocol.
Code Sample
A real-time data response can look similar to the following:
{
"ProcessTime": "Wed Jul 27 16:17:42 UTC 2016",
"User_DPID": "12345",
"Client_ID": "74323",
"AAM_Destination_Id": "423",
"User_count": "2",
"Users": [{
"AAM_UUID": "19393572368547369350319949416899715727",
"DataPartner_UUID": "4250948725049857",
"Segments": [{
"Segment_ID": "14356",
"Status": "1",
"DateTime": "Wed Jul 27 16:17:22 UTC 2016"
},
{
"Status": "0",
}
]
},
{
"AAM_UUID": "0578240750487542456854736923319946899715232",
"Segments": [{
"Status": "1",
},
{
"Status": "1",
}]
}]
}
341
Digitally Signed HTTP Requests
Audience Manager requires the HTTP server-to-server requests to be digitally signed for validity. This document
describes how you can encrypt HTTP requests with private keys.
Overview
Using a private key provided by you and shared with Audience Manager, we can digitally sign the HTTP requests
that are sent between IRIS and your HTTP server. This ensures:
• Authenticity: only the sender that has the private key (IRIS) can send valid HTTP(S) messages to the partner.
• Message integrity: with this approach, even on HTTP, you are protected from a man in the middle attack where
the messages get distorted.
IRIS has built-in support to rotate the keys with zero downtime, as shown in the Rotating the private key section
below.
Information you need to provide
For an HTTP real-time server-to-server destination, contact your Audience Manager consultant and specify:
• The key used to sign the request.
• The name of the HTTP header that will hold the generated signature (X-Signature in the example header below).
• Optional: the type of hash used for the signature (md5, sha1, sha256).
* Connected to partner.website.com (127.0.0.1) port 80 (#0)
> POST /webpage HTTP/1.1
> Host: partner.host.com
> Accept: */*
> Content-Type: application/json
> Content-Length: 20
> X-Signature: wxa2ByMWhhP328EvHQsVlOD5jTc=
POST message content
How it works
1. IRIS creates the HTTP message to be sent to the partner.
2. IRIS creates a signature based on the HTTP message and the private key communicated by the partner.
3. IRIS sends the HTTP(S) request to the partner. This message contains the signature and the actual message,
as seen in the example above.
4. The partner server receives the HTTP(S) request. It reads the message body and the signature received from
IRIS.
5. Based on the message body received and the private key, the partner server recalculates the signature. See the
How to calculate the signature section just below on how to achieve this.
6. Compare the signature created on the partner server (receiver) with the one received from IRIS (sender).
7. If the signatures match, then the authenticity and message integrity have been validated. Only the sender,
who has the private key, can send a valid signature (authenticity). Moreover, a man in the middle can't modify
the message and generate a new valid signature, since they don't have the private key (message integrity).
342
How to calculate the signature
HMAC (Hash-based message authentication code) is the method used by IRIS for message signing. Implementations
and libraries are available basically in every programming language. HMAC has no known extension attacks. See
an example in Java below:
// Message to be signed.
// For GET type HTTP destinations, the message used for signing will be the REQUEST_PATH +
QUERY_STRING
// For POST type HTTP destinations, the message used for signing will be the REQUEST_BODY.
// String getData = "/from-aam-s2s?sids=1,2,3";
String postData = "POST message content";
// Algorithm used. Currently supported: HmacSHA1, HmacSHA256, HmacMD5.
String algorithm = "HmacSHA1";
// Private key shared between the partner and Adobe Audience Manager.
String key = "sample_partner_private_key";
// Perform signing.
SecretKeySpec signingKey = new SecretKeySpec(key.getBytes(), algorithm);
Mac mac = Mac.getInstance(algorithm);
mac.init(signingKey);
byte[] result = mac.doFinal(postData.getBytes());
String signature = Base64.encodeBase64String(result).trim();
// signature = wxa2ByMWhhP328EvHQsVlOD5jTc=
The RFC for the HMAC hash implementation is http://www.ietf.org/rfc/rfc2104.txt. A test site:
http://asecuritysite.com/encryption/hmac (note that you have to convert the hex encoding to base64).
343
Rotating the private key
For security reasons, it's recommended to periodically rotate the private key. It is up to you to decide the private key
and the rotation period. In order to achieve the key rotation with zero downtime, IRIS supports adding multiple
signature headers. One header will contain the signature generated with the old key, another header will contain
the signature generated using the new private key. See below the steps in detail:
1. Partner communicates the new private key to Adobe Audience Manager.
2. IRIS will start sending two signature headers (one using the old key, the other one using the new key).
3. Once you start receiving both headers, you can choose to discard the old key and only look at the new signature.
4. The old key is removed from Audience Manager and IRIS only sends the new signature header. The keys have
been rotated.
Data used for signing
For GET type destinations, the message used for signing will be the REQUEST_PATH + QUERY STRING (e.g.
/from-aam-s2s?sids=1,2,3). IRIS does not take into account the hostname or HTTP headers - these can be modified
/ misconfigured along the path or reported incorrectly.
For POST type destinations, the message used for signing is the REQUEST BODY. Again, headers or other request
parameters are ignored.
OAuth 2.0 Integration for Real-Time Outbound Transfers
When publishing segments to the partner destination via a realtime server-to-server integration, Audience Manager
can be set up to authenticate using OAuth2.0 when making the requests. This presents the ability to issue
authenticated requests from Audience Manager to your endpoint.
Authentication Flow
The Adobe Audience Manager OAuth 2.0 authentication implementation is based on the Client Credentials grant
flow and follows these steps:
1. You must provide us with:
• The OAuth 2.0 endpoint that generates the authentication token.
• The credentials used to generate a token;
2. An Audience Manager consultant sets up the destination using the information you provided.
3. Once a segment is mapped to this destination, our real-time data transfer system, IRIS, makes a POST request
to the token endpoint to exchange the credentials for a bearer token.
4. For each segment publishing request to the partner endpoint, IRIS uses the bearer token to authenticate.
344
Requirements
As an Audience Manager partner, the following endpoints are needed to receive authenticated requests:
Endpoint 1 used by IRIS to obtain a bearer token
This endpoint will accept the credentials provided at step 1 and generate a bearer token which will be used on
subsequent requests.
• The endpoint must accept HTTP POST requests.
• The endpoint must accept and look at the Authorization header. The value for this header will be: Basic
<credentials_provided_by_partner>.
• The endpoint must look at the Content-type header and validate that its value is
application/x-www-form-urlencoded ; charset=UTF-8.
• The body of the request will be grant_type=client_credentials.
Example request made by Audience Manager to the partner endpoint in order to obtain a bearer token
POST /oauth2/token HTTP/1.1
Host: api.partner.com
User-Agent: Adobe Audience Manager Iris
Authorization: Basic
zq2LOO1CcYGrODS5nXiNHpEz97eCpVHAoMF8pAgCntXAzxp5uRV7DTAE2qtPLjhMQwrEX3O6MHV4S
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Content-Length: 29
Accept-Encoding: gzip
grant_type=client_credentials
Example response from the partner endpoint:
HTTP/1.1 200 OK
Status: 200 OK
Content-Type: application/json; charset=utf-8
...
Content-Encoding: gzip
Content-Length: 121
{"token_type":"bearer","access_token":"glIbBVohK8d86alDEnllPWi6IpjZvJC6kwBRuuawts6YMkw4tZkt84rEZYU2ZKHCQP3TT7PnzCQPI0yY"}
345
Endpoint 2 used by IRIS to publish segments using the bearer token
Audience Manager sends data to this endpoint in near real-time as users qualify for segments. Additionally, this
method can send batches of offline or onboarded data as frequently as every 12 hours.
The bearer token generated by endpoint 1 is used to issue requests to this endpoint. The Audience Manager real-time
data transfer system, IRIS, constructs a normal HTTPS request and includes an Authorization header. The value
for this header will be: Bearer <bearer token from step 1>.
Example response from the partner endpoint:
GET /segments/aam HTTP/1.1
Host: api.partner.com
User-Agent: Adobe Audience Manager Iris
Authorization: Bearer
glIbBVohK8d86alDEnllPWi6IpjZvJC6kwBRuuawts6YMkw4tZkt84rEZYU2ZKHCQP3TT7PnzCQPI0yY
Content-Type: application/json
Accept-Encoding: gzip
{
"ProcessTime": "Wed Jul 27 16:17:42 UTC 2016",
"User_DPID": "12345",
"Client_ID": "74323",
"User_count": "2",
"Users": [{
"AAM_UUID": "19393572368547369350319949416899715727",
"Segments": [{
"Status": "1",
}
]
}]
}
Note: This request contains a standard payload (request content).
Important considerations
Tokens are passwords
The credentials presented by the partner and the tokens obtained by Audience Manager when authenticating using
the OAuth2.0 flow, are sensitive information and must not be shared to third parties.
SSL is required
SSL must be used In order to maintain a secure authentication process. All requests, including the ones used to
obtain and use the tokens must use HTTPS endpoints.
Batch Outbound Data Transfers
Audience Manager sends batch data to third-party content providers according to these specifications.
Outbound Data File Name: Syntax and Examples
Describes the required fields, syntax, and conventions used to name an outbound data file.
Note: The style elements (monospaced text, italics, brackets [ ] ( ), etc.) in this document indicate code
elements and options. See Style Conventions for Code and Text Elements for more information.
346
Syntax and File Name Elements
Outbound file names contain the following required and optional elements:
SYNC_TYPE_DID_DPID_SYNC_MODE_TIMESTAMP[-SPLIT_NUMBER].sync[.gz]
Parameters
The table defines the elements in an outbound data file name.
File Name Element
Description
SYNC_TYPE
Refers to the data transfer methods. Transfer methods include:
• FTP
• Amazon S3
• HTTP
DID
Destination ID.
DPID
Data-provider or data source ID. This is a unique ID assigned by Audience
Manager to the Data Partner who is receiving the data.
SYNC_MODE
Sync mode is a macro placeholder that adds a label to the file name based
on synchronization type. Synchronization types include full and incremental.
They'll appear in the file name as iter or full.
• iter: Indicates an "iterative" or incremental synchronization. An
incremental file contains only new data collected since the last
synchronization..
• full: Indicates a "full" synchronization. A fully synchronized file contains
old data and any new data collected since the last synchronization.
TIMESTAMP
A 13-digit UNIX timestamp in milliseconds, in the UTC time zone.
[-SPLIT_NUMBER]
An integer. Identifies part of a file that's been split into multiple parts to
improve processing times. The number indicates which part of the original
file the data belongs to.
File Name Examples
The following examples show properly formatted file names. Your file names could look similar.
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
347
Outbound Data File Contents: Syntax and Parameters
Describes the required fields, syntax, and conventions used to organize information in an outbound data file. Format
your data according to these specifications.
Note: The style elements (monospace text, italics, brackets [ ] ( ), etc.) in this document indicate code elements
and options. See Style Conventions for Code and Text Elements for more information.
Syntax
Fields in the data file appear in this order:
UUID<SPACE>SEGMENT_1,SEGMENT_2<SPACE>REMOVED_SEGMENT_1,...
Parameters
The table lists variables that define the contents of a data file.
Parameter
Description
UUID
A unique user ID assigned by Audience Manager.
<SPACE>
Separate the UUID and segment data with a space
SEGMENT_N
The segment ID that a visitor belongs to. Separate multiple segments with a comma.
REMOVED_SEGMENT_N
The segment ID from which the user was disqualified. Separate multiple segments with
a comma. With a full synchronization, you can ignore the removed segments because
the data file will contain the complete list of current segments for the user. Usually, you
want to know about segments a user belongs to rather than those they've been removed
from. See also Outbound Data File Name: Syntax and Examples.
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. Another space separates the
sets of segment IDs. In this example, a user belongs to segments 24, 26, and 27. They've been removed from
segments 25 and 28.
59767559181262060060278870901087098252
24,26,27
25,28
Transfer-Control Files for Log File Transfers
Transfer-control (.info) files provide metadata information about file transfers so that partners can verify that
Audience Manager handled file transfers correctly.
Audience Manager 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:
• 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)
348
• 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.
Outbound Template Macros
Lists the macros you can use to create outbound templates. These include file name macros, header macros, and
content macros.
Contents:
File Name and File Header Macros
Content Macros
Note: For examples, see Outbound Macro Examples.
File Name and File Header Macros
The table lists and describes the macros you can use in the file name and to define header fields.
Macro
Description
ASCII_SOH
A non-printing ASCII character. It indicates the start of a row or a section of content. It
can also be used to separate data columns in a file.
349
Macro
Description
DPID
Data provider ID.
ORDER_ID
Order / destination ID.
PIDALIAS
An alias for an order / destination ID.
The alias is set in the admin UI.
SYNC_MODE
Indicates synchronization type and includes:
• full: Full synchronization.
• iter: Incremental synchronization.
SYNC_TYPE
Indicates data transfer method and includes:
• ftp
• http
• s3
TAB
Used as a separator, this macro inserts a tab between fields.
TIMESTAMP
A 10-digit, UTC, Unix timestamp.
It can also be formatted as <TIMESTAMP; format="YYYYMMDDhhmmss"> following Java
date/timestamp formatting rules.
Content Macros
Macros used to format the contents of a data file.
Macro
Description
CLOSE_CURLY_BRACKET
Inserts a close curly bracket } character.
DP_UUID
Data Partner Unique User Identifier.
This is the ID for the data partner you send data to in an outbound file.
DP_UUID_LIST
Returns a list that contains multiple IDs for a data partner. This is useful if you have
a large organization with multiple subdivisions or other organizational groups you're
allowed to share data with. This macro returns a list of the IDs for those subordinate
groups.
DPID
Data provider ID.
Macro
350
Description
This combination of macros creates a conditional statement that lists the segments
REMOVED_SEGMENT_LIST)endif users belong to and have been removed from. It returns an empty string if both
conditions are not met or there's no data.
if(SEGMENT_LIST &&
MCID
Adobe Marketing Cloud ID.
OPEN_CURLY_BRACKET
Inserts an open curly bracket { character.
OPT_OUT
Deprecated. Do not use.
ORDER_ID
Order or destination ID.
OUTPUT_ATTRIBUTE_TYPE
Deprecated. Do not use.
OUTPUT_ATTRIBUTE_VALUE
Returns 1 as a static, hardcoded value.
PID
Partner ID.
PIDALIAS
An alias for an order / destination ID.
The alias is set in the admin UI.
REMOVED_SEGMENT_LIST
Returns a list of segments, if any, that have been removed.
SEGMENT_LIST
Returns a list of segments in a list. Accepts the following optional arguments:
• segmentId: Segment ID. Deprecated. Use sid.
• csegid: Customer segment ID. Deprecated. Use sid.
• sid: Segment ID
• type: Returns 5, a static, hardcoded value that identifies data as segment data.
• alias: Deprecated. Do not use.
• lastUpdateTime: A Unix time stamp that indicates the last time a segment was
realized.
Put these variables in curly brackets after the macro. For example, this code
separates results with a pipe "|" character:
<SEGMENT_LIST:{seg|<seg.type>,<seg.SID}; separator=",”>
SET_ATTRIBUTES
Returns 1, as a static, hardcoded value.
SYNC_MODE
Indicates synchronization type and includes:
• full: Full synchronization.
• iter: Incremental synchronization.
351
Macro
Description
SYNC_TYPE
Indicates data transfer method and includes:
• ftp
• http
• s3
TAB
Used as a separator, this macro inserts a tab between fields.
TRAIT_LIST
Returns a list of traits. Accepts the following optional arguments:
• type: Identifies trait types by numeric ID. Returns:
• 10 which identifies a DPM trait (offline, onboarded by an inbound job).
• 3 which identifies a rules-based trait (realtime, onboarded through the DCS).
• traitId: trait ID.
• lastRealized: The last time the trait was realized. Unix time stamp.
Put these variables in curly brackets after the macro. For example, this code
separates the results with a pipe "|" character:
TRAIT_LIST{type|traitId};separator="|"
Audience Manager user ID.
UUID
Outbound Macro Examples
Examples of how some of the common macros are used to create outbound file templates.
Contents:
File Name Macros
Header Row Macros
File Content Macros
Note: In the tables, boldface type identifies each macro with its related output. For the format examples, the
< > symbols have been added to help visually separate each macro. For a list of available macros and
definitions, see Outbound Template Macros.
File Name Macros
Macro
Format and Output Examples
DPID
Format: <SYNC_TYPE>_<ORDER_ID>_<DPID>_<SYNC_MODE>_<TIMESTAMP>.sync
Output: ftp_215_888_iter_1449756724.sync
ORDER_ID
Macro
352
SYNC_MODE
Output:
• Full: ftp_215_888_full_1449756724.sync
• Incremental: ftp_215_888_iter_1449756724.sync
SYNC_TYPE
Output:
• FTP: ftp_215_888_iter_1449756724.sync
• HTTP: http_215_888_iter_1449756724.sync
• S3: s3_215_888_iter_1449756724.sync
TIMESTAMP
Format: <SYNC_TYPE>_<ORDER_ID>_<DPID>_<SYNC_MODE>_<TIMESTAMP>_<admin><.sync>
Header Row Macros
Macro
TAB
Format: <ORDER_ID><TAB><SYNC_TYPE>
Output: 888 full.sync
In the output, the non-printing tab character separates each element.
File Content Macros
Macro
DP_UUID
Format: <DP_UUID><TAB><DP_UUID_LIST;separator=TAB>
Output: 123456 UUID1 UUID2 UUID3
DP_UUID_LIST
REMOVED_SEGMENT_LIST
Format: <DP_UUID><REMOVED_SEGMENT_LIST>;separator=" ">
Output: 123456 105955 101183 101180 101179
SEGMENT_LIST
Format: <DP_UUID><SEGMENT_LIST>;separator=" ">
Output: 123456 105955 101183 101180 101179
353
Macro
if(SEGMENT_LIST &&
Format:
REMOVED_SEGMENT_LIST)endif {"AdvertiserId":"<PIDALIAS>", "DataCenterId": 2,"TDID":"<DP_UUID>",
"Data":[<SEGMENT_LIST:{seg|<OPEN_CURLY_BRACKET>"Name":"<seg.alias>"<CLOSE_CURLY_BRACKET>};
separator=","><if(SEGMENT_LIST && REMOVED_SEGMENT_LIST)><COMMA><endif>
<REMOVED_SEGMENT_LIST:{seg|<OPEN_CURLY_BRACKET>"Name":"<seg.alias>",
"TtlInMinutes":0<CLOSE_CURLY_BRACKET>}; separator=",">]}
Output:
//First example
{"AdvertiserId":"12345", "DataCenterId": 2,
"TDID":"dfd215e4-8d6b-4fdb-90b9-fab4456f2c9d","Data":[{"Name":"4321"}]}
//Second example
{"AdvertiserId":"12345", "DataCenterId": 2,
"TDID":"9099e8fe-abab-5114-abaa-28bdaa0539ca","Data":[{"Name":"4321"},{"Name":"987","TtlInMinutes":0},
{"Name":"654","TtlInMinutes":0}]}
Note: In the first example, the macro only returns data for SEGMENT_LIST
because REMOVED_SEGMENT_LIST is empty. The second example returns data
for both macros.
SET_ATTRIBUTES
Format:
<PID><TAB><UUID><TAB><DP_UUID><TAB><SET_ATTRIBUTES><TAB><OPT_OUT><TAB><SEGMENT_LIST:{seg|<seg.type>,<seg.alias>,<OUTPUT_ATTRIBUTE_VALUE>,<seg.lastUpdateTime>&}>
Output: 1159 00088008579683653741516297509717335000 17t0aj01b120hp 1
0 5,103714,1,1344114661000&5,103713,1,1343250661000
TAB
In the output, the non-printing tab character separates each element.
TRAIT_LIST
Format:
<PID><TAB><DP_UUID><TAB><SET_ATTRIBUTES><TAB><TRAIT_LIST;separator=“|”>
Output: 1131 12345 1 123|456|789
Sending Audience Data
Send audience data from other sources to Audience Manager.
Real-Time Inbound Data Integration
Information about the Real-Time Audience Manager integration.
Real-Time Data Transfer Process Described
A general overview of how Audience Manager performs real-time data transfers with a third-party content provider.
Real-Time Data Transfers
354
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.
The real-time data integration process works as follows:
1. A user visits a customer's site that contains Audience Manager code.
2. Audience Manager 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 Manager.
5. Audience Manager receives this segment information and makes it available for targeting and building new traits
and segments.
Technical Specifications for Inbound, Real-Time Data Transfers
Third-party content providers can expect to exchange data with Audience Manager 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 Manager 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 Manager 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.
355
Examples
This basic event call sends trait ID 1234 to Audience Manager.
http://something.demdex.net/event?d_sid=1234"
You can serialize trait IDs in an event call to help reduce HTTP traffic from the page. Append additional trait 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 Manager.
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.
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
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 Manager 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.
356
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
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
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 Manager. 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 Manager
357
Mail your taxonomy (and any updates) to [email protected]. 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 Manager 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.
1.
2.
3.
4.
A user visits a customer site.
Audience Manager and the third-party data provider assign the visitor a unique ID (usually with a cookie).
Audience Manager calls the third-party data provider to match visitor IDs.
A scheduled request, usually on a daily interval, exchanges visitor segment data between Audience Manager
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.
358
Send Batch Data to Audience Manager Overview
An overview for technical and non-technical customers who want to bring data from other systems (offline) into
Audience Manager.
Advantages
You can make data from other systems available in Audience Manager. 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 Manager 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 Manager 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) 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 Manager 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 Manager
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 Manager 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
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 Manager 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
Manager from your website.
See Data Translation File.
Step 3: Data File Format
359
File names and content follow strict guidelines. You must name and organize data files according to these
specifications in this guide. See:
• Inbound Data File Contents: Syntax, Invalid Characters, Variables, and Examples
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
Manager exports trait and segment information to an FTP location of your choice. Contact your Partner Solutions
manager for additional information or assistance.
Environments
Audience Manager provides the following environments for file drop-off:
Environment
Production
Sandbox
Hostname
ftp-in.demdex.com
sandbox-ftp-in.demdex.com
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 Manager according to these specifications.
For a list of frequently asked questions about onboarding an offline CRM database into Audience Manager, see
Inbound Customer Data Ingestion FAQ.
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 Manager. ID synchronization can begin after you send your data taxonomy to Audience Manager.
ID synchronization is the first step in the inbound, asynchronous data transfer process. In this step, Audience Manager
and the vendor compare and match IDs for their respective site visitors. For example, an Audience Manager customer
may know a user by ID 123. However, your data partner could identify this user with ID 456. The synchronization
process allows Audience Manager and a data vendor to reconcile these different IDs and identify users in their
respective systems. Once complete, Audience Manager 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 Manager:
• 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>
360
The URL for your inbound ID synchronization call should contain variables described in the table below.
Parameter
Description
<VENDOR_ID>
Unique ID for the content provider (assigned by Audience Manager).
<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.
Name and Content Requirements for ID Synchronization Files
File-based ID synchronization Describes the required fields, syntax, and naming conventions used for file-based ID
synchronization. Name and organize your file contents according to these specifications.
Contents:
File Name Syntax and Examples
File Content Syntax and Examples
Synchronization Matches DPIDs to UUIDs
Other Format Requirements
Note: The text styles (monospaced text, italics, brackets [ ] ( ), etc.) in this document indicate code elements
File Name Syntax and Examples
ID file names contain the following required and optional elements:
adobe_id_MASTERDPID_DPID[_DPID_DPID]_TIMESTAMP.sync[.SPLIT_NUMBER][.gz]
361
Parameter
Description
adobe_id
A static prefix that identifies the file as an ID file.
MASTERDPID
The master data provider ID is the parent ID of the DPIDs in the file name.
Also, the first user ID in the data file corresponds to the master ID. The
subsequent DPIDs are other identifiers that belong to the master.
Synchronization maps DPIDs in the file name to UUIDs in the file.
DPID
Data provider IDs. These IDs represent entities or data sources associated
with the master DPID. Synchronization maps DPIDs in the file name to UUIDs
in the file.
The number of DPIDs in the file name must match the number of UUIDs in
the data file. For example, say your file name contains a master DPID and 3
DPIDs. Your data file must include 4 corresponding columns of UUIDs,
formatted as described in the file content section below.
timestamp
A 10-digit, UNIX timestamp in seconds. The timestamp helps make each file
name unique.
.sync
Indicates a normal, full synchronization.
[.SPLIT_NUMBER]
An integer. Used when you split large files into multiple smaller files. This
helps improve processing times.The number indicates which part of the original
file you're sending in. See the file name examples below.
[.gz]
Specifies that your file is compressed with optional gzip compression.
File Name Examples
The following examples show properly formatted files names. Your file names could look similar.
adobe_id_111_222_333_444_1454442149.sync
adobe_id_123_898_456_1454442149.sync.1.gz
adobe_id_123_898_456_1454442149.sync.2.gz
File Content Syntax and Examples
The contents of an ID file include the following elements:
UUID <tab> UUID <tab> UUID <tab> UUID
The file contains user IDs (UUID). In each row, separate the IDs with a tab. The following example shows a properly
formatted ID file. Your contents could look similar.
abc123 def456 ghi789 xyz987
362
Synchronization Matches DPIDs to UUIDs
Synchronization maps the master DPID and its related DPIDs to the UUIDs. Where you put the IDs in the file name
and body determines how these identifiers are mapped to each other. For example, say you have an ID file named
and populated with data as shown here:
• Name: adobe_id_111_222_333_444_1454442149.sync
• Contents: abc123 def456 ghi789 xyz987
Given the sample name and contents, the IDs map together like this:
Other Format Requirements
User IDs cannot:
• Have tabs in the ID itself. Tabs are used only to separate individual IDs in the data file.
• Contain personally identifiable information (PII).
• Use URL encoding. Pass in unencoded IDs only.
Amazon S3 Name and File Size Requirements for Inbound Data Files
Describes the required fields, syntax, naming conventions and file sizes you need to follow when sending data to
Audience Manager. Set the names and sizes of your files according to these specifications when you send data to
an Audience Manager / Amazon S3 directory.
Contents:
• File Name Syntax
• File Name Examples
• Accepted File Sizes
File Name Syntax
S3 file names contain the following required and optional elements:
• S3 prefix: s3n://AWS_directory/partner_name/date=yyyy-mm-dd/
• File name elements:
ftp_dpm_DPID[_DPID_TARGET_DATA_OWNER]_TIMESTAMP(.sync|.overwrite)[.SPLIT_NUMBER][.gz]
Name Elements
The table defines the elements in an S3 file name.
363
Name Element
Description
AWS_directory
The path to and name of your Amazon S3 bucket. Contact your Account Manager for your
S3 directory name, path, and credentials.
date=yyyy-mm-dd
A timestamp (based on UTC time) of when you send the files to your S3 bucket.
DPID
The Data Provider ID (DPID) is an identifier that tells Audience Manager if a data file
contains your own user IDs or Android or iOS IDs. Accepts the following options:
Data Partner ID
This is a unique ID Audience Manager assigns to your company or organization. Use this
assigned ID in a file name when sending in data that contains your own user IDs. For
example, ...ftp_dpm_21_123456789.sync tells Audience Manager that a partner with
ID 21 sent the file and it contains user IDs assigned by that partner.
Android IDs (GAID)
Use ID 20914 as the DPID in a data file name if the file contains Android IDs. When you
use ID 20914 as the DPID, you still need to identify your company to Audience Manager.
This means the file name must use the _DPID_TARGET_DATA_OWNER parameter to hold
your company ID. For example, say you're passing in files with Android IDs and your Data
Provider ID is 21. In this case, the file name would look like
...ftp_dpm_20914_21_123456789.sync. This tells Audience Manager the file contains
Android IDs and is from a partner identified by ID 21.
iOS IDs (IDFA)
Use ID 20915 as the DPID in a data file name if the file contains Android IDs. When you
use ID 20915 as the DPID, you still need to identify your company to Audience Manager.
This means the file name must use the _DPID_TARGET_DATA_OWNER parameter to hold
your company ID. For example, say you're passing in files with Android IDs and your Data
Provider ID is 21. In this case, the file name would look like
...ftp_dpm_20915_21_123456789.sync. This tells Audience Manager the file contains
iOS IDs and is from a partner identified by ID 21.
Note: Do not mix ID types in your data files. For example, if your file name includes
the Android identifier, don't put iOS IDs or your own IDs in the data file.
See also the _DPID_TARGET_DATA_OWNER entry below.
_DPID_TARGET_DATA_OWNER A placeholder for an ID. For example, you could set it to your Audience Manager ID if you
set the DPID to a data source ID or an Android or iOS ID. This lets Audience Manager link
the file data back to your organization.
For example:
• ...ftp_dpm_33_21_1234567890.sync shows a partner with ID 21 has sent in data from
a data source that uses ID 33.
Name Element
364
Description
• ...ftp_dpm_20914_21_1234567890.sync shows a partner with ID 21 has sent in data
that contains Android IDs.
that contains iOS IDs.
parnter_name
The company or organization name you use in Audience Manager.
TIMESTAMP
A 10-digit, UTC UNIX timestamp in seconds. The timestamp helps make each file name
unique.
(.sync|.overwrite) Synchronization options that include:
• sync: Normal scenario when third-party data providers send traits on a per-user basis to
be added or removed in the Audience Manager 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
Manager. You do not need to include all of your users in an overwrite file. Include only
those users that you want to change.
[SPLIT_NUMBER]
An integer. Used when you split large files into multiple parts to improve processing times.
The number indicates which part of the original file you're sending in.
For efficient file processing, the split your data files as indicated:
• Uncompressed: 1 GB
• Compressed: 20-30 MB
See the first 2 file name examples below.
[.gz]
When sending files to Amazon S3, use gzip compression only. When compressed, these
files get the .gz extension. Do not use .zip compression.
Compressed files must be 100 MB or smaller. If your files files are larger, please talk to
Customer Care. Although Audience Manager can handle large files, we may be able to
help you reduce the size of your files and make data transfers more efficient. See File
Compression for Inbound Data Transfer Files.
File Name Examples
s3n://<AWS_Bucket>/<partner_name>/date=2016-05-09/ftp_dpm_478_1366545717.sync.1.gz
s3n://<AWS_Bucket>/<partner_name>/date=2016-05-09/ftp_dpm_478_1366545717.sync.2.gz
s3n://<AWS_Bucket>/<partner_name>/date=2016-05-09/ftp_dpm_478_1366545717.sync
s3n://<AWS_Bucket>/<partner_name>/date=2016-05-09/ftp_dpm_478_567_1366545717.sync.gz
s3n://<AWS_Bucket>/<partner_name>/date=2016-05-09/ftp_dpm_478_1366545717.overwrite
365
You can download the sample file if you want additional examples. This file has been saved with the .overwrite
file extension. Open it with a simple text editor.
Accepted File Sizes
Consider the figures below for fastest/earliest processing of your files as well as for file size limitations when you
send data to an Audience Manager / Amazon S3 directory.
File Type
Compressed
Uncompressed
Optimal Size
Maximum Size
20-30 MB
100 MB
1 GB
5 GB
FTP Name and File Size Requirements for Inbound Data Files
Describes the required fields, syntax, naming conventions and file sizes you need to follow when sending data to
Audience Manager. Set the names and sizes of your files according to these specifications when you send data to
an Audience Manager FTP directory.
Contents:
File Name Syntax
File Name Examples
Accepted File Sizes
and options. See Style Conventions for Code and Text Elements for more information .
File Name Syntax
FTP file names contain the following required and optional elements:
ftp_dpm_DPID[_DPID_TARGET_DATA_OWNER]_TIMESTAMP(.sync|.overwrite)[.SPLIT_NUMBER][(.gz|.tar|.tgz|.zip)]
Name Elements
The table defines the elements in an FTP file name.
File Name Element
Description
DPID
An lD that tells Audience Manager if a data file contains your own user IDs or Android
or iOS IDs. Accepts the following options:
• Data Partner ID: This is a unique ID Audience Manager assigns to your company or
organization. Use this assigned ID in a file name when sending in data that contains
your own user IDs. For example, ...ftp_dpm_21_123456789.sync tells Audience
Manager that a partner with ID 21 sent the file and it contains user IDs assigned by
that partner.
• Android IDs (GAID): Use ID 20914 in a data file name if it contains Android ID. For
example, ...ftp_dpm_20914_123456789.sync tells Audience Manager that the data
file contains Android IDs only.
File Name Element
366
Description
• iOS IDs (IDFA): Use ID 20915 in a data file name if it contains iOS IDs. For example,
...ftp_dpm_20915_123456789.sync tells Audience Manager that the data file contains
iOS IDs only.
Note: Do not mix ID types in your data files. For example, if your file name
includes the Android identifier, don't put iOS IDs or your own IDs in the data file.
_DPID_TARGET_DATA_OWNER A placeholder for an ID. For example, you could set it to your Audience Manager ID if
you set the DPID to a data source ID or an Android or iOS ID. This lets Audience
Manager link the file data back to your organization.
For example:
from a data source that uses ID 33.
• ...ftp_dpm_20914_21_1234567890.sync shows a partner with ID 21 has sent in
data that contains Android IDs.
• ...ftp_dpm_20915_21_1234567890.sync shows a partner with ID 21 has sent in
data that contains iOS IDs.
(.sync|.overwrite)
Synchronization options that include:
• sync: Normal scenario when third-party data providers send traits on a per-user basis
to be added or removed in the Audience Manager system.
• overwrite: Lets customers and data providers send a list of traits on a per-user basis
that should overwrite all of this user's existing traits for a given data source in Audience
Manager. You do not need to include all of your users in an overwrite file. Include only
those users that you want to change. Traits that are not assigned to the target data
source will not be erased.
ftp_dpm_
The path to and name of your Audience Manager FTP directory. Contact your Account
Manager for the FTP directory and credentials.
[SPLIT_NUMBER]
An integer. Used when you split large files into multiple parts to improve processing
times. The number indicates which part of the original file you're sending in.
For efficient file processing, the split your data files as indicated:
• Uncompressed: 1 GB
• Compressed: 20-30 MB
See the first 2 file name examples below.
TIMESTAMP
A 10-digit, UTC UNIX timestamp in seconds.The timestamp helps make each file name
unique.
File Name Element
367
Description
[(.gz | .tar | .tgz | Allowed compression options for an FTP file name. If you use one of these options,
.zip)]
make sure the file name has the proper extension.
Compressed files must be 100 MB or smaller. If your files files are larger, please talk
to Customer Care. Although Audience Manager can handle large files, we may be able
to help you reduce the size of your files and make data transfers more efficient. See
File Compression for Inbound Data Transfer Files .
File Name Examples
ftp_dpm_478_1366545717.sync.1.gz
ftp_dpm_478_1366545717.sync.2.gz
ftp_dpm_478_1366545717.sync.zip
ftp_dpm_478_1366545717.sync.tgz
ftp_dpm_478_1366545717.overwrite
Download the sample file if you need additional examples. This file is saved with the .overwrite file extension.
Open it with a simple text editor.
Accepted File Sizes
Consider the figures below for fastest/earliest processing of your files as well as for file size limitations when you
send data to an Audience Manager / FTP directory.
File Type
Compressed
Uncompressed
Optimal Size
Maximum Size
20-30 MB
100 MB
1 GB
5 GB
Inbound Data File Contents: Syntax, Invalid Characters, Variables, and Examples
Required fields, syntax, and rules you should follow when formatting an inbound trait data file.
File Content Syntax
Fields in the inbound data file must appear in the order shown below. In this example, the < > symbols have been
added to help separate each element visually. You do not need to include these in your data file.
<UUID><TAB><trait ID><trait ID>,<trait ID>,...
Note: We have a limit of 200 lines we can process for each UUID sent in the inbound data file. For example,
if you send 300 lines for a UUID, the first 200 lines are kept and the additional 100 lines are discarded.
Invalid Characters in Inbound Data Files
Invalid Characters in Trait ID Names
368
In order to successfully process files, it is mandatory to avoid the special characters below in trait IDs. See also,
Basic Information for Traits.
• Commas (,)
• Dashes (-)
• Hyphens (-)
• Equals (=)
• Quote (")
• Vertical bar or pipe symbol (|)
Note: We recommend that you only use numbers, letters (uppercase and lowercase and not necessarily
Latin alphabet) and the underscore (_) character in trait ID names.
Invalid Characters in the Value part of Key-Value pairs
The quote sign (") is the only invalid character in the value part of key-value pairs in inbound data files.
File Variables Defined
The table lists and defines the variables used in a properly formatted inbound data file. Italics indicates a variable
placeholder.
Variable
Description
UUID
A Unique User ID can be:
• A unique user ID assigned by Audience Manager or a data provider.
• A mobile Android or iOS device ID in its original, unmodified form as exposed by
the mobile operating system.
TAB
Separate the UUID and trait IDs with a single tab delimiter.
trait ID
The Audience Manager trait ID.
Note: The Trait ID can be found by using the GET method that returns details
about all your traits. For more information, see Return Properties for all Traits.
Formatting Trait IDs
The following table describes the prefixes that identify trait names or IDs in an inbound data file. See the sample
files for examples.
Prefix
Description
d_sid=
The d_sid prefix tells our system that the ID is an Audience Manager trait ID. This is the
same ID that's shown in the user interface. You can also return trait IDs with the API GET
method. See Return Properties for all Traits.
369
Prefix
Description
d_unsid=
Data prefixed with d_unsid removes users from that trait. The d_unsid prefix is ignored
in an overwrite file.
The d_unsid= prefix tells our system that the ID is an Audience Manager trait ID. . This
is the same ID that's shown in the user interface. You can also return trait IDs with the
API GET method. See Return Properties for all Traits.
ic=
Trait rules let you set criteria for trait qualification. If you format a trait rule as ic ==
trait ID, you can send in traits in a simple comma formatted list.
For example, say you create these 3 trait rules:
ic == "123"
ic == "456"
ic == "789"
These traits are associated with the ic key. This lets you create a simpler trait list in the
data file. And, you do not need to include the ic prefix. As a result, the contents of your
data file could look like this:
UUID <TAB> 123,456,789
Key-value pairs
Trait data can be formatted as key-value pairs using alphanumeric strings. For example,
"age"="32" or "gender"="m".
Data File Examples
Data File Format
Description and Example
With d_sid or d_unsid This data file shows a user qualified for traits 24, 26, 27 and has been removed from trait
28.
59767559181262060060278870901087098252
d_sid=24,d_sid=26,d_sid=27,d_unsid=28
With ic==
These traits have been added to a trait rule with the ic prefix. As such, you can add them
to the data file separated by commas as shown. A tab separates the UUID and the trait
IDs. The ic prefix is not required in the file.
Numeric IDs
DBwFoc3dhfMNCFBh2M4F9ZkJEXMNnRDh2PXvnI1
String IDs
DBwFoc3dhfMNCFBh2M4F9ZkJEXMNnRDh2PXvnI1
intent_category:52,intent_category:55
30608,50354,50338,50352,30626
Data File Format
With key-value pairs
370
Description and Example
This file data uses key-value pairs to pass in data to Audience Manager.
59767559181262060060278870901087098252
“gender”=”female”,“luxury_shopper”=”yes”
Download the sample data file if you need additional examples. The download file has a .overwrite file extension.
You can open it with a simple text editor.
File Compression for Inbound Data Transfer Files
As an option, you can compress data files when sending them to Audience Manager.
Audience Manager supports the following file compression types for inbound, asynchronous data transfers:
• tar (.tar)
• gzip (.gz)
• tar and gzip (.tgz and .tar.gz)
• zip (.zip)
Audience Manager also supports uncompressed files.
Amazon S3 Compression
For delivery to Amazon S3, you must use .gz or uncompressed files. Compressed files must be 100 MB or smaller.
If the files are larger, please discuss the file and transfer process with Customer Care. Although Audience Manager
can handle very large files, there may be ways to reduce the file size or make transfer of data more efficient.
Important: Your FTP client must use binary mode to transfer compressed or encrypted files. Compressed
or encrypted files sent in ASCII mode will corrupt the data transfer file.
Best Practices
• Files should be gzip compressed (and have a .gz file extension.)
• The maximum compressed file size for a .gz compressed file is 100 MB.
• Optimal split sizes, for fastest/earliest processing of your files, is approximately 1 GB uncompressed or 20-30 MB
compressed.
• Amazon S3 imposes its own, 5 GB file size limit on uploaded files.
File PGP Encryption for Inbound Data Types
As an option, you can encrypt data files with PGP encryption when sending them to Audience Manager.
1. Download the Audience Manager public key
(https://marketing.adobe.com/resources/help/en_US/aam/downloads/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
371
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 Manager supports only the Advanced Encryption Standard (AES) data-encryption algorithm.
Audience Manager 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: [email protected][[email protected]]
Subject: SFTP Server-To-Server Processing Result:
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
Records received: 40669900
Invalid lines: 7
Invalid UUIDs: 112
Failed UUID lookup: 0
Records without traits: 26730823
Records processed: 40669900
372
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.
Records received
Invalid lines
Invalid UUIDs
Failed UUID lookup:
Records without traits
Records processed
Succeeded
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.
Line
User without new traits
Total signals
Total unused signals
Total realized traits
Total new traits
Total removed traits
Total skipped duplicated
users
373
Description
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.
Job start time
The time the inbound job starts.
Job end time
The time the inbound job ends.
Send Segments to a Google AdWords Remarketing List
This procedure requires an AdWords remarketing list, pixel code, and an Audience Manager URL destination. It is
also known as a remarketing list for search ads (RLSA) integration. Applies to paid search only.
To set up an AdWords remarketing list as an Audience Manager URL destination:
1. In AdWords, create a website re-marketing list.
2. Copy the pixel code from the dynamic remarketing tag. Do not copy the code this example.
Your pixel code / image request will look similar to this:
<img height="1" width="1" style="border-style:none;" alt=""
src="//googleads.g.doubleclick.net/pagead/viewthroughconversion/xxxxxxxx/?
value=0&guid=ON&script=0"/>
3. Remove all the image and source metadata from the pixel code.
374
Your edited code snippet should look similar to this:
//googleads.g.doubleclick.net/pagead/viewthroughconversion/xxxxxxxx/?
value=0&guid=ON&script=0
4. Create a URL destination or edit an existing destination.
5. In the Segment Mappings section of your URL destination, add the edited code to the URL and Secure URL
boxes. Prefix the code with http: and https: in the URL and Secure URL boxes, respectively.
Important: Replace encoded ampersands & with un-encoded ampersands &
Unsecure URL code:
http://googleads.g.doubleclick.net/pagead/viewthroughconversion/xxxxxxxx/?
Secure URL code:
https://googleads.g.doubleclick.net/pagead/viewthroughconversion/xxxxxxxx/?
6. Click Save.
Note: If you're working with multiple segments, get a new pixel for each segment you want to map to an
AdWords destination. This ensures the data is applied to the appropriate remarketing list.
A completed mapping could look similar to this:
Share Data between Marketing Cloud Solutions
Guides to help you integrate Adobe Marketing Cloud solutions with Audience Manager.
375
Analytics Data Integration
This document describes how to use the Audience Manager Data Information Library (DIL) module to bring Analytics
data in to Audience Management.
The Audience Manager Data Integration Library (DIL)
DIL is a self-contained code module that helps you collect data from Analytics and send that information to Audience
Manager. 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 Manager - 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 Manager.
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:
HTTP Call To
Looks Like
Analytics
http://...107.net?c30=foo&v35=bar&events=event10
Audience Manager
http://...demdex.net/event?c_prop30=foo&c_evar35=bar&c_events=event10
Analytics Data in Audience Manager
Audience Manager turns Analytics Props, eVars, and events into traits.
Analytics Props, eVars, and events work like traits in Audience Management. Traits are expressed as 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 Manager 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_.
376
See the table for examples:
Analytics Data Element
Analytics Example
As Audience Manager Trait
prop
c30=foo
c_prop35=foo
evar
v35=bar
c_evar=bar
events
events=event10
c_events=event10
Analytics Data as Unused Signals
Audience Manager 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 Manager traits that match the Analytics data passed in by DIL.
Integration Methods
Supported Audience Manager - 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 Manager 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 Manager Partner Solutions manager.
• Serve DIL and s_code.js through Tag management.
Configuration Steps
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 Manager 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 Manager Partner Solutions manager.
Configuration Steps
377
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:

<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 = ""
s.t()
}
//]]></script>

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 Manager.
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.
Profiles and Audiences Integration with the Audience Management Module
Use Profiles and Audiences to send data directly from Adobe Analytics to Audience Manager rather than using the
Data Integration Library (DIL).
See Profiles and Audiences for more information.
Configure the Audience Management Module
To set up this integration, add the Audience Management Module to your Analytics JavaScript code.
1. Contact your Audience Manager consultant to have Profiles and Audiences enabled for your account.
2. Download AppMeasurement from Analytics Code Manager. Requires version 1.4 or later.
378
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
DIL 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. Many of the variables use a special prefix to identify the type of data they contain. For
more information about these variable prefixes, see Prefix Requirements for Key Variables.
Data Sent
Configuration Variables
Description
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 content about the destination to be
sent back to the client.
d_mid
Marketing Cloud Visitor ID passed in to Analytics.
HTTP Header
Description
Host
Set to the client specific DCS hostname specified in the Analytics host config
(PARTNER.demdex.net).
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.
HTTP Header
Description
Referer
Set to the page URL passed in to Analytics or gathered from the Referer header
passed in to Analytics.
Signal
Description
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 or 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
Options include:
• custom
• download
• 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
379
380
Signal
Description
c_linkExitURL
URL of exit links
c_mediaPlayerType
Fro media stream tracking requests. Options include:
• other
• primetime
c_screenResolution
Width and height
c_colorDepth
16 bit or 32 bit color
c_clientDateTime
Timestamp formatted as:
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 and
Width and height of a browser window
c_browserHeight
c_cookiesEnabled
Options include:
• yes
• no
• unknown
c_connectionType
Options include:
• modem
• lan
c_javaScriptVersion
Version of JavaScript supported by browser
c_javaEnabled
Options include:
• yes
• no
• unknown
c_channel
s.channel
c_campaign
s.campaign
c_prop#
Custom props
Signal
Description
c_evar#
Custom evars
c_list#
Custom list variables
c_hier#
Custom hierarchy variables
c_contextData.*
Example:
381
• 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 Manager - Auditude integration lets you send segments (in the form of key-value pairs) to Auditude.
Once configured, you can use Audience Manager 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 Manager - Auditude data integration.
Benefits of Audience Manager - Auditude Data Integration
Advantages of integrating Audience Manager 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 Manager synchronization processes help keep information
current).
• Extensive code changes are not required (but you will have to add two small functions to the Auditude plug-in).
The Audience Manager 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 Manager.
Destinations
In Audience Manager, 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
382
processes. Audience Manager destination features are located in Manage Data > Destinations. To get started, click
Add New Destination and follow the steps below.
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:
2. Select "Cookie" from the Type dropdown.
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.
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.
3. Click Done.
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 Manager 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 Manager.
Replace the italicized parameter with the following Audience Manager 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 Manager Data Fetching
383
When set to true, this code tells the Auditude plug-in that you want to call Audience Manager 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 Manager segments.
Define Custom Key-Value Pairs
To work with Audience Manager 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 Manager
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 Manager 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.
Target Audience Manager Expressions in Custom Targeting
The Auditude custom targeting features let you create display qualification requirements for Audience Manager 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
384
Click the By expression tab to create targeting rules by writing expressions with simple code and symbols. To
define and identify the Audience Manager 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 Manager and Adobe Experience Manager.
As part of the Adobe Marketing Cloud, Audience Manager 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.
Marketing Cloud Audiences in Analytics
Share Audience Manager segments with Analytics in real-time.
This is how the real-time processing works: When someone goes to a web page, and the Analytics hit arrives at
Adobe's servers, we ask Audience Manager (in the same hit) about all segments/audiences that apply to this hit.
These segments get sent back and then get sent to the Analytics reporting interface, again within the same hit.
Compare this to a cookie-based destination listVar, where you would have to wait for the next page to get reporting
results.
To share Audience Manager segments with Analytics, see Marketing Cloud Audiences in Analytics.
Target Data Integration
This integration brings Audience Manager segment data into Adobe Target. When complete, you can create Target
offers and experiences with Audience Manager data.
Benefits and Requirements
Describes benefits and requirements of an Audience Manager and Target data integration
Audience Manager User Profile Data in Target
Data integration lets you use Audience Manager data in Target to help improve rules-based content delivery. The
advantages of bringing Audience Manager 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 Manager synchronization processes help
keep user profiles current).
• Access to profile data older than 14 days.
• Creating customized user experiences based on first- and third-party data.
• Cross-domain visitor targeting.
385
Requirements
You must be an Audience Manager and Adobe Target customer to perform this data integration.
Data Exchange Process
A general overview of how the Audience Manager and Adobe Target data integration process works.
At a high level, Audience Manager sends data to Target as described below:
1. As the page loads, API code makes a call to Audience Manager.
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.
Follow these procedures to bring Audience Manager data into Adobe Target.
The data integration process uses the available features in Audience Manager and Target. Other steps require code
changes to the Targetmbox.js file.
The following table summarizes the integration workflow.
Product or Platform
Action
Audience Manager
Create a cookie destination for Target.
386
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 Manager data.
Your Website
Upload the new mbox.js file to your website.
Audience Manager Set Up
As a first step, set up Adobe Target as a cookie-based destination in Audience Manager.
Destinations
In Audience Manager, a destination is any other system (ad server, DSP, ad network, exchange, etc.) that you want
to share data with. Audience Manager destination features are located in Manage Data > Destinations. To get
started, click Add New Destination and follow the steps below.
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.
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.
3. Click Done.
Target Set Up
Create an Adobe Target campaign and add integration code to your website.
387
Edit the Target mbox.js File
Add the plug-in code and the API call to the mbox.js file. See Edit the Target 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 Manager
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 Manager customer using Tag Management to deploy and collect data with DIL.
Source Code Location
Placement Sequence
<head>
Put the mbox.js file in the header. Include the plug-in code and API call. See Edit
the Target mbox.js File.
<body>
Inside the Tag Management container:
1. Analyticss_code.js file (if used)
2. Audience Manager DIL module
3. Analyticss.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 Manager segment data.
Obtain the plug-in code from your Adobe account consultant.
Prerequisite: In Audience Manager, create cookie-based destination for Target.
To add the integration code to a Targetmbox.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 Manager data. Obtain the plug-in from your Target or
Audience Manager 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);
}
}
}
}
}
388
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 Manager. Obtain a customized API call from your Target or Audience
Manager 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 Manager:
Parameter
Description
omniture.demdex.net/event?
The event call to the Audience Manager Data Collection Server (DCS).
d_stuff=1
Defines an array returned by the DCS that contains Audience Manager 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 Manager.This makes Audience Manager data available
in Target.
Sample Response
In the response, the Audience Manager 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"})
Server Side Forwarding
Server-side forwarding is designed for customers who use Analytics and Audience Manager. Server-side forwarding
lets you remove DIL (Audience Manager's data collection code) and replace it with the Audience Management
Module. When added to your AppMeasurement code, this module lets your Analytics implementation collect and
send data to Audience Manager via server-side data transfers.
Contents:
Advantages
Order of Operations
389
Next Steps
Advantages
Server-side forwarding improves upon DIL data collection because it:
• Reduces calls from the page. Removing DIL eliminates an Audience Manager/event call. Fewer calls helps improve
page load times, which makes for a better customer experience on your site.
• Lets you take advantage of new and upcoming Marketing Cloud features. For example, server-side forwarding is
required if you want to share Audience Manager segments with Analytics. See also, Marketing Cloud Audiences
in Adobe Analytics.
• Conforms with our best practices for Audience Manager code implementation and deployment.
Tip: Current Audience Manager customers who use Analytics should migrate to server-side forwarding. New
customers should implement server-side forwarding (instead of DIL) as the default data collection and transfer
method.
Order of Operations
Server-side forwarding requires planning and coordination. It involves external changes to your site code and internal
steps that Adobe must take to provision your account. In fact, many of these migration procedures need to happen
in parallel and get released together. Your migration path to server-side forwarding should follow this sequence of
events:
1. Work with your Analytics and Audience Manager contacts to plan a migration the Marketing Cloud ID service.
Two important components of your implementation strategy should include server-side forwarding and choosing
a tracking server.
2. Get provisioned for Profiles & Audiences. Visit the integrations and provisioning site to get started.
3. Implement the ID service and the Audience Management Module simultaneously.To work properly, the Audience
Management Module (server-side forwarding) and the ID service must be released for the same set of pages
and at the same time. See the requirements and the implementation steps in the following section.
Next Steps
Work with your Analytics and Audience Manager consultants to get started. Also, review the following requirements,
procedures, and code samples.
Requirements for Server-Side Forwarding
You must meet these Marketing Cloud solution, service, and code requirements to implement server-side forwarding.
These requirements also include instructions on how to check for code versions and where to get the latest code
libraries.
Contents:
Solution Requirements
Service Requirements
Code Version Requirements
Tip: Refer to the order of operations for the sequence of service and code changes you should follow when
migrating to server-side forwarding.
390
Solution Requirements
Server-side forwarding works with Analytics and Audience Manager.
Service Requirements
Server-side forwarding requires the Marketing Cloud services listed in the following table:
Service
Description
Profiles & Audiences
Profiles & Audiences works in conjunction with the Marketing Cloud ID service to
enable server-side forwarding. You need to be provisioned for Profiles &
Audiencesand deploy the ID service before server-side forwarding will work.
To get started with Profiles & Audiences, complete the Marketing Cloud Integrations
Provisioning form. The form contains important provisioning and implementation
information. Review that information carefully before submitting the form.
Important: List the tracking servers you want to use for server-side forwarding
in the implementation form.
Marketing Cloud ID Service
The Marketing Cloud ID service provides a universal ID that identifies site visitors
across all the solutions in the Marketing Cloud. You need to be provisioned for
Profiles & Audiences and deploy the ID service before server-side forwarding will
work.
Code Version Requirements
Server-side forwarding requires version 1.5 (or newer) of the code libraries listed below. As a best practice, we
recommending using the latest versions rather than the required minimums.
• AppMeasurement.js
• AppMeasurement_Module_AudienceManagement.js
• VisitorAPI.js
Determine Your Code Library Version
Any tool that monitors the HTTP requests made by a browser can show you the version number for your
AppMeasurement and Visitor API code. The AppMeasurement_Module_AudienceManagement.js does not contain
or return a version ID. The following examples show you what the version IDs for look like for AppMeasurement.js
and VisitorAPI.js code.
• AppMeasurement.js: Adobe Debugger returns the AppMeasurement version like this: Version of Code |
JS-1.5.1. Other tools may use a different label, but the value always follows the pattern JS-X.X.X, where X is a
version number.
• VisitorAPI.js: Look for the d_visid_ver parameter. It will show you the Visitor ID service like this: d_visid_ver:
1.5.5.
Attention: Visitor API code older than version 1.5.2 did not include a version number. You're probably using
an older code library (and need to upgrade) if your monitoring results do not return a version number. See the
implementation steps for information about how to get the latest VisitorAPI.js file.
391
Implement Server-Side Forwarding
This section lists and describes the required AppMeasurement.js and other service changes that let you migrate to
server-side forwarding. Work closely with your Audience Manager and Analytics consultants during the migration
process.
Important:
• Read the requirements before you begin.
• Configure and test this code in a development environment before implementing it in production.
• This procedure is for customers who already use Analytics and Audience Manager and may or may not be
enabled for Profiles & Audiences.
Get Provisioned for Profiles and Audiences
You must be provisioned for Profiles & Audiences to implement server-side forwarding. This service uses the
Audience Management Module to send data to Audience Manager. To get started, work closely with your Analytics
and Audience Manager consultants and complete the Marketing Cloud provisioning form. The link takes you to a
page that contains important provisioning and implementation information. Review that information carefully before
submitting the form.
Important: List the tracking servers you want to use for server-side forwarding in the implementation form.
Download the AppMeasurement Code Libraries
Server-side forwarding requires the AppMeasurement_Module_AudienceManagement.js file. To download this code
library:
1. In Analytics, go to Admin > Code Manager.
2. In Code Manager, click JavaScript (New). This downloads a .zip file that contains the required code libraries.
3. Decompress the code file and save the AppMeasurement_Module_AudienceManagement.js file.
Add Audience Management Code to AppMeasurement
In this step, you'll add a line of loader code and the AppMeasurement_Module_AudienceManagement.js code to
the AppMeasurement.js file. To edit the AppMeasurement file:
1. Open the AppMeasurement.js file in your preferred code editor.
2. Add this loader code, s.loadModule("AudienceManagement"); to the AppMeasurement file. Place this code
above the warning text, DO NOT ALTER ANYTHING BELOW THIS LINE!
3. Copy and paste the code from the AppMeasurement_Module_AudienceManagement.js file below the
s.loadModule call. Again, make sure to put this code above the warning text, DO NOT ALTER ANYTHING BELOW
THIS LINE!
4. Save your changes.
Your edited AppMeasurement file should look similar to the sample code below. The Audience Management code
has been shortened for brevity.
//Load the Audience Management module
s.loadModule("AudienceManagement");
//AppMeasurement_Module_AudienceManagement code has been shortened in this example because it's
really long
392
function AppMeasurement_Module_AudienceManagement(d){var a=this;a.s=d;var
b=window;b.s_c_in||(b.s_c_il=[],b.s_c_in=0);a._il=b.s_c_il;a._in=b.s_c_in;a._il[a._in]=a;b.s_c_in++;a._c="s_m";a.setup=function(c){b.DIL&&c&&(c.disableDefaultRequest=!0,c.disableScriptAttachment=!0,a.instance=b.DIL.create(c),a.tools=b.DIL.tools)};a.isReady=function(){return
a.instance?!0:!1};a.getEventCallConfigParams=function(){return
a.instance&&a.instance.api&&a.instance.api.getEventCallConfigParams?a.instance.api.getEventCallConfigParams():
{}};a.passData=function(b){a.instance&&a.instance.api&&a.instance.api.passData&&a.instance.api.passData(b)}}
...
/*
============== DO NOT ALTER ANYTHING BELOW THIS LINE ! ==============
Version and copyright section
*/
//AppMeasurement code here
function AppMeasurement(){var a=this;a.version="1.6";
...
Replace DIL with the Audience Manager Module
In this step you can replace or comment-out DIL code in the AppMeasurement.js file. If you do not remove or
comment out DIL code, Audience Manager will receive duplicated trait data (from the new AppMeasurement code
and from DIL). To avoid double-counting, remove or comment out your DIL code. To edit the AppMeasurement file:
1. Find the DIL code in your AppMeasurement.js file (it's usually in the doPlugins section).
2. Comment out the DIL code and replace it with the Audience Management Module as shown in the example
below.
3. Save your changes.
Your edited AppMeasurement file should look similar to the sample code below. In the sample code, some values
have been replaced with plan-text descriptions or placeholders.
function s_doPlugins(s) {
/*User CRM ID - example of it getting set in eVar1*/
s.eVar1="123456789";
//Comment out your DIL code
/*var vidObj = {
partner: 'partner name here',
uuidCookie: {
name: 'aam_uuid',
days: 30
},
visitorService: {
namespace: 'Marketing Cloud ID here'
},
declaredId : {
dpuuid : s.eVar1,
dpid : '12345'
},
}
var vidDil = DIL.create(vidObj);
/*var _scDilObj = s_gi(s.account);
DIL.modules.siteCatalyst.init(_scDilObj, vidDil, {
names: ['pageName', 'channel', 'campaign', 'products', 'events', 'pe', 'referrer', 'server',
'purchaseID', 'zip', 'state'],
iteratedNames: [{
name: 'eVar',
maxIndex: 75
}, {
name: 'prop',
maxIndex: 75
}, {
name: 'pev',
393
maxIndex: 3
}, {
name: 'hier',
maxIndex: 4
}]
});
if(s.eVar1){
vidDil.api.aamIdSync({
dpid: '54321',
dpuuid: s.eVar1,
minutesToLive: 20160
});
}
*/
//Replace DIL with the Audience Manager Module
s.AudienceManagement.setup({
"partner":"partner name here",
"containerNSID":0,
"uuidCookie": { //optional if you want to set the UUID in the first-party domain
"name":"aam_uuid",
"days": 30
}
});
}
s.doPlugins=s_doPlugins
Update ID Synchronization Code
This change is required if you're synchronizing IDs with Audience Manager. Skip this change if you do not sync IDs.
This update replaces the Audience ManageraamIdSync function with the visitor.setCustomerIDs function, which
is provided by the Marketing Cloud ID service. To use this ID synchronization code:
1. Find the Audience Manager ID sync code in your AppMeasurement.js file. It should look similar to this:
vidDil.api.aamIdSync({
dpid: '12345',
dpuuid: '12345abcd',
minutesToLive: 20160
});
2. Replace the Audience Manager ID sync code with the ID service sync function as shown below. In this new
function, an integration code replaces the DPID. An integration code is an identifier you apply to an Audience
Manager data source. See also, Customer IDs and Authentication States.
Visitor.setCustomerIDs({
"my_integration_code_here":{ //You must use an integration code instead of a DPID
"id": '12345abcd',
"authState": Visitor.AuthState.AUTHENTICATED
Test, Verify, and Deploy
Depending on what version of App Measurement code you’re using, this migration makes significant changes to the
way you work with Analytics and Audience Manager. As a result, you should test and troubleshoot this code thoroughly
before deploying it in a live, production environment. Work closely with your Adobe consultant during this phase and
see the following documentation:
• How to Determine if Your Account is Ready to Receive Forwarded Data
• How to Determine if Your Account is not Ready to Receive Forwarded Data
394
How to Determine if Your Account is Ready to Receive Forwarded Data
Server-side forwarding is ready when you see an Audience Manager response to the Analytics call in your preferred
HTTP proxy or debugger tool. This section shows you how to check for these indicators and what to look for in the
HTTP requests and response calls.
Contents:
Recommended Tools
Checking the Status of Server-Side Forwarding in Charles
Other Structure and Request Elements
Recommended Tools
The Charles HTTP proxy is a great tool to use when you want to check if server-side forwarding is working properly.
The examples in this section are based on the results returned by Charles. Feel free to use whatever tool or debugger
works best for you.
To check the status of server-side forwarding:
1.
2.
3.
4.
5.
Start Charles.
Load a test page that contains updated AppMeasurement code.
In Charles, expand the file path from the tracking server to the actual script call.
Click the script call to select it.
Click the Response tab. If the response contains Audience Manager data, then server-side forwarding is working.
Your response could look similar to the example below. Prior to server-side forwarding, the response would return
2 X 2 as text.
395
Other Structure and Request Elements
These calls and data indicate that indicate server-side forwarding and the Audience Management Module are working
properly.
Data in the Structure Tab
Element
Description
Data Provider Match
(DPM) Call
Look for a call to http://dpm.demdex.net.
Tip: To check for these calls, clear your browser cookies or check for this code
with your browser in anonymous mode.
If you expand this call, some important elements to look for include:
• The id folder. This contains the ID service request call made for a new visitor. This
call is a very long string similar to the following:
rd?d_rtb=json&d_ver=2&d_verify=1&d_orgid=Organization ID here...
• The Inbound Synchronization (IBS) call. This is an ID sync. Yours may look similar
to this: ibs:dpid=1234&dpuuid=98765 (1x1).
Destination IFrame
Look for a call to http://fast.some name here.demdex.net
Folder 10
As shown in the image above, this is a subdirectory of your Analytics report suite folder.
It is used instead of folder 1 after you implement server-side forwarding.
Data in the Request Tab
The following request elements indicate that server-side forwarding is working (click the Request tab in Charles):
• A query string parameter in the Analytics request (e.g., callback | s_c_il[1].AudienceManagement.passData).
• A Marketing Cloud ID (e.g., mid | 1234567890987654321).
For an example of an unsuccessful server-side response, see How to Determine if Your Account is not Ready to
Receive Forwarded Data.
How to Determine if Your Account is not Ready to Receive Forwarded Data
Server-side forwarding is not ready when you see "status":"SUCCESS" as the Audience Manager response to an
Analytics call in your preferred HTTP proxy or debugger tool. This section shows you how to check the status of
server-side forwarding and what to do if you see the somewhat misleading "status":"SUCCESS" message.
Contents:
Recommended Tools
Fix a Successful Failure
396
Recommended Tools
The Charles HTTP proxy is a great tool to use when you want to check if server-side forwarding is working properly.
The examples in this section are based on the results retuned by Charles. Feel free to use whatever tool or debugger
works best for you.
To check the status of server-side forwarding:
1. Start Charles.
2. Load a test page that contains updated AppMeasurement code.
3. In Charles, expand the file path from the tracking server to the actual script call.
4. Click the script call to select it.
5. Click the Response tab. If the response contains the key-value pair "status":"SUCCESS" then server-side
forwarding is not working. This status indicates that your tracking server has not been properly configured on
internal Adobe systems.
File Structure, Request and Response Data are Accurate
Troubleshooting server-side forwarding is also a challenge because failed and successful implementations return
similar data. This includes data such as:
• The structure (folder path) of the tracking server call.
• Folder name constants: b, ss, 10, and JS-version number here.
• A script call to Analytics in the JS folder.
• Request elements (click the Request tab in Charles). These include:
• A query string parameter in the Analytics request (e.g., callback | s_c_il[1].AudienceManagement.passData).
• A Marketing Cloud ID (e.g., mid | 1234567890987654321).
Remember: Always check for "status":"SUCCESS" in the response. That tells you server-side forwarding
is not working even if the file structure and request data are accurate.
397
Fix a Successful Failure
Although the "status":"SUCCESS" message is one you don't want to see, it has value as a troubleshooting tool. It
indicates that your tracking servers were not included with the Profiles & Audiences provisioning request or that
the wrong tracking servers are forwarding data.
To fix this problem, contact client care and ask them to check the tracking servers associated the Profiles &
Audiences settings for your account. Let client care know you're seeing the "status":"SUCCESS" message. They
will check our internal systems to make sure your tracking server is configured properly. When this problem is
resolved, the Audience Manager response will contain data passed by an Analytics call.
For an example of a successful server-side response, see How to Determine if Your Account is Ready to Receive
Forwarded Data.
Reference
398
Reference
Contains technical documentation about system functionality, data integration, and help files.
Amazon S3: About
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 and high availability storage services.
• 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 Manager.
• Amazon S3 provides encryption-at-rest for encrypting outbound data files. We use the SSE-S3 encryption method,
which allows encryption keys to be automatically generated and managed by Amazon S3.
• Debug and Backup Support: Amazon S3 allows Audience Manager 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.
Advertiser and Publisher Use Cases
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.
Reference
Goal
399
Benefit
Example
• 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
• Leverage site behavior, offline data, • Identify new audiences with
third-party data, campaign metrics
behaviors and profiles that mirror
to create valuable audience profiles. the original audience.
Example
• Identify customers who make
expensive purchases.
• Run an Audience Management
• Model those segments against other • Search against your own data and
look-alike model to identify the most
data sources to increase reach.
other third-party data that you have influential audience members in that
access to. This helps you find and
segment.
identify the most influential data
• Target those segments to improve
points for high-value audience
current display advertising or
profiles.
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 sites through a DSP to
increase ad targeting effectiveness.
• Align analytics data points with
display advertising.
• Create a "Vacations - Searchers No
Conversion" segment.
• Reduction in wasted impressions
(don't show impressions to current
customers).
• Add a rule to exclude recent
converters.
• 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
• Offer customers special rates based • Improve offer management and
on segment data from business
conversion rates by taking
partners.
advantage of data from strategic
partners.
Example
• Import partner data segments,
combine them with your own, and
offer relevant experiences with
Test&Target.
Reference
Goal
400
Benefit
Example
• For in-segment customers, reinforce • Break down organization and data • Increase the scale of email
this special offer through email
silos with systems designed to
marketing initiatives or DSP
marketing.
manage and optimize cross-channel campaign alignment.
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.
• Increase conversion rates and
loyalty by offering customers
relevant creative experiences.
• In Test&Target, create a campaign
to offer airline points for seasonal
purchases.
• 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 • Create a "Purchase Intenders - No
initiatives.
Conversion" segment.
• Combine Analytics data with
customer data.
• Target that segment with related
emails.
• Improve collaborative offer
management.
• Continue to offer content on-site
through Test&Target.
Tailor the Visitor's Purchase Path with Current Customer and Third-party Data
Goal
Benefit
Example
Take advantage of existing and
third-party visitor data to optimize and
personalize a customer's digital
experience.
• In Audience Management, ingest
Personalized customer experience
third-party segment data targeted to
helps increase conversion rates.
Presenting the right products, offers, small business owners.
and creative experiences can drive • In Test&Target, create an on-site
purchase activity and improve
campaign that offers small business
customer engagement or loyalty.
owners targeted messages and
offers.
• Track performance with Audience
Manager reports.
Reference
401
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 • Discover audiences, run smarter ad
that provides you with an overview of or sales campaigns, and manage
all your users and data points. This
customer insight.
includes information like site behavior
• Aggregate related customer insights
(potentially from Analytics), display
across all your channels.
impressions, 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
Example
Extract maximum value from
first-party data to create actionable
audience segments, package them,
and sell these segments to
advertisers looking for specific
audiences.
Enhance revenue by monetizing
audiences instead of content.
• Aggregate a first-party segment of
"Tech Geeks" across a network of
properties.
Improve Personalized Site Content Delivery
• Include technical email newsletter
registrants.
• Monetize "Tech Geeks" as a
premium product on the digital rate
card for relevant advertisers.
Reference
Goal
402
Benefit
Example
Present specific content to the user
to help:
• Analytics provides first-party data
Audience Manager's real-time
about audience interest in travel
analysis helps improve audience
• Increase segment size, page views, recognition, which enhances the
content. Create a segment called
and impressions.
"Travel Enthusiasts" based on this
on-site experience by delivering
information.
• Create a more relevant experience relevant, personalized content.
for that site visitor.
• Integrate Audience Management
This gives you the opportunity to add
with a system like Adobe CQ to
content personalization as a line item
manage content personalization
to your premium audience products.
campaigns.
• Target the travel segment to an
airline, 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 inventory sources through a
DSP.
Align analytics data points with on-site • Create an "Income Tax
and off-site display advertising and
Researchers" segment.
monetize audience inventory in
• Align on-side ad campaign sold to
'sold-out' 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 Manager's algorithmic modeling process.
Goal
Benefit
• Leverage site behavior, offline data, • Identify new audiences with
third-party data, campaign metrics
behaviors and profiles that mirror
to create valuable audience profiles. the original audience.
Example
• Identify "Xbox gamers" in your
customer database.
• Run a look-alike model to find and
• Model those segments against other • Search against your own data and
identify the most influential users in
data sources to increase reach.
other third-party data that you have that segment.
access to. This helps you find and • Target those segments to optimize
identify the most influential data
on-site display advertising with
points for high-value audience
Test&Target.
profiles.
Reach an Advertiser's Requested Demographics with First and Third-Party Data
Reference
403
Goal
Benefit
Example
• Combine first and third-party data to • Improved monetization for digital
• Answer demo-targeted RFPs with
create more relevant, actionable
ads.
ready-made, third-party audience
audience segments.
• Identify the most valuable first-party segments aligned with your
first-party data.
• Package and sell enhanced
data and improve that information
segments to advertisers looking for with complimentary third-party data. • Provide recommendations to the
specific demographics like age,
advertiser based on the historical
gender, income, etc.
segment performance.
• Create the right kinds segments for
ad sales for any campaign strategy.
Boolean Expressions in Trait and Segment Builder
This article explains how the Audience Manager 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.
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.
Reference
404
Expression
Use it to create
To qualify
NOT
Narrow, focused audience qualification requirements. Users must not belong to an excluded
trait or segment.
Useful when there are multiple conditions that make
defining audience qualification requirements difficult
or inefficient. Occasionally, it is easier to validate
against requirements that exclude rather than include.
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).
Bulk Management Tools
The Bulk Management Tools let you create and manage multiple objects at once with single operation. You can
use Bulk Management Tools to work with data sources, derived signals, destinations, folders, segments, and traits.
Attention: The Bulk Management Tools are not supported by Audience Manager. This tool is provided for
convenience and as a courtesy only. For bulk changes, we recommend that you work with the Audience
Manager APIs instead.
Overview
This feature uses an Excel spreadsheet with macros that make secure, authenticated calls to the Audience Manager
APIs. The API provides the methods and services that let you make changes in bulk. You don't have to know how
to code or work with our APIs to use it. The worksheet contains column headers and tabs that perform specific bulk
change functions. To make bulk changes, all you do is add the pre-defined headers to specific worksheets, provide
Reference
405
the information you want to change in bulk, and click an action button. The worksheet and the APIs do the rest of
the work for you.
Getting Started With Bulk Management
Prerequisites, available operations, and authentication requirements.
Prerequisites
To use the Bulk Management Tools, you need the following:
• Your Audience Manager user name and password. As a customer, you should already have these credentials.
• An API client ID and secret key. Your account manager can provide you with these.
• The Bulk Management Tools worksheet. Download the latest verison (v0.4.2).
• Excel running on Windows or in a Windows virtual machine running on OS X. 32-bit Windows is preferred.
Actions and operations
The Bulk Management Tools worksheet consists of action tabs, action buttons, and a Headers tab. The Headers
tab contains the pre-formatted column headers used by the action tabs. The action tabs contain macros that perform
your selected bulk operation. To perform a bulk operation, you copy a set of headers into the appropriate action tab,
enter header data, and click an action button.
Open the spreadsheet and click the BAAAM tab to view and work with the Bulk Management Tools.
Reference
406
The table below lists the operations you can perform and items you can manipulate with the Bulk Management
Tools worksheets.
Actions
Objects
Bulk actions appear in tabs at the bottom of the worksheet The objects you can change in bulk are located under
and include:
the Headers tab and include:
• Requests
• Data sources
• Update
• Derived signals
• Create
• Destinations
• Estimate
• Trait folders and segment folders
• Delete
• Segments
• Traits
Reference
407
Bulk operation example
As an example, let's take a look at how to create multiple traits at one time. To create multiple traits in a bulk operation
you would:
1. Click the Headers tab and copy all the labels under the Create a Trait option.
2. Click the Create tab and paste the labels starting in row 1, column A.
3. Provide information related to each column header and click Create Traits. This action prompts you to log on.
Your bulk job runs after you successfully authenticate (see the authentication requirements below). Check the
lower left corner of the worksheet for a job status notification.
Note: When working with large requests, the worksheet might become unresponsive and appear to be inactive.
In these cases, just leave it alone. The worksheet will become responsive when the bulk request is complete.
If the worksheet does not respond for a long period of time, see the troubleshooting section.
Authentication requirements and options
Bulk changes require authentication. When you select an action, the worksheet prompts you to log in. Because the
worksheet makes API calls, you need to configure it to read your secret key. And, the Domain field lets you make
bulk changes in a staging/test environment or against your live, production account.
API authentication requirements
To set up API authentication, you must:
• Copy and save the secret key to a text (.txt) file.
• Name the text file with your API client ID. For example, if your client ID is "Bulk-User," save the key in a file titled
"Bulk-User.txt."
• Save the secret key and worksheet together in the same folder.
When making bulk changes, you'll still have to enter a user name, password, client ID, and domain, but API
authentication is automatic.
Domain authentication options
Reference
408
Domain authentication gives you the option to test bulk requests or apply them directly to your production account.
Making bulk changes to the test environment won't affect your production account. Production changes are effective
immediately. The Domain field accepts the following addresses, depending on the environment you want to work
in:
• Testing: staging-api.demdex.com
• Production: api.demdex.com
Bulk Requests
A bulk request returns data you can use with the different headers in the Update, Create, Estimate, and Delete
worksheets.
The Request worksheet does not have its own set of column headers and you don't need to copy IDs to any of the
columns. Instead, it returns data based on the action button you click in the toolbar. And, an optional reporting feature
returns a frequency count for pixel fires and unique user count for several fixed time intervals.
To make bulk requests, open the Bulk Management Tools worksheet and:
1. Click the Request tab.
2. In the tool bar at the top of the worksheet, click a request button corresponding to the data you want to work with.
You can request:
•
•
•
•
•
•
Data provider IDs
Derived signals
Destination mappings
Rule-based and on-boarded traits
Segments
Trait and segment folder IDs
The Audience Manager API writes bulk data back to the Request worksheet.
Note: In your results, the createTime and updateTime columns return data in exponential notation. The
underlying date/time stamps are recorded in UNIX UTC time. Currently, the worksheet cannot return date/time
stamps in a readable format.
If your bulk update returns an error or fails, see Troubleshooting Tips for Bulk Management Tools.
Bulk Updates
A bulk update lets you edit multiple segments, traits, and segment or trait folders elements in a single operation.
Follow these instructions to make bulk updates.
To make bulk updates, open the Bulk Management Tools worksheet and:
Reference
409
1. Click the Headers tab and copy the update headers for the item you want to edit.
2. Click the Update tab.
3. Paste the update headers into the first row of the update worksheet. Note the following:
•
•
When updating a folder, all headers are required.
When updating segments or traits, you only need the segment ID (SID) and the header element that needs
to be changed. Delete unused headers.
4. Paste or type the data you want to change into a corresponding column based on the header label.
5. In the worksheet toolbar, click an update button that matches the item you're updating.
This action opens the Account Information dialog box.
6. Provide the required log on information and click Submit.
The worksheet creates a Results column. The Results column returns the JSON response for a successful
operation. See the REST APIs for examples.
Before entering data, your bulk update worksheet should look similar to the following:
Bulk Create
Bulk create lets you construct multiple data sources, derived signals, segments, traits, and other items with a single
operation. Follow these instructions to make a bulk creation request.
Reference
410
: Do not mix object types in a bulk creation request. The headers for each object are unique and cannot be combined.
Clear the worksheet and make a separate request for different items.
To create objects in bulk, open the Bulk Management Tools worksheet and:
1.
2.
3.
4.
5.
Click the Headers tab and copy the create headers for the item you want to add.
Click the Create tab.
Paste the create headers into the first row of the update worksheet.
Paste or type the data you want to change into a corresponding column based on the header label.
In the worksheet toolbar, click the create button that matches the item you're updating.
The worksheet creates a Results column. The Results column returns the JSON response for a successful
operation. See the REST APIs for examples.
Before entering data, your bulk create worksheet should look similar to the following example. Note, all the different
create options are not shown here. This is included to help you understand what a completed worksheet could look
like.
Bulk Estimates
A bulk estimate returns segment size data based on segment rules. Follow these instructions to make a bulk estimate
request.
To make bulk updates, open the Bulk Management Tools worksheet and:
1. Click the Headers tab and copy the Estimate Segment Size header.
2. Click the Estimate tab.
Reference
411
3. Paste the estimate header into the first row of the estimate worksheet.
4. Paste or type the data you want to change into a corresponding column based on the header label.
5. In the worksheet toolbar, click the create button that matches the item you're updating.
This action creates a Response column in the worksheet that contains estimated segment size data.
Before entering data, your bulk estimate worksheet should look similar to the following:
Bulk Delete
Bulk delete lets you remove multiple segments, traits, folders, derived signals, and destinations with a single operation.
Follow these instructions to make a bulk delete request.
Note: A bulk delete for destination mappings will fail if you have segments mapped to the destination. Remove
your segments from that destination in the user interface before attempting to bulk delete destinations. Also,
trait and segment folders must be empty before you can delete them.
To delete multiple items, open the Bulk Management Tools worksheet and:
1.
2.
3.
4.
5.
Click the Headers tab and copy the create headers for the item you want to add.
Click the Delete tab.
Paste the delete headers into the first row of the update worksheet.
Paste or type the IDs for the objects you want to delete in the column below the header.
Provide the required log on information and click Submit.
The worksheet creates a Results column. The Results column returns a message that indicates if the item has
been deleted or an error message.
Before entering data, your bulk update worksheet should look similar to the following:
Reference
412
Create or Update Trait Rules and Segment Rules
The create and update worksheets accept a traitRule header that lets you apply multiple rules in a single operation.
Follow these instructions to make bulk rule requests.
Working with trait rules
In your worksheet, the trait rule column returns and accepts rules that consist of Boolean expressions, comparison
operators, and regular expressions. You can create rules with trait or segment builder in Audience Manager and
copy them to your worksheet. Or, if you're familiar with rule syntax, you can write expressions directly in the
worksheets.
Rule builder example
Let's take a look at an example that demonstrates how to use Segment Builder to create a rule you can to the bulk
worksheet. However, this isn't a set of step-by-step instructions for those tools. Instead we're going to start with a
simple rule that's already been created. For instructions about how to use the rule builders see Segment Builder
and Trait Builder.
With the visual rule builder, we've created a segment rule with 3 traits and a Boolean AND operator.
Reference
413
Click Code View to get the text version of this rule.
Tip: Click Validate Expression to check your rule logic. This will help prevent you from uploading an invalid
rule.
Paste the rule into the Bulk Management Tools worksheet and commit your changes to update segment rules in
bulk.
Creating your own rules
You can write your own rules outside of Rule Builder. Before you start, be sure to read the documentation that
covers things like operators, expression, and required variables. We recommend you review the following:
• Working With Comparison Operators In Trait Builder
• Order of Operations
• Prefix Requirements for Key Variables
• Sample Expressions With Boolean and Comparison Operators
Troubleshooting Tips for Bulk Management Tools
What to do when the worksheets return an error or your bulk request fails.
Responding to error messages
Factors like heavy network traffic, server usage, and large data sets can cause a bulk request to fail or time out. If
there is an issue, the worksheet stops writing data and displays an error message. When this happens, you should:
Reference
414
• Read the error message.
• Fix the problem.
• Delete all the rows that have been already updated.
• Try the bulk request again.
Long delays or unresponsive behavior
The following table lists some common problems you may encounter when making bulk requests with the worksheets.
Try to fix these issues with the recommended solutions. If the recommended solutions do not resolve the problem,
you should save your work, restart your computer, and try the request again without launching or working with other
applications.
Problem
Solution
Long delays
• Turn off compatibility mode: Check if you have other worksheets open in Excel's
compatibility mode. Compatibility mode can increase runtimes. Close any
spreadsheets you may have open in this mode and try your bulk request again.
• System resources: Limited system resources contribute to long delays. Try closing
all your other programs before making a bulk request.
No response
If you click on an action button and nothing happens:
• Make sure you have the right set of headers for the selection action.
• Make sure you're using the right worksheet for the copied headers.
• Check the position of the data you want to use in a bulk operation. All headers start
in column A, row 1. All data goes in corresponding headers starting in column A,
row 2 (immediately below the headers).
Bulk Management Tools Glossary
Column header labels defined.
Column header
Definition
dataSourceId
The ID of a data source you want to return or assign in bulk.
derivedSignalId
A derived signal ID.
description
A brief, informative description that you can give to an object.
destinationId
The ID of the destination you want to map or delete.
destinationMappingId
A special ID assigned to a segment when it is mapped to a destination.
Reference
415
Column header
Definition
folderId
The ID of your segment or trait folder.
name
The name of the object you're working with.
parentFolderId
The ID of a segment or trait folder that contains other folders.
sid
Segment ID.
sourceKey
Signals are bits of data passed in to Audience Manager based on user
activity. These are transmitted as key-value pairs. The source key is
a constant that does not change. It helps categorize the source value
which can change. See Derived Signals.
sourceValue
The source value is a variable passed in as part a key-value pair.
startDate
Indicates when a segment can start to be sent to a destination. Uses
yyyy-mm-dd format.
targetKey
The key used in the derived signal. See Derived Signals.
targetValue
The value passed in with a derived signal key. See Derived Signals.
traitAlias
An ID passed to a non-cookie based destination. For a cookie-based
destination, this is the key in a key-value pair.
traitRule / segmentRule
The actual trait or segment rule used to collect data. A bulk request
returns the rules created in Audience Manager with the trait rule builder
or the segment rule builder.You can also use these tools to build rules
and apply them in bulk when you update a segment or trait.
See also, Create or Update Trait Rules and Segment Rules.
traitType
A string that identifies the trait type. Options include:
• RULE_BASED_TRAIT
• ON_BOARDED_TRAIT
• SEGMENT
url
Pixel fired by DIL when a user qualifies for a segment.
valueAlias
The key in a key-value pair passed to a cookie destination.
Reference
416
CID Replaces DPID and DPUUID
Update your code to use d_cid or d_cid_ic instead of d_dpid and d_dpuuid. The DPID and DPUUID variables
will continue to work, but you should consider them deprecated. This includes DPID and DPUUID variants without
the d_ prefix.
Contents:
DPID and DPUUID: A Review
CID and CID_IC: About
DPID and DPUUID: A Review
The DPID and the DPUUID are key-value pairs that contain a data provider ID and a user ID. These key-value pairs
link provider IDs to user IDs. They send in data during event calls, for inbound synchronization events, and for ID
calls. Without them, Audience Manager, and other services or features, would not have a way to match and
synchronize IDs. These variables are sometimes expressed with or without the d_ prefix as shown below. Note, in
the code, italics indicates a variable placeholder.
Variable
Syntax
Data Provider ID (DPID)
• d_dpid=data provider ID
• dpid=data provider ID
Data Provider Unique User ID
(DPUUID)
• d_dpuuid=data provider unique user ID
• dpuuid=data provider unique user ID
These key-value pairs still work, but they are deprecated.You should update your code to use CID or CID_IC instead.
CID and CID_IC: About
The CID and CID_IC key-value pairs replace DPID and DPUUID. They provide the same functions as the DPID and
DPUUID, but are more efficient because they include the data provider ID and user ID (or integration code) in a
single key-value pair. In each key-value pair:
• The = symbol separates the key from its related values.
• The non-printing ASCII character %01 separates the values.
d_cid and d_cid_ic use the syntax shown below. Note, in the code, italics indicates a variable placeholder.
Variable
Syntax
Customer ID (CID)
d_cid=data provider ID%01user ID
Customer ID Integration
Code (CID_IC)
d_cid_ic=integration code%01user ID
An integration code is an alternate ID you can use instead of the Audience Manager
ID. See Create or Edit a Data Source if you need to configure an integration code.
See also, URL Variables and Syntax for Declared IDs.
Reference
417
Examples
The following table provides examples by event type.
Event Type
Example
Event
• New: .../event?d_cid=123%01987...
• Deprecated: .../event?d_dpid=123&d_dpuuid=987...
Inbound
Synchronization (IBS)
• New: .../ibs:d_cid=123%01987...
• Deprecated: .../ibs:d_dpid=123&d_dpuuid=987
Note: IBS calls do not support the CID and CID_ID key-value pairs yet. Our
engineering teams are working on this for a future release.
ID
• New: .../id?d_cid=123%01987...
• Deprecated: .../id?d_dpid=123&d_dpuuid=987
Each call can also include multiple d_cid and d_cid_ic key value pairs like this:
...?d_cid=123%01456&d_cid=123%01789&d_cid_ic=543%01333...
Data Retention
Describes data retention and user activity in the back-end and on the edge.
This section coitions the following information:
• Back-End Data Retention and User Activity
• Data Retention on The Edge and User Activity
Back-End Data Retention and User Activity
After 120 days of user inactivity across all customers, AAM deletes the user completely from our back-end (the User
Profile store). If a user maintained at least some DCS activity in that 120 days, they will continue to retain traits and
segments that were acquired even longer than 120 days.
Data Retention on The Edge and User Activity
User data on the edge is kept fresh as long as the user has been active. After 14 days of user inactivity across all
customers, AAM clears their real-time data from the edge. This means that if the user becomes active again after
the 14 day period, there will be a delay between that first new page view and when the user becomes actionable.
It will take 6-18 hours to get the full profile back out to the edge center where they showed up again (after > 14 days
of inactivity).
Key-Value Pairs Explained
Defines and describes standard and serialized key-value pairs.
Reference
418
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 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)
Reference
419
Password Requirements, Locked Accounts, and Forgotten Passwords
Audience Manager passwords expire every 30-days. Refer to this section for password requirements and how to
recover a lost or forgotten password.
Password Requirements
To be valid, your Audience Manager password must meet the following requirements:
Requirements
Description
Length
Passwords may be between 12 to 40 characters long.
Contents
Passwords must:
• Begin and end with an alphanumeric character.
• Contain at least 1 uppercase and lowercase character.
• Contain at least 1 number.
• Contain at least 1 special character (colons ":" excluded).
• Consist of Latin alphabet letters only.
Versions
Passwords must be different from your previous 12 passwords.
Prohibited Items
Passwords must not contain your:
• First name or last name.
• Email address.
• Adobe user ID.
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 Manager 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.
Reporting and File Transfer Time-Frame Guidelines
Information describing the time frames when Audience Manager receives information to populate reports and when
Audience Manager 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
420
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.
• 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
Manager, see Reports.
Inbound and Outbound File Transfers
Audience Manager processes and sends inbound and outbound Server-to-Server (S2S) file transfers according to
the schedules described in this section. Given these schedules and the cut-off times, you might see discrepancies
with new segments between real-time and total segment numbers.
Inbound File Ingestion (Offline Data)
File processing starts at 06:00 UTC and 18:00 UTC. These procedures ingest data and prepare it for delivery. File
delivery times vary because they are affected by the total amount of customer data that needs to be processed.
Outbound File Export
File processing takes place at 00:00 UTC and 12:00 UTC. File delivery depends on the amount of time it takes this
procedure to run and the amount of data it needs to publish. However, unlike the inbound data file process, you
should receive these files between 11:00 UTC and 15:00 UTC for the first daily run and between 23:00 UTC and
3:00 UTC for the second daily run.
Beta Environment
The beta environment is for testing your Audience Manager implementation. Changes made in beta do not affect
production data. Contact your Audience Manager Partner Solutions representative if you're interested in using the
beta environment.
Service
URL/Hostname
FTP
sandbox-ftp-in.demdex.com
DCS
https://dcs-beta.demdex.net/...
UI
https://bank-beta.demdex.com
API
https://api-beta.demdex.com/...
Note: The FTP is used for both inbound and outbound traffic, there is no dedicated FTP for outbound data.
To access the DCS in the beta environment:
1. Determine the load balancer's endpoint IP addresses.
Reference
421
Run the dig command to determine the IP address of the nearest load balancer. The dig command queries the
Domain Name System and returns the name and IP addresses of the Audience Manager Data Collection Servers
(DCS).
dig dcs-beta.demdex.net
...
dcs-sandbox-1754093861.us-east-1.elb.amazonaws.com. 60 IN A 52.87.15.51
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:
52.87.15.51 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.
52.87.15.51 dpm.demdex.net .
3. Make a DCS call, using the curl command. Curl is a tool to transfer data from or to a server, using one of many
supported protocols.
For example:
https://<domain>/event?product=camera
4. Verify that your request was served by the beta DCS by looking for "sandbox" in the DCS response header.
For example:
curl -v http://dcs-beta.demdex.net/?event
[...]
< DCS: va6-sandbox-dcs-3.sandbox.demdex.com <release_number>
[...]
Signals, Traits, and Segments
Describes the components of an Audience Manager segment, the expressions used to set audience qualification
criteria, and how data is transmitted in an event call.
Composition and Purpose
Audience Manager 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 Manager segment.
Element
Signal
Consists of
Example
Signals are the smallest data units in Audience
Manager and are expressed as key-value pairs.
• product=camera
• The key is a constant that defines a data set (e.g.,
gender, color, price).
• type=digital SLR
• price>1000
Reference
Element
422
Consists of
Example
• 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.
Segment
From the available signals, you could
create a "High End Camera Browser"
rule expressed as:
Create precise qualification requirements with
combinations of traits and trait groups.
product=camera AND price>1000
Users who share a set of common attributes and
qualify for related traits.
From the available traits and signals,
you could create a segment rule
expressed as:
Boolean expressions, along with recency/frequency
requirements, let you create segment qualification
rules.
Create precise qualification requirements with
combinations of trait and segment rules.
(product=camera AND
type=digital SLR) OR
(price>1000)
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 Manager 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 Manager
An event call sends data from your website to Audience Manager. 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 Manager.
http://<domain>/event?product=camera&price>100
Supported Browsers
Lists the browsers supported by the Audience Manager user interface.
Unless indicated otherwise, Audience Manager is supported on the latest versions of the following browsers:
• Chrome
• Firefox
• Internet Explorer (version 9 or greater)
• Safari
Reference
423
Other browsers may work, but are not supported by our technical and product teams. If you're having trouble working
with Audience Manager, make sure you're using an updated, supported browser.
System Components
A high-level tour of the major components and data flows in the Audience Manager system.
Introduction
This guide provides a basic overview of the main components that power Audience Manager. It is written for:
• Non-technical and technical readers.
• Current Audience Manager customers curious about how it all works.
• Potential Audience Manager customers who need to evaluate this system as part of a due diligence or request for
proposal process.
This guide tries to strike a balance between general descriptions and a deep dive. However, some things are
proprietary so we're just not going there. After all, there's more to special sauce than just mayonnaise and ketchup.
We need to keep the pickles a secret. As always, you can check with your Audience Manager consultant if you have
any questions.
Contents
Key Components in the Audience Manager System
Audience Manager 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 Manager. 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.
Reference
424
Data Action Components
Data action components include Customer Data Feeds, the Data Collection Server, SFTP/S3/HTTP publishers,
IRIS, and the Profile Cache Server.
Action components are systems and processes that let you move data in and out of Audience Manager and (for the
lack of a better phrase) do things with it. These Audience Manager components include:
• Customer Data Feeds (CDF)
• Data Collection Server (DCS)
• SFTP/S3
• HTTP Publisher
• IRIS
• Profile Cache Server (PCS)
Customer Data Feeds (CDF)
CDF are files sent hourly to customers. These contain user IDs along with associated segment IDs, trait IDs, and
other data. For more information, see Customer Data Feed Overview.
Data Collection Server (DCS)
See Data Collection Components.
SFTP/S3
The SFTP/S3 publishers receive synchronized ID data from the Outbound Feed Converter. When these files are
ready, the SFTP/S3 publishers send this data to a destination specified by the client.These files contain synchronized
ID data with a one-to-many mapping of Audience Manager user IDs (UUID) to:
• Device ID/data provider IDs (DPUUID)
• Qualified segment IDs
• Trait IDs
Audience Manager customers do not have access to features that directly control the SFPT/S3 publishers. Customers
use this service indirectly when they create and send data to destinations. The SFTP/S3 system is, essentially, an
automated job process that runs at scheduled intervals.
HTTP Publisher
The HTTP Publisher works with the same type of data as the SFTP/S3 system. However, the HTTP Publisher is
different because it sends data to destinations in real time rather than at set intervals. This is a separate system
because the SFTP/S3 publishers can't send data to an HTTP destination and they're not designed for real-time data
transfers. To perform these functions, the HTTP Publisher service takes advantage of the real-time features provided
by IRIS.
There are no UI controls that let customers work directly with this system. Customers work with the HTTP Publisher
indirectly when setting up real-time data transfers. The HTTP Publisher is another automated job process for
real-time data transfers.
Reference
425
IRIS
In Greek mythology, Iris is a figure who travels and delivers messages rapidly. The IRIS system is a namesake that
reflects the characteristics of this figure from the ancient world. In modern terms, IRIS is a low-latency, high-frequency
cookie synchronization and data transfer service. Examples of IRIS services and features include:
• Providing rapid (within 30 seconds) synchronization for cookies and segments. It can synchronize the Audience
Manager cookie, partner cookies, or both.
• Real-time data transfers. IRIS is responsible for sending real-time segment qualification events to a partner or
other destination. This data is JSON-formatted and sent via an HTTP POST request.
• Bulk server-to-server data transfers: If you exchange large amounts of data with Audience Manager, IRIS is the
system that your servers engage with to transfer data.
• Reliable infrastructure that works at scale and is fault tolerant. Systems that power IRIS include Amazon SQS,
Amazon EC2, and Cassandra.
Sample data file
The following example contains real-time segment data from IRIS. Keep in mind this is sample data only. Each
customer may have different formatting requirements so the contents can vary.
{
"ProcessTime": "Tue Jul 21 19:12:45 UTC 2015",
"Client_ID": "111111",
"User_count": "5",
"Users": [
{
"AAM_UUID": "28272096202945091600036434734793744071",
"DataPartner_UUID": "CAESEFdv5pk-Lurd8vL9Yfb3qFg",
"Segments": [
{
"Segment_ID": "1200598",
"Status": "1",
"DateTime": "Tue Jul 21 19:12:12 UTC 2015"
}
]
},
{
"AAM_UUID": "35183292386788708387827965829455926157",
"DataPartner_UUID": "CAESEF_d8blvZjchQ2WTzdB65yk",
"Segments": [
{
"Segment_ID": "1306742",
"Status": "1",
}
]
},
{
"AAM_UUID": "28012470144260632050402316345856327572",
"DataPartner_UUID": "CAESEEPfHBiRjhkzvBPXQ-0MFRE|UzCESAAABOnFeHJy",
"Segments": [
{
"Segment_ID": "1306742",
"Status": "1",
}
]
},
{
"AAM_UUID": "18981483751565214534184221210627150539",
"DataPartner_UUID": "CAK4NDH0ESEE6NBEhoWDkB7s7ZY|VPYFQQAAASXPElL0",
"Segments": [
{
"Segment_ID": "1306742",
"Status": "1",
Reference
426
}
]
},
{
"AAM_UUID": "04761851136483019318109155624251711702",
"DataPartner_UUID": "CAESEDkM5aSaKMV8MfaBhgSspmE|VYnTNwAAASzvVhxy",
"Segments": [
{
"Segment_ID": "1306742",
"Status": "1",
}
]
}
]
}
There are no UI controls that let customers work directly with IRIS. Customers work with IRIS indirectly when they
create and send data to destinations, and for other processes that require rapid data transfers.
Profile Cache Server (PCS)
SeeData Collection Components.
Data Collection Components
Data collection components include the Data Collection Servers, the DIL API, inbound server-to-server data transfers,
and log files.
Audience Manager contains the following data-collection components:
• Data Collection Servers (DCS) and Profile Cache Servers (PCS)
• Data Integration Library (DIL)
• Inbound Server-to-Server
• Log Files
Data Collection Servers (DCS) and Profile Cache Servers (PCS)
The DCS and PCS work together and separately provide services related to trait realization, audience segmentation,
and data storage.
Data Collection Servers (DCS) Function
In Audience Manager, the DCS:
• Receives and evaluates trait data from an event call. This includes information used for real-time segmentation
and data passed in at scheduled intervals by server-to-server transfers.
• Segments users based on their realized traits and the qualification rules you create with Segment Builder.
• Creates and manages device IDs and authenticated profile IDs. This includes identifiers such as data provider IDs,
user IDs, declared IDs, integration codes, etc.
• Checks the PCS for additional traits a user has already realized prior to a real-time event call. This lets the DCS
qualify users based on real-time data and historical data.
• Writes log files and sends those to analytics systems for storage and processing.
DCS Manages Demand Through Global Server Load Balancing (GSLB)
The DCS is a geographically distributed and load-balanced system. This means Audience Manager can direct
requests to and from a regional data center based on the geographic location of a site visitor. This strategy helps
Reference
427
improve response times because a DCS response goes directly to a data center that contains information about
that visitor. GSLB makes our system efficient because relevant data is cached in servers closest to the user.
In an event call, geographic location is captured in a key-value pair returned in a larger body of JSON data. This
key-value pair is the "dcs_region":region ID parameter.
As a customer, you engage with the DCS indirectly through our data collection code. You can also work directly with
the DCS through a set of APIs. For sample code, event calls, responses, and more information about working with
the DCS, see:
• DCS Integration
• Real-Time Data Transfers With the DCS API
Profile Cache Servers (PCS)
The PCS is a large database (basically, a huge server-side cookie). It stores data received for active users from
server-to-server transfers and the DCS. PCS data consists of device IDs, authenticated profile IDs, and their
associated traits. When the DCS receives a real time call, it checks the PCS for other traits a user may belong to
or qualify for. And, if a trait is added to a segment at a later time, those trait IDs are added to the PCS and users
can qualify for that segment automatically, without a visit to a particular site or app. The PCS helps deepen Audience
Manager's understanding of your users because it can match and segment users in real time or behind the scenes
with new and historic trait data. This behavior gives you a more complete and accurate picture of your users than
from real-time qualifications alone.
There are no UI controls that lets our customers work directly with the PCS. Customer access to the PCS is indirect,
through its role as a data store and data transfers. The PCS runs on Apache Cassandra.
Purging inactive IDs from the PCS
As indicated previously, the PCS stores trait IDs for active users. An active user is any user who has been seen by
the edge data servers from any domain during the last 14-days. These calls to the PCS keep a user in an active
state:
• /event calls
• /ibs calls (ID syncs)
Reference
428
• /dpm calls (third-party, data-provider traits passed in during user visit)
The PCS flushes traits if they're inactive for 17-days. These traits aren't lost however. They're stored in Hadoop. If
the user is seen again at another time, then Hadoop pushes all of their traits back to the PCS, typically within a
12-hour period.
Other DCS/PCS Processes: Privacy Opt-out
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. For more information about our privacy policies see the Adobe Privacy
Center.
Data Integration Library (DIL)
DIL is code you place on the page for data collection. See the DIL API for more information about available services
and methods.
Inbound Server-to-Server
These are systems that receive data sent in by various server-to-server integrations with our clients. See the
documentation on sending audience data for more information.
Log Files
The PCS creates and writes data to the log files. These are sent to other database systems for processing, reporting,
and storage.
Data Processing Components
Data processing components include Hadoop, Redshift, SOLR, and Tableau.
Audience Manager uses the following components to process data:
Hadoop
In Audience Manager, Hadoop is the master database that contains everything Audience Manager knows about a
user. For example, when the Profile Cache Servers create log files that contain data about your users, it sends that
data to Hadoop for storage. 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. It processes and manages inbound and outbound data, trait rules, algorithmic
modeling information, and performs many other functions related to storing and moving data to different systems.
Customers do not have direct access to these systems. However, customers do work with them indirectly as these
components store important data about their site visitors.
Redshift
RedShift is a massive cloud database. It provides data to many of the dashboard graphs and their related text boxes
that display the % change for each item in the graph. If you use Audience Manager and look at the dashboard
reports, you're interacting with data provided by Redshift.
Reference
429
Figure 1: Sample Dashboard Graph Powered by Redshift
This is by no means a comprehensive list, but some common dashboard reports that Redshift is responsible for
include:
• Daily Trait Variation Report
• Delivery and Performance Report
• All the overlap reports (see the Interactive Reports section for information about each overlap report).
• Unused Signals Report
SOLR
SOLR is an open-source database and server system from Apache. It provides robust and fast search capabilities
over our large data sets. As an Audience Manager customer, you can see SOLR in action when you build segments.
It provides data to the Estimated Historic Segment Size report. SOLR is ideal for this role because of its speed.
For example, SOLR is able to update the historic size data as you build rules and add new traits to a segment.
Reference
430
Figure 2: Historic Segment Size Estimator Powered by SOLR
Tableau
Audience Manager uses Tableau to display data in the Interactive Reports and the Advertiser Analytics 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.
Figure 3: Sample Report Powered by Tableau
Tag Management Components
Audience Manager tag management components include the client portal, Adobe Tag Manager, DIL, Akamai, and
the control database.
Audience Manager contains the following components:
• Client Portal
• DIL/TIM Container
• Data Integration Library (DIL)
• Akamai
Reference
431
• 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.
DIL/TIM Container
The DIL container helps deploy Audience Manager data collection code to your website. TIM is the deprecated Tag
Insertion Manager. It is no longer used by Audience Manager. Instead, you use Dynamic Tag Management 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 Manager.
Data Integration 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 information. Finally, DIL helps you integrate Audience Manager
with other products in the Adobe Marketing Cloud.
Akamai
Audience Manager 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, creating traits and destinations).
• Transmits data to Akamai, which includes data used to build the container template and destination publishing
iFrame.
• Returns data for UI reporting systems.
Platform Architecture: Data Flow Map
This map contains the major Audience Manager systems. It visually represents how data flows into, out of, and
among Audience Manager components.
How to read this map
In the map, the gray box contains Audience Manager systems. Some components are completely internal and others
sit on the boundary between Audience Manager and the outside world. As an Audience Manager customer, internal
components are often transparent or inaccessible. However, sometimes you may engage with these systems through
the user interface or data integrations. Systems on the edge of the box collect and send data between Audience
Manager and the outside world.
Colors define the type of data that flows in and out of Audience Manager. Green is client data, blue is customer data
(people visiting your site), and orange is data used for reporting.
For system descriptions and summaries see the data action, collection, processing, and tag management sections.
Reference
432
Understanding the Edge Data Center
Audience Manager uses distributed, edge-computing topologies to meet the demands placed on our systems by
external sources.
Edge Data Center Basics
Edge computing provides improved performance in response to diffuse, Internet-wide demand because the “edge”
itself is a global boundary. This means Audience Manager 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 Manager.
The Audience Manager edge data center includes:
• Core Servers: These are the main Audience Manager 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
Manager and the Internet. Edge servers, such as the DCS or Akamai systems, typically handle data and requests
flowing into and out of Audience Manager.
• 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 Manager edge data center environment.
Reference
433
Geographic Distribution and Load Balancing
See the DCS section in Data Collection Components.
Style Conventions for Code and Text Elements
These elements identify code options and variables used throughout the help documentation. Generally, you would
not include these symbols or style elements in your code or data files. They're visual indicators only.
Convention
Explanation
variable
Variables appear in italics. Substitute the appropriate value for the variable name.
For visual clarity, sometimes variables and other code elements appear between < >
brackets. You do not need to use these symbols in your code.
[optional]
Items in square brackets are optional.
Reference
434
Convention
Explanation
(this|that)
Items in parenthesis indicate a Boolean OR choice.
literal
Include text or code exactly as shown.
< >
Sometimes variables and other code elements appear between < > brackets. These
are used to improve clarity in long code blocks. Unless specified, do not include these
symbols in a data file name or its contents.
Time Zones in Audience Manager
Audience Manager uses Coordinated Universal Time (UTC) across its entire UI.
Unless otherwise specified, all the dates and date ranges you can select in the Adobe Audience Manager UI are
Coordinated Universal Time (UTC). For example, in the Create Destination flow, when mapping segments to your
destination, the start and end date you select are midnight UTC. The same applies for all the dates in Audience
Manager.
FAQ
435
FAQ
Frequently asked questions about Audience Manager features, functions, and common issues.
API FAQ
Common API questions and issues.
The REST API documentation contains details about specific methods and code samples.
Why does DIL make event calls with GET and POST methods?
DIL passes data to Audience Manager with a GET or POST method based on the length of the query string of the
event call. This behavior is built in to GET and POST methods by default. It is not specific to Audience Manager.
• DIL makes event calls with GET when a URL contains 2048 characters or less. A GET event call includes data in
the URL as query string parameters, which are passed in as key-value pairs.
• DIL makes event calls with POST when a URL contains more than 2048 characters. A POST event call includes data
in the body of the request. DIL puts data into key-value pairs and passes information as form data rather than in
the URL query string.
Although each method passes data in a different way, this does not affect functionality. For example, with either
method, Audience Manager still sends data to destinations, ID syncs works normally, and you can create traits from
data signals.
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 Manager, 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 Manager DIL module
3. Analytics s.t() function
FAQ
436
As a best practice, set up your Audience Manager-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.
SeeData Integration Library (DIL) API.
Why are my Analytics variables missing from an Audience Manager 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.
• 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 Manager. However,
Audience Manager 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 Manager.
Can I get raw data from Audience Manager and how granular is it?
Yes, Audience Manager can provide you with data collected for users we've seen on your inventory. This includes:
• The unique user ID (UUID) assigned by Audience Manager
• Trait and segment IDs
• Unused signals
• Time stamps
• Page URLs
FAQ
437
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 Manager 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 Manager 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 Manager cannot get segment information to DFP.
What is the best third-party data provider?
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 Manager set cookies and pass variables to DFP?
Audience Manager 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 Manager?
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 Customer Data Ingestion FAQ
Frequently asked questions about bringing offline data into Audience Manager.
Can you summarize the onboarding process?
The onboarding process consists of 3 core components described in the Technical Specifications for Inbound Batch
Data Transfers. These involve:
• ID synchronization
• Data Translation File (or Taxonomy File)
• Inbound Data File (.sync file or .overwrite file)
Below is a list of questions and answers you might find helpful after reviewing the documentation.
Note: The examples in this section are simplified or shortened for brevity and demonstration purposes. Refer
to the online documentation for detailed specifications about file formats and syntax.
Can you summarize the deployment process?
We recommend the following:
FAQ
438
• Work with your data provider to format the daily inbound data file according to Adobe specifications.
• Transfer a test data file to Adobe for format verification.
• 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.
• In the staging/development environment, confirm that the ID sync is configured to properly pick up the data provider's
visitor ID and transfer it to the Audience Manager servers in realtime.
• Deploy DIL/ID sync to production. The ID sync will already be configured as a module within the DIL code by your
Adobe consultant.
• Transfer production data files to Audience Manager. 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.
What FTP mode should I use to transfer compressed or encrypted files?
See File Compression for Inbound Data Transfer Files.
Can I upload an inbound data file (.sync or .overwrite file) before deploying Audience Manager code into
production?
• If the data provider is configured to use Profile Link for cross-device targeting, the data available for targeting shortly
after an ID sync identifies to the matching Audience Manager visitor ID.
• If the data provider is not configured to use the Profile Link feature, Audience Manager processes only the data
for visitor IDs in the inbound data file that have been previously synced/matched back to an Audience Manager
visitor ID.
Consider the following use cases in which the data provider is not configured to use Profile Merge:
Use Case
Description
Case 1
On Monday, a visitor identified in the CRM database as visitor ABC logs in, which initiates a client-side
ID sync. Audience Manager stores the mapping of visitor ABC to Audience Manager visitor 123.
On Tuesday, the CRM database transfers a data file (.sync) to the Audience Manager server with
the following record:
ABC "gender"="male","luxury_shopper"="yes"
In this case, Audience Manager:
• Recognizes visitor ABC from the stored ID sync mapping.
• Associates the traits male and luxury_shopper with the visitor 123 profile.
Case 2
On Monday, the CRM database pushes a data file (.sync) to the Audience Manager server with the
following record:
DEF "gender"="female","wine_enthusiast"="yes"
Audience Manager does not have a record of this visitor (or an associated visitor ID) so this record
is not processed.
On Tuesday, visitor DEF logs in. This action initiates the first client-side ID sync for that visitor. This
action maps visitor DEF to Audience Manager ID 456. However, this visitor does not have CRM data
FAQ
439
Use Case
Description
associated with their profile. As a result, Audience Manager does not go back and reprocess old
files.
On Wednesday, the CRM database pushes another data file to the Audience Manager server with
the following record:
DEF "gender"="female","wine_enthusiast"="yes","dma"="paris"
In this case, Audience Manager:
• Recognizes visitor DEF from the stored ID sync mapping.
• Associates the traits female, paris, and wine_enthusiast with the visitor 456 profile.
What time of day should I transfer my file?
Audience Manager checks for and processes files multiple times throughout the day. Upload your data whenever
you're ready.
How long does it take before data from an uploaded file is available for targeting?
Data is available for targeting after 12-36 hours. Also, do not interpret the "successful upload" email as a statement
that the data is available. This only means that Audience Manager has picked up the file and completed the first
step of processing.
How often should I send files and should these be full or incremental files?
As a best practice, send an incremental file once per day for new visitors and for visitors whose data has changed.
Many Audience Manager customers send a full file once per month. However, these file intervals and increments
are flexible. You should send data in increments and at times that make sense for you.
How long does Audience Manager keep my files on the server?
FTP files are removed after they've been processed. S3 files are removed after 30-days.
What's the difference between full and incremental files?
• Full: A full file overwrites all of your existing visitor profiles and replaces them with the data in your file. Full files
are identified by the .overwrite tag appended to the file name. You can use a .overwrite file to reset visitor
traits or remove stale, obsolete traits.
Note: The .overwrite files only overwrite Audience Manager profile data associated to this data provider.
In other words, all Adobe Analytics data associated to the visitor remains intact after a .overwrite file has
been processed.
• Incremental: An incremental file appends new data to your existing visitor profiles. Incremental files are identified
by the .sync tag appended to the file name. Sending in an incremental file does not erase or overwrite existing
profiles.
The following use cases demonstrate how these file types affect stored visitor profiles.
FAQ
Use Case
440
Description
Incremental • Day 1 .sync file contents: visitor123 = a,b,c
and Full
• Day 2 .overwrite file contents: visitor123 = c,d,e
• Day 3 visitor profile ID 123 contains c,d,e
Incremental • Day 1 .sync file contents: visitor123 = a,b,c
Only
• Day 2 .sync file contents: visitor123 = c,d,e
• Day 3 visitor profile ID 123 contains a,b,c,d,e
For more information about full and incremental file types, see:
What happens if I send in a file with IDs for visitors that have never performed the on-page ID sync?
During processing, Audience Manager simply skips that record and moves on to the next. If a DPID (Data provider
ID) is set up as a cross-device DPID, data that is ingested before an ID sync is saved and is available for use shortly
after the ID sync occurs.
What is the time stamp, what is it for, and can you provide an example?
Time stamps are used for logging and record keeping. They are required by the syntax used for a properly formatted
inbound file name. See:
What is a Data Provider ID (DPID) and how do I get it?
Your Adobe consultant will assign a three-digit or four-digit DPID to your particular data source. This ID is unique
and does not change.
How large can the daily data files be?
See File Compression for Inbound Data Transfer Files.
Does Audience Manager support file compression?
Yes, see:
• File Compression for Inbound Data Transfer Files
What is the taxonomy (data translation file) for?
The taxonomy is required so Audience Manager can resolve unstructured data contained in the inbound data file
into a structured trait and folder hierarchy. Additionally, some customers store their CRM data as codes (e.g.,
008937) so the taxonomy gives you a way to assign human-readable designations to these values. Without a
taxonomy, Audience Manager cannot match data in inbound files to traits. See Data Translation File.
How often should I update the taxonomy?
FAQ
441
For most use cases, the taxonomy isn’t something that needs to be updated very often. Generally, data provider
databases have a finite number of data points that don’t change often. See Data Translation File.
The primary key in my data source database is an email address. Is that considered personally identifiable
information?
Yes. Audience Manager does not store email addresses in our database. visitors 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: A Unique User ID (UUID) and profile data, usually in the form of
key-value pairs or codes. The UUID is case-sensitive. Generally, profile or key-value data is not case-sensitive.
Should I use FTP or Amazon S3 to transfer files?
As best practice, we recommend Amazon S3 because the process is simpler. Audience Manager transfers FTP
files to S3 regardless, so the process is more streamlined if you drop the files on Amazon S3 yourself. Amazon S3
is also replicated and distributed, so it is generally safer and more reliable than an FTP server. For more information,
see Amazon S3: About.
Privacy FAQ
Common privacy-related questions and issues.
The Adobe Privacy Center contains additional information about common privacy topics.
How does Audience Manager use cookies?
Technologically speaking, cookies are called "HTTP cookies". These are small text files stored by your web browser
and which help our customers uniquely identify your browser. Audience Manager sets a number of cookies on user's
browsers. Visit the Marketing Cloud Cookies page for more detailed information on the cookies set by Audience
Manager.
Can Audience Manager clients in the US target users on EU properties?
Yes. Audience Manager 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 Manager 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
Manager (and our partners) comply with existing and future PII-related legislation.
Product Features and Functions FAQ
Common product and function-related questions and issues.
FAQ
442
Can I create traits or destinations in bulk?
Yes. See Bulk Management Tools. Note, The bulk tools are not supported by Audience Manager. They're provided
for convenience and as a courtesy only. For bulk changes, we recommend you work with the Audience Manager
APIs instead.
Can Audience Manager reduce the need for third-party tags or pixels and improve page load times?
If Audience Manager is integrated with your third-party data partner, you can replace their pixels and tags with a
server-to-server ID call to Audience Manager. In this case, Audience Manager would fire a single ID call the first
time we see a user and synchronize that information with your third-party partner. This eliminates the need to make
multiple pixels call from every page. Reducing pixel calls can improve page load times.
Reporting FAQ
Common reporting-related questions and issues.
For new onboarded traits, why does the Trait Graph sometimes display lower than expected numbers or 0?
Sometimes, after you upload traits, the Trait Graph doesn't show any results or shows lower than expected numbers.
This happens when the volume of data we receive is so great that the inbound processing job cannot finish ingesting
this information until after the reporting deadline for that day. As a result, this data is sent to the reporting system
late and won't show up in the 1-day reporting interval which is used for plotting the Trait Graph. However, you can
view this data in the 7, 14, 30, and 60-day report intervals in a Trend or General Report on the following day.
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 also:
• Reports and Data Sampling Methodologies
• 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.
FAQ
443
I have a segment consisting of just one trait. When I look at Reporting metrics, their counts don't match.
Why is that?
See Trait and Segment Size Data in Segment Builder.
I Inbound a file and my Inbound receipt shows a high number of successfully processed records, but
reporting shows much lower numbers. Why?
In the backend, onboarded data gets attached only to users that are still active in AAM (user must have had recent
DCS activity in the past 120 days). Therefore, if you onboard data for users that have already expired in AAM,
Inbound might tell you that a certain number of user records were onboarded, but if these users have not had any
recent activity, this data is dropped when it reaches our User Profile Store and reporting will surface that.
Why are the trait uniques for my cross-device onboarded traits much higher than the total number of
onboarded records?
If you onboard a file for a cross-device data provider keyed off the customer ID, Audience Manager performs a
lookup to get all device IDs that are associated with each of the onboarded customer IDs. Audience Manager then
assigns the onboarded traits to the device ID associated with the customer ID.
As an example, suppose you have onboarded 100 records. For each of these customer IDs, on average, AAM has
associated three device IDs. As a result, the trait that was onboarded is assigned to 300 device IDs.
There are two reasons why a single cross-device customer ID can be associated with multiple device IDs:
• Users are logging in to the same cross-device account from multiple computers/browsers.
• Users are clearing their cookies. Note: “Abandoned” cookies are deleted after 120 days of user inactivity.
Why are Total Fires for my onboared traits always 0?
Total fires correspond to page loads. Total trait fires provide the number of times that specific trait has fired in realtime.
This number is calculated for rule-based traits only. Onboarded traits always show Total Fires as 0.
Targeting FAQ
Common targeting-related questions and issues.
Where can I find a full list of third-party data providers supported by Audience Manager?
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 Manager supports.
To target users I've never seen on my site with third-party data, should I use third-party data in Audience
Manager 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 Manager 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 Manager lets you aggregate users and market to them based on shared attributes or traits. However, to
comply with industry regulations, Audience Manager customers may not send personally identifiable information
FAQ
444
(PII) to 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 Manager 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 Manager 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 Manager 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
Manager user for segment performance reporting. However, if an ad server is present on site, then we synch IDs
directly on the page.
Does Audience Manager count a user who logs on from different devices as one unique user or different
unique users?
Declared ID Targeting helps Audience Manager 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 Manager 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 Manager 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 Manager 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?
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 Manager 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 Manager cookies?
The user interface lets you determine the cookie expiration interval. You can set cookies to expire after n number
of days or never.
FAQ
445
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.
Documentation Updates
446
Small updates or changes to the Audience Manager guide that might not be included in the Marketing Cloud release
notes.
For information about feature releases, enhancements, and bug fixes see the Marketing Cloud Release Notes. See
the previous release notes for older Marketing Cloud announcements.
October, 2016
Topic
Description
Algorithmic Models
Changed title to Algorithmic Models from Models.
What Happens After a Provider
Deactivates My Data Feed
Fixed incorrect header names provided in the deactivation email attachment.
Declared ID Variables
Fixed broken link to ID service documentation.
Import DCM Data Files Into
Audience Manager
Added note to remind customers to check their file format with their DCM
account manager.
GA.init
Revised to note that GA.init() does not work with the latest version of
Google's analytics code, analytics.js.
Amazon S3: About
Added encryption-at-rest for batch outbound data transfers.
Profile Merge Rule Options Defined Revised to include more information about the Adobe Marketing Cloud Device
Co-op.
September, 2016
Topic
Description
Privacy FAQ
Modified the demdex cookie's and the partner cookie's time-to-live (TTL) value
to 180 days to comply with French CNIL regulations.
Cookies used in the Marketing Cloud Modified the demdex cookie's and the partner cookie's time-to-live (TTL) value
to 180 days to comply with French CNIL regulations.
Understanding the Data Integration A general overview of the Data Information Library (DIL).
Library (DIL)
Inbound Data File Contents: Syntax, Updated the invalid characters list in trait IDs for inbound data files.
Invalid Characters, Variables, and
Examples
Addressable Audiences
Minor revisions and reorganized content.
447
Topic
Description
Time Zones in Audience Manager
Audience Manager uses Coordinated Universal Time (UTC) across its entire
UI.
API Code Migration
Added links to Segment Test Group APIs & Data Feed Request API.
August, 2016
Topic
Description
Audience Lab
Create mutually exclusive test segments in Segment Test Groups to compare
and measure effectiveness of different destinations.
DCS Error Codes, Messages, and
Examples
Added new customer-facing error codes to the index.
Digitally Signed HTTP Requests
A document explaining why and how to encrypt server-to-server HTTP
requests.
Device Targeting With Platform-level
Added a downloadable list of the most common device keys, according to
Keys
Device Atlas measurements.
DCS Error Codes, Messages, and
Examples
Added new customer-facing error codes to the index.
secureDataCollection
Control how DIL makes data collection calls with HTTP or HTTPS.
API FAQ
Updated content that explains why DIL uses GET and POST methods to send
data in an event call.
Real-Time Outbound Data Transfers Updated with additional requirements and information.
July, 2016
Topic
Description
Onboarding Status Report: About
Revised documentation for the UI redesign.
Getting Started With Bulk
Management
A new bulk management template, v0.4.2 is available for download.
Updated the Advertiser Analytics reports with Cross Channel Conversion,
Role-Based Access Control, Conversion Groups, and the Reported Conversion
Traits report.
448
Topic
Description
Cross Channel Conversion
The Cross Channel Conversion option in the Advertiser Analytics reports
allows you to attribute offline conversions to served online impressions or
clicks.
Reported Conversion Traits
This report shows you all the traits labeled as conversion traits for a conversion
group at a certain date.
Geotargeting With Platform-level
Keys
Updated the keys list with the latest values.
Device Targeting With
Platform-level Keys
A new document which describes the common platform-level key-value pairs
you can use to target users with device-related variables across all properties
in your Audience Manager account.
June, 2016
Topic
Description
Server Side Forwarding
Server-side forwarding replaces DIL code with the
Audience Management Module as the data collection
and transfer mechanism for Audience Manager.
Updated to include passing mobile IDs with d_cid.
Beta Environment
Updated the DCS, UI and API hostnames.
API URLs
Updated the Beta environment hostname.
April, 2016
Topic
Description
Marketing Cloud Visitor ID Versions
Revised text for IDs 1 and 2.
Profile Merge Rules Dashboard
Revised to show new Merge Rule cards on the
dashboard.
Profile Merge Rule Options Defined
Revised to include new report metrics.
Report Metrics for Profile Merge Rules
New documentation defines the report metrics and graphs
for Profile Merge.
449
Topic
Description
Audience Manager Segments in Analytics
Share Audience Manager segments with Analytics in
real-time.
Destinations
Revisions introduce significant changes to the content
and organization of the Destination docs.These changes
are designed to reduce complexity and make the cookie
and URL destination workflows more clear.
March, 2016
Topic
Description
Working with Comparison Operators in TraitBuilder
Added a new named operator, Matcheswords. It let's you
specify a matching word patters without using a regular
expression.
February, 2016
Topic
Description
Deactivate a Subscriber's Data Feed
Describes how Audience Marketplace data providers
deactivate a subscriber's feed.
What Happens After a Provider Deactivates My Data
Feed
Describes what an Audience Marketplace data buyer
can expect if a provider revokes access to a data feed.
Added error 172 for blocked cookies.
Name and Content Requirements for ID Synchronization Revised content to improve clarity. New section about
Files
how the file names and file content IDs map to each other.
Amazon S3 Name and File Size Requirements for
Inbound Data Files
Revised content to include syntax for Android and iOS
codes in the file names.
FTP Name and File Size Requirements for Inbound Data
Files
January, 2016
Topic
Description
OAuth Authentication
Added link for authorized and implicit authentication.
Topic
450
Description
Send Segments to a Google AdWords Remarketing List Instructions on how to send segment data to a Google
AdWords remarketing list.
Added a note that says access to this feature requires
admin permissions.
DIL create
Revised text for declaredId. Customer IDs must be
passed in as un-encoded values only. Encoding IDs will
create double-encoded identifiers.
Making DCS API Calls
Revised text to include the d_mid variable.
Supported Variables
Added new key and macro entries for d_mid and
d_region.
Data Files for Advertiser Analytics Reports
Added new description for Event Type.
Understanding the Data Provider Billing Report
New documentation that lists and defines the items in an
Audience Marketplace billing report.
Trait and Segment Size Data in Segment Builder
Updated text to describe the differences between 30-day
totals for traits and segments.
Understanding the Plan Details Page in Audience
Marketplace
New documentation that describes the plan information
shown in a buyer's subscription details page.
Older Changes
2015: New and Revised Documentation
November, 2015
Topic
Description
Geotargeting With Platform-level Keys
Updated with links to a downloadable list of region IDs.
Password Requirements, Locked Accounts, and
Forgotten Passwords
Revised to include new password requirements.
451
Topic
Description
Billing and Impression Allocation for CPM Data Feeds
Instructions on how to allocate impressions for different
CPM Data Feeds.
Billing and Impression Allocation for Flat Fee Data Feeds Instructions on how to allocate impressions for different
flat fee Data Feeds.
Usage Limits
Audience Manager sets a maximum limit on the number
of traits, segments, destinations, and algorithmic models
you can create for an account.
Discounts for Data Providers
Discounts let data providers reduce the price of a data
feed for selected buyers.
Discounts for Data Buyers
Buyers can request or subscribe to discounted data feeds.
October, 2015
Topic
Description
CID Replaces DPID and DPUUID
Update your code to use d_cid or d_cid_ic instead of
d_dpid and d_dpuuid. The DPID and DPUUID variables
will continue to work, but you should consider them
deprecated. This includes DPID and DPUUID variants
without the d_ prefix.
URL Variables and Syntax for Declared IDs
Revised text to include the d_cid and d_cid_ic key-value
pairs.
Declared ID Targeting
Private Data Feeds
A private data feed is an option that lets providers limit
buyer access to their data. Data providers and buyers
should review this section for information about creating
and subscribing to private data feeds.
A list and descriptions of error codes and messages
returned by the DCS.
September, 2015
Topic
Description
Data and Metadata Files for Advertiser Analytics Reports Format and content requirements for bringing data into
the Advertiser Analytics Reports.
452
Topic
Description
Text revisions and updates. Also, included new key-value
pairs required to use and see readable data names in
the Advertising Analytics reports.
Capturing Campaign Click Data via Pixel Calls
Text revisions and updates. Also, included new key-value
pairs required to use and see readable data names in
the Advertising Analytics reports.
Updated intro with requirement information.
August, 2015
Topic
Description
Bulk Management Tools
The Bulk Management Tools let you create and manage
multiple objects at once with single operation. You can
use Bulk Management Tools to work with data sources,
derived signals, destinations, folders, segments, and
traits.
Profiles and Audiences Integration with the Audience
Management Module
The context data variable ended incorrectly with a dot
instead of an underscore.
• Correct: c_contextData.*
• Incorrect: c_contextData_*
Profile Merge Customer Enablement
Analytics customers need to set an integration code when
using the Master Marketing Profile and passing declared
IDs through the Visitor ID service to Audience Manager.
This document is deprecated and has been replaced by
Create a Cross-Device Data Source.
Reporting FAQ
A new FAQ entry explains why, sometimes, newly
onboarded traits do not show up in the Trait Graph.
Trait and Segment Size Data in Segment Builder.
Revised the description for estimated segment size.
System Components
Updated text and new images that explain how various
Audience Manager systems work and how data flows
through our system.
453
July, 2015
Topic
Description
Documentation links and cross-references.
Updated obsolete links. Clicking a cross-reference should
take you to the correct document instead of a redirect
notification.
Import DCM Data Files Into Audience Manager
Bring your DoubleClick Campaign Manager data into
Audience Manager.
DCS Integration
Use DCS code as an API for real-time data transfers.
June, 2015
Topic
Description
The DIL DIL create method.
• Removed the optional parameter,
iframeAttachmentDelay.
• Added a note to declaredId variable. When using the
Visitor ID Service, set the ID with setCustomerIDs
instead of DIL. See Customer IDs and Authenticated
States.
May, 2015
Topic
Description
Audience Marketplace lets data providers and buyers
execute data deals in a self-service manner with minimum
effort. It does this by providing specialized features that
vary depending on your role as a data buyer or data
seller.
Revisions:
• Simplified steps and directions for creating a group and
assigning permissions.
• Create Groups
• Understanding Wild Card Permissions
• Added information about Wild Card Permissions and
how to use them.
April, 2015
Topic
Description
Inbound Data File Contents:
Syntax, Invalid Characters,
Variables, and Examples
Added following note:
Note: Audience Manager does not support .zip files for inbound S3 buckets.
454
Topic
Description
Reporting FAQ
Added a new FAQ that explains why Total Fires for onboarded traits always displays
as 0.
Geotargeting With
Platform-level Keys
Added information about targeting in the United Kingdom and Netherlands Antilles.
March, 2015
Topic
Description
Reporting FAQ
Added a new FAQ that explains why the number of
successfully processed records might differ when
comparing the Inbound receipt and reporting in AAM.
Added a new FAQ that explains why the trait uniques for
my cross-device onboarded traits are higher than the
total number of onboarded records.
System Components
Removed information about Talend.
Removed information about Netezza and replaced it with
information about RedShift.
Data Retention
New topic.
February, 2015
Topic
Description
Reporting and File Transfer Time-Frame Guidelines
Updated the times for daily inbound file ingestion and
outbound file export.
Reports Dashboard
Added information explaining how the delta change is
calculated depending on the chosen time frame.
Added a note explaining how to investigate an unusually
large delta change in unique visitors.
Added the following information to the Limitations and
Rules section:
• Frequency-capping expressions include all the users
whose number of trait realizations is below a desired
value.
For example:
455
Topic
Description
frequency([1000T]) <= 5
This expression includes all users that have realized
the trait with the ID "1000" fewer than five times,
including users who have not realized the trait.
• 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.
Using the above example, frequency([1000T]) <=
5, the expression becomes valid when joined with
another trait.
For example:
frequency([1000T]) <= 5 AND isSiteVisitorTrait
• For advertising frequency-capping use cases, you could
create a segment rule similar to the following:
(frequency([1000T] <= 2D) >= 5)?
This expression includes all users that have realized
the trait with the ID "1000" in the last 2 days more than
five times.
You can achieve the capping by sending this segment
to the ad server and then include a NOT on the segment
in the ad server. This approach achieves greater
performance in Audience Manager, while still serving
the same purpose for frequency capping.
January, 2015
Topic
Description
Return Properties for an
Individual Segment Folder
Changed the code sample to include the folder count property.
New topic.
Inbound Customer Data
Ingestion FAQ
Clarified the amount of time is takes for inbound data to be propagated to the edge.
Reports Dashboard
New topic.
General Reports
Added section explaining how numbers in General Reports are generated.
siteCatalyst.init
Added an optional that excludes Personally Identifiable Information (PII).
Significantly edited topic.
456
Topic
Description
Reporting FAQ
Added information explaining why there could be a difference between real-time
segment population and the unique values.
Profile Merge Customer
Enablement
Added additional step to explain how to add the use of Declared IDs to DIL and
the Mobile SDK.
This document has been deprecated and replaced by Create a Cross-Device Data
Source.
Inbound Data File Contents:
Syntax, Invalid Characters,
Variables, and Examples
Revised topic.
Profile Merge Architecture
Updated text and added illustrations.
This document has been deprecated and replaced by Profile Link.
Added bullet explaining that you can configure frequency requirements without
configuring recency requirements by leaving recency blank.
Outbound Data File Contents: Added information about removed segments in outbound files.
Syntax and Parameters
Outbound Template Macros
Added new topic.
Help, Privacy, and Legal
457
Resources for customer care, data privacy, and legal issues related to the use of this product and documentation.
If There's a Problem
Customer Care is prepared to help you solve any issues that might arise. Provide the as much of this information
as you can when contacting Customer Care. This will help that team understand and resolve your issue.
Basic Information
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 Manager team.
• Email: [email protected]
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 Manager 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 Manager
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.
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
458
Manager, 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)
Data Privacy
Describes Audience Manager integration and compliance with generally accepted best practices related to consumer
privacy and opt-out procedures.
• Consumer Privacy Protection
• Data Privacy
• Collection of IP Addresses
Consumer Privacy Protection
Audience Manager 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 Manager remains
committed to providing transparency and control to consumers, and meeting or exceeding the Online Behavioral
Advertising (OBA) Self-Regulatory Principles.
Data Privacy
See the Adobe Privacy Center.
Collection of IP Addresses
Adobe has enabled processes and offers settings that allow customers to use Audience Manager 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 Manager 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
459
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 Manager 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 Manager 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 Manager. 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.
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
Copyright 2014 Adobe Systems Incorporated. All Rights Reserved.
Published by Adobe Systems Incorporated.
Terms of Use | Privacy Center
460
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.
04142015

Audience Manager Help - Adobe Marketing Cloud

Transcription

Similar documents

TTCSI Services Talk final proposal

Mendel`s Second Experiment: Dihybrid Cross • wanted to see how

Thomas Buckner Tom Hamilton jump the jump the

o - ANMI

That`s Entertainment April 2006

Lesson 12: Dividing Segments Proportionately

Whitepages Pro Caller Identification API

Oregon 99W is the main highway through Newberg and Dundee. It

7 Segment Display Driver