API Campagnes

Liste les campagnes du projet par ordre de priorité (au plus 100), l’ordre dans lequel la résolution les lit. reserved est présent sur chaque campagne.

Un appelant limité aux écrans (docs/screen-scope.md) voit chaque campagne, avec editable à true seulement quand toute l’audience est dans son périmètre (une feuille d’étiquette et la règle racine de tous les écrans ne le sont jamais ; une règle all exige un enfant contenu, une règle any chaque enfant) et que l’appelant peut modifier ce qui est diffusé.

Crée une campagne : chaque écran de son audience passe à playlist_id tant que from, until et windows sont valides dans le fuseau horaire de l’écran (screenrig.schedule/v1 ; omettez les trois pour toujours), et revient en arrière quand ils ne le sont plus.

Un écran détermine sa liste de lecture ainsi : sa prise de contrôle, puis la première campagne qui s’applique dans l’ordre de priorité (priority, la plus élevée d’abord, puis la plus récemment créée), puis son horaire de liste de lecture, puis sa liste de lecture par défaut. Une campagne ne s’applique qu’à un écran ayant une liste de lecture par défaut ; celle qui a from, until ou windows exige le fuseau horaire de l’écran.

La liste de lecture doit exister et être approuvée (playlist_not_approved). Les écrans changent en une minute ; GET /api/campaigns/{id}/screens montre la situation de chaque écran. Une organisation a au plus 100 campagnes, tous projets confondus (campaign_limit_reached).

Ajoute campaign.created. reserved à true réserve la campagne, et seule une personne qui peut approuver le définit (reserved_item pour un agent, un client de service ou toute autre personne), ce qui ajoute campaign.reserved_changed.

Un appelant limité aux écrans (docs/screen-scope.md) ne crée une campagne que pour une audience dans son périmètre (feuilles folder et screen_id ; ni étiquette, ni tous les écrans), sinon outside_screen_scope, et seulement en tant que personne qui peut approuver (approver_required).

Une campagne dont l’audience atteint un écran protégé est une révision protected_change décidée par un second approbateur (202 pending_review) à tous les niveaux d’accès. reserved true relève des dossiers protégés et paused true sur une nouvelle campagne (un brouillon) relève du contrôle des changements d’horaire, les deux faisant partie du forfait Enterprise ; un projet dont le forfait n’inclut pas cette fonctionnalité est refusé avec feature_not_in_plan (402).

Ce qu’une écriture de campagne changerait, sans l’effectuer. Avec id, body est le corps PATCH de cette campagne ; sans, c’est le corps POST d’une nouvelle. Le corps est vérifié comme l’écriture le vérifie (une règle d’audience, une fenêtre, une liste de lecture non approuvée, un dossier d’écrans que le projet n’a pas).

La réponse liste les écrans qui gagneraient la campagne sur leur pile et ceux qui la perdraient (count, et les 500 premiers identifiants d’écran), et le calendrier d’horaire des écrans de l’ancienne et de la nouvelle audience tel qu’il est (before) et tel qu’il serait (after) de from à to (par défaut : une semaine à partir de maintenant ; au plus 93 jours), regroupé comme GET /api/schedule/calendar regroupe.

Une campagne en pause n’est sur aucune pile, donc en publier une gagne son audience ; une modification qui garde la campagne sur la pile d’un écran ne gagne ni ne perd rien et apparaît dans les calendriers. Accès Lecture seule : rien n’est écrit.

Une campagne. reserved est toujours présent ; editable est présent pour un appelant limité aux écrans (voir listCampaigns).

Modifie les membres que le corps définit ; null efface from, until ou windows. paused true arrête la campagne sur tous les écrans et false la reprend. Une campagne en pause est un brouillon : elle n’est sur la pile d’aucun écran, et une écriture qui la laisse en pause ne réévalue aucun écran.

Le publier pour un test est ce PATCH avec paused false et une audience qui est un dossier de test ou quelques écrans ; POST /api/campaigns/{id}/promote copie ensuite cette audience sur la vraie. Chaque écran de l’ancienne et de la nouvelle audience résout à nouveau dans la minute. Ajoute campaign.updated. If-Match protège la révision.

Chaque écriture est stockée dans l’historique de la campagne (GET /api/campaigns/{id}/revisions). campaign.updated. If-Match protège la révision. reserved définit ou efface l’indicateur de réservation (une campagne réservée n’est modifiée, mise en pause ou dont la réservation est levée que par une personne qui peut approuver : sinon reserved_item) ; un basculement ajoute campaign.reserved_changed.

Un appelant limité aux écrans (docs/screen-scope.md) ne modifie une campagne que si son audience enregistrée et sa nouvelle audience se trouvent dans son périmètre (outside_screen_scope ; sinon elle est en lecture seule pour lui).

Une campagne qui atteint un écran protégé est une révision protected_change décidée par un second approbateur (202 pending_review). reserved true sur une campagne qui n’est pas réservée relève des dossiers protégés, que le forfait Enterprise inclut ; un projet dont le forfait n’inclut pas cette fonctionnalité est refusé avec feature_not_in_plan (402).

La mise en pause ou la reprise d’une campagne, ainsi que la modification ou la libération d’une campagne réservée, sont ouvertes à tous les forfaits.

Supprime la campagne et son historique de révisions. Chaque écran qui l’affiche revient à ce qu’il afficherait sans elle dans la minute. Ajoute campaign.deleted. If-Match protège la révision. Une campagne réservée n’est supprimée que par une personne qui peut approuver (reserved_item).

Un appelant limité aux écrans (docs/screen-scope.md) ne supprime une campagne que si son audience se trouve dans son périmètre (outside_screen_scope). Une campagne qui atteint un écran protégé est une révision protected_change décidée par un second approbateur (202 pending_review).

Les révisions de la campagne, de la plus récente à la plus ancienne : la campagne telle que stockée après chaque écriture par une personne, un agent ou une importation d’horaires (une création, une mise à jour, une promotion, une restauration), avec le type de changement et son auteur.

L’historique commence par la révision qu’une campagne détenait lorsque l’historique des révisions a été enregistré pour la première fois : jusqu’à sa prochaine écriture, la liste contient cette seule révision, avec change baseline. Une campagne dont l’historique ne contient aucune révision avec paused false est un brouillon. Les révisions sont conservées aussi longtemps que la campagne et disparaissent avec elle.

Au plus 50 par page ; next_cursor tant qu’il en reste, null sur la dernière page.

Remet une révision antérieure comme révision actuelle en la copiant vers l’avant par la même écriture que PATCH : ses champs name, playlist, audience, rule, placement, priority et paused deviennent une nouvelle révision (change restored, restored_from la révision copiée), vérifiée comme l’est une mise à jour (sa liste de lecture doit encore exister et être approuvée), et chaque écran de l’ancienne et de la nouvelle audience est réévalué, sauf si la campagne était en pause et le reste.

Les révisions antérieures restent telles qu’elles étaient. If-Match est obligatoire et nomme la révision actuelle (invalid_request en son absence, revision_conflict si obsolète). Une révision dont le contenu est le contenu actuel ne change rien et répond avec la campagne actuelle. Le même accès que PATCH.

Publie un test. Une publication de test est un PATCH d’un brouillon avec paused false et une audience qui est un dossier de test ou quelques écrans ; promote copie alors l’audience de revision (la révision du brouillon lui-même, en pause) sur la campagne en une seule écriture (change promoted, restored_from la révision copiée) et chaque écran de l’ancienne et de la nouvelle audience est réévalué.

Refusé (invalid_request, nommant revision) lorsque cette révision n’était pas en pause, puisqu’elle n’est pas un brouillon, et lorsque la campagne est en pause maintenant, puisqu’il n’y a aucun test à promouvoir. If-Match est obligatoire et nomme la révision actuelle. Une révision dont l’audience est l’audience actuelle ne change rien. Le même accès que PATCH.

La promotion relève du contrôle des changements d’horaire, que le forfait Enterprise inclut ; un projet dont le forfait n’inclut pas cette fonctionnalité est refusé avec feature_not_in_plan (402). L’historique des révisions, la restauration et les aperçus sont ouverts à tous les forfaits.

La portée de la campagne. counts couvre chaque écran actif de son audience (audience, puis un compte par statut) ; items est une page de ces écrans dans l’ordre des identifiants d’écran avec la situation de la campagne sur chacun (voir CampaignStatus).

Un appelant limité aux écrans (docs/screen-scope.md) ne voit et ne compte que les écrans de l’audience qui sont dans son périmètre ; les totaux et la pagination portent sur cet ensemble.