Audience | Metadata API Developer Guide

File Suffix and Directory Location

Audience components have the suffix .audience and are stored in the audience folder.

Version

Audience components are available in API version 44.0 and later.

Special Access Rules

Access to the Audience type requires the AudienceMetadata permission. This permission is on by default for orgs that have Networks enabled.

Access to permission criteria for the Audience type requires the AudiencePermissionCriteria permission. This permission is available in API version 45.0 and later and is on by default for orgs that have Networks enabled.

Access to audience targets requires the PersonalizationActivity and PersonalizationTargetApi permissions. These permissions are available in API version 47.0 and later for orgs that have Networks enabled but are off by default. These permissions are on for orgs participating in the Personalization pilot.

We provide Personalization to selected customers through a pilot program that requires agreement to specific terms and conditions. To be nominated to participate in the program, contact Salesforce. Pilot programs are subject to change, and we can’t guarantee acceptance. Personalization isn’t generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. We can’t guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features.

Note

Fields

Field Name	Field Type	Description
audienceName	string	Required. The name of the audience.
container	string	Required. The name of the community or org that contains the audience.
criteria	AudienceCriteria	Required. Criteria in an audience. This field is available in API version 47.0 and later.
criterion	AudienceCriterion[]	Removed. List of criteria in an audience. This field is available in API version 44.0–46.0. In API version 47.0 and later, use criteria instead. Warning
description	string	The description of the audience.
formula	string	Formula used to determine the audience. This field is available in API version 45.0 and later.
formulaFilterType	FormulaFilterType(enumeration of type string)	Indicates the audience’s formula type. Valid values are `AllCriteriaMatch` `AnyCriterionMatches` `CustomLogicMatches` (available in API version 45.0 and later)
targets	PersonalizationTargetInfos	Targets for the audience. This field is available in API version 47.0 and later.

AudienceCriteria

Represents criteria for an audience. This subtype is available in API version 47.0 and later.

Field Name	Field Type	Description
criterion	AudienceCriterion[]	List of criteria for an audience.

AudienceCriterion

Represents a criterion for an audience.

Field Name	Field Type	Description
criteriaNumber	int	The number associated with the criterion in a formula, for example, (1 AND 2) OR 3. This field is available in API version 45.0 and later.
criterionValue	AudienceCriteriaValue	The value of the criterion.
operator	AudienceCriterionOperator(enumeration of type string)	The operator associated with this criterion. Valid values are: `Equal` `NotEqual` `GreaterThan` `GreaterThanOrEqual` `LessThan` `LessThanOrEqual` `Contains` `StartsWith` `Includes` (available in API version 45.0 and later) `NotIncludes` (available in API version 45.0 and later)
type	AudienceCriterionType(enumeration of type string)	Valid values are: `GeoLocation` `Domain` `Profile` `FieldBased` `Permission` (available in API version 45.0 and later) `Default` (available in API version 47.0 and later) For a list of AudienceCriteriaValue fields that you can use with each AudienceCriterion type field value, see this table.

AudienceCriteriaValue

Represents the value of a criterion in an audience. For a list of AudienceCriteriaValue fields that you can use with each AudienceCriterion type field value, see this table.

Field Name	Field Type	Description
city	string	City of a user. This field can be used only when the value of the AudienceCriterion type field is `GeoLocation`.
country	string	Country of a user. This field can be used only when the value of the AudienceCriterion type field is `GeoLocation`.
domain	string	Domain of a user. This field can be used only when the value of the AudienceCriterion type field is `Domain`.
entityField	string	Field of an object. This field can be used only when the value of the AudienceCriterion type field is `FieldBased`.
entityType	string	Type of object. This field can be used only when the value of the AudienceCriterion type field is `FieldBased`.
fieldValue	string	Value of a field. This field can be used only when the value of the AudienceCriterion type field is `FieldBased`.
isEnabled	string	Indicates whether the permission is enabled (`true`) or not (`false`) for a user. This field is available in API version 45.0 and later and can be used only when the value of the AudienceCriterion type field is `Permission`.
permissionName	string	Valid API name of a standard user or custom permission. This field is available in API version 45.0 and later and can be used only when the value of the AudienceCriterion type field is `Permission`.
permissionType	string	Type of permission. Valid values are `Standard` and `Custom`. This field is available in API version 45.0 and later and can be used only when the value of the AudienceCriterion type field is `Permission`.
profile	string	Profile of a user. This field can be used only when the value of the AudienceCriterion type field is `Profile`.
subdivision	string	Subdivision of a user. This field can be used only when the value of the AudienceCriterion type field is `GeoLocation`.

This table summarizes which AudienceCriteriaValue fields you can use with the different AudienceCriterion type field values.

AudienceCriterion Type	AudienceCriteriaValue Fields
`GeoLocation`	city country subdivision
`Domain`	domain
`Profile`	profile
`FieldBased`	entityField entityType fieldValue
`Permission`	isEnabled permissionName permissionType

PersonalizationTargetInfos

Represents targets for an audience. This subtype is available in API version 47.0 and later.

Field Name	Field Type	Description
target	PersonalizationTargetInfo[]	List of targets for an audience.

PersonalizationTargetInfo

Represents a target for an audience. This subtype is available in API version 47.0 and later.

Field Name	Field Type	Description
groupName	string	Required. Group name of the target. Groups bundle related target and audience pairs. Determining group names for targets in Metadata API works the same way as in Chatter REST API. To determine the groupName for targets, see Personalization Target Group Names in Chatter REST API Developer Guide.
priority	int	Priority of the target. Within a group, priority determines which target is returned if the user matches more than one audience.
targetType	string	Required. Type of target, indicating the nature of the data being targeted. In API version 47.0 and later, `ExperienceVariation` is the only supported value. For more information on the `ExperienceVariation` target type, see ExperienceBundle (Pilot).
targetValue	string	Required. Value of the target, which is the developer name of the experience variation, such `ContactSupport_ContactSupportForCalifornia_Page` for a page variation.

Declarative Metadata Sample Definition

The following is an example of an Audience component.

1<?xml version="1.0" encoding="UTF-8"?>
2<Audience xmlns="http://soap.sforce.com/2006/04/metadata">
3    <audienceName>Audience Metadata</audienceName>
4    <container>Customer</container>
5    <criteria>
6        <criterion>
7            <criteriaNumber>1</criteriaNumber>
8            <criterionValue>
9                <country>United States</country>
10                <subdivision>Nevada</subdivision>
11            </criterionValue>
12            <operator>Equal</operator>
13            <type>GeoLocation</type>
14        </criterion>
15        <criterion>
16            <criteriaNumber>2</criteriaNumber>
17            <criterionValue>
18                <profile>customer community user</profile>
19            </criterionValue>
20            <operator>Equal</operator>
21            <type>Profile</type>
22        </criterion>
23        <criterion>
24            <criteriaNumber>3</criteriaNumber>
25            <criterionValue>
26                <domain>sampledomain.example.com</domain>
27            </criterionValue>
28            <operator>Equal</operator>
29            <type>Domain</type>
30        </criterion>
31        <criterion>
32            <criteriaNumber>4</criteriaNumber>
33            <criterionValue>
34                <entityField>Manager.Profile.CreatedBy.Contact.MailingCountry</entityField>
35                <entityType>User</entityType>
36                <fieldValue>USA</fieldValue>
37            </criterionValue>
38            <operator>StartsWith</operator>
39            <type>FieldBased</type>
40        </criterion>
41        <criterion>
42            <criteriaNumber>5</criteriaNumber>
43            <criterionValue>
44                <entityField>RecordTypeId</entityField>
45                <entityType>CollaborationGroup</entityType>
46                <fieldValue>CollaborationGroup.Group_RT2</fieldValue>
47            </criterionValue>
48            <operator>Equal</operator>
49            <type>FieldBased</type>
50        </criterion>
51        <criterion>
52            <criteriaNumber>6</criteriaNumber>
53            <criterionValue>
54                <isEnabled>true</isEnabled>
55                <permissionName>ManageUsers</permissionName>
56                <permissionType>Standard</permissionType>
57            </criterionValue>
58            <operator>Equal</operator>
59            <type>Permission</type>
60        </criterion>
61        <criterion>
62            <criteriaNumber>7</criteriaNumber>
63            <criterionValue>
64                <isEnabled>false</isEnabled>
65                <permissionName>NamespaceXYZ__CustomPermABC</permissionName>
66                <permissionType>Custom</permissionType>
67            </criterionValue>
68            <operator>Equal</operator>
69            <type>Permission</type>
70        </criterion>
71    </criteria>
72    <formula>1 AND (2 OR 3 OR 4 OR 5 OR 6 OR 7)</formula>
73    <formulaFilterType>CustomLogicMatches</formulaFilterType>
74    <targets>
75        <target>
76            <groupName>c194d79c-5c6b-4c6a-8d14-0e7042564355$#$Branding</groupName>
77            <priority>1</priority>
78            <targetType>ExperienceVariation</targetType>
79            <targetValue>Customer_Service_testBrandingSet_Branding</targetValue>
80        </target>
81    </targets>
82</Audience>

Usage

You can’t delete an audience using Metadata API.

In API version 47.0 and later, you can’t create an audience without criteria.

The list of targets provided in the input for an audience is considered the state of target assignments that you want. For example, see the following information for deleting, creating, and updating targets.

If you don’t have a default audience, updating targets can result in the UI erroneously showing a target assigned to the default audience. The target assignment data in the API is correct. To work around the UI issue, temporarily assign another target to the default audience and then delete it.

Note

Delete targets

To delete a single target from an audience, deploy the entire list of targets for the audience minus the one you want to delete.

To delete all the targets from an audience, deploy the audience with empty targets tags. For example:

1<?xml version="1.0" encoding="UTF-8"?>
2<Audience
3    xmlns="http://soap.sforce.com/2006/04/metadata">
4    <audienceName>testAudience</audienceName>
5    <container>testContainer</container>
6    <criteria>
7        <criterion>
8            <criteriaNumber>1</criteriaNumber>
9            <criterionValue>
10                <country>United States</country>
11                <subdivision>Nevada</subdivision>
12            </criterionValue>
13            <operator>Equal</operator>
14            <type>GeoLocation</type>
15        </criterion>
16    </criteria>
17    <formulaFilterType>AllCriteriaMatch</formulaFilterType>
18    <targets>
19    </targets>
20</Audience>

Update an audience without updating targets

To update an audience without updating targets, deploy the audience without targets tags. For example:

1<?xml version="1.0" encoding="UTF-8"?>
2<Audience
3    xmlns="http://soap.sforce.com/2006/04/metadata">
4    <audienceName>testAudience</audienceName>
5    <container>testContainer</container>
6    <criteria>
7        <criterion>
8            <criteriaNumber>1</criteriaNumber>
9            <criterionValue>
10                <country>United States</country>
11                <subdivision>Nevada</subdivision>
12            </criterionValue>
13            <operator>Equal</operator>
14            <type>GeoLocation</type>
15        </criterion>
16    </criteria>
17    <formulaFilterType>AllCriteriaMatch</formulaFilterType>
18</Audience>

Create targets

To create a target, deploy the entire list of targets for the audience plus the one you want to create.

Update the priority of a target

To change the priority of a target within an audience, deploy the entire list of targets for the audience with the new priority values for the targets.

To change the priority of a target that affects priority in another audience, deploy both audiences with their entire list of targets with the new priority values for the targets.

Update the target assignment for an audience

To reassign a target to a new audience, deploy both audiences with their entire list of targets; one list with the target removed, and the other list with the target added.

Wildcard Support in the Manifest File

This metadata type supports the wildcard character * (asterisk) in the package.xml manifest file. For information about using the manifest file, see Deploying and Retrieving Metadata with the Zip File.