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.

Fields

Field Name	Field Type	Description
audienceName	string	Required. The name of the audience.
container	string	Required. The name of the site 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)
isDefaultAudience	boolean	Indicates whether the audience is the default audience (`true`) or not (`false`). This field is available and required in API version 48.0. In API version 49.0 and later, this field is optional. The default audience file name is of format `Default_Network Name.audience`.
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. An audience can have up to 100 criteria.

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)	Required. 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. You can use this field only when the value of the AudienceCriterion type field is `GeoLocation`.
country	string	Country of a user. You can use this field only when the value of the AudienceCriterion type field is `GeoLocation`.
domain	string	Domain of a user. You can use this field only when the value of the AudienceCriterion type field is `Domain`.
entityField	string	Field of an object. You can use this field only when the value of the AudienceCriterion type field is `FieldBased`.
entityType	string	Type of object. You can use this field only when the value of the AudienceCriterion type field is `FieldBased`.
fieldValue	string	Value of a field. You can use this field 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. You can use this field 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. You can use this field 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. You can use this field only when the value of the AudienceCriterion type field is `Permission`.
profile	string	Profile of a user. You can use this field only when the value of the AudienceCriterion type field is `Profile`.
subdivision	string	Subdivision of a user. You can use this field 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.

When deploying an audience, you must include ExperienceBundle in your package to support experience variation targets.

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. You can have up to 2,000 groups and 500 targets per group. To determine the target group name, see Personalization Target Developer and Group Names in the Experience Cloud Developer Guide.
priority	int	Priority of the target. Within a group, priority determines which target is returned when the user matches more than one audience.
targetType	string	Required. Type of target, indicating the nature of the data being targeted. Supported values include: `ExperienceVariation` (API version 47.0 and later) `NavigationLinkSet` (API version 49.0 and later) `Report` (API version 49.0 and later) `Dashboard` (API version 49.0 and later) You can have up to 2,500 `ExperienceVariation` targets and 25,000 record targets. For more information on the `ExperienceVariation` target type, see ExperienceBundle.
targetValue	string	Required. Value of the target, which is the developer name of the experience variation, such as `ContactSupport_ContactSupportForCalifornia_Page` for a page variation. To determine the target developer name, see Personalization Target Developer and Group Names in the Experience Cloud Developer Guide.

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    <isDefaultAudience>false</isDefaultAudience>
75    <targets>
76        <target>
77            <groupName>c194d79c-5c6b-4c6a-8d14-0e7042564355$#$Branding</groupName>
78            <priority>1</priority>
79            <targetType>ExperienceVariation</targetType>
80            <targetValue>Customer_Service_testBrandingSet_Branding</targetValue>
81        </target>
82    </targets>
83</Audience>

Usage

You can’t use Metadata API to delete an audience.

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

Personalization using audience targeting varies what the user can see in the browser but doesn’t secure data in any way. To prevent users accessing sensitive data, use standard Salesforce security features, such as sharing rules and permission sets.

Important

Delete targets

To delete a single target from an audience, deploy the entire list of targets for the audience minus the one that 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    <isDefaultAudience>false</isDefaultAudience>
19    <targets>
20    </targets>
21</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    <isDefaultAudience>false</isDefaultAudience>
19</Audience>

Create targets

To create a target, deploy the entire list of targets for the audience plus the one that 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. Deploy 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.