Pricing

Audience

Schema, including its fields, nested structure, and relationships

Definition

An Audience defines a set of rules (conditions) that determine a group of visitors. Audiences are used to target campaigns: a campaign can be set to run only for visitors who meet the criteria of a certain audience. The Audience resource is more complex, as it contains nested logic for targeting rules. It includes grouping of conditions (all/any logic) and many condition types (device type, browser, location, etc.). This allows non-technical users to create rich targeting without writing code – the schema captures these rules in a structured way.

Parent Relationship

  • Parent Resource Type: None

  • Parent Identifier Field: None

  • Rule: Audiences are top-level resources (they are not children of campaigns in the JSON structure; rather, campaigns reference audiences by ID when needed). You don’t nest an audience under another object in the resource loader output.

Payload Properties

When creating or updating an Audience, the payload fields are:

  • id (Integer, optional) – The audience’s unique ID. Required only when updating an existing audience. Example: 100000.

  • name (String, required) – The name of the audience. Choose a descriptive name, e.g., "Mobile Users in US". Example: "NewBanner" (as an audience name, though in practice it might be more descriptive like "New Banner Audience").

  • description (String, optional) – A description of the audience. This can document what the audience is (e.g., "Users on mobile devices and using Chrome browser"). Example: "Audience for mobile Chrome users."

  • hidden (Boolean, optional) – A flag indicating if the audience should be hidden in the listing/UI. If true, this audience might be hidden from normal lists (perhaps used for internal or archived audiences). Defaults to false (visible). Example: false.

  • allow_duplicated_config (Boolean, optional) – Default is false. This flag indicates whether the same conditions and groups can be used more than once in that audiences. For example, if allow_duplicated_config is true. This is an internal setting to prevent accidental duplicate conditions; usually, you will leave this as true (allowing duplicates).

  • groups (Array of Arrays, required) – The core of the audience definition – an array of targeting groups, where each targeting group is itself an array of conditions. Each group represents a set of conditions that are combined together (typically with an AND logic within the group), and multiple groups are combined with OR logic (meaning a visitor can meet any one group to qualify for the audience). At least one group must be defined, even if it contains only a single condition.

In essence, each audience is a list of one or more groups, and each group is a list of one or more conditions. All conditions in a group must be met (if the group’s logic is AND), and an audience can have multiple groups (a visitor meeting any one group qualifies). This structure allows complex logic like "(Condition1 AND Condition2) OR (Condition3)". The schema captures additional settings to fine-tune this logic as described below.

Targeting Group Properties

Within an audience’s groups, each targeting group can have its own parameters:

  • id (Integer, optional) – The targeting group’s unique ID. Only needed when updating an existing audience’s groups; for creation, new IDs are generated. Example: 100000.

  • operator (String, required) – The logical operator for combining conditions within this group. Possible values are "and", "or", or "auto".

    • "and" means all conditions in this group must be true for the group to be true.

    • "or" means at least one condition in the group must be true for the group to be true.

    • "auto" Let the API decide (commonly, it behaves like "and" for multiple conditions, and if only one condition is present, it doesn’t matter).

      In most cases, audiences use "and" within groups (so that all conditions in a group must hold). Example: "auto" (The API will handle logic, often interpreted as AND).

  • type (String/Int, required) – The type of targeting group. This is an internal classification of the group. For most audiences, this can be an internal code like "ACTION_TRACKING" or similar, depending on how the audience is constructed. This field might link to how the group is evaluated. Generally, you can think of it as an identifier for the kind of logic the group contains. (In many contexts, this might not need to be manually set by a user; the API handles it.) Example: "ACTION_TRACKING".

  • conditions (Array of Condition, required) – The list of condition objects in this group. Each condition defines one specific criterion (device, browser, etc. – see next section for condition properties). All these conditions will be evaluated together according to the operator specified above. There must be at least one condition in the array.

  • mutation_observer (Boolean, optional) – Enable or disable Mutation Observer mode for selector conditions in this group. If true, and if the group has any DOM Element (Selector) conditions, the API will continuously observe the page for changes to match the condition (rather than just checking once). Default is false. This is useful if you expect the targeted element to load dynamically after initial page load. Example: false.

  • count (Integer, conditionally used) – A field that is defined only for certain group types or conditions that require a count. For example, if the group is of type "ACTION_TRACKING" or sequence-based, count might specify how many times an action should occur. In standard audiences, you typically won’t use this unless a specific condition (like number of page views, etc.) demands it.

Most of the above group properties are managed by the API when you create an audience via a user interface. When writing JSON directly, you typically ensure operator is set (often to "and"), provide the list of conditions, and optionally set allow_duplicated_config. The type, mutation_observer, and count may be auto-set depending on the condition types you include.

Condition Properties (Audience Conditions)

Each type in an audience targeting group specifies one rule about the visitor or their environment. There are many types of conditions available. Below is a list of condition types and the fields each type uses. In all cases, every condition object will have a type field (to specify which type of condition it is, e.g., "DEVICE", "BROWSER", etc.), and typically an include field (to indicate if we’re including or excluding visitors matching the condition). Additional fields vary by condition type. We will break down the common condition types:

  • Device Condition ("DEVICE") – Targets visitors by device type (desktop, tablet, mobile).

    • include (Boolean, required) – Whether to include visitors of the specified device type (true) or to exclude them (false).

    • value (Integer, required) – The device type code. Conventionally: 1 = mobile, 2 = tablet, 3 = desktop.

      Example: To target only mobile users, you could use a Device condition with include: true and value: 1. Conversely, to target all except mobile, use include: false and value: 1.

  • Browser Condition ("BROWSER") – Targets visitors by their web browser.

    • include (Boolean, required) – Include (true) or exclude (false) visitors using the specified browser(s).

    • value (Integer, required) – The browser type code. Conventionally: 1 = chrome, 2 = firefox, 3 = IE, 4 = safari, 5 = Edge, 6 = custom, 7 = uc browser

      Example: A Browser condition could target Chrome users by setting include: true and value: 1. To exclude Chrome users, set include: false with 1.

  • IP Condition ("IP") – Targets based on the visitor’s IP address (or range).

    • include (Boolean, required) – Whether to include visitors from the specified IP/range (true) or exclude them (false).

    • range (Boolean, required) – If true, the condition will interpret the IP values as a range; if false, it will treat it as a single IP match.

    • from (String, required) – The starting IP address (IPv4) of the range, or the single IP if not using a range.

    • to (String, optional) – The ending IP address of the range (required if range is true to define the range’s end).

    • description (String, optional) – A short description or label for this IP range (for user reference).

      Example: To target a single IP, say 192.168.0.100, you would use include: true, range: false, from: "192.168.0.100". To target an IP range, say 192.168.0.1 to 192.168.0.255, use include: true, range: true, from: "192.168.0.1", to: "192.168.0.255". Setting include to false would exclude those IPs instead.

  • Geolocation Condition ("GEO" or "GEOLOCATION") – Targets visitors by geographical location (typically country, and optionally region/city).

    • include (Boolean, required) – Include visitors from the specified location if true, or exclude them if false.

    • country (String, required) – Country code in ISO 3166-1 alpha-2 format (2-letter country code). This defines the country to target. Example: "US" for United States, "FR" for France.

    • city (String, optional) – City name (or region) to narrow down within the country. This can further refine the targeting to a specific city. If omitted, the condition targets all visitors in the specified country.

    • least_subdivision (String, optional) – The smallest administrative subdivision (e.g., state or province) to target, if supported. (This field appears in schema for completeness but often not needed unless you target specific states/regions.)

      Example: A Geolocation condition for Canada (anywhere in Canada) would be include: true, country: "CA". To exclude visitors in Paris, one might set include: false, country: "FR", city: "Paris".

  • URL Parameter Condition ("URL_PARAMETER") – Targets based on the presence or value of a URL query parameter in the page URL.

    • include (Boolean, required) – Include visitors who meet this parameter condition if true, or exclude them if false.

    • name (String, required) – The name of the URL parameter to check. For example, "utm_campaign".

    • value (String or Array of Strings, required in most modes) – The value to check for. This can be a specific string or an array of strings depending on the operator.

  • Cookie Condition ("COOKIE") – Targets based on the presence or value of a browser cookie.

    • include (Boolean, required) – Include visitors who meet the cookie condition if true, or exclude them if false.

    • name (String, required) – The name of the cookie to check.

    • value (String or Array of Strings, required in most cases) – The value to match for the cookie.

  • Referrer URL/Previous Page Condition ("PREVIOUS_PAGE") – Targets based on the visitor’s referrer or previous page URL. This is useful to target users coming from a specific site or page.

    • include (Boolean, required) – Include or exclude based on the referrer condition.

    • value (String or Array of Strings, required) – The URL or part of URL to match in the referrer.

    • condition (Integer, required) – The matching condition/operator to use. Common condition codes for Previous Page (and similarly for other text-based conditions) include:

      • 1 for "equals"

      • 2 for "not equals"

      • 10 for "contains"

      • 13 for "does not contain"

      • 41 for "is defined (declared)" (parameter exists)

      • 42 for "is not defined" (parameter missing)

      • 11 for "matches regex"

      • 20 for "greater than" (usually for numeric values)

      • 21 for "lower than"

      • 22 for "greater than or equals" (usually for numeric values)

      • 23 for "lower than or equals"

      • 24 for "between" (likely requires an array of two values)

      Example: To target visitors coming from Google, you might check the referrer URL contains "google.com": include: true, value: "google.com", condition: 10 (contains).

  • Landing Page Condition ("LANDING_PAGE") – Targets users based on whether the current page is the first page of their visit (the landing page of their session).

    • include (Boolean, required) – If true, include visitors on their landing page; if false, include visitors who are not on their landing page (i.e., those who have navigated beyond the first page of their session).

    • value (String or Array of Strings, required) – The URL or part of URL to match in the landing page.

    • condition (Integer, required) – The matching condition/operator to use. Common condition codes for Previous Page (and similarly for other text-based conditions) include:

      • 1 for "equals"

      • 2 for "not equals"

      • 10 for "contains"

      • 13 for "does not contain"

      • 41 for "is defined (declared)" (parameter exists)

      • 42 for "is not defined" (parameter missing)

      • 11 for "matches regex"

      • 20 for "greater than" (usually for numeric values)

      • 21 for "lower than"

      • 22 for "greater than or equals" (usually for numeric values)

      • 23 for "lower than or equals"

      • 24 for "between" (likely requires an array of two values)

      Example: To target visitors coming from Google, you might check the landing page URL contains "google.com": include: true, value: "google.com", condition: 10 (contains).

  • New/Returning Visitor Condition ("NEW_VISITOR" / "RETURNING_VISITOR") – Targets users based on whether they are first-time visitors or returning visitors.

    • new_visitor (Boolean, required) – new visitor or returning visitor (true or false)

  • Page Interest Condition ("PAGE_INTEREST") – Targets users based on their level of engagement with the page (often measured by scroll depth or time spent). AB Tasty uses a "page interest" metric to gauge if a visitor is likely interested in the content.

    • value (String, required) – The mode or criterion for interest. This might be something like "time" or "scroll" depending on how interest is defined. (The exact schema isn’t fully clear, but possibly a key like "percentage" or "duration").

    • include (Boolean, required) – Include or exclude visitors who meet the page interest threshold. Typically include: true to target those who have high interest (e.g., scrolled past X% or spent Y seconds).

    • condition (Integer, required) – The matching condition/operator to use. (and similarly for other text-based conditions) include:

      • 1 for "equals"

      • 2 for "not equals"

      • 10 for "contains"

      • 13 for "does not contain"

      • 41 for "is defined (declared)" (parameter exists)

      • 42 for "is not defined" (parameter missing)

      • 11 for "matches regex"

      • 20 for "greater than" (usually for numeric values)

      • 21 for "lower than"

      • 22 for "greater than or equals" (usually for numeric values)

      • 23 for "lower than or equals"

      • 24 for "between" (likely requires an array of two values)

  • Campaign Exposure Condition ("CAMPAIGN_EXPOSURE") – Targets users based on whether they have been exposed to (seen) a particular campaign or not. This can be used to sequence campaigns or avoid overlap.

    • include (Boolean, required) – Include users who have seen the specified campaign(s) if true, or exclude them if false.

    • type (Integer, required) – The matching operator to use include:

      • 1 for "campaign"

      • 2 for "personalization"

    • campaign_id (Integer, required) - Specific ID campain exposed

    • variation_id (Integer, optional) - Specific ID variation exposed

  • Number of Page Views Condition ("NUMBER_PAGE_VIEWS") – Targets users based on how many pages they have viewed in their session or overall.

    • include (Boolean, required) – Include users who meet the page view criteria if true, or exclude them if false.

    • value (Integer, required) – The number of page views to compare against. If using a between operator, this could be an array [min, max]. If using greater/less, a single number.

  • Action Tracking Condition ("ACTION_TRACKING") – Targets users based on custom events or actions they have performed (these are typically pre-defined tracking events on the site, e.g., clicking a specific button, adding to cart, etc.).

    • include (Boolean, required) – Include users who performed the action if true, or exclude them if false.

    • value (String, required) – An identifier for the action/event (this could be an event name or ID that has been configured in the platform).

    Example: To target users who have triggered a "Add to Cart" action at least once, you might use an Action Tracking condition with include: true, value: "add_to_cart"

  • Session Number Condition ("SESSION_NUMBER") – Targets users by how many sessions they have had on the site. This distinguishes new visitors from those who have visited multiple times, beyond just first vs returning.

    • include (Boolean, required) – Include users matching the session criteria if true, or exclude them if false.

    • value (Integer, required) – The session count number to compare (e.g., 1 for first session, 2 for second session, etc.).

    • condition (Integer, required) – The operator for comparison. For example, 1 (equals), 20 (greater than), 21 (less than).

    • The matching condition/operator to use. (and similarly for other text-based conditions) include:

      • 1 for "equals"

      • 2 for "not equals"

      • 10 for "contains"

      • 13 for "does not contain"

      • 41 for "is defined (declared)" (parameter exists)

      • 42 for "is not defined" (parameter missing)

      • 11 for "matches regex"

      • 20 for "greater than" (usually for numeric values)

      • 21 for "lower than"

      • 22 for "greater than or equals" (usually for numeric values)

      • 23 for "lower than or equals"

      • 24 for "between" (likely requires an array of two values)

      Example: To target users on their second session or later, you could use include: true, value: 1, condition: 20 (greater than 1 session). To target users on exactly their first session, use include: true, value: 1, condition: 1.

  • Data Layer Variable Condition ("DATALAYER") – Targets users based on a value in the website’s data layer or a global JavaScript variable.

    • key (String, required) – The name of the data layer variable or JavaScript variable to evaluate.

    • value (Array of Strings, required depending on usage) – The expected value of that variable (if checking equality or contains, etc.).

    • condition (Integer, required) – The comparison operator (similar codes as URL parameter and cookie conditions: equals, contains, etc.).

    • The matching condition/operator to use. (and similarly for other text-based conditions) include:

      • 1 for "equals"

      • 2 for "not equals"

      • 10 for "contains"

      • 13 for "does not contain"

      • 41 for "is defined (declared)" (parameter exists)

      • 42 for "is not defined" (parameter missing)

      • 11 for "matches regex"

      • 20 for "greater than" (usually for numeric values)

      • 21 for "lower than"

      • 22 for "greater than or equals" (usually for numeric values)

      • 23 for "lower than or equals"

      • 24 for "between" (likely requires an array of two values)

  • JS Code Condition ("CODE") – A custom JavaScript condition where you can evaluate an arbitrary script for truthiness. This allows ultimate flexibility by writing a JS function that returns true or false for targeting.

    • value (String, required) – The lines of code or script to execute. The string could represent a multi-line script.

    • include (Boolean, required) – Include users for whom the code condition returns true if include: true. If include: false, then we invert it (i.e., exclude those who meet the code condition).

      Example: If you want to target users for whom window.isLoggedIn() returns true, you could write a Code condition with a value like ["return window.isLoggedIn();"], condition: 1 (meaning equals true), and include: true. This will include users who are logged in (assuming that function returns a boolean). If you set include: false, it would target users for whom the code returns false (not logged in).

Example Audience JSON

To illustrate how all this comes together, here’s a simple example of an audience defined in JSON. This audience targets mobile visitors who are new (first session) or tablet visitors. It will be represented as two groups:

  • Group 1: device is mobile AND session number is 1 (new visitor).

  • Group 2: device is tablet.

{
  "name": "Mobile New or Tablet Visitors",
  "description": "Targets new mobile visitors or any tablet visitors",
  "groups": [
    [
      {
        "type": "DEVICE",
        "include": true,
        "value": 1        /* mobile */
      },
      {
        "type": "SESSION_NUMBER",
        "include": true,
        "value": 1,
        "condition": 1    /* equals 1 (first session) */
      }
    ],
    [
      {
        "type": "DEVICE",
        "include": true,
        "value": 2        /* tablet */
      }
    ]
  ]
}

In this JSON:

  • The first group has two conditions (mobile AND first session). The operator for that group would be "and" (and by default, with two conditions it’s treated as AND).

  • The second group has one condition (tablet). A single condition group is trivially true if that one condition is true.

  • The two groups are in an array, so by default they are combined with OR logic: a visitor who satisfies either Group 1 or Group 2 will be in this audience. (A new mobile visitor satisfies Group 1; any tablet visitor satisfies Group 2.)

  • We did not explicitly specify operator or other group fields in this example for brevity – in practice, they would default to "and" for the first group (with two conditions) and it doesn’t matter for the second (single condition). The audience builder or API would typically fill in those group-level fields like operator and maybe type.

This example demonstrates how multiple conditions and groups can be structured to form a complex audience rule in a relatively readable JSON format.

Response Fields

When an Audience is retrieved, it will include all the fields provided in the payload (id, name, description, hidden, groups with their conditions) and possibly some metadata:

  • id – The unique audience ID (if it wasn’t already known, e.g., after creation you’d get this).

  • updated_at – Timestamp info when it was last updated, similar to other resources.

  • updated_by – Which user updated it last.

  • created_at – When it was created.

The structure of the audience in the response will mirror the input structure: an audience object with groups and conditions as nested. There aren’t additional computed fields beyond those, since an audience is essentially a configuration object.

Error Codes

For audiences, error codes include the general ones with some specific context:

  • InvalidPayload – The audience definition was incomplete or invalid (e.g., a group with no conditions, or a condition with a wrong value type).

  • PermissionDenied – The user is not allowed to create audiences in this account.

  • DuplicateRef – (Possibly if audience names must be unique) an audience with the same name already exists.

  • InvalidDependency – If an audience references something that doesn’t exist (this is less common, since audiences are mostly self-contained; an example might be referencing a segment ID or provider that’s invalid).

(Audiences don’t have a parent resource, so ParentNotFound is not directly applicable unless perhaps an internal scenario with account context. The above codes align with the general error code definitions.)

PreviousFolderNextIntegrations

Last updated

Was this helpful?