REST API audience conditions - 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"
}