API Контрольных групп

Контрольная группа — это удержанная часть пользователей приложения, которая никогда не получает маркетинговые сообщения, что позволяет измерять эффект от рассылок в сравнении с ней. Этот API управляет контрольными группами и отвечает на запросы о членстве для каждого пользователя. Используйте его, чтобы дублировать действия из раздела Настройки > Контрольные группы в Control Panel из ваших собственных систем или чтобы проверять, находятся ли конкретные User ID в удержанной группе перед отправкой или импортом.

Базовый URL

https://rpc-api.svc-nue.pushwoosh.com

Все конечные точки обслуживаются по HTTPS. Запросы и ответы используют application/json, если не указано иное.

Аутентификация

Каждый запрос должен содержать заголовок Authorization с вашим токеном Server API:

Authorization: Api YOUR_API_TOKEN

Соглашения

• Именование полей: тела запросов и параметры пути/запроса принимают lowerCamelCase (например, controlGroupCode, userIds), и сервер десериализует любой из этих регистров. Ответы всегда сериализуются с использованием имен полей proto в snake_case (application_id, in_control_group и так далее). Примеры ответов и справочник по объекту контрольной группы ниже используют этот регистр.
• code: каждый ответ контрольной группы содержит собственный код, сгенерированный при Create. Передавайте этот код как controlGroupCode в Get, UpdatePercentage, UpdateCountries, Rename, Disable, Reshuffle, ForceUpdateCalculation, GetCalculationStatus, GetAnalytics и CheckControlGroupMembership.
• Несколько групп: у приложения может быть несколько контрольных групп. Каждая включенная группа удерживает пользователей от каждой маркетинговой отправки в пределах своих стран и тега, независимо от других групп, и группы могут пересекаться. Отправка не выбирает группу. Группа с пустым name — исходная группа приложения, и работает так же.

Ответы об ошибках

HTTP-статус	Значение
400 Bad Request	Недопустимый аргумент, например, percentage вне диапазона 1–20, userIds пуст или содержит более 1000 записей, нераспознанный код страны, scopeValues без scopeTag, scopeTag с названием тега, которого нет в аккаунте, или значение в scopeValues, которое отклоняет UpdateSettings (см. ниже). Также возвращается (как FailedPrecondition при передаче) методами UpdatePercentage, UpdateCountries, UpdateSettings, Disable, Reshuffle и Delete для контрольной группы, которая принадлежит собственной удержанной группе кампании, согласно предупреждению ниже. Только Reshuffle также отклоняет запрос таким образом для отключенной (percentage 0) группы.
401 Unauthorized	Отсутствует или недействителен заголовок Authorization.
403 Forbidden	Приложение или контрольная группа не принадлежат аккаунту вызывающей стороны.
404 Not Found	Контрольная группа или приложение не найдены.
409 Conflict	При Create использовано name, которое уже существует в приложении.
500 Internal Server Error	Неожиданный сбой на стороне сервера.

Конечные точки

Метод	Путь	Описание
GET	/api/applications/{code}/control_groups	Получить список контрольных групп приложения
POST	/api/applications/{code}/control_groups	Создать контрольную группу
GET	/api/applications/{code}/control_groups/{control_group_code}	Получить одну контрольную группу
POST	/api/applications/{code}/control_groups/{control_group_code}	Изменить размер контрольной группы
POST	/api/applications/{code}/control_groups/{control_group_code}/countries	Ограничить контрольную группу набором стран
POST	/api/applications/{code}/control_groups/{control_group_code}/settings	Применить размер, область действия по странам и тегу и режим срока действия одним вызовом
POST	/api/applications/{code}/control_groups/{control_group_code}/display_name	Переименовать контрольную группу
POST	/api/applications/{code}/control_groups/{control_group_code}/disable	Отключить контрольную группу
POST	/api/applications/{code}/control_groups/{control_group_code}/reshuffle	Перераспределить контрольную группу
POST	/api/applications/{code}/control_groups/{control_group_code}/recalculate	Принудительно пересчитать размер контрольной группы
GET	/api/applications/{code}/control_groups/{control_group_code}/calculation_status	Опросить статус выполняющегося расчета размера
GET	/api/applications/{code}/control_groups/{control_group_code}/analytics	Получить аналитику “Контрольная группа vs. Тестовая группа”
GET	/api/applications/{code}/control_groups/{control_group_code}/cycles	Получить список закрытых циклов группы
POST	/api/applications/{code}/control_groups/{control_group_code}/membership	Проверить членство для пакета User ID
DELETE	/api/applications/{code}/control_groups/{control_group_code}	Удалить контрольную группу

Получение списка

Возвращает список всех контрольных групп, настроенных для приложения; первой идет безымянная исходная группа.

GET /api/applications/{code}/control_groups

Параметры пути

Параметр	Тип	Описание
code	string	Код приложения, для которого нужно получить список контрольных групп.

Ответ

Поле	Тип	Описание
control_groups	массив объектов контрольной группы	Все контрольные группы, настроенные для приложения.

Создание

Создает именованную контрольную группу для приложения и возвращает ее со сгенерированным кодом. Новая группа удерживает пользователей от каждой маркетинговой отправки в пределах своих стран и тега, наряду с другими включенными группами приложения.

POST /api/applications/{code}/control_groups

Тело запроса

Параметр	Тип	Обязательный	Описание
code	string	Да	Код приложения, в котором создается группа.
name	string	Да	Название группы, до 64 символов и без двоеточия. Должно быть уникальным в пределах приложения. Входит в ключ членства, поэтому никогда не меняется.
percentage	integer	Да	Размер удержанной группы в процентах, 1–20.
segment	string	Нет	Выражение Seglang для измерения группы. Опустите, чтобы измерять по всей базе.
countries	массив строк	Нет	Коды стран в нижнем регистре по стандарту ISO-3166-1 alpha-2 для ограничения удержанной группы. Опустите для всех стран. Коды нечувствительны к регистру на входе.
scopeTag	string	Нет	Строковый или булев тег, которым ограничивается удержанная группа, объединяется с countries по AND. Опустите, чтобы не ограничивать по тегу. См. Область действия по тегу ниже.
scopeValues	массив строк	См. примечание	Значения scopeTag, при которых пользователь попадает в область действия. Обязательно, если задан scopeTag, и должно быть пустым в противном случае.
displayName	string	Нет	Название, которое показывает Control Panel, до 64 символов. Опустите, чтобы показывать name.

Пример запроса

{
  "code": "XXXXX-XXXXX",
  "name": "Q3 holdout",
  "percentage": 10
}

Ответ

Возвращает { "group": { ... } }, новый объект контрольной группы.

Получение

Возвращает одну контрольную группу по ее коду, с ее размером удержания, поколением и количеством пользователей.

GET /api/applications/{code}/control_groups/{control_group_code}

Параметры пути

Параметр	Тип	Описание
code	string	Код приложения, к которому принадлежит группа.
control_group_code	string	Код контрольной группы.

Ответ

Поле	Тип	Описание
group	Объект контрольной группы	Запрошенная контрольная группа.
total_users	integer	Все пользователи в приложении.
control_group_users	integer	Пользователи, находящиеся в удержанной группе.
calculation_status	string	TASK_STATUS_NOT_STARTED, TASK_STATUS_IN_PROGRESS или TASK_STATUS_COMPLETED.
has_data	boolean	Доступны ли кэшированные данные о размере.

Изменение процента

Устанавливает процент удержания (1–20) для одной контрольной группы. При изменении размера все существующие участники сохраняются: удержанная группа растет или сокращается вокруг них, а не пересоздается. Заменен методом UpdateSettings, который применяет размер, область действия и режим срока действия одним вызовом, но по-прежнему поддерживается.

POST /api/applications/{code}/control_groups/{control_group_code}

Осторожно

Кампания может создать собственную удержанную выборку, которая также является контрольной группой, но не отображается в Списке. Эта конечная точка, а также UpdateCountries, UpdateSettings, Disable, Reshuffle и Delete откажутся изменять такую группу, возвращая 400 Bad Request (“контрольная группа принадлежит кампании и не может быть изменена”).

Тело запроса

Параметр	Тип	Обязательный	Описание
percentage	integer	Да	Новый размер удержанной группы в процентах, 1–20.

Ответ

Пустой объект в случае успеха: {}.

Изменение стран

Устанавливает страны, на которые распространяется одна контрольная группа. Изменение области действия перезапускает измерение прироста, так как сравниваемая популяция меняется. Сама удержанная группа не пересоздается. Заменен методом UpdateSettings, который также задает область действия по тегу, но по-прежнему поддерживается.

POST /api/applications/{code}/control_groups/{control_group_code}/countries

Тело запроса

Параметр	Тип	Обязательный	Описание
countries	массив строк	Да	Коды стран в нижнем регистре по стандарту ISO-3166-1 alpha-2. Пустой список расширяет группу обратно на все страны. Коды нечувствительны к регистру на входе.

Пример запроса

{
  "countries": ["us", "ca", "gb"]
}

Ответ

Пустой объект в случае успеха: {}.

Обновление настроек

Применяет размер контрольной группы, область действия по странам и тегу и режим срока действия одним вызовом. Изменение, которое меняет, кого удерживают или как долго (размер, область действия, режим, период обновления или дата окончания), закрывает текущий цикл и начинает новый. Отправка текущих значений ничего не меняет. Отклоняет контрольную группу, которая принадлежит собственной удержанной группе кампании, так же, как UpdatePercentage.

POST /api/applications/{code}/control_groups/{control_group_code}/settings

Тело запроса

Параметр	Тип	Обязательный	Описание
percentage	integer	Да	Размер удержанной группы в процентах, 1–20.
countries	массив строк	Нет	Коды стран в нижнем регистре по стандарту ISO-3166-1 alpha-2. Пустой список расширяет группу обратно на все страны.
scopeTag	string	Нет	Строковый или булев тег, которым ограничивается удержанная группа, объединяется с countries по AND. Пустое значение снимает ограничение по тегу. См. Область действия по тегу ниже.
scopeValues	массив строк	См. примечание	Значения scopeTag, при которых пользователь попадает в область действия. Обязательно, если задан scopeTag, и должно быть пустым в противном случае.
mode	string	Нет	Срок действия членства: CONTROL_GROUP_MODE_PERMANENT (по умолчанию), CONTROL_GROUP_MODE_AUTO_REFRESH или CONTROL_GROUP_MODE_EXPERIMENT.
refreshPeriodDays	integer	См. примечание	Число дней между перераспределениями, 7–365. Обязательно для CONTROL_GROUP_MODE_AUTO_REFRESH, в остальных случаях должно быть опущено.
endsAt	string (RFC 3339)	См. примечание	Когда эксперимент отключается, не менее чем через 30 дней. Обязательно для CONTROL_GROUP_MODE_EXPERIMENT, в остальных случаях должно быть опущено.

Каждое поле применяется так, как отправлено, как и в UpdateCountries: пустой countries расширяет группу обратно на все страны, а пустой scopeTag снимает ограничение по тегу.

Ответ

Возвращает { "group": { ... } }, обновленный объект контрольной группы.

Область действия по тегу

Контрольная группа может удерживать только тех пользователей, значение одного строкового или булева тега которых входит в выбранный вами набор, в сочетании с countries по AND, если заданы оба. Задается через Create или UpdateSettings.

• scopeTag называет тег; пустое значение означает отсутствие ограничения по тегу. Это не может быть Country: ограничение по стране задается через countries, а не тегом.
• scopeValues перечисляет, какие значения scopeTag входят в область действия. Если задан scopeTag, нужно указать хотя бы одно значение, повторяться они не могут. Значения строкового тега не могут быть пустыми строками. Каждое значение булева тега должно быть "true" или "false".
• Устройство без значения scopeTag находится вне области действия, так же как устройство без тега Country.
• Само членство не меняется: формула, которая назначает пользователей, область действия не затрагивает. Ограничения по тегу и по стране — это проверка каждого устройства поверх формулы: она сужает, какие из устройств выбранного пользователя действительно исключаются, а не то, кого выбирает формула.
• Тег уровня пользователя копируется на каждое устройство этого пользователя при его установке, поэтому проверка на уровне устройства выше охватывает и теги уровня пользователя, а не только теги уровня устройства.
• Изменение scopeTag или изменение scopeValues как набора (одна лишь перестановка не считается) закрывает текущий цикл с причиной CONTROL_GROUP_CYCLE_CLOSE_REASON_RESCOPED, так же как изменение countries. Отключение группы сохраняет ее ограничение по тегу, как и countries.

Переименование

Задает название, которое Control Panel показывает для одной контрольной группы. name входит в ключ членства и не меняется, поэтому группа сохраняет тех же пользователей и текущий цикл.

POST /api/applications/{code}/control_groups/{control_group_code}/display_name

Тело запроса

Параметр	Тип	Обязательный	Описание
code	string	Да	Код приложения, к которому принадлежит группа.
controlGroupCode	string	Да	Код контрольной группы.
displayName	string	Нет	Новое название, до 64 символов, уникальное в пределах приложения. Отправьте пустую строку, чтобы снова показывать name.

Ответ

Возвращает { "group": { ... } }, переименованный объект контрольной группы.

Отключение

Отключает одну контрольную группу, сохраняя ее и ее поколение, чтобы при повторном включении восстановилась та же удержанная группа, а не создавалась новая.

POST /api/applications/{code}/control_groups/{control_group_code}/disable

Ответ

Пустой объект в случае успеха: {}.

Перераспределение

Пересоздает удержанную группу для одной контрольной группы путем инкремента ее поколения. Это единственный способ получить другую выборку: членство детерминировано, поэтому отключение и повторное включение воспроизводит точно ту же самую группу.

POST /api/applications/{code}/control_groups/{control_group_code}/reshuffle

Осторожно

Отклоняет запрос для отключенной группы (percentage 0) с ошибкой 400 Bad Request (“контрольная группа не включена”). Перераспределение такой группы лишь переместило бы удержанную группу, в которой никого нет, и молча потребило бы одно поколение.

Ответ

Поле	Тип	Описание
generation	integer	Поколение группы после перераспределения.

Принудительный пересчет

Запускает новый подсчет размера одной контрольной группы. Ранее кэшированные числа продолжают использоваться до завершения нового подсчета. Опрашивайте GetCalculationStatus для отслеживания прогресса.

POST /api/applications/{code}/control_groups/{control_group_code}/recalculate

Ответ

Пустой объект в случае успеха: {}.

Получение статуса расчета

Опрашивает только изменяющиеся счетчики пользователей одной контрольной группы во время выполнения расчета размера.

GET /api/applications/{code}/control_groups/{control_group_code}/calculation_status

Ответ

Поле	Тип	Описание
total_users	integer	Все пользователи в приложении.
control_group_users	integer	Пользователи в удержанной группе, подсчитанные по всему приложению.
calculation_status	string	TASK_STATUS_NOT_STARTED, TASK_STATUS_IN_PROGRESS или TASK_STATUS_COMPLETED.
has_data	boolean	Доступны ли кэшированные данные о размере.

Получение аналитики

Возвращает предварительно рассчитанную аналитику “Контрольная группа vs. Тестовая группа” для одной контрольной группы.

Примечание

Ночная задача вычисляет аналитику для каждой включенной группы, именованной или нет. Для группы, измеряемой по segment, аналитики пока нет.

GET /api/applications/{code}/control_groups/{control_group_code}/analytics

Параметры запроса

Параметр	Тип	Обязательный	Описание
windowDays	string	Нет	Предустановка окна ретроспективы: WINDOW_DAYS_3, WINDOW_DAYS_7 или WINDOW_DAYS_30.

Ответ

Поле	Тип	Описание
events	массив объектов	Одна запись на каждое отслеживаемое событие, каждая с event, treatment и control (users, conversions, conversion_rate, events_per_user), uplift_pct, incremental_events, percent_of_treatment, z_score, p_value, confidence_pct и significance (SIGNIFICANCE_NOT_ENOUGH_DATA, SIGNIFICANCE_NOT_SIGNIFICANT или SIGNIFICANCE_SIGNIFICANT).

Получение списка циклов

Возвращает закрытые циклы одной контрольной группы, самые новые первыми. Каждый цикл — это членство, с которым группа работала между двумя изменениями настроек, вместе с настройками, по которым оно было сформировано. Текущий (выполняющийся) цикл в этот список не входит. Его настройки находятся в самом объекте контрольной группы.

GET /api/applications/{code}/control_groups/{control_group_code}/cycles

Ответ

Поле	Тип	Описание
cycles	массив объектов цикла контрольной группы	Самые новые первыми.

Объект цикла контрольной группы

Поле	Тип	Описание
cycle_number	integer	Порядковый номер в пределах группы; собственный cycle_number группы следует за последним закрытым здесь.
mode	string	Режим срока действия, в котором группа работала в этом цикле: CONTROL_GROUP_MODE_PERMANENT, CONTROL_GROUP_MODE_AUTO_REFRESH или CONTROL_GROUP_MODE_EXPERIMENT.
generation	integer	Поколение группы в этом цикле.
percentage	integer	Размер удержанной группы в этом цикле.
countries	массив строк	Область действия по странам в этом цикле; пустое значение означает все страны.
started_at / ended_at	string (RFC 3339)	Когда выполнялся этот цикл.
close_reason	string	Почему цикл завершился: CONTROL_GROUP_CYCLE_CLOSE_REASON_ROLLOVER, _EXPIRED, _RESHUFFLED, _RESIZED, _RESCOPED, _MODE_CHANGED или _DISABLED.
scope_tag	string	Тег, которым была ограничена удержанная группа цикла, объединяется с countries по AND. Пусто, если ограничения по тегу не было, и для каждого цикла, закрытого до появления ограничения по тегу, даже если оно появилось у группы позже.
scope_values	массив строк	Значения scope_tag, при которых пользователь попадал в область действия в этом цикле; задается только вместе с scope_tag.

Проверка членства в контрольной группе

Сообщает для каждого User ID, находится ли он в данный момент в удержанной группе. Членство вычисляется только на основе ID. Запись пользователя не считывается, поэтому ответ будет дан и для ID, которого приложение никогда не видело, а для отключенной группы будет возвращено false для каждого ID, а не ошибка. Группа с ограничением по стране или тегу удерживает пользователя, только если одно из его устройств входит в эту область, поэтому невиданный ID (вообще без устройства) возвращается там как false, хотя тот же ID вернулся бы как true для группы без ограничений. Используйте этот метод вместо экспорта всей группы для проверки пользователей конкретной отправки или импорта.

POST /api/applications/{code}/control_groups/{control_group_code}/membership

Тело запроса

Параметр	Тип	Обязательный	Описание
userIds	массив строк	Да	User ID для проверки, не более 1000 за один вызов.

Пример запроса

{
  "userIds": ["user-1", "user-2", "user-3"]
}

Ответ

Поле	Тип	Описание
users	массив объектов	Одна запись на каждый запрошенный ID, в том порядке, в котором они были переданы (включая дубликаты). Каждая запись содержит user_id (string) и in_control_group (boolean).

Пример ответа

{
  "users": [
    { "user_id": "user-1", "in_control_group": false },
    { "user_id": "user-2", "in_control_group": true },
    { "user_id": "user-3", "in_control_group": false }
  ]
}

Удаление

Полностью удаляет контрольную группу. Она перестает удерживать пользователей, а ее статистику больше нельзя открыть. Остальные группы приложения продолжают работать.

DELETE /api/applications/{code}/control_groups/{control_group_code}

Осторожно

Это действие нельзя отменить. Чтобы прекратить удерживать пользователей, но сохранить группу, ее поколение и историю, отключите ее.

Ответ

Пустой объект в случае успеха: {}.

Объект контрольной группы

Поле	Тип	Описание
code	string	Код контрольной группы (формат XXXXX-XXXXX), стабильный на протяжении всего времени существования группы.
name	string	Название группы, входит в ключ членства. Пустое значение означает исходную, безымянную группу приложения.
display_name	string	Название, которое показывает Control Panel. Пустое значение показывает name, а безымянная группа отображается как Global.
segment	string	Выражение Seglang, по которому измеряется группа; пустое значение означает всю базу.
percentage	integer	Размер удержанной группы в процентах, 1–20. Ноль означает, что группа отключена.
enabled	boolean	Удерживает ли группа в данный момент пользователей.
generation	integer	Инкрементируется при каждом перераспределении; 0 означает, что перераспределение никогда не производилось.
last_modified_at	string (RFC 3339)	Время последнего изменения настроек группы.
last_modified_by	string	Email пользователя, который последним изменил группу.
application_id	integer	Числовой ID приложения, первая часть ключа членства <application_id>:<generation>:<name>:<user_id>, который хэширует CheckControlGroupMembership для определения, находится ли пользователь в удержанной группе.
countries	массив строк	Коды стран в нижнем регистре по стандарту ISO-3166-1 alpha-2, на которые распространяется удержанная группа. Пустое значение означает все страны.
scope_tag	string	Тег, которым ограничена удержанная группа, объединяется с countries по AND; пустое значение означает отсутствие ограничения по тегу. См. Область действия по тегу.
scope_values	массив строк	Значения scope_tag, при которых пользователь попадает в область действия; для булева тега используются "true" и "false".

Связанные материалы

Контрольные группы (руководство по продукту)

API Сегментации (Фильтры)