Audience Metadata Type in SFDX

Architectural Overview#

The Audience metadata type defines personalization segments and targeting assignments for Experience Cloud sites. With Audience, architects can dynamically swap out entire page variations, individual Lightning Web Components, branding sets, or navigation menus inside an ExperienceBundle based on who the logged-in (or guest) user is.

Architecturally, Audience separates two responsibilities inside one metadata file:

1. criteria (AudienceCriteria): The targeting rules (User field values, Custom/Standard Permissions, Profile, Domain, or Geo-Location).
2. targets (PersonalizationTargetInfos): The exact Experience Cloud page variations, component instances, or CMS content items assigned to this segment.

Directory Location and File Suffix#

Key Metadata Fields#

Declarative XML and Package Manifest Examples#

Below is a production Audience targeting Gold Partner users who hold the Gold_Partner_Portal_Access custom permission and belong to an active partner account:

<?xml version="1.0" encoding="UTF-8"?>
<Audience xmlns="http://soap.sforce.com/2006/04/metadata">
    <audienceName>Gold Tier Partners</audienceName>
    <container>Partner Central</container>
    <criteria>
        <criterion>
            <criteriaNumber>1</criteriaNumber>
            <criterionValue>
                <isEnabled>true</isEnabled>
                <permissionName>Gold_Partner_Portal_Access</permissionName>
                <permissionType>Custom</permissionType>
            </criterionValue>
            <operator>Equal</operator>
            <type>Permission</type>
        </criterion>
        <criterion>
            <criteriaNumber>2</criteriaNumber>
            <criterionValue>
                <entityField>Contact.Account.Partner_Tier__c</entityField>
                <entityType>User</entityType>
                <fieldValue>Gold</fieldValue>
            </criterionValue>
            <operator>Equal</operator>
            <type>FieldBased</type>
        </criterion>
    </criteria>
    <description>Targets Gold-tier partner portal users for executive deal registration views.</description>
    <formulaFilterType>AllCriteriaMatch</formulaFilterType>
    <isDefaultAudience>false</isDefaultAudience>
</Audience>

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Gold_Tier_Partners</members>
        <name>Audience</name>
    </types>
    <version>68.0</version>
</Package>

SFDX CLI Retrieval and Deployment Commands#

Retrieve and deploy Audience metadata alongside your Experience Cloud site:

# Retrieve all Audience definitions from the org
sf project retrieve start --metadata "Audience:*" --target-org exp-cloud-uat

# Deploy Audience together with ExperienceBundle
sf project deploy start \
  --metadata Audience:Gold_Tier_Partners "ExperienceBundle:Partner_Central1" \
  --target-org exp-cloud-prod

Senior Architect Best Practices and Gotchas#

1. targets UUID Synchronization with ExperienceBundle: The <targetValue> and <groupName> fields inside an Audience’s <targets> block reference internal component and view UUIDs inside your ExperienceBundle JSON files. Always commit and deploy Audience and ExperienceBundle changes in the same Git commit and deployment transaction.
2. Audience Limits per Site: An Experience Cloud site supports up to 1,500 custom audiences, and a single Audience can contain up to 100 criteria rows (with a maximum depth of 4 lookup relationships on FieldBased criteria such as User.Contact.Account.Parent.Tier__c).
3. Security vs. Personalization: Audience component visibility is a client-side / UX personalization layer, not an object security boundary. Always enforce record and field security via Sharing Sets, Sharing Rules, and PermissionSet FLS.

Frequently asked questions

Where are Audience metadata files stored in an SFDX project?

They are stored in the force-app/main/default/audiences/ directory with the file extension .audience-meta.xml.

Why does deploying an Audience with Profile criteria sometimes fail across orgs?

If the criterion references a Profile or Record ID that differs or does not exist in the target org, deployment fails. Using Custom Permissions in Audience criteria is much more portable.

How does Audience connect to ExperienceBundle page variations?

The targets block inside the Audience XML maps specific Experience Cloud page variations, component variations, or branding sets to that audience.

What formulaFilterType values are supported in Audience?

Audience supports AllCriteriaMatch, AnyCriterionMatches, and CustomLogic using boolean expressions like 1 AND (2 OR 3).