Impression Based Remarketing List Record - Bulk

Defines a impression based remarketing list that can be downloaded and uploaded in a bulk file.

You can download all Impression Based Remarketing List records in the account by including the DownloadEntity value of ImpressionBasedRemarketingLists 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 impression based remarketing list.

Type,Status,Id,Parent Id,Client Id,Modified Time,Name,Description,Membership Duration,Scope,Audience,Impression Campaign Id,Impression Ad Group Id,Entity Type
Format Version,,,,,,6.0,,,,,,
Impression Based Remarketing List,Active,-10,ParentIdHere,ClientIdGoesHere,,,New impression based remarketing list description,30,Account,Impression Based Remarketing List Name,CampaignIdHere,AdGroupIdHere,AdGroup
Impression Based Remarketing List,Active,-11,ParentIdHere,ClientIdGoesHere,,,New impression based remarketing list description,30,Account,Impression Based Remarketing List Name1,CampaignIdHere,,Campaign

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 BulkImpressionBasedRemarketingList 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 BulkImpressionBasedRemarketingList
var bulkImpressionBasedRemarketingList = new BulkImpressionBasedRemarketingList
{
    // 'Client Id' column header in the Bulk file
    ClientId = "ClientIdGoesHere",

    // Map properties in the Bulk file to the 
    // ImpressionBasedRemarketingList object of the Campaign Management service.
    ImpressionBasedRemarketingList = new ImpressionBasedRemarketingList
    {
        // 'Audience Network Size' column header in the Bulk file
        AudienceNetworkSize = null,
        // 'Description' column header in the Bulk file
        Description = "New Impression Based Remarketing List",
        // 'Id' column header in the Bulk file
        Id = impressionBasedRemarketingListIdKey,
        // 'Membership Duration' column header in the Bulk file
        MembershipDuration = 30,
        // 'Audience' column header in the Bulk file
        Name = "Impression Based Remarketing List" + DateTime.UtcNow,
        // 'Parent Id' column header in the Bulk file
        ParentId = accountIdKey,
        // 'Scope' column header in the Bulk file
        Scope = EntityScope.Account,
        // 'Impression Ad Group Id' column header in the Bulk file
        AdGroupId = AdGroupIdHere,
        // 'Impression Campaign Id' column header in the Bulk file
        CampaignId = CampaignIdHere,
        // 'Audience Search Size' column header in the Bulk file
        SearchSize = null,
        // 'Supported Campaign Types' column header in the Bulk file
        SupportedCampaignTypes = null,
        // 'Entity Type' column header in the Bulk file
        EntityType = ImpressionBasedEntityType.AdGroup
    },
                
    // 'Status' column header in the Bulk file
    Status = Status.Active
};

uploadEntities.Add(bulkImpressionBasedRemarketingList);

var entityUploadParameters = new EntityUploadParameters
{
    Entities = uploadEntities,
    ResponseMode = ResponseMode.ErrorsAndResults,
    ResultFileDirectory = FileDirectory,
    ResultFileName = DownloadFileName,
    OverwriteResultFile = true,
};

var uploadResultEntities = (await BulkServiceManager.UploadEntitiesAsync(entityUploadParameters)).ToList();

For a Impression Based Remarketing List record, the following attribute fields are available in the Bulk File Schema.

• Audience
• Audience Network Size
• Audience Search Size
• Client Id
• Description
• Entity Type
• Id
• Impression Ad Group Id
• Impression Campaign Id
• Membership Duration
• Modified Time
• Parent Id
• Scope
• Status
• Supported Campaign Types

Audience

The name of the impression based remarketing list.

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 impression based remarketing list membership duration, rule, or tag identifier.

This property will be empty if the UET tag associated with the impression based remarketing list has a status of Unverified or Inactive, because the impression based remarketing list 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 impression based remarketing list. Use a description to help you remember what audience you are targeting with this impression based remarketing list.

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

Entity Type

This entity type is based on how users have viewed an ad. You must specific the entity type when you create an impression based remarketing list. Possible values are AdGroup or Campaign.

Add: Required
Update: Optional. If no value is set for the update, this setting is not changed.
Delete: Read-only

Id

The system-generated identifier of the impression based remarketing list.

Add: Read-only
Update: Read-only and Required
Delete: Read-only and Required

Impression Ad Group Id

The AdGroupId used to create the impression based remarketing list.

Add: If Entity Type is AdGroup, this is Required. If Entity Type is Campaign, this is empty.
Update: Optional. If no value is set for the update, this setting is not changed.
Delete: Read-only

Impression Campaign Id

The CampaignId used to create the impression based remarketing list.

Add: Required
Update: Optional. If no value is set for the update, this setting is not changed.
Delete: Read-only

Membership Duration

When you create a impression based remarketing list, you can specify how far back in time Microsoft Advertising should look for actions that match your impression based remarketing list definition in order to add people to your list.

The minimum duration is 1 day and the maximum duration allowed is 30 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).

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

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 impression based remarketing list 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 impression based remarketing list.

PageVisitors Rule Template

For the PageVisitors rule, you must include one or more rule item groups.

If the normal form is conjunctive (CNF), the rule item conditions for the same page are first joined using the logical OR operator. Then, each result from the list of rule item groups are joined using the logical AND operator. In other words the user will be added to your impression based remarketing list if any of the specified rule item conditions within all of the rule item groups are met.

• Rule 1 AND Rule 2
• (Rule 1 OR Rule 2) AND Rule 3
• (Rule 1 OR Rule 2) AND (Rule 3 OR Rule 4)

If the normal form is disjunctive (DNF), the rule item conditions for the same page are first 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 impression based remarketing list if all of the specified rule item conditions within any one of the rule item groups are met.

• Rule 1 OR Rule 2
• (Rule 1 AND Rule 2) OR Rule 3
• (Rule 1 AND Rule 2) OR (Rule 3 AND Rule 4)

For an example of DNF evaluation, 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 impression based remarketing list.

PageVisitorsWhoDidNotVisitAnotherPage Rule Template

Remarketing rules are conditions used to determine who to add to your impression based remarketing list. 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 impression based remarketing list 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 impression based remarketing list.

PageVisitorsWhoVisitedAnotherPage Rule Template

Remarketing rules are conditions used to determine who to add to your impression based remarketing list. 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 impression based remarketing list 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 impression based remarketing list.

Scope

Scope defines what accounts can use this impression based remarketing list. If scope is set to Account, the impression based remarketing list can only be associated with campaigns and ad groups within one specified account (Parent Id). If scope is set to Customer, the impression based remarketing list 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 impression based remarketing list 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 impression based remarketing list.

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