Advanced Tags Guide

The basics are very simple – all filters are performed on the sets of entities.

The method is intended for Advanced Targeting of your messages, and can be used for sending messages across several or **all** of your apps. If you do not include Application Code in your device filters, the message will be sent to **any** device registered in your account, that fits the Tag condition.

Please make sure that you target proper applications, in order to avoid test pushes to be sent to the application(s) in Production.

## Sets

Sets are defined as:

  1. Devices subscribed to the particular app
  2. Devices that match the specific tag value
  3. Devices subscribed to one app of the app group

Syntax

Let’s try with some samples according to the list above.

A("XXXXX-XXXXX", ["iOS", "Android", "Blackberry", "Windows_Phone”, "ASHA", "OsX", "Windows", "Amazon", "Safari", "Chrome""])

Defines the set of devices that are subscribed to the app with the App Code “XXXXX-XXXXX”. The platform specifier is optional and, if omitted, means that the message will be sent to all platforms available for this app.

T("age", BETWEEN, [17,20])

Defines the set of the devices which have the “age” tag set to one of the values: 17, 18, 19, 20.

G("11111-11111", ["iOS","Android"])

Same as “A” but applicable to the app groups.

AT(“XXXXX-XXXXX”, “TagName”, EQ, “VALUE”)

Applicable to Application-specific Tags only.

Tags

The very important thing to understand is that tags are shared between the apps, and it presents a very powerful instrument for segmenting and filtering your target users without binding yourself to a particular app.

The tag could be one of the three different types: String, Integer, List. This defines different operators you can use for a particular tag.

**String:**EQ, IN

Example: T("username", EQ, "my_username"), T("favorite_color", IN, ["red","green","blue"]).

You can use numeric values with the string tags but such values will be converted to a string.

Integer: GTE, LTE, EQ, BETWEEN

GTE – Greater than or equal to

LTE – Less than or equal to

BETWEEN – T("age", BETWEEN, [min_value,max_value]). ‘min_value’ and ‘max_value’ must be integer numbers. ‘min_value ‘must be less than ‘max_value’.

List: The syntax is the same as with the String. The only difference is that your tag can have a set of multiple values.

Operations

  • “+” – joins two sets
  • “*” – intersects two sets
  • “\” – subtracts one set from another

All the operations are left associative. “+” and “*” have the same priority. “\” has greater priority. You can use brackets to define priorities of the calculations.

Note that “\” operation is not commutative. A("12345-12345") \ A("67890-67890") is not the same as A("67890-67890") \ A("12345-12345").

Examples

Easy:

A("00000-00000", ["iOS"]) – all iOS devices subscribed to the app 00000-00000

A("00000-00000") * T("gender", EQ, "F") – all devices subscribed to the app 00000-00000, which have the gender tag set to “female”.

A("00000-00000") * T("username", EQ, "myuser") – all devices subscribed to the app 00000-00000 which have the “myuser” username .

Hard:

( A("00000-00000") + A("11111-11111") ) \ A("12345-12345") – all devices subscribed to the app 00000-00000 OR 11111-11111, which don’t have the app 12345-12345 installed

Hardcore:

( A("00000-00000") * T("gender", EQ, "M") ) + ( A("12345-12345") * T("gender", EQ, "F") ) – Targets all men with the app 00000-00000 and all girls with the app 12345-12345

Fun:

T("gender", EQ, "F") * T("age", BETWEEN, [18, 22]) – targets college-aged girls who have any of your apps installed.

Usage

Creating message:

/json/1.3/createTargetedMessage

Note that you cannot use any of the following targeting-related parameters in the /createTargetedMessage request: `"application", "applications_group", "platforms", "devices", "filter", "conditions"`
 
{"request":{ "auth":"PW AUTH TOKEN", "send_date":"now", "content": "Hello world", "devices_filter":"A(\"00000-00000\") * T(\"age\", BETWEEN, [17, 19])" }}
When using the “devices_filter” parameter you are not allowed to use any other filtering options. In particular, you are not allowed to use “application”, “applications_group” top level parameters and “platforms”, “devices”, “filter”, “conditions” parameters of the **notification** tag. Otherwise, you will get an error, and the message will not be created.
There is a known issue with the createTargetedMessage method: if you don’t specify any applications in “devices_filter” section, Pushwoosh doesn’t display any applications in push details.