API de Campanhas

Lista as campanhas do projeto em ordem de precedência (no máximo 100), a ordem em que a resolução as lê. reserved está presente em toda campanha.

Um chamador limitado a telas (docs/screen-scope.md) vê todas as campanhas, com editable true somente quando todo o público está dentro do seu escopo (uma folha de tag e a regra de todas as telas na raiz nunca estão; uma regra all precisa de um filho contido, uma regra any de todos os filhos) e o chamador pode alterar o que é reproduzido.

Cria uma campanha: toda tela em seu audience muda para playlist_id enquanto from, until e windows valem no fuso horário da tela (screenrig.schedule/v1; omita os três para sempre) e volta quando deixam de valer.

Uma tela resolve sua playlist assim: primeiro o takeover, depois a primeira campanha aplicável na ordem de precedência (priority, maior primeiro, depois a criada mais recentemente), depois a programação de playlist e, por fim, a playlist padrão. Uma campanha se aplica apenas a uma tela com playlist padrão; uma campanha com from, until ou windows exige o fuso horário da tela.

A playlist deve existir e estar aprovada (playlist_not_approved). As telas mudam em até um minuto; GET /api/campaigns/{id}/screens mostra a situação de cada tela. Uma organização tem no máximo 100 campanhas em todos os seus projetos (campaign_limit_reached).

Acrescenta campaign.created. reserved true reserva a campanha, e somente uma pessoa que pode aprovar o define (reserved_item para um agente, um cliente de serviço ou qualquer outro), acrescentando campaign.reserved_changed.

Um chamador limitado a telas (docs/screen-scope.md) só cria uma campanha para um público dentro do seu escopo (folhas folder e screen_id; nenhuma tag, nem todas as telas), caso contrário outside_screen_scope, e somente como uma pessoa que pode aprovar (approver_required).

Uma campanha cujo público alcança uma tela protegida é uma revisão protected_change decidida por um segundo aprovador (202 pending_review) em todo nível de acesso. reserved true é o recurso de pastas protegidas e paused true em uma nova campanha (um rascunho) é o recurso de controle de alterações da programação, e ambos fazem parte do plano Enterprise; um projeto cujo plano não o inclui é recusado com feature_not_in_plan (402).

O que uma gravação de campanha alteraria, sem realizá-la. Com id, body é o corpo PATCH dessa campanha; sem, é o corpo POST de uma nova. O corpo é verificado como a gravação o verifica (uma regra de público-alvo, uma janela, uma playlist não aprovada, uma pasta de telas que o projeto não tem).

A resposta lista as telas que ganhariam a campanha em sua pilha e as que a perderiam (count e os primeiros 500 ids de tela), e o calendário de programação das telas do público-alvo antigo e do novo como está (before) e como ficaria (after) de from a to (padrão: uma semana a partir de agora; no máximo 93 dias), agrupado como GET /api/schedule/calendar agrupa.

Uma campanha pausada não está em nenhuma pilha, então publicá-la ganha seu público-alvo; uma edição que mantém a campanha na pilha de uma tela não ganha nem perde nada e aparece nos calendários. Acesso de leitura: nada é gravado.

Uma campanha. reserved está sempre presente; editable está presente para um chamador limitado a telas (veja listCampaigns).

Altera os membros que o corpo define; null limpa from, until ou windows. paused true interrompe a campanha em todas as telas e false a retoma. Uma campanha pausada é um rascunho: não está na pilha de nenhuma tela, e uma gravação que a deixa pausada não resolve novamente nenhuma tela.

Publicá-la para um teste é este PATCH com paused false e um público-alvo que é uma pasta de teste ou algumas telas; POST /api/campaigns/{id}/promote então copia esse público-alvo para o real. Toda tela do público-alvo antigo e do novo resolve novamente em até um minuto. Acrescenta campaign.updated. If-Match protege a revisão.

Cada gravação é armazenada no histórico da campanha (GET /api/campaigns/{id}/revisions). campaign.updated. If-Match protege a revisão. reserved define ou limpa o sinalizador reserved (uma campanha reservada só é alterada, pausada ou desreservada por uma pessoa que pode aprovar; caso contrário, reserved_item); uma inversão acrescenta campaign.reserved_changed.

Um chamador limitado a telas (docs/screen-scope.md) só altera uma campanha quando o público armazenado e o novo estão dentro do seu escopo (outside_screen_scope; caso contrário ela é somente leitura para ele).

Uma campanha que alcança uma tela protegida é uma revisão protected_change decidida por um segundo aprovador (202 pending_review). reserved true em uma campanha que não é reservada é o recurso de pastas protegidas, que o plano Enterprise inclui; um projeto cujo plano não o inclui é recusado com feature_not_in_plan (402).

Pausar ou retomar uma campanha, e editar ou liberar a reserva de uma campanha reservada, estão disponíveis em todos os planos.

Exclui a campanha e seu histórico de revisões. Toda tela que a exibe volta ao que exibiria sem ela em até um minuto. Acrescenta campaign.deleted. If-Match protege a revisão. Uma campanha reservada só é excluída por uma pessoa que pode aprovar (reserved_item).

Um chamador limitado a telas (docs/screen-scope.md) só exclui uma campanha quando o público dela está dentro do seu escopo (outside_screen_scope). Uma campanha que alcança uma tela protegida é uma revisão protected_change decidida por um segundo aprovador (202 pending_review).

As revisões da campanha, da mais recente para a mais antiga: a campanha como armazenada após cada gravação feita por uma pessoa, um agente ou uma importação de programação (uma criação, uma atualização, uma promoção, uma restauração), com o tipo de alteração e quem a fez.

O histórico começa com a revisão que uma campanha tinha quando o histórico de revisões foi gravado pela primeira vez: até sua próxima gravação, a lista contém apenas essa revisão, com change baseline. Uma campanha cujo histórico não tem nenhuma revisão com paused false é um rascunho. As revisões são mantidas enquanto a campanha existir e saem junto com ela.

No máximo 50 por página; next_cursor enquanto restarem mais, null na última página.

Torna uma revisão anterior atual novamente copiando-a adiante pela mesma gravação de PATCH: seu name, playlist, audience, rule, placement, priority e paused viram uma nova revisão (change restored, restored_from a revisão copiada), verificada como uma atualização (sua playlist ainda deve existir e estar aprovada), e toda tela do público-alvo antigo e do novo resolve novamente, a menos que a campanha estivesse pausada e continue pausada.

As revisões anteriores permanecem como estavam. If-Match é obrigatório e indica a revisão atual (invalid_request quando ausente, revision_conflict quando obsoleta). Uma revisão cujo conteúdo é o conteúdo atual não altera nada e responde com a campanha atual. O mesmo acesso de PATCH.

Publica um teste. Uma publicação de teste é um PATCH de um rascunho com paused false e um público-alvo que é uma pasta de teste ou algumas telas; promote então copia o público-alvo de revision (a revisão pausada do próprio rascunho) para a campanha em uma única gravação (change promoted, restored_from a revisão copiada) e toda tela do público-alvo antigo e do novo resolve novamente.

Recusada (invalid_request, nomeando revision) quando essa revisão não estava pausada, pois não é um rascunho, e quando a campanha está pausada agora, pois não há teste para promover. If-Match é obrigatório e indica a revisão atual. Uma revisão cujo público-alvo é o atual não altera nada. O mesmo acesso de PATCH.

Promover é o recurso de controle de alterações da programação, que o plano Enterprise inclui; um projeto cujo plano não o inclui é recusado com feature_not_in_plan (402). O histórico de revisões, a restauração e as prévias estão disponíveis em todos os planos.

O alcance da campanha. counts cobre toda tela ativa em seu audience (audience, depois uma contagem por status); items é uma página dessas telas em ordem de id de tela, com a situação da campanha em cada uma (veja CampaignStatus).

Um chamador limitado a telas (docs/screen-scope.md) vê e conta apenas as telas do público que estão dentro do seu escopo; as contagens e a paginação cobrem esse conjunto.