Dev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideProduct feedbackGitHubNuGetDev CommunitySubmit a ticketLog In

Audience conditions

This topic describes audience conditions for Optimizely Web Experimentation.

Audiences are defined using logical rules called conditions. Each condition is a rule like "Browser equals Chrome", and an audience is a Boolean combination of these rules, like "Browser equals Chrome OR Referrer matches the substring google.com".

Each individual condition is a JSON object with a type and other properties depending on that type. You can see how each condition type is defined below, or just create an audience on Optimizely and GET it back to see its condition JSON.

Conditions are joined together in lists. The first element in each list should be "and", "or", or "not", and the rest of the conditions are combined using that operator. You can replace any individual condition with another list, which allows for a nested structure of ANDs and ORs. A "not" list should only have one condition or list, which are negated. Otherwise, a list with a single condition like ["and", {...}] will just match that condition.

The full condition object should be passed to the API as a serialized string (for example, by using JSON.stringify(data) in JavaScript). We will return it in the same format, so to traverse it, you must parse it as an object (with JSON.parse(string) or equivalent).

For information on Audience Conditions in the Optimizely Web Experimentation, see Audience conditions: Descriptions and examples.

// Condition Grammar: "conditions" should be any value of the form
["and", **]
["or" , **]
["not",  *]
"{..}" // an object with keys like ('type', 'value', 'match_type', 'name')
// ** = one or more values from the list above
// * = one value of the form listed above

// Chrome users on SpringSale or FallSale campaign
[
  "and",
  {
    "type": "browser",
    "value": "gc"
  },
  [
    "or",
    {
      "type": "query",
      "name": "utm_campaign",
      "value": "SpringSale"
    },
    {
      "type": "query",
      "name": "utm_campaign",
      "value": "FallSale"
    },
  ]
]

// Visitor is not on Firefox
[
  "not",
  {
    "type": "browser",
    "value": "ff"
  }
]

Ad campaign

  • type – campaign
  • match_type – required
  • value – optional

Will match if the utm_campaign query parameter matches value according to match_type. If you don't provide a match type, it will default to exact if a value is provided or exists if a value is not provided.

Any string value is allowed except:

  • none

The match_type can be:

  • exists has any value
  • exact equals
  • substring contains
  • regex matches
{
  "type": "campaign",
  "match_type": "exact",
  "value": "campaign_name"
}

For more information about targeting audiences using Ad campaign, see Target audiences using conditions.

Browser or Device (deprecated)

This condition has been replaced by: "Browser / Version", "Device", and "Platform / OS".

  • type – browser
  • value – required

For visitors on PC's, this is their browser. For visitors on mobile, this is their device or operating system. Acceptable values are:

  • mobile – Any mobile browser
  • android – Android (any browser)
  • blackberry – Blackberry (any browser)
  • ipad – iPad (any browser)
  • iphone – iPhone (any browser)
  • windows phone – Windows Phone (any browser)
  • ff2 – Firefox 2
  • ff3 – Firefox 3
  • ff4 – Firefox 4
  • ff – Firefox (any Desktop version)
  • ie6 – Internet Explorer 6(deprecated)
  • ie7 – Internet Explorer 7(deprecated)
  • ie8 – Internet Explorer 8
  • ie9 – Internet Explorer 9
  • ie10 – Internet Explorer 10
  • ie11 – Internet Explorer 11
  • safari3 – Safari 3
  • safari4 – Safari 4
  • safari5 – Safari 5
  • safari6 – Safari 6
  • safari7 – Safari 7
  • safari8 – Safari 8
  • gc – Google Chrome
  • opera – Opera
{
  "type": "browser",
  "value": "ie10"
}

Browser/Version

  • type – browser_version
  • value – required

Represents the browser the visitor is using. You may target all browsers in a family (e.g. "safari") or only a specific version, for supported browsers.

Acceptable values are:

  • ff – Firefox (any version)
  • ie – Internet Explorer (any version)
  • ie8 – Internet Explorer 8
  • ie9 – Internet Explorer 9
  • ie10 – Internet Explorer 10
  • ie11 – Internet Explorer 11
  • edge – Microsoft Edge (any version)
  • safari – Safari (any version)
  • safari6 – Safari 6
  • safari7 – Safari 7
  • safari8 – Safari 8
  • safari9 – Safari 9
  • safari10 – Safari 10
  • safari11 – Safari 11
  • gc – Google Chrome
  • opera – Opera
  • ucbrowser – UC Browser
{
  "type": "browser_version",
  "value": "ie10"
}

Cookie

  • type – cookies
  • name – required
  • match_type – required
  • value – optional

Will match if cookie name matches value according to match_type. If you don't provide a match type, it will default to exact if a value is provided or exists if a value is not provided.

The match_type can be:

  • exists has any value
  • exact equals
  • substring contains
  • regex matches
{
  "type": "cookies",
  "name": "my_cookie",
  "value": "chocolate .*",
  "match_type": "regex"
}

Custom Attribute

  • type – custom_attribute
  • name – required
  • match_type – optional
  • value – optional

Will match if the custom_attribute parameter matches value according to match_type. If you don't provide a match type, it will default to exact if a value is provided or exists if a value isn't provided.

Note: Full Stack accepts string, number, and boolean values and exists, exact, substring, gt,
and lt match types. Web accepts only string values of an exact match type.

Optimizely Web Experimentation:

{
  "type": "custom_attribute",
  "name": "Subscriber Status",
  "match_type": "exact",
  "value": "active",
}

Optimizely Feature Experimentation:

{
  "type": "custom_attribute",
  "name": "Subscriber ID",
  "match_type": "lt",
  "value": 9,
}

Device

  • type – device
  • value – required

The specific device, or device type, the visitor is using.

Acceptable values are:

  • iphone – iPhone
  • ipad – iPad
  • mobile – Other mobile phone
  • tablet – Other tablet
  • desktop – Desktop/Laptop
{
  "type": "device",
  "value": "ipad"
}

Custom Event

  • type – event
  • name – required

Will match if the visitor triggered the goal with event name name.

{
  "type": "event",
  "name": "event_name"
}

Custom Javascript

  • type – code
  • value – required

Will match if the Javascript code in value evaluates to a truthy value.

{
  "type": "code",
  "value": "myVariable == true"
}

Custom Tags

  • type – custom_tag
  • name – required
  • match_type – required
  • value – optional

Will match if the custom tag name matches value according to match_type. If you don't provide a match type, it will default to exact if a value is provided or exists if a value is not provided.

The match_type can be:

  • exists has any value
  • exact equals
  • substring contains
  • regex matches
{
  "type": "custom_tag",
  "name": "continent",
  "value": "America", // Would match "North America" or "South America"
  "match_type": "substring"
}

Dimension

  • type – custom_dimension
  • name – required
  • value – optional

You can build audiences out of your custom dimension by providing the dimension's name (not ID) in the name parameter.

{
  "type": "custom_dimension",
  "name": "whatever",
  "value": "1234"
}

IP Address

  • type – ip
  • match_type – required
  • value – required

Will match if the visitor's IP matches value according to the match type.

The match_type can be:

  • exact Exact match
  • regex Regular expression match
  • cidr CIDR Notation (subnet/mask)
  • prefix Prefix match
{
  "type": "ip",
  "match_type": "exact",
  "value": "1.2.3.4"
}

Language

  • type – language
  • value – required

Will match visitors based on their browser's preferred language setting.

Acceptable values are:

  • ar – Arabic - any
  • af – Afrikaans
  • sq – Albanian
  • ar-dz – Arabic - Algeria
  • ar-bh – Arabic - Bahrain
  • ar-eg – Arabic - Egypt
  • ar-iq – Arabic - Iraq
  • ar-jo – Arabic - Jordan
  • ar-kw – Arabic - Kuwait
  • ar-lb – Arabic - Lebanon
  • ar-ly – Arabic - Libya
  • ar-ma – Arabic - Morocco
  • ar-om – Arabic - Oman
  • ar-sa – Arabic - Saudi Arabia
  • ar-sy – Arabic - Syria
  • ar-qa – Arabic - Qatar
  • ar-tn – Arabic - Tunisia
  • ar-ae – Arabic - U.A.E.
  • ar-ye – Arabic - Yemen
  • eu – Basque
  • be – Belarusian
  • bg – Bulgarian
  • ca – Catalan
  • zh – Chinese - any
  • zh-hk – Chinese - Hong Kong
  • zh-cn – Chinese - PRC
  • zh-sg – Chinese - Singapore
  • zh-tw – Chinese - Taiwan
  • hr – Croatian
  • cs – Czech
  • da – Danish
  • nl – Dutch - any
  • nl-be – Dutch - Belgian
  • en – English - any
  • en-au – English - Australian
  • en-bz – English - Belize
  • en-gb – English - British
  • en-ca – English - Canadian
  • en-ie – English - Ireland
  • en-jm – English - Jamaica
  • en-nz – English - New Zealand
  • en-za – English - South Africa
  • en-tt – English - Trinidad
  • en-us – English - United States
  • et – Estonian
  • fa – Farsi
  • fi – Finnish
  • fr – French - any
  • fr-be – French - Belgian
  • fr-ca – French - Canadian
  • fr-lu – French - Luxembourg
  • fr-ch – French - Swiss
  • gd – Gaelic - any
  • de – German - any
  • de-at – German - Austrian
  • de-li – German - Liechtenstein
  • de-lu – German - Luxembourg
  • de-ch – German - Swiss
  • el – Greek
  • he – Hebrew
  • hi – Hindi
  • hu – Hungarian
  • is – Icelandic
  • in – Indonesian
  • it – Italian - any
  • it-ch – Italian - Swiss
  • ja – Japanese
  • ko – Korean
  • ko – Korean - Johab
  • lv – Latvian
  • lt – Lithuanian
  • ms – Malaysian
  • mt – Maltese
  • no – Norwegian
  • pl – Polish
  • pt – Portuguese - any
  • pt-br – Portuguese - Brazil
  • ro – Romanian - any
  • ro-mo – Romanian - Moldavia
  • ru – Russian - any
  • ru-mo – Russian - Moldavia
  • sr – Serbian
  • sk – Slovak
  • sl – Slovenian
  • sb – Sorbian
  • es – Spanish - any
  • es-ar – Spanish - Argentina
  • es-bo – Spanish - Bolivia
  • es-c – Spanish - Chile
  • es-co – Spanish - Colombia
  • es-cr – Spanish - Costa Rica
  • es-do – Spanish - Dominican Republic
  • es-ec – Spanish - Ecuador
  • es-sv – Spanish - El Salvador
  • es-gt – Spanish - Guatemala
  • es-hn – Spanish - Honduras
  • es-mx – Spanish - Mexican
  • es-ni – Spanish - Nicaragua
  • es-pa – Spanish - Panama
  • es-py – Spanish - Paraguay
  • es-pe – Spanish - Peru
  • es-pr – Spanish - Puerto Rico
  • es-uy – Spanish - Uruguay
  • es-ve – Spanish - Venezuela
  • sx – Sutu
  • sv – Swedish - any
  • sv-fi – Swedish - Finland
  • th – Thai
  • ts – Tsonga
  • tn – Tswana
  • tr – Turkish
  • uk – Ukrainian
  • ur – Urdu
  • vi – Vietnamese
  • xh – Xhosa
  • ji – Yiddish
  • zu – Zulu
{
  "type": "language",
  "value": "af"
}

Location

  • type – location
  • value – required

Will geo-target visitors based on their location. Also allows for DMA Regions.

{
  "type": "location",
  "value": "US|CA|SANFRANCISCO"
}

New/Returning Session

{
  "type": "first_session"
}

Platform / OS

  • type – platform
  • value – required

Mobile or desktop platform (OS) the visitor is using.

Acceptable values are:

  • mobile – Any mobile platform(deprecated)
  • desktop – Any desktop platform(deprecated)
  • ios – iOS (any version)
  • ios_6 – iOS 6 (deprecated)
  • ios_7 – iOS 7 (deprecated)
  • ios_8 – iOS 8 (deprecated)
  • ios_9 – iOS 9 (deprecated)
  • ios_10 – iOS 10 (deprecated)
  • ios_11 – iOS 11 (deprecated)
  • android – Android (any version)
  • android_2.3 – Gingerbread (2.3) (deprecated)
  • android_4.0 – Ice Cream Sandwich (4.0) (deprecated)
  • android_4.1_4.3 – Jellybean (4.1-4.3) (deprecated)
  • android_4.4 – KitKat (4.4) (deprecated)
  • android_5 – Lollipop (5.0) (deprecated)
  • android_6 – Marshmallow (6.0) (deprecated)
  • android_7 – Nougat (7.0) (deprecated)
  • android_8 – Oreo (8.0) (deprecated)
  • windows phone – Windows Phone (any version)
  • blackberry – Blackberry
  • windows – Windows (any desktop version)
  • windows_7 – Windows 7 (deprecated)
  • windows_8 – Windows 8 (deprecated)
  • windows_8.1 – Windows 8.1 (deprecated)
  • windows_10 – Windows 10 (deprecated)
  • mac os – OS X (any version)
  • mac os_10.6 – Snow Leopard (10.6) (deprecated)
  • mac os_10.7 – Lion (10.7) (deprecated)
  • mac os_10.8 – Mountain Lion (10.8) (deprecated)
  • mac os_10.9 – Mavericks (10.9) (deprecated)
  • mac os_10.10 – Yosemite (10.10) (deprecated)
  • mac os_10.11 – El Capitan (10.11) (deprecated)
  • mac os_10.12 – Sierra (10.12) (deprecated)
  • mac os_10.13 – High Sierra (10.13) (deprecated)
  • linux – Linux (any distro)
{
  "type": "platform",
  "value": "windows"
}

Query Parameters

  • type – query
  • name – required
  • match_type – required
  • value – optional

Will match if the query parameter name equals value. according to match_type. If you don't provide a match type, it will default to exact if a value is provided or exists if a value is not provided.

The match_type can be:

  • exists has any value
  • exact equals
  • substring contains
  • regex matches
{
  "type": "query",
  "name": "my_parameter",
  "value": "my_value",
  "match_type": "exact"
}

Referrer URL

  • type – referrer
  • match_type – required
  • value – required

Will match visitors who came from a URL that matches value according to match_type.

The match_type can be:

  • simple Simple match (hostname/path only)
  • exact Exact match
  • substring Substring match
  • regex Regular expression match
{
  "type": "source_type",
  "value": "referral"
}

Traffic Source

  • type – source_type
  • value – required

Acceptable values are:

  • direct – Direct
  • search – Search
  • referral – Referral
  • campaign – Campaign
{
  "type": "source_type",
  "value": "referral"
}

Time/Day of Visit

  • type – time_and_day
  • value – required

Will match visitors who come during certain days of the week, and certain times within those days. The value takes the form START_END_DAYS, where the start and end are 24-hour times in the form hh:mm like 14:30 for 2:30pm. Use 00:00_23:59 to target the full day.

For days, provide a comma separated list of lowercase days of the week like saturday,sunday. You must provide at least one day.

To target the full week, use monday,tuesday,wednesday,thursday,friday,saturday,sunday.

Putting this together, to target just weekday mornings, you could provide value: '06:00_11:00_monday,tuesday,wednesday,thursday,friday'.

{
  "type": "time_and_day",
  "value": "07:00_11:00_monday,tuesday,wednesday,thursday,friday"
}