API Révisions

Les révisions du projet (docs/reviews.md) : les modifications de listes de lecture et d’écrans proposées sous l’accès Proposer, les écritures de campagne, de dossier d’écrans et de déplacement qui atteignent un écran protégé (kind protected_change, docs/screen-scope.md), et, pour un réseau publicitaire, les créatifs que les acheteurs ont soumis (kind ad_creative).

Les plus récents d’abord, au maximum limit (par défaut 50, au maximum 100) par page ; renvoyer next_cursor comme curseur avec les mêmes filtres. state pending (par défaut), decided (tout autre état) ou all ; kind restreint à un type.

Une session du tableau de bord lit tous les types ; un porteur lit les types que couvrent ses capacités (listes de lecture pour playlist_change, écrans pour screen_change et protected_change, publicité pour ad_creative), et un type qu’il ne peut pas lire donne une page vide. pending_count compte les révisions en attente de chaque type que voit l’appelant.

Un appelant limité aux écrans ne voit que les révisions screen_change et protected_change dont toute la portée est dans son périmètre (une révision qui sélectionne des écrans par étiquette ne l’est jamais) et les révisions playlist_change ; les révisions ad_creative lui sont masquées, et pending_count compte ce qu’il voit.

Une révision. Une modification de liste de lecture ajoute preview : la liste de lecture active et la liste proposée dans la forme stockée (pages avec resolved_media) ; live est null pour une création. Un porteur qui ne peut pas lire le type de la révision (voir listReviews) obtient not_found, tout comme un appelant limité aux écrans pour une révision dont la portée n’est pas dans son périmètre.

Le projet auquel appartient une révision, pour le lien courriel : une personne connectée qui est membre de ce projet obtient son id et son nom et y bascule (PUT /api/session/project) avant de lire la révision. Toute autre personne obtient not_found. Fonctionne quel que soit le projet sélectionné par la session.

Approuve une révision en attente en tant que personne pouvant approuver (propriétaire du projet ou membre avec can_approve ; sinon approver_required). Le drapeau est relu dans la transaction de décision, donc une personne dont l’approbation a été désactivée entre-temps ne décide rien (approver_required). Les sessions d’ombre du personnel ne peuvent pas décider.

Une mise à jour de liste de lecture s’applique avec la révision de base comme If-Match ; quand la liste de lecture active avance, la révision devient obsolète et l’appel répond review_stale.

Une création ou mise à jour dont l’étiquette, le dossier ou tous les sélecteurs joueraient maintenant des médias qu’ils ne résolvaient pas lors de la proposition, que la révision ne nomme pas et que la version en direct ne joue pas déjà, devient aussi obsolète (review_stale).

Un changement d’écran rejoue sa requête stockée (une étiquette se résout maintenant) : l’appel applique les écrans pendant quelques secondes et le reste continue en arrière-plan pendant que screen_change.result.applying est vrai.

Un changement d’écran en attente d’une revue de liste de lecture répond review_blocked en la nommant ; un dont la liste de lecture n’a pas de version approuvée répond playlist_not_approved. include_dependents approuve aussi, dans l’ordre, les changements d’écran en attente de cette revue de liste de lecture. Les événements du changement appliqué portent la personne comme acteur et l’agent proposant comme agent.

La réponse porte des avertissements (PlaylistWarning) : screen_fact_missing lorsque le changement approuvé place sur des écrans qui n’ont pas la valeur des pages dont le src d’iframe ou les params d’application lisent un jeton d’écran. Une revue décidée donne review_not_pending ; répéter la même décision rejoue la réponse.

Une révision marquée protégée (un protected_change, ou un screen_change qui a atteint un écran protégé) est décidée par un approbateur autre que le proposeur et que la personne responsable de l’agent proposeur : sinon second_approver_required (403), de même quand le proposeur ne peut pas être rattaché à une personne (docs/screen-scope.md).

Un approbateur limité aux écrans ne décide que d’une révision dont toute la portée est dans le périmètre (outside_screen_scope, 403). Un protected_change est appliqué par cette requête, au nom de la personne qui approuve, à la révision sur laquelle il a été proposé ; une campagne ou un dossier qui a changé ou disparu depuis, ou des écrans qui ont été déplacés, rendent la révision périmée (review_stale, 409).

Une dépendance qui ne peut pas être approuvée signale les mêmes codes dans dependents[].problem.

Rejette une révision en attente avec une raison que le proposeur lit. Approbateur seulement, comme approveReview ; un approbateur limité aux écrans ne décide que d’une révision dans son périmètre (outside_screen_scope), et aucune personne limitée aux écrans ne décide d’un créatif publicitaire. Rien ne change à l’écran ; une création de liste de lecture rejetée reste non approuvée.

Demande des modifications au proposeur avec une note qu’il lit ; le proposeur propose de nouveau. Approbateur seulement, comme approveReview. Pour un créatif publicitaire, l’acheteur lit la note sur le créatif. Un approbateur à périmètre est limité comme dans rejectReview.

Retire une révision en attente de liste de lecture, d’écran ou protected_change. Un porteur ne retire que ce que son propre agent ou client de service a proposé (sinon forbidden) ; une personne retire en tant qu’approbateur ou en tant que personne responsable du proposeur ; une personne limitée aux écrans ne retire qu’une révision dans son périmètre (outside_screen_scope).

Une création de liste de lecture retirée reste non approuvée.