Audience format
An audience is a boolean expression made of criteria (variables) operators (“not”, “and” or “or”) and parenthesis. Additionally, a set of filters can be added to an audience.
If the boolean expression is true for a given device, and the device is not filtered, then the device is part of the audience. An audience is represented by a JSON string. The format is describes as follow:
Symbol | Type | Expression/Description |
|---|---|---|
<audience> | object |
{
"expression": <expression>,
"criteria": <criteria>,
"filters": <filters>,
}
|
Symbol | Type | Expression/Description |
|---|---|---|
<expression> | object | Following is the expression language grammar in a pseudo Backus–Naur Form (BNF):
Expr ::= OrExpr
OrExpr ::= AndExpr ( "or" AndExpr )*
AndExpr ::= UnaryExpr ("and" UnaryExpr )*
UnaryExpr ::= "(" Expr ")" | "not" UnaryExpr | <CRITERION>
<Criterion> ::= ["A"-"Z"]["a"-"z", "A"-"Z", "_", "0"-"9"]*
|
 Note |
|---|
Criterion names in the audience expression must start with a capital letter and can only contain alphanumeric (A-Z,a-z,0-9) and underscore (_) characters. |
String-based criterion such as Carrier name, Application version, Device manufacturer for instance support the wildcard characters ? and *.
To perform a single character wildcard matching use the ? symbol. For example, to match text or test you can use the string te?t.
To perform a multiple character wildcard search use the * symbol. For example, to match HTC Magic, HTC Desire or HTC Wildfire you can use the string HTC *.
All string-based criteria can be used to match users whose associated information is not available. Instead of the string value, you should use the null JSON value. For example, the following criterion will target users running on a device with an unknown carrier name:
{
"type": "carrier-name",
"name": null
}
Symbol | Type | Expression/Description |
|---|---|---|
<criteria> | object |
{
<criterion>: <criterion-def>,
*
}
|
<criterion> | string | Name of the criterion. |
<criterion-def> | object | One of the criteria defined blow. |
You can apply the null JSON object as a value to set the criterion as ‘undefined’.
Used to target devices based on their carrier name.
Property Name | Description |
|---|---|
type | Must be the string, "carrier-name". |
name | Carrier name value. |
Examples:
Target users having Vodafone as their mobile carrier
{
"type": "carrier-name",
"name": "Vodafone"
}
Target users whose mobile carrier is unknown
{
"type": "carrier-name",
"name": null
}
Used to target devices based on their carrier country.
Property Name | Description |
|---|---|
type | Must be the string, "carrier-country". |
name | Two-characters country code (ISO 3166-1). |
Example:
{
"type": "carrier-country",
"name": "gb"
}
Used to target devices based on their firmware version.
Property Name | Description |
|---|---|
type | Must be the string, "firmware-version". |
name | Firmware version string. |
Example:
{
"type": "firmware-version",
"name": "1.0"
}
Used to target devices based on the device manufacturer.
Property Name | Description |
|---|---|
type | Must be the string, "device-manufacturer". |
name | The device manufacturer string. |
Example:
{
"type": "device-manufacturer",
"name": "HTC"
}
Used to target devices based on the device model.
Property Name | Description |
|---|---|
type | Must be the string, "device-model". |
name | The device model string. |
Example:
{
"type": "device-model",
"name": "HTC *"
}
Used to target devices based on the version of the application they are using.
Property Name | Description |
|---|---|
type | Must be the string, "application-version". |
name | The application version string. |
Example:
{
"type": "application-version",
"name": "1.2.?"
}
Used to target devices based their network type.
Property Name | Description |
|---|---|
type | Must be the string, "network-type". |
name | The network type (Wifi, Mobile...). |
Example:
{
"type": "network-type",
"name": "WIFI"
}
Used to target devices based on the locale of their device.
Property Name | Description |
|---|---|
type | Must be the string, "language". |
name | Two character language code (ISO 639-1). |
Example:
{
"type": "language",
"name": "fr"
}
Used to target devices based on the screen resolution of their device.
Property Name | Description |
|---|---|
type | Must be the string, "screen-size". |
name | Screen size using the following format WIDTH**x**HEIGHT |
Example:
{
"type": "screen-size",
"name": "640x960"
}
Used to target devices based on their last know area.
Property Name | Description |
|---|---|
type | Must be the string, "location". |
country | Two character country code where the user is located (ISO 3166-1). |
region | Optional. An administrative region of the country, such as a state or province. |
locality | Optional. A locality within the administrative region, such as a town or city |
Example:
{
"type": "location",
"country": "FR",
"region": "Brittany",
"locality": "Rennes"
}
Used to target devices based on a specific region. A center point (defined by a latitude and longitude) and a radius form the boundary for the region. This criterion will be met when the user crosses the boundaries of the region.
Property Name | Description |
|---|---|
type | Must be the string, "geo-fencing". |
lat | The latitude of the central point of the region. |
lon | The longitude of the central point of the region. |
radius | The radius of the central point of the region, in meters. |
expiration | Number of minutes before device location is considered to be expired. |
Example:
{
"type": "geo-fencing",
"lat": 48.10689,
"lon": -1.67198,
"radius": 30,
"expiration": 1
}
Used to target devices who received an announcement.
Property Name | Description |
|---|---|
type | Must be the string, "announcement-feedback". |
content-id | The unique identifier of the announcement. |
action | Action that was performed on the announcement. Can be either: pushed, replied, actioned or exited. |
Example:
{
"type": "announcement-feedback",
"content-id": 3,
"action": "exited"
}
Used to target devices who received a poll.
Property Name | Description |
|---|---|
type | Must be the string, "poll-feedback". |
content-id | The unique identifier of the poll. |
action | Action that was performed on the poll. Can be either: pushed, replied, actioned or exited. |
Example:
{
"type": "poll-feedback",
"content-id": 4,
"action": "actioned"
}
Used to target devices who answered X to a given question.
Property Name | Description |
|---|---|
type | Must be the string, "poll-answer-feedback". |
content-id | The unique identifier of the poll. |
choice-id | The unique identifier of the choice.. |
Example:
{
"type": "poll-answer-feedback",
"content-id": 4,
"choice-id:" 1
}
Used to target devices who received a data push.
Property Name | Description |
|---|---|
type | Must be the string, "datapush-feedback". |
content-id | The unique identifier of the poll. |
action | Action that was performed on the data push (action depends on the return value in the callbacks you declared in the client code). Can be either: pushed, replied, actioned or exited. |
Example:
{
"type": "datapush-feedback",
"content-id": 4,
"action": "replied"
}
Tag (aka appInfo) can only be used if you have injected them into Mobile Engagement (by using the SDK API or the Tag devices API). This information is specific to your application and should be registered in its settings page to be used on the U.I.
You can apply the null JSON object as a value to set the criterion as ‘undefined’.
| Note |
|---|
For migrating Capptain customers, you can also keep using the same syntax for appInfo criteria as it was documented in Capptain API to create and update campaigns. However, the new syntax is used when returning campaign details with the Get campaign call. |
Target devices based on a string tag value.
Property Name | Description |
|---|---|
type | Must be the string, "string-tag". |
name | The name of the custom tag. |
value | A custom string to match for tag value (? and * characters can be used to perform wildcard matching). |
Examples:
Target users who set the ‘contacts’ page as their favorite one:
{
"type": "string-tag",
"name": "favorite_page",
"value": "contacts"
}
Target users who don’t have a favorite page:
{
"type": "string-tag",
"name": "favorite_page",
"value": null
}
Target devices based on a date tag value.
Property Name | Description |
|---|---|
type | Must be the string, "date-tag". |
name | The name of the custom tag. |
value | It can be either:
|
op | Relational operator: EQ (equal to), LT (less than), GT (greater than), LE (less than or equal to) or GE (greater than or equal to). |
Examples:
Target people who have signed up after December 5th, 2011:
{
"type": "date-tag",
"name": "signup_date",
"value": "2011-05-12",
"op": "GE"
}
Target people who have signed up 3 days ago:
{
"type": "date-tag",
"name": "signup_date",
"value": "-3",
"op": "EQ"
}
Target devices based on a integer tag value.
Property Name | Description |
|---|---|
type | Must be the string, "integer-tag". |
name | The name of the custom tag. |
value | A custom integer value. |
op | Relational operator: EQ (equal to), LT (less than), GT (greater than), LE (less than or equal to) or GE (greater than or equal to). |
Example:
{
"type": "integer-tag",
"name": "launch_count",
"value": 3,
"op": "GT"
}
Target devices based on a boolean tag value.
Property Name | Description |
|---|---|
type | Must be the string, "boolean-tag". |
name | The name of the custom tag. |
value | A custom boolean value. |
Example:
{
"type": "boolean-tag",
"name": "mailing_enabled",
"value": true
}
Target devices based on an existing segment.
Property Name | Description |
|---|---|
type | Must be the string, "segment". |
id | Segment identifier. |
exclude | If value is true, the criterion will target users that are NOT part of the segment. |
Example:
{
"type": "segment",
"id": 2,
"exclude": false
}
Global filters applied to all devices.
Symbol | Type | Expression/Description |
|---|---|---|
<filters> | array |
[ <filter>, * ] |
filter | object | One of the following filters shown below. |
Send only to a maximum of max users.
Property Name | Description |
|---|---|
type | Must be the string, "engage-subset". |
max | An integer value representing the maximum users that should be pushed. |
Example:
{
"type": "engage-subset",
"max": 1000
}
Send only to users whose first app use is more than {threshold} days old.
Property Name | Description |
|---|---|
type | Must be the string, "engage-old-users". |
max | An integer value representing the threshold to apply on this filter. |
Example:
{
"type": "engage-old-users",
"threshold": 7
}
Send only to users whose first app use is less than {threshold} days old.
Property Name | Description |
|---|---|
type | Must be the string, "engage-new-users". |
max | An integer value representing the threshold to apply on this filter. |
Example:
{
"type": "engage-new-users",
"threshold": 30
}
Send only to users who have used the app in the last {threshold} days.
Property Name | Description |
|---|---|
type | Must be the string, "engage-active-users". |
max | An integer value representing the threshold to apply on this filter. |
Example:
{
"type": "engage-active-users",
"threshold": 30
}
Send only to users who haven't used the app in the last {threshold} days.
Property Name | Description |
|---|---|
type | Must be the string, "engage-idle-users". |
max | An integer value representing the threshold to apply on this filter. |
Example:
{
"type": "engage-idle-users",
"threshold": 30
}
Engage only users with native push enabled.
Property Name | Description |
|---|---|
type | Must be the string, "native-push-enabled". |
Example:
{
"type": "native-push-enabled"
}
Engage only users for whom the push quota is not reached.
Property Name | Description |
|---|---|
type | Must be the string, "push-quota". |
Example:
{
"type": "push-quota"
}
| Note |
|---|
This is a special filter that is automatically added if your campaign contains appInfo parameters. It is not intended to be public and should not be used as it could be removed or replaced by the API. |
Send only to users who have some app info set.
Property Name | Description |
|---|---|
type | Must be the string, "push-quota". |
appInfo | An array containing all the required appInfo. |
Example:
{
"type": "app-info",
"appInfo" : ["foo", "bar"]
}
Here is an example of an audience targeting all users speaking french or english, running the application on a real device and using Orange or Vodafone as a network carrier:
{
"expression": "(French or English) and (Orange or Vodafone) and not Emulator",
"criteria": {
"French": {
"type": "language",
"name": "fr"
},
"English": {
"type": "language",
"name": "en"
},
"Orange": {
"type": "carrier",
"name": "orange"
},
"Vodafone": {
"type": "carrier",
"name": "vodaphone"
},
"Emulator": {
"type": "device-model",
"name": "emulator"
}
}
}
Here is another example of an audience excluding all users that selected choice 3 to a previous poll sent on another application:
{
"expression": "not PeopleWhoAnwseredPoll123",
"criteria": {
"PeopleWhoAnwseredPoll123": {
"type": "poll-answer-feedback",
"application-id": "gcs000679",
"content-id": 123,
"choice-id": 3
}
}
}