Activity Generation Configs

Visão geral

Uma Activity Generation Config (AGC) descreve como a plataforma deriva o estado do ciclo de vida de retenção de um usuário a partir de dados brutos de atividade. É uma configuração somente de ciclo de vida: metadados base, uma audiência opcional e exatamente três pilares de ciclo de vida obrigatórios.

Toda AGC pertence a um projeto: os endpoints trabalham sobre as AGCs do projeto ativo, e uma AGC de outro projeto responde 404 como se não existisse. Seu nome é único dentro do projeto.

Os três pilares são 1:1 com a AGC: toda AGC sempre tem exatamente um activationConfig, um engagementConfig e um resurrectionConfig. Você não pode criar uma AGC com um pilar faltando, nem criar um pilar que não esteja associado a uma AGC.

Status

Toda AGC tem um status:

O status só muda por meio de duas ações, ambas com a permissão activity-generation-config:update:

• Publicar — draft ou paused → active.
• Pausar — active → paused.

status não é aceito em nenhum corpo de criação ou de atualização. Apenas as configurações active estão pensadas para rodar: liste-as com GET /api/activity-generation-configs?status=active.

Audiência efetiva

audienceId é a audiência própria da AGC, e é opcional. As leituras — GET /:id e a lista — retornam também effectiveAudienceId, a audiência sobre a qual a AGC roda:

• audienceId, quando a AGC tem audiência própria;
• caso contrário, a audiência raiz do projeto (veja Projetos → Audiência raiz).

effectiveAudienceId nunca é null. É calculado ao ler a AGC: não é armazenado e não é enviado em nenhum corpo.

Config hashes

GET /:id retorna um objeto configHashes — um hash determinístico por pilar (16 caracteres hexadecimais) para cada um dos três pilares:

{
  "activation": "9f1c2a3b4d5e6f70",
  "engagement": "a1b2c3d4e5f60718",
  "resurrection": "0f1e2d3c4b5a6978"
}

Os clientes usam esses hashes para detectar de forma econômica quando a configuração de um pilar mudou, sem precisar comparar o payload aninhado completo. O hash é calculado apenas sobre o conteúdo semântico do pilar: campos voláteis (id, timestamps) são removidos, e as coleções filhas são hasheadas de forma independente da ordem, de modo que reordenar filhos sem alterar seus valores não muda o hash.

Autenticação

Todos os endpoints exigem um token JWT Bearer, o header x-tenant-id identificando o tenant sobre cujo esquema a requisição opera, e o header x-project-id identificando o projeto em que a requisição trabalha (veja Autenticação → Contexto de Projeto).

-H "Authorization: Bearer <token>"
-H "x-tenant-id: <tenant-id>"
-H "x-project-id: <project-id>"

Permissões

Endpoints