Product Audience Record - Bulk
Defines a product audience that can be downloaded and uploaded in a bulk file.
Note
Dynamic remarketing lists were formerly known as product audiences in Microsoft Advertising. You'll see "Dynamic remarketing list" in the Microsoft Advertising UI, but to avoid breaking changes the API objets are still named "product audience".
Dynamic remarketing lists pair customers with specific products based on what they have looked at, considered, or already purchased on your website. You can use dynamic remarketing lists in both search campaigns and audience campaigns (not everyone has audience campaigns yet).
Dynamic remarketing lists work best with both Shopping campaigns and feed-based Audience campaigns i.e., those campaigns that leverage a Microsoft Merchant Center store ID.
Important
Be sure to edit the script corresponding to the UET Tag Id on your website to include the ecomm_prodid and ecomm_pagetype parameters.
The ecomm_prodid parameter is the product ID of the product on the page. It is unique for each item and must match either the id or item_group_id attribute in your product feed. Numeric and alphanumeric (including hyphens) characters only, with a maximum of 50 characters.
The ecomm_pagetype parameter identifies the type of page the user has visited. Valid options: home, searchresults, category, product, cart, purchase, other.
window.uetq = window.uetq || [];
window.uetq.push('event', '', {'ecomm_prodid': 'REPLACE_WITH_PRODUCT_ID', 'ecomm_pagetype': 'REPLACE_WITH_PAGE_TYPE'});
Tip
For an overview and more information about audiences, see the Audience APIs technical guide.
You can download all Product Audience records in the account by including the DownloadEntity value of ProductAudiences in the DownloadCampaignsByAccountIds or DownloadCampaignsByCampaignIds service request. Additionally the download request must include the EntityData scope. For more details about the Bulk service including best practices, see Bulk Download and Upload.
The following Bulk CSV example would add a new product audience.
Type,Status,Id,Parent Id,Client Id,Modified Time,Name,Description,Membership Duration,Scope,UET Tag Id,Audience,Product Audience Type,Supported Campaign Types
Format Version,,,,,,6.0,,,,,,,
Product Audience,Active,-10,ParentIdHere,ClientIdGoesHere,,,New product audience,30,Account,TagIdHere,My Product Audience,GeneralVisitors,Search;DynamicSearchAds;Shopping;Audience
If you are using the Bing Ads SDKs for .NET, Java, or Python, you can save time using the BulkServiceManager to upload and download the BulkProductAudience object, instead of calling the service operations directly and writing custom code to parse each field in the bulk file.
var uploadEntities = new List<BulkEntity>();
// Map properties in the Bulk file to the BulkProductAudience
var bulkProductAudience = new BulkProductAudience
{
// 'Client Id' column header in the Bulk file
ClientId = "ClientIdGoesHere",
// Map properties in the Bulk file to the
// ProductAudience object of the Campaign Management service.
ProductAudience = new ProductAudience
{
// 'Audience Network Size' column header in the Bulk file
AudienceNetworkSize = null,
// 'Description' column header in the Bulk file
Description = "New product audience",
// 'Id' column header in the Bulk file
Id = productAudienceIdKey,
// 'Membership Duration' column header in the Bulk file
MembershipDuration = 30,
// 'Audience' column header in the Bulk file
Name = "My Product Audience",
// 'Parent Id' column header in the Bulk file
ParentId = accountIdKey,
// 'Product Audience Type' column header in the Bulk file
ProductAudienceType = ProductAudienceType.GeneralVisitors,
// 'Scope' column header in the Bulk file
Scope = EntityScope.Account,
// 'Audience Search Size' column header in the Bulk file
SearchSize = null,
// 'Supported Campaign Types' column header in the Bulk file
SupportedCampaignTypes = null,
// 'UET Tag Id' column header in the Bulk file
TagId = tagIdKey
},
// 'Status' column header in the Bulk file
Status = Status.Active
};
uploadEntities.Add(bulkProductAudience);
var entityUploadParameters = new EntityUploadParameters
{
Entities = uploadEntities,
ResponseMode = ResponseMode.ErrorsAndResults,
ResultFileDirectory = FileDirectory,
ResultFileName = DownloadFileName,
OverwriteResultFile = true,
};
var uploadResultEntities = (await BulkServiceManager.UploadEntitiesAsync(entityUploadParameters)).ToList();
For a Product Audience record, the following attribute fields are available in the Bulk File Schema.
- Audience
- Audience Network Size
- Audience Search Size
- Client Id
- Description
- Id
- Membership Duration
- Modified Time
- Parent Id
- Product Audience Type
- Scope
- Status
- Supported Campaign Types
- UET Tag Id
Audience
The name of the product audience.
The name can contain a maximum of 128 characters.
Add: Required
Update: Optional. If no value is set for the update, this setting is not changed.
Delete: Read-only
Audience Network Size
The total number of people who are active members of this audience in the Audience network. This gives you an idea of how many Audience network users you can target.
The audience needs to have at least 300 people before Microsoft Advertising will use it for optimizations.
Add: Read-only
Update: Read-only
Delete: Read-only
Audience Search Size
The total number of people who are active members of this audience in the Search network. This gives you an idea of how many search users you can target.
The audience needs to have at least 300 people before Microsoft Advertising will use it for optimizations.
This property will be empty for up to 24 hours while the audience is being built, for example if you add or update the product audience membership duration, rule, or tag identifier.
This property will be empty if the UET tag associated with the product audience has a status of Unverified or Inactive, because the product audience can't receive the customer information from your website that it needs to build the list.
Add: Read-only
Update: Read-only
Delete: Read-only
Client Id
Used to associate records in the bulk upload file with records in the results file. The value of this field is not used or stored by the server; it is simply copied from the uploaded record to the corresponding result record. It may be any valid string to up 100 in length.
Add: Optional
Update: Optional
Delete: Read-only
Description
The description of the product audience. Use a description to help you remember what audience you are targeting with this product audience.
The description can contain a maximum of 1,024 characters.
Add: Optional
Update: Optional. If no value is set for the update, this setting is not changed. If you set this field to the delete_value string, the prior setting is removed.
Delete: Read-only
Id
The system-generated identifier of the product audience.
Add: Read-only
Update: Read-only and Required
Delete: Read-only and Required
Membership Duration
When you create a product audience, you can specify how far back in time Microsoft Advertising should look for actions that match your product audience definition in order to add people to your list.
The mimimum duration is 1 day and the maximum duration allowed is 180 days.
Add: Optional
Update: Optional. If no value is set for the update, this setting is not changed.
Delete: Read-only
Modified Time
The date and time that the entity was last updated. The value is in Coordinated Universal Time (UTC).
Note
The date and time value reflects the date and time at the server, not the client. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types.
Add: Read-only
Update: Read-only
Delete: Read-only
Parent Id
The system-generated identifier of the account or customer. If the Scope is set to Account, this is the account ID, and otherwise it is the customer ID.
Add: Optional
Update: Read-only. You cannot change the parent ID.
Delete: Read-only
Product Audience Type
Determines who to add to your product audience.
The possible values are GeneralVisitors, ProductSearchers, ProductViewers, ShoppingCartAbandoners, and PastBuyers.
Add: Required
Update: Optional. If no value is set for the update, this setting is not changed.
Delete: Read-only
Scope
Scope defines what accounts can use this product audience. If scope is set to Account, the product audience can only be associated with campaigns and ad groups within one specified account (Parent Id). If scope is set to Customer, the product audience can be associated with any campaigns and ad groups across all of the customer's accounts.
Add: Required
Update: Read-only. You cannot change the scope.
Delete: Read-only
Status
The product audience status.
Possible values are Active or Deleted.
Add: Optional. The default value is Active.
Update: Read-only
Delete: Required. The Status must be set to Deleted.
Supported Campaign Types
The semicolon delimited list of campaign types that support this product audience.
Supported values are Audience, DynamicSearchAds, Search, and Shopping. New campaign types might be added in the future, so you should not take any dependency on a fixed set of values.
Add: Read-only
Update: Read-only
Delete: Read-only
UET Tag Id
The Microsoft Advertising identifier of the Universal Event Tracking (UET) tag that is used with the product audience.
Important
Be sure to edit the UET script on your website to include the prodid and pagetype parameters.
window.uetq = window.uetq || [];
window.uetq.push({'prodid': 'PRODUCT_ID', 'pagetype': 'PAGE_TYPE'});
Add: Required
Update: Optional. If no value is set for the update, this setting is not changed.
Delete: Read-only
CustomEvents Rule Template
For the CustomEvents rule, you must include one or more of the following conditional event operator pairs: (ActionOperator and Action), (CategoryOperator and Category), (LabelOperator and Label), (ValueOperator and Value). If more than one condition is specified, the conditions are joined using the logical AND operator. In other words the visitor will only be added to your product audience if all of the specified rule conditions are met.
For example let's say that the following custom events are set as a logical expression in the bulk file:
CustomEvents(Category Equals video) and (Action Equals play) and (Label Equals trailer) and (Value Equals 5)
Evaluation of the logical expression determines who will be added to the product audience.
PageVisitors Rule Template
For the PageVisitors rule, you must include one or more rule item groups. With each rule item group, the rule item conditions for the same page are joined using the logical AND operator. Then, each result from the list of rule item groups are joined using the logical OR operator. In other words the user will be added to your product audience if all of the specified rule item conditions within any one of the rule item groups are met.
For example let's say that the following rule item groups are set as a logical expression in the bulk file:
PageVisitors((Url Contains X) and (ReferrerUrl DoesNotContain Z)) or ((Url DoesNotBeginWith Y)) or ((ReferrerUrl Equals Z))
Evaluation of the logical expression determines which of the following example users will be added to the product audience.
| User | Url Visited | Referrer Url | Added to List |
|---|---|---|---|
| User 1 | A |
X | Yes. Evaluation of the logical expression results as True. ((Url Contains X) and (ReferrerUrl DoesNotContain Z)) or ((Url DoesNotBeginWith Y)) or ((ReferrerUrl Equals Z)) (False and True) or (True) or (False) False or True or False True |
| User 2 | B |
Y | No. Evaluation of the logical expression results as False. ((Url Contains X) and (ReferrerUrl DoesNotContain Z)) or ((Url DoesNotBeginWith Y)) or ((ReferrerUrl Equals Z)) (False and True) or (False) or (False) False or False or False False |
| User 3 | C |
Z | Yes. Evaluation of the logical expression results as True. ((Url Contains X) and (ReferrerUrl DoesNotContain Z)) or ((Url DoesNotBeginWith Y)) or ((ReferrerUrl Equals Z)) (False and False) or (True) or (True) False or True or True True |
PageVisitorsWhoDidNotVisitAnotherPage Rule Template
Remarketing rules are conditions used to determine who to add to your product audience. For the PageVisitorsWhoDidNotVisitAnotherPage rule, you must include one or more rule item groups for the page visited (IncludeRuleItemGroups), and you must also include one or more rule item groups for the page that must not have been visited (ExcludeRuleItemGroups).
For each rule item group within IncludeRuleItemGroups, the rule item conditions for the same page are joined using the logical AND operator. Then, each result from the list of rule item groups are joined using the logical OR operator.
Likewise for each rule item group within ExcludeRuleItemGroups, the rule item conditions for the same page are joined using the logical AND operator. Then, each result from the list of rule item groups are joined using the logical OR operator. Finally, the logical NOT operator will be applied to the aggregated result of exclude rule item groups.
In other words the visitor will be added to your product audience if any of the include rule item group conditions are met, and none of the exclude rule item group conditions are met.
For example let's say that the following rule item groups are set as a logical expression in the bulk file:
(((Url Contains X) and (ReferrerUrl DoesNotContain Z)) or ((Url DoesNotBeginWith Y)) or ((ReferrerUrl Equals Z))) and not (((Url BeginsWith A) and (ReferrerUrl BeginsWith B)) or ((Url Contains C)))
Evaluation of the logical expression determines which of the following example users will be added to the product audience.
| User | Url Visited | Referrer Url | Added to List |
|---|---|---|---|
| User 1 | A |
X | Yes. Evaluation of the logical expression results as True. (((Url Contains X) and (ReferrerUrl DoesNotContain Z)) or ((Url DoesNotBeginWith Y)) or ((ReferrerUrl Equals Z))) and not (((Url BeginsWith A) and (ReferrerUrl BeginsWith B)) or ((Url Contains C))) ((False and True) or (True) or (False)) and not ((True and False) or (False)) (False or True or False) and not (False or False) True and not False True |
| User 2 | B |
Y | Yes. Evaluation of the logical expression results as True. (((Url Contains X) and (ReferrerUrl DoesNotContain Z)) or ((Url DoesNotBeginWith Y)) or ((ReferrerUrl Equals Z))) and not (((Url BeginsWith A) and (ReferrerUrl BeginsWith B)) or ((Url Contains C))) ((False and True) or (True) or (False)) and not ((False and False) or (False)) (False or True or False) and not (False or False) True and not False True |
| User 3 | C |
Z | No. Evaluation of the logical expression results as False. (((Url Contains X) and (ReferrerUrl DoesNotContain Z)) or ((Url DoesNotBeginWith Y)) or ((ReferrerUrl Equals Z))) and not (((Url BeginsWith A) and (ReferrerUrl BeginsWith B)) or ((Url Contains C))) ((False and False) or (True) or (True)) and not ((False and False) or (True)) (False or True or True) and not (False or True) True and not True False |
PageVisitorsWhoVisitedAnotherPage Rule Template
Remarketing rules are conditions used to determine who to add to your product audience. For the PageVisitorsWhoVisitedAnotherPage rule, you must include one or more rule item groups for the page visited (RuleItemGroups), and you must also include one or more rule item groups for another page that must have been visited (AnotherRuleItemGroups).
For each rule item group within RuleItemGroups, the rule item conditions for the same page are joined using the logical AND operator. Then, each result from the list of rule item groups are joined using the logical OR operator.
Likewise for each rule item group within AnotherRuleItemGroups, the rule item conditions for the same page are joined using the logical AND operator. Then, each result from the list of rule item groups are joined using the logical OR operator.
In other words the visitor will be added to your product audience if any of the rule item group conditions are met, and any of the another rule item group conditions are met.
For example let's say that the following rule item groups are set as a logical expression in the bulk file:
(((Url Contains X) and (ReferrerUrl NotEquals Z)) or ((Url DoesNotBeginWith Y)) or ((ReferrerUrl Equals Z))) and (((Url BeginsWith A) and (ReferrerUrl BeginsWith B)) or ((Url Contains C)))
Evaluation of the logical expression determines which of the following example users will be added to the product audience.
| User | Url Visited | Referrer Url | Added to List |
|---|---|---|---|
| User 1 | A |
X | No. Evaluation of the logical expression results as False. (((Url Contains X) and (ReferrerUrl NotEquals Z)) or ((Url DoesNotBeginWith Y)) or ((ReferrerUrl Equals Z))) and (((Url BeginsWith A) and (ReferrerUrl BeginsWith B)) or ((Url Contains C))) ((False and True) or (True) or (False)) and ((True and False) or (False)) (False or True or False) and (False or False) True and False False |
| User 2 | B |
Y | No. Evaluation of the logical expression results as False. (((Url Contains X) and (ReferrerUrl NotEquals Z)) or ((Url DoesNotBeginWith Y)) or ((ReferrerUrl Equals Z))) and (((Url BeginsWith A) and (ReferrerUrl BeginsWith B)) or ((Url Contains C))) ((False and True) or (True) or (False)) and ((False and False) or (False)) (False or True or False) and (False or False) True and False False |
| User 3 | C |
Z | Yes. Evaluation of the logical expression results as True. (((Url Contains X) and (ReferrerUrl NotEquals Z)) or ((Url DoesNotBeginWith Y)) or ((ReferrerUrl Equals Z))) and (((Url BeginsWith A) and (ReferrerUrl BeginsWith B)) or ((Url Contains C))) ((False and True) or (True) or (True)) and ((False and False) or (True)) (False or True or True) and (False or True) True and True True |
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for