Segmentation Methods

The segmentation methods are used to create, update, delete or get info on the segments associated with your app. Segments are used to target a subset of your app users. Available Methods are:

  • Create: Create a new segment to target a cohort of your app users
  • Update: Update an existing segment
  • Delete: Delete an existing segment 
  • List: Query existing segment and get a list of results
  • Info: Get info on a single segment

 

Create

Used to create a segment that will be associated with your app.

URL

api/external/create/segment

Parameters

Parameter Description
apptoken Your App token
title The title of your segment
conditions See explanation of conditions below

Conditions have the following basic format:

{
    "title": "Test",
    "conditions":  {
        "operator": "AND",
        "0": {
            "operator": "AND",
            "0": [ condition1 ],
            "1": [ condition2 ], 
             .....
        }, .....
    }
}

An operator is used between groups of conditions. Options are "AND" or "OR". Groups of conditions are label from 0-n i.e. "operator": "AND", "0": {group 1}, "operator": "AND", "1": {group 2}, ...... An operator is also used for at the start of a group of conditions, the options are also "AND" or "OR". All conditions are combined using this operator. An individual condition is made up of a mix of possible components:

  • keyword
    • comparator
    • value
  • option
    • comparator
    • value
  • date modifier
    • dates

All conditions must use a keyword to indicate what type of condition is to be used, and a comparator and value to describe a relationship that defines the condition such as "country equals Ireland". Some conditions have an option such as hits for for location and tags that also takes a comparator and value for example "tag Facebook sign-in hit more than 10 times". Some conditions also support date modifiers to link the condition to a time period. There are two options date range or a number of days ago. For example "tag Facebook sign-in hit more than 10 times from the 1st to the 30th of Feb" A full break down of condition options is given in the following table

Keyword Comparator Option Date Modifier
segment equals a specific segment id    
tags equals a specific tag id/title hit more than, less than or equal to a number of times daterange or days ago, optional if not used defaults to all time
tags_flag equals a specific flag id/title status on/off -
tags_attribute equals a specific tag id/title that is an attribute with a specific value value - equals, not equals, more than, less than -
locations equals a specific location id hit more than, less than or equal to a number of times daterange or days ago, optional if not used defaults to all time
app_opened more than, less than or equal to a number of times daterange or days ago, optional if not used defaults to all time  
app_last_opened within time period set using date modifier - daterange or days ago
app_downloaded within time period set using date modifier - daterange or days ago
country Equal or not equal to a two character country code (ISO 3166-1 alpha-2) e.g.[ "country", "=", "IE" ] - -
language Equal or not equal to a devices selected language(ISO 3166-1 alpha-2) e.g. [ "language", "=", "Spanish" ] - -
carrier_name Equal or not equal to a carrier or mobile network operator e.g. [ "carrier_name", "!=", "T-Mobile" ] - -
device_os Equal or not equal to specific device OS e.g. [ "device_os", "!=", "8.2" ] - -
device_model Equal or not equal to specific device model e.g. [ "device_model", "=", "IPhone 6" ] - -
app_version Equal or not equal to specific app version e.g. [ "app_version", "=", "8.2" ] - -
id Equal or not equal to a specific XtremePush id, or in or not in a list of ids e.g. [ "id", "in", [ID1, ID2, ...] ] - -
token Equal or not equal to a specific device token, or in or not in a list of tokens e.g. [ "token", "=", "TOKEN" ] - -
device_id Equal or not equal to a specific device id (IDFV on iOS or Android ID on Android, or in or not in a list of device ids e.g. [ "device_id", "=", "DEVICE_ID" ] - -

Condition Examples

Tags:

[
    "tags", 
    "=",
    "TAG_ID or TAG_TITLE",
    ["hits", "> / < / =", "number of hits"]
    daterange or days ago (optional) (see examples below)
]

Flags:

[
    "tags_flag",
    "=",
    "TAG_ID or TAG_TITLE",
    ["status", "=", "on / off"]
]

Attributes:

[
    "tags_attributes",
    "=",
    "TAG_ID or TAG_TITLE",
["value", "> / < / = / !=", "some value"]
]
 

Locations:

[
    "locations", 
    "=",
    "LOCATION_ID",
    ["hits", "> / < / =", "number of hits"],
    daterange or days ago (optional) (see examples below)
]

App opened all time:

[
    "app_opened",
    "> / < / =",
    "10"
]

App opened with date range:

[
    "app_opened",
    "> / < / =",
    "10",
    null,
    daterange or days ago (see examples below)
]

App last opened:

[
    "app_last_opened",
    null,
    null,
    daterange or days ago (see examples below)
]

App downloaded:

[
    "app_downloaded",
    null,
    null,
    daterange or days ago (see examples below)
]

Daterange format:

["daterange", "between", "2015-01-01 to 2015-01-30", "2015-01-01", "2015-01-30"]

Days ago format:

["days_ago", "> / < / =", null, null, null, "10"]

Other attributes:

[
    "keyword",
    "= / != / in / not in",
    "value"
]

Example

An example of creating a segment combining a tag, the number of days since the app was downloaded and a country.

curl -X POST -d '
{
    "apptoken": "YOUR_APPTOKEN",
    "title": "Test",
    "conditions":  {
        "operator": "AND",
        "0": {
            "operator": "AND",
            "0": [
                "tags",
                "=",
                "test",
                ["hits", ">", "5"],
                ["daterange", "between", 
                 "2015-01-01 to 2015-01-30", 
                 "2015-01-01", "2015-01-30"]            
            ],
            "1": [
                "app_downloaded",
                null,
                null,
                ["days_ago", ">", null, null, null, 10]
            ],
            "2": [
                "country",
                "=",
                "IE"
            ]
        }
    }
}' https://external-api.xtremepush.com/api/external/create/segment

Example response from a successfully created segment

{
    "code": 200,
    "success": true,
    "message": "Segment successfully created",
    "model": {
        "id": "SEGMENT_ID",
        "project_id": "PROJECT_ID",
        "title": "Test",
        "conditions": {
            "0": {
                "0": [
                    "tags", 
                    "=", 
                    "15_01_04",
                    [
                        "hits", 
                        ">", 
                        "5"
                    ], 
                    [
                        "daterange", 
                        "between", 
                        "2015-01-01 to 2015-01-30", 
                        "2015-01-01", 
                        "2015-01-30"
                    ]
                ], 
                "1": [
                    "app_downloaded", 
                    null, 
                    null, 
                    [
                        "days_ago", 
                        ">", 
                        null, 
                        null, 
                        null, 
                        10
                    ]
                ], 
                "2": [
                    "country", 
                    "=", 
                    "IE"
                ], 
                "operator": "AND"
            }, 
            "operator": "AND"
        },
    },
}

 

Update

Used to update an existing segment.

URL

api/external/update/segment

Parameters

Parameter Description
apptoken Your App token
id The id of the segment you want to update
more params The other params are the same as those available in the create method

 

Delete

Used to delete a segment that has previously been created

URL

api/external/delete/segment

Parameters

Parameter Description
apptoken Your App token
id The id of the segment you want to delete

Example

Example of deleting segment

curl -X POST -d '{ "apptoken": "YOUR_APPTOKEN", "id":SEGMENT_ID}' https://external-api.xtremepush.com/api/external/delete/segment

 

List

Used to get a list of all the segments associated with your project. All segments may be returned or lists of segments of a certain type if criteria are provided.

URL

api/external/list/segment

Parameters

Parameter Description
apptoken Your App token
order Order the list in either ascending or descending order based on any of the attributes e.g. "order": ["id ASC", "id" ] or "order": ["id DESC", "id" ]
select Select what attributes to return e.g. "select": ["id", "title"]
condition Filter the segments based on some criteria e.g. "condition": [ ["id", ">" , 250] ]
limit Used with offset for pagination e.g. "limit: 50, "offset": 0 returns a max of 50 segments starting at position 0
offset Used with limit for pagination e.g. "limit: 50, "offset": 0 returns a max of 50 segments starting at position 0

Example

List all segments:

curl -X POST -d '{"apptoken":"YOUR_APPTOKEN"}' https://external-api.xtremepush.com/api/external/list/segment

List all segments ordered by id in ascending order:

curl -X POST -d '{"apptoken":"YOUR_APPTOKEN", "order": ["id ASC", "id" ]}' https://external-api.xtremepush.com/api/external/list/segment

Example response to a request to list all segments

{
    "code": 200,
    "success": true,
    "data": [
        {
            "id": SEGMENT_ID,
            "title": "Test",
            ...
        },
        ...
    ],
}

 

Info

Used to get info on a single segment.

URL

api/external/info/segment

Parameters

Parameter Description
apptoken Your App Token
id The id of the segment you are looking for
select Select what attributes to return e.g. "select": ["id", "title"]

Example

Get all info on the segment:

curl -X POST -d '{"apptoken":"YOUR_APPTOKEN", "id":SEGMENT_ID}' https://external-api.xtremepush.com/api/external/info/segment

 

Have more questions? Submit a request

0 Comments

Article is closed for comments.