API de Grupos de Controle

Um grupo de controle é uma parcela de retenção dos usuários de um aplicativo que nunca recebe mensagens de marketing, para que o efeito das mensagens possa ser medido em comparação a ele. Esta API gerencia grupos de controle e responde sobre a participação por usuário. Use-a para espelhar as ações de Configurações > Grupos de controle do Painel de Controle a partir de seus próprios sistemas, ou para verificar se IDs de usuário específicos estão retidos antes de um envio ou importação.

URL Base

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

Todos os endpoints são servidos via HTTPS. As solicitações e respostas usam application/json, a menos que seja indicado o contrário.

Autenticação

Toda solicitação deve incluir um cabeçalho Authorization com seu token de API do Servidor:

Authorization: Api YOUR_API_TOKEN

Convenções

• Nomenclatura de campos: corpos de solicitação e parâmetros de consulta/caminho aceitam lowerCamelCase (por exemplo, controlGroupCode, userIds), e o servidor decodifica qualquer um dos casos. As respostas são sempre codificadas usando os nomes de campo do proto, em snake_case (application_id, in_control_group, e assim por diante). Os exemplos de resposta e a referência do Objeto de grupo de controle abaixo usam essa formatação.
• code: toda resposta de grupo de controle carrega seu próprio código, gerado em Create. Passe este código como controlGroupCode para Get, UpdatePercentage, UpdateCountries, Rename, Disable, Reshuffle, ForceUpdateCalculation, GetCalculationStatus, GetAnalytics e CheckControlGroupMembership.
• Vários grupos: um aplicativo pode ter vários grupos de controle. Cada grupo ativado retém usuários de todo envio de marketing dentro dos seus próprios países e tag, independentemente dos outros grupos, e os grupos podem se sobrepor. Um envio não seleciona um grupo. O grupo com um name vazio é o grupo original do aplicativo e funciona da mesma forma.

Respostas de erro

Status HTTP	Significado
400 Bad Request	Argumento inválido, como percentage fora de 1–20, userIds vazio ou com mais de 1.000 entradas, um código de país não reconhecido, scopeValues definido sem scopeTag, scopeTag com o nome de uma tag que a conta não possui, ou uma entrada de scopeValues que UpdateSettings rejeita (veja abaixo). Também retornado (como um FailedPrecondition na transmissão) por UpdatePercentage, UpdateCountries, UpdateSettings, Disable, Reshuffle e Delete em um grupo de controle que pertence a uma retenção própria de uma campanha, conforme a advertência abaixo. Reshuffle sozinho também recusa desta forma em um grupo desativado (percentage 0).
401 Unauthorized	Cabeçalho Authorization ausente ou inválido.
403 Forbidden	O aplicativo ou grupo de controle não pertence à conta do chamador.
404 Not Found	O grupo de controle ou aplicativo não foi encontrado.
409 Conflict	Create usou um name que já existe no aplicativo.
500 Internal Server Error	Falha inesperada no lado do servidor.

Endpoints

Método	Caminho	Descrição
GET	/api/applications/{code}/control_groups	Listar os grupos de controle de um aplicativo
POST	/api/applications/{code}/control_groups	Criar um grupo de controle
GET	/api/applications/{code}/control_groups/{control_group_code}	Obter um único grupo de controle
POST	/api/applications/{code}/control_groups/{control_group_code}	Redimensionar um grupo de controle
POST	/api/applications/{code}/control_groups/{control_group_code}/countries	Redefinir o escopo de um grupo de controle para um conjunto de países
POST	/api/applications/{code}/control_groups/{control_group_code}/settings	Aplicar tamanho, escopo de países e tag e modo de duração em uma única chamada
POST	/api/applications/{code}/control_groups/{control_group_code}/display_name	Renomear um grupo de controle
POST	/api/applications/{code}/control_groups/{control_group_code}/disable	Desativar um grupo de controle
POST	/api/applications/{code}/control_groups/{control_group_code}/reshuffle	Reembaralhar um grupo de controle
POST	/api/applications/{code}/control_groups/{control_group_code}/recalculate	Forçar o recálculo do tamanho de um grupo de controle
GET	/api/applications/{code}/control_groups/{control_group_code}/calculation_status	Consultar um cálculo de tamanho em andamento
GET	/api/applications/{code}/control_groups/{control_group_code}/analytics	Obter análises de Controle vs. Tratamento
GET	/api/applications/{code}/control_groups/{control_group_code}/cycles	Listar os ciclos encerrados do grupo
POST	/api/applications/{code}/control_groups/{control_group_code}/membership	Verificar a participação de um lote de IDs de usuário
DELETE	/api/applications/{code}/control_groups/{control_group_code}	Excluir um grupo de controle

Listar

Lista todos os grupos de controle configurados para um aplicativo, com o original, sem nome, primeiro.

GET /api/applications/{code}/control_groups

Parâmetros de caminho

Parâmetro	Tipo	Descrição
code	string	O código do aplicativo para o qual listar os grupos de controle.

Resposta

Campo	Tipo	Descrição
control_groups	array de Objetos de grupo de controle	Todo grupo de controle configurado para o aplicativo.

Criar

Cria um grupo de controle nomeado para um aplicativo e o retorna com seu código gerado. O novo grupo retém usuários de todo envio de marketing dentro dos seus próprios países e tag, junto com os outros grupos ativados do aplicativo.

POST /api/applications/{code}/control_groups

Corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
code	string	Sim	O código do aplicativo no qual criar o grupo.
name	string	Sim	Nome do grupo, até 64 caracteres e sem dois pontos. Deve ser único dentro do aplicativo. Faz parte da chave de participação, portanto nunca muda.
percentage	integer	Sim	Tamanho da retenção como uma porcentagem, 1–20.
segment	string	Não	Expressão Seglang para medir o grupo. Omita para medir sobre toda a base.
countries	array de strings	Não	Códigos de país ISO-3166-1 alfa-2 em minúsculas para restringir a retenção. Omita para todos os países. Os códigos não diferenciam maiúsculas de minúsculas na entrada.
scopeTag	string	Não	Uma tag de string ou booleana para restringir a retenção, combinada com countries por AND. Omita para não restringir por tag. Veja Escopo de tag abaixo.
scopeValues	array de strings	Ver nota	Valores de scopeTag que colocam um usuário no escopo. Obrigatório se scopeTag estiver definido, e deve ficar vazio caso contrário.
displayName	string	Não	Nome exibido pelo Control Panel, até 64 caracteres. Omita para exibir name.

Exemplo de solicitação

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

Resposta

Retorna { "group": { ... } }, o novo Objeto de grupo de controle.

Obter

Retorna um grupo de controle por seu código, com seu tamanho de retenção, geração e as contagens de usuários por trás dele.

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

Parâmetros de caminho

Parâmetro	Tipo	Descrição
code	string	O código do aplicativo ao qual o grupo pertence.
control_group_code	string	O código do grupo de controle.

Resposta

Campo	Tipo	Descrição
group	Objeto de grupo de controle	O grupo de controle solicitado.
total_users	integer	Todos os usuários no aplicativo.
control_group_users	integer	Usuários atualmente retidos.
calculation_status	string	TASK_STATUS_NOT_STARTED, TASK_STATUS_IN_PROGRESS ou TASK_STATUS_COMPLETED.
has_data	boolean	Se os números de tamanho em cache já estão disponíveis.

UpdatePercentage

Define a porcentagem de retenção (1–20) de um grupo de controle. O redimensionamento mantém todos os membros existentes: a retenção cresce ou diminui em torno deles, em vez de ser redesenhada. Substituído por UpdateSettings, que aplica tamanho, escopo e modo de duração em uma única chamada, mas ainda é suportado.

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

Cuidado

Uma campanha pode criar sua própria amostra de retenção, que também é um grupo de controle, mas não aparece em Listar. Este endpoint, UpdateCountries, UpdateSettings, Disable, Reshuffle e Delete se recusam a tocar em um, retornando 400 Bad Request (“o grupo de controle pertence a uma campanha e não pode ser alterado”) em vez disso.

Corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
percentage	integer	Sim	Novo tamanho de retenção como uma porcentagem, 1–20.

Resposta

Um objeto vazio em caso de sucesso: {}.

UpdateCountries

Define os países aos quais um grupo de controle está restrito. Mudar o escopo reinicia a medição de uplift, porque a população sendo comparada muda. A retenção em si não é redesenhada. Substituído por UpdateSettings, que também define um escopo de tag, mas ainda é suportado.

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

Corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
countries	array de strings	Sim	Códigos de país ISO-3166-1 alfa-2 em minúsculas. Uma lista vazia amplia o grupo de volta para todos os países. Os códigos não diferenciam maiúsculas de minúsculas na entrada.

Exemplo de solicitação

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

Resposta

Um objeto vazio em caso de sucesso: {}.

UpdateSettings

Aplica o tamanho, o escopo de países e tag e o modo de duração de um grupo de controle em uma única chamada. Uma alteração que muda quem é retido ou por quanto tempo (tamanho, escopo, modo, período de atualização ou data de término) encerra o ciclo em execução e inicia um novo. Enviar os valores atuais não altera nada. Recusa um grupo de controle que pertence a uma retenção própria de uma campanha, da mesma forma que UpdatePercentage.

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

Corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
percentage	integer	Sim	Tamanho da retenção como uma porcentagem, 1–20.
countries	array de strings	Não	Códigos de país ISO-3166-1 alfa-2 em minúsculas. Uma lista vazia amplia o grupo de volta para todos os países.
scopeTag	string	Não	Uma tag de string ou booleana para restringir a retenção, combinada com countries por AND. Vazio remove o escopo de tag. Veja Escopo de tag abaixo.
scopeValues	array de strings	Ver nota	Valores de scopeTag que colocam um usuário no escopo. Obrigatório se scopeTag estiver definido, e deve ficar vazio caso contrário.
mode	string	Não	Duração da participação: CONTROL_GROUP_MODE_PERMANENT (padrão), CONTROL_GROUP_MODE_AUTO_REFRESH ou CONTROL_GROUP_MODE_EXPERIMENT.
refreshPeriodDays	integer	Ver nota	Dias entre os redesenhos, 7–365. Obrigatório com CONTROL_GROUP_MODE_AUTO_REFRESH, e deve ser omitido caso contrário.
endsAt	string (RFC 3339)	Ver nota	Quando um experimento é desligado, com pelo menos 30 dias de antecedência. Obrigatório com CONTROL_GROUP_MODE_EXPERIMENT, e deve ser omitido caso contrário.

Todo campo é aplicado como enviado, da mesma forma que em UpdateCountries: um countries vazio amplia o grupo de volta para todos os países, e um scopeTag vazio remove o escopo de tag.

Resposta

Retorna { "group": { ... } }, o Objeto de grupo de controle atualizado.

Escopo de tag

Um grupo de controle pode reter apenas os usuários cujo valor de uma tag de string ou booleana está em um conjunto que você escolher, combinado por AND com countries se ambos estiverem definidos. Defina-o com Create ou UpdateSettings.

• scopeTag nomeia a tag; vazio significa sem escopo de tag. Não pode ser Country: o escopo por país usa countries, não uma tag.
• scopeValues lista quais valores de scopeTag estão no escopo. Pelo menos um é obrigatório quando scopeTag está definido, e nenhum pode se repetir. Os valores de uma tag de string não podem ser strings vazias. Os valores de uma tag booleana devem ser cada um "true" ou "false".
• Um dispositivo sem valor para scopeTag está fora do escopo, da mesma forma que um dispositivo sem a tag Country.
• A participação em si não muda: a fórmula que atribui os usuários não é afetada pelo escopo. O escopo de tag e o de país são ambos uma verificação por dispositivo além dela, restringindo quais dispositivos de um usuário selecionado são realmente excluídos, e não quem a fórmula seleciona.
• Uma tag em nível de usuário é copiada para todos os dispositivos desse usuário quando é definida, então a verificação por dispositivo acima já cobre também as tags em nível de usuário, e não apenas as em nível de dispositivo.
• Alterar scopeTag, ou alterar scopeValues como um conjunto (apenas reordenar não conta), encerra o ciclo em execução com CONTROL_GROUP_CYCLE_CLOSE_REASON_RESCOPED, da mesma forma que alterar countries. Desativar um grupo mantém seu escopo de tag, assim como já mantém countries.

Renomear

Define o nome que o Control Panel exibe para um grupo de controle. name faz parte da chave de participação e não muda, então o grupo mantém os mesmos usuários e seu ciclo em execução.

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

Corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
code	string	Sim	O código do aplicativo ao qual o grupo pertence.
controlGroupCode	string	Sim	O código do grupo de controle.
displayName	string	Não	Novo nome, até 64 caracteres e único dentro do aplicativo. Envie uma string vazia para voltar a exibir name.

Resposta

Retorna { "group": { ... } }, o Objeto de grupo de controle renomeado.

Desativar

Desliga um grupo de controle, mantendo-o e sua geração para que, ao ligá-lo novamente, a mesma retenção seja restaurada em vez de desenhar uma nova.

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

Resposta

Um objeto vazio em caso de sucesso: {}.

Reembaralhar

Redesenha a retenção de um grupo de controle incrementando sua geração. Esta é a única maneira de obter uma amostra diferente: a participação é determinística, então desativar e reativar reproduz exatamente a mesma.

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

Cuidado

Recusa um grupo desativado (percentage 0) com 400 Bad Request (“o grupo de controle não está ativado”). Reembaralhá-lo apenas moveria uma retenção em que ninguém está, e consumiria silenciosamente uma geração.

Resposta

Campo	Tipo	Descrição
generation	integer	A geração do grupo após o reembaralhamento.

ForceUpdateCalculation

Inicia uma nova contagem do tamanho de um grupo de controle. Os números em cache anteriormente continuam sendo servidos até que a nova contagem termine. Consulte GetCalculationStatus para o progresso.

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

Resposta

Um objeto vazio em caso de sucesso: {}.

GetCalculationStatus

Consulta apenas as contagens de usuários em mudança de um grupo de controle enquanto um cálculo de tamanho está em execução.

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

Resposta

Campo	Tipo	Descrição
total_users	integer	Todos os usuários no aplicativo.
control_group_users	integer	Usuários retidos, contados sobre o aplicativo.
calculation_status	string	TASK_STATUS_NOT_STARTED, TASK_STATUS_IN_PROGRESS ou TASK_STATUS_COMPLETED.
has_data	boolean	Se os números de tamanho em cache estão disponíveis.

GetAnalytics

Retorna as análises pré-computadas de Controle vs. Tratamento para um grupo de controle.

Nota

Uma tarefa noturna calcula as análises de todos os grupos ativados, com nome ou sem. Um grupo medido sobre um segment ainda não tem análises.

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

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
windowDays	string	Não	Predefinição da janela de lookback: WINDOW_DAYS_3, WINDOW_DAYS_7 ou WINDOW_DAYS_30.

Resposta

Campo	Tipo	Descrição
events	array de objetos	Uma entrada por evento rastreado, cada uma com event, treatment e control (users, conversions, conversion_rate, events_per_user), uplift_pct, incremental_events, percent_of_treatment, z_score, p_value, confidence_pct e significance (SIGNIFICANCE_NOT_ENOUGH_DATA, SIGNIFICANCE_NOT_SIGNIFICANT ou SIGNIFICANCE_SIGNIFICANT).

ListControlGroupCycles

Lista os ciclos encerrados de um grupo de controle, do mais recente ao mais antigo. Cada ciclo é a participação com a qual o grupo funcionou entre duas alterações de configurações, junto com as configurações a partir das quais foi desenhado. O ciclo em execução (atual) não está nesta lista. Suas configurações estão no próprio Objeto de grupo de controle.

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

Resposta

Campo	Tipo	Descrição
cycles	array de Objetos de ciclo de grupo de controle	Do mais recente ao mais antigo.

Objeto de ciclo de grupo de controle

Campo	Tipo	Descrição
cycle_number	integer	Sequencial dentro do grupo; o cycle_number do próprio grupo é o seguinte ao último encerrado aqui.
mode	string	Modo de duração em que o grupo funcionou durante este ciclo: CONTROL_GROUP_MODE_PERMANENT, CONTROL_GROUP_MODE_AUTO_REFRESH ou CONTROL_GROUP_MODE_EXPERIMENT.
generation	integer	A geração do grupo durante este ciclo.
percentage	integer	Tamanho da retenção durante este ciclo.
countries	array de strings	Escopo de países durante este ciclo; vazio significa todos os países.
started_at / ended_at	string (RFC 3339)	Quando este ciclo foi executado.
close_reason	string	Por que o ciclo terminou: CONTROL_GROUP_CYCLE_CLOSE_REASON_ROLLOVER, _EXPIRED, _RESHUFFLED, _RESIZED, _RESCOPED, _MODE_CHANGED ou _DISABLED.
scope_tag	string	Tag à qual a retenção do ciclo foi restrita, combinada com countries por AND. Vazio quando não há escopo de tag e em todo ciclo encerrado antes de o escopo de tag existir, mesmo que o grupo tenha passado a ter um depois.
scope_values	array de strings	Valores de scope_tag que colocam um usuário no escopo durante este ciclo; definido apenas junto com scope_tag.

CheckControlGroupMembership

Informa para cada ID de usuário se ele está retido por um grupo de controle no momento. A participação é calculada apenas a partir do ID. Nenhum registro de usuário é lido, então um ID que o aplicativo nunca viu também é respondido, e um grupo desativado responde false para cada ID em vez de um erro. Um grupo com escopo de país ou de tag retém um usuário apenas se um de seus dispositivos estiver nesse escopo, então um ID não visto (sem nenhum dispositivo) retorna false ali, mesmo que o mesmo ID retornasse true em um grupo sem escopo. Use isso em vez de exportar o grupo inteiro para verificar os usuários de um envio ou importação específicos.

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

Corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
userIds	array de strings	Sim	IDs de usuário para verificar, no máximo 1.000 por chamada.

Exemplo de solicitação

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

Resposta

Campo	Tipo	Descrição
users	array de objetos	Uma entrada por ID solicitado, na ordem em que foram fornecidos (duplicatas incluídas). Cada um tem user_id (string) e in_control_group (boolean).

Exemplo de resposta

{
  "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 }
  ]
}

Excluir

Remove um grupo de controle completamente. Ele deixa de reter usuários, e suas estatísticas não podem mais ser abertas. Os outros grupos do aplicativo continuam funcionando.

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

Cuidado

Isso não pode ser desfeito. Para parar de reter usuários, mantendo o grupo, sua geração e seu histórico, desative-o em vez disso.

Resposta

Um objeto vazio em caso de sucesso: {}.

Objeto de grupo de controle

Campo	Tipo	Descrição
code	string	Código do grupo de controle (formato XXXXX-XXXXX), estável durante a vida do grupo.
name	string	Nome do grupo, parte da chave de participação. Vazio é o grupo original do aplicativo, sem nome.
display_name	string	Nome exibido pelo Control Panel. Vazio exibe name, e o grupo sem nome é exibido como Global.
segment	string	Expressão Seglang sobre a qual o grupo é medido; vazio é a base inteira.
percentage	integer	Tamanho da retenção como uma porcentagem, 1–20. Zero significa que o grupo está desativado.
enabled	boolean	Se o grupo está atualmente retendo usuários.
generation	integer	Incrementado a cada reembaralhamento; 0 significa nunca reembaralhado.
last_modified_at	string (RFC 3339)	Quando as configurações do grupo foram alteradas pela última vez.
last_modified_by	string	E-mail do usuário que alterou o grupo pela última vez.
application_id	integer	ID numérico do aplicativo, a primeira parte da chave de participação <application_id>:<generation>:<name>:<user_id> que CheckControlGroupMembership usa para decidir se um usuário é retido.
countries	array de strings	Códigos de país ISO-3166-1 alfa-2 em minúsculas aos quais a retenção está restrita. Vazio significa todos os países.
scope_tag	string	Tag à qual a retenção é restrita, combinada com countries por AND; vazio significa sem escopo de tag. Veja Escopo de tag.
scope_values	array de strings	Valores de scope_tag que colocam um usuário no escopo; uma tag booleana usa "true" e "false".

Relacionado

Grupos de controle (guia do produto)

API de Segmentação (Filtros)