User Groups¶
This article describes resources and services you can use to view, add, and update user groups.
Overview¶
A user group is a category of consumers you define for the purpose of performing A/B testing. Each user group consists of two or more subgroups (entries
) that represent campaign elements you want to test.
To run an A/B test, create one line for each subgroup that you want to target. Each experiment requires at least two lines. To learn more, refer to A/B Testing Targeting.
Hierarchy¶
A User Group
is an advertiser-level object.
Endpoint¶
/traffic/usergroups
Use the following HTTP methods:
Use the
GET
method to view an existing user group.Use the
POST
method to create a new user group.Use the
PUT
method to update an existing user group.
Resources¶
User Group¶
The User Group
object contains the following fields:
Field |
Description |
Data Type |
Create |
Update |
---|---|---|---|---|
|
Specifies the user group ID. |
|
N/A |
Required |
|
Specifies the name of the user group. |
|
Required |
Optional |
|
Specifies the advertiser ID. To learn more, refer to Advertisers. |
|
Required |
Optional |
|
Specifies an array of entries. |
|
Required |
Optional |
Entries¶
The entries
object contains the following fields:
Field |
Description |
Data Type |
Create |
Update |
---|---|---|---|---|
|
Specifies the subgroup ID. Required to update an existing subgroup in the |
|
N/A |
Required |
|
Specifies the name of the subgroup. |
|
Required |
Required |
|
Specifies the percentage of the total traffic to be directed to the subgroup. The sum of all |
|
Required |
Required |
|
Specifies the ID number of the parent user group. |
|
N/A |
Optional |
|
Read-only field that reports the minimum percentage of traffic directed to the subgroup. |
|
N/A |
N/A |
|
Read-only field that reports the maximum percentage of traffic directed to the subgroup. |
|
N/A |
N/A |
Read User Group¶
Get data for a specific user group.
GET /traffic/usergroups/{id}
Parameters¶
Parameter |
Parameter Type |
Description |
Data Type |
Required |
---|---|---|---|---|
|
path |
Specifies the user group ID. |
|
Y |
Example Request URL¶
GET https://dspapi.admanagerplus.yahoo.com/traffic/usergroups/16890
Example Response¶
{
"response": {
"id": 16890,
"name": "test3ug",
"accountId": 1356341,
"entries": [
{
"id": 36517,
"name": "g1",
"userGroupId": 16890,
"trafficPercent": 30,
"lowerBound": 0,
"upperBound": 29
},
{
"id": 36518,
"name": "g2",
"userGroupId": 16890,
"trafficPercent": 70,
"lowerBound": 30,
"upperBound": 99
}
]
},
"errors": null,
"timeStamp": "2017-09-22T05:56:03Z"
}
Read User Groups¶
Get a filtered list of user groups.
GET /traffic/usergroups?accountId={accountId}&query={query}&page={page}&limit={limit}&sort={sort}&dir={dir}
All of the accepted parameters are query parameters.
Parameters¶
Parameter |
Description |
Data Type |
Required |
---|---|---|---|
|
Specifies the advertiser ID. |
|
Y |
|
Specifies the search term. Use URL encoding conventions (i.e. replace spaces with a |
|
N |
|
Specifies the page number. |
|
N |
|
Specifies the total number of items to return. Maximum allowed value is |
|
N |
|
Specifies the column to sort by. |
|
N |
|
Specifies the sort direction. Allowed values:
|
|
N |
Example Request URL¶
GET https://dspapi.admanagerplus.yahoo.com/traffic/usergroups?accountId=1356341&query=test
Example Response¶
{
"response": [
{
"id": 16890,
"name": "test3ug",
"accountId": 1356341,
"entries": [
{
"id": 36517,
"name": "g1",
"userGroupId": 16890,
"trafficPercent": 30,
"lowerBound": 0,
"upperBound": 29
},
{
"id": 36518,
"name": "g2",
"userGroupId": 16890,
"trafficPercent": 70,
"lowerBound": 30,
"upperBound": 99
}
]
}
],
"errors": null,
"timeStamp": "2017-09-22T06:01:59Z"
}
Create User Group¶
Create a new user group.
POST /traffic/usergroups/
Parameters¶
All fields are specified in the body of the application/json payload.
Example Request URL¶
POST https://dspapi.admanagerplus.yahoo.com/traffic/usergroups
Example Request Body¶
{
"accountId": 1356341,
"name": "test3ug",
"entries": [
{
"trafficPercent": 30,
"name": "g1"
},
{
"trafficPercent": 70,
"name": "g2"
}
]
}
Example Response¶
{
"response": {
"id": 16890,
"name": "test3ug",
"accountId": 1356341,
"entries": [
{
"id": 36517,
"name": "g1",
"userGroupId": 16890,
"trafficPercent": 30,
"lowerBound": 0,
"upperBound": 29
},
{
"id": 36518,
"name": "g2",
"userGroupId": 16890,
"trafficPercent": 70,
"lowerBound": 30,
"upperBound": 99
}
]
},
"errors": null,
"timeStamp": "2017-09-22T05:56:03Z"
}
Update User Group¶
Update an existing user group.
PUT /traffic/usergroups/{id}
Partial updates are supported; values of supported fields that are not in the payload remain unchanged.
Parameters¶
The User Group id
is specified in the url path. All other fields are specified in the body of the application/json payload.
Example Request URL¶
PUT https://dspapi.admanagerplus.yahoo.com/traffic/usergroups/16890
Example Request Body¶
The sum of the subgroups specified in the entries
array must equal 100.
You do not need to specify an ID for new subgroups added to the entries
array. The following example shows a payload that updates two existing subgroups (32438
and 32439
) and adds a third named zz99
.
{
"accountId": 1356341,
"name": "xyz889",
"entries": [
{
"id": 32438,
"trafficPercent": 60,
"name": "zz57",
"userGroupId": 14828
},
{
"id": 32439,
"trafficPercent": 30,
"name": "zz6"
},
{
"trafficPercent": 10,
"name": "zz99"
}
]
}
Example Response¶
{
"response": {
"id": 16890,
"name": "xyz889",
"accountId": 1356341,
"entries": [
{
"id": 32455,
"name": "zz99",
"userGroupId": 16890,
"trafficPercent": 10,
"lowerBound": 90,
"upperBound": 99
},
{
"id": 32439,
"name": "zz6",
"userGroupId": 16890,
"trafficPercent": 30,
"lowerBound": 60,
"upperBound": 89
},
{
"id": 32438,
"name": "zz57",
"userGroupId": 16890,
"trafficPercent": 60,
"lowerBound": 0,
"upperBound": 59
}
]
},
"errors": null,
"timeStamp": "2017-09-22T06:04:26Z"
}
Delete User Group¶
The DSP Traffic API does not support the deletion of user groups.