Partager via

User Group Pattern service

  • Article

The User Group Pattern Service allows you to divide a hypothetical audience into up to five discrete buckets, each bucket defined to cover a percentage of total users. The most common use case for doing this is defining user groups for A/B testing of campaign targeting strategies. For more information, see Test and Control Targeting in documentation.

Note

It is important to note that a pattern does not perform any actual targeting; it simply helps you calculate user group targeting values that you can manually apply to your campaign profiles.

Here's the general process:

  1. You create a JSON file that defines your pattern.
  2. You make the POST request shown below.
  3. The response includes usergroup_target values for your pattern. You update the relevant profiles with these values. For more details, see user_group_targets in the Profile Service.

REST API

HTTP Method Endpoint Description
GET https://api.appnexus.com/usergroup-pattern?id=USER_GROUP_PATTERN_ID View a specific user group pattern.
GET https://api.appnexus.com/usergroup-pattern View all of your user group patterns.
POST https://api.appnexus.com/usergroup-pattern Add a new user group pattern.

JSON fields

Field Type (Length) Description
cookieless boolean If true, the first user group in the groups array will be set to include cookieless users. By default, this is set to false because you cannot track clicks or conversions for cookieless users and, therefore, cannot test performance on them.
Required On: POST
Default: false
groups array of objects The user groups in the pattern. No more than five groups can be included. For more details, see Groups below.
Required On: POST
id int The ID of the user group pattern.
last_modified timestamp The date on which the user group pattern was last modified.
member_id in The member to which the user group pattern belongs.
Required On: POST
name string (255) The name of the user group pattern.
Required On: POST

Groups

Field Type (Length) Description
id int The ID of the user group.
name string The name of the user group.
Required On: POST
percent int The percent of users that this group will target. The total for all user groups must add up to 100%.
Required On: POST
usergroup_target object This object is returned on POST and GET and specifies the information that you would use in the user_group_targets array of a profile. For formatting, see the example below.

Examples

Add a new user group pattern

$ cat pattern
{
    "usergroup-pattern": {
        "name": "Test pattern",
        "member_id": 1066,
        "cookieless": false,
        "groups": [
            {
                "name": "Group 1",
                "percent": 25
            },
            {
                "name": "Group 2",
                "percent": 25
            },
            {
                "name": "Group 3",
                "percent": 25
            },
            {
                "name": "Group 4",
                "percent": 25
            }
        ]
    }
}
$ curl -b cookies -c cookies -X POST -d @pattern 'https://api.appnexus.com/usergroup-pattern'
{
    "response": {
        "status": "OK",
        "count": 1,
        "id": 43,
        "start_element": 0,
        "num_elements": 100,
        "usergroup-pattern": {
            "id": 43,
            "member_id": 1066,
            "name": "Test pattern",
            "cookieless": false,
            "groups": [
                {
                    "id": 1,
                    "name": "Group 1",
                    "percent": 25,
                    "usergroup_target": {
                        "include_cookieless_users": false,
                        "groups": [
                            {
                                "low": 0,
                                "high": 24
                            }
                        ]
                    }
                },
                {
                    "id": 2,
                    "name": "Group 2",
                    "percent": 25,
                    "usergroup_target": {
                        "include_cookieless_users": false,
                        "groups": [
                            {
                                "low": 25,
                                "high": 49
                            }
                        ]
                    }
                },
                {
                    "id": 3,
                    "name": "Group 3",
                    "percent": 25,
                    "usergroup_target": {
                        "include_cookieless_users": false,
                        "groups": [
                            {
                                "low": 50,
                                "high": 74
                            }
                        ]
                    }
                },
                {
                    "id": 4,
                    "name": "Group 4",
                    "percent": 25,
                    "usergroup_target": {
                        "include_cookieless_users": false,
                        "groups": [
                            {
                                "low": 75,
                                "high": 99
                            }
                        ]
                    }
                }
            ],
            "last_modified": "2011-12-13 20:18:02"
        }
    }
}

View user group pattern 43

$ curl -b cookies -c cookies 'https://api.appnexus.com/usergroup-pattern?id=40'
{
    "response": {
        "status": "OK",
        "count": 1,
        "start_element": 0,
        "num_elements": 100,
        "usergroup-pattern": {
            "id": 43,
            "member_id": 1066,
            "name": "Test pattern",
            "cookieless": false,
            "groups": [
                {
                    "id": 1,
                    "name": "Group 1",
                    "percent": 25,
                    "usergroup_target": {
                        "include_cookieless_users": false,
                        "groups": [
                            {
                                "low": 0,
                                "high": 24
                            }
                        ]
                    }
                },
                {
                    "id": 2,
                    "name": "Group 2",
                    "percent": 25,
                    "usergroup_target": {
                        "include_cookieless_users": false,
                        "groups": [
                            {
                                "low": 25,
                                "high": 49
                            }
                        ]
                    }
                },
                {
                    "id": 3,
                    "name": "Group 3",
                    "percent": 25,
                    "usergroup_target": {
                        "include_cookieless_users": false,
                        "groups": [
                            {
                                "low": 50,
                                "high": 74
                            }
                        ]
                    }
                },
                {
                    "id": 4,
                    "name": "Group 4",
                    "percent": 25,
                    "usergroup_target": {
                        "include_cookieless_users": false,
                        "groups": [
                            {
                                "low": 75,
                                "high": 99
                            }
                        ]
                    }
                }
            ],
            "last_modified": "2011-12-13 20:18:02"
        }
    }
}