API de Campañas

Lista las campañas del proyecto en orden de precedencia (como máximo 100), el orden en que las lee la resolución. reserved está presente en cada campaña.

Un llamador limitado a pantallas (docs/screen-scope.md) ve todas las campañas, con editable true solo cuando toda la audiencia está dentro de su alcance (una hoja de etiqueta y la regla raíz de todas las pantallas nunca lo están; una regla all necesita un hijo contenido, una regla any todos los hijos) y el llamador puede cambiar lo que se reproduce.

Crea una campaña: cada pantalla de su audience cambia a playlist_id mientras from, until y windows se cumplen en la zona horaria de la pantalla (screenrig.schedule/v1; omita los tres para siempre), y vuelve cuando dejan de cumplirse.

Una pantalla resuelve su lista de reproducción así: primero su takeover, luego la primera campaña que se aplica en orden de precedencia (priority, la más alta primero y después la creada más recientemente), luego su programación de lista de reproducción y, por último, su lista de reproducción predeterminada. Una campaña se aplica solo a una pantalla con lista de reproducción predeterminada; una con from, until o windows necesita la zona horaria de la pantalla.

La lista de reproducción debe existir y estar aprobada (playlist_not_approved). Las pantallas cambian en un minuto; GET /api/campaigns/{id}/screens muestra la situación de cada pantalla. Una organización tiene como máximo 100 campañas en todos sus proyectos (campaign_limit_reached).

Añade campaign.created. reserved true reserva la campaña, y solo lo define una persona que puede aprobar (reserved_item para un agente, un cliente de servicio o cualquier otro), y añade campaign.reserved_changed.

Un llamador limitado a pantallas (docs/screen-scope.md) crea una campaña solo para una audiencia dentro de su alcance (hojas folder y screen_id; ni tag ni la regla de todas las pantallas), de lo contrario outside_screen_scope, y solo como persona que puede aprobar (approver_required).

Una campaña cuya audiencia alcanza una pantalla protegida es una revisión protected_change decidida por un segundo aprobador (202 pending_review) en todos los niveles de acceso. reserved true corresponde a las carpetas protegidas y paused true en una campaña nueva (un borrador) corresponde al control de cambios de la programación, y ambos forman parte del plan Enterprise; un proyecto cuyo plan no lo incluye se rechaza con feature_not_in_plan (402).

Qué cambiaría una escritura de campaña, sin realizarla. Con id, body es el cuerpo PATCH de esa campaña; sin él, es el cuerpo POST de una nueva. El cuerpo se comprueba como lo comprueba la escritura (una regla de audiencia, una ventana, una lista de reproducción no aprobada, una carpeta de pantallas que el proyecto no tiene).

La respuesta lista las pantallas que ganarían la campaña en su pila y las que la perderían (count y los primeros 500 ids de pantalla), y el calendario de programación de las pantallas de la audiencia anterior y de la nueva tal como está (before) y como quedaría (after) de from a to (por defecto: una semana desde ahora; como máximo 93 días), agrupado como lo agrupa GET /api/schedule/calendar.

Una campaña pausada no está en ninguna pila, así que publicar una gana su audiencia; una edición que mantiene la campaña en la pila de una pantalla no gana ni pierde nada y aparece en los calendarios. Acceso de lectura: no se escribe nada.

Una campaña. reserved siempre está presente; editable está presente para un llamador limitado a pantallas (véase listCampaigns).

Cambia los miembros que establece el cuerpo; null borra from, until o windows. paused true detiene la campaña en todas las pantallas y false la reanuda. Una campaña pausada es un borrador: no está en la pila de ninguna pantalla, y una escritura que la deja pausada no vuelve a resolver ninguna pantalla.

Publicarla para una prueba es este PATCH con paused false y una audiencia que es una carpeta de prueba o unas pocas pantallas; POST /api/campaigns/{id}/promote copia entonces esa audiencia a la real. Cada pantalla de la audiencia anterior y de la nueva vuelve a resolverse dentro de un minuto. Agrega campaign.updated. If-Match protege la revisión.

Cada escritura se guarda en el historial de la campaña (GET /api/campaigns/{id}/revisions). campaign.updated. If-Match protege la revisión. reserved establece o quita la marca de reservada (una campaña reservada solo la cambia, la pausa o deja de reservarla una persona que pueda aprobar: reserved_item en caso contrario); un cambio de valor agrega campaign.reserved_changed.

Un llamador limitado a pantallas (docs/screen-scope.md) cambia una campaña solo cuando su audiencia guardada y la nueva están dentro de su alcance (outside_screen_scope; de lo contrario, le es de solo lectura).

Una campaña que alcanza una pantalla protegida es una revisión protected_change decidida por un segundo aprobador (202 pending_review). reserved true en una campaña que no está reservada corresponde a las carpetas protegidas, que incluye el plan Enterprise; un proyecto cuyo plan no lo incluye se rechaza con feature_not_in_plan (402).

Pausar o reanudar una campaña, y editar o liberar una reservada, están abiertos en todos los planes.

Elimina la campaña y su historial de revisiones. Cada pantalla que la muestra vuelve a lo que mostraría sin ella dentro de un minuto. Agrega campaign.deleted. If-Match protege la revisión. Una campaña reservada solo la elimina una persona que pueda aprobar (reserved_item).

Un llamador limitado a pantallas (docs/screen-scope.md) elimina una campaña solo cuando su audiencia está dentro de su alcance (outside_screen_scope). Una campaña que alcanza una pantalla protegida es una revisión protected_change decidida por un segundo aprobador (202 pending_review).

Las revisiones de la campaña, de la más reciente a la más antigua: la campaña tal como se almacenó después de cada escritura de una persona, un agente o una importación de programación (una creación, una actualización, una promoción, una restauración), con el tipo de cambio y quién lo hizo.

El historial comienza con la revisión que tenía una campaña cuando se registró por primera vez el historial de revisiones: hasta su siguiente escritura la lista contiene solo esa revisión, con change baseline. Una campaña cuyo historial no contiene ninguna revisión con paused false es un borrador. Las revisiones se conservan mientras exista la campaña y desaparecen con ella.

Como máximo 50 por página; next_cursor mientras queden más, null en la última página.

Vuelve a hacer actual una revisión anterior copiándola hacia adelante mediante la misma escritura que PATCH: su name, playlist, audience, rule, placement, priority y paused pasan a ser una nueva revisión (change restored, restored_from la revisión copiada), comprobada como se comprueba una actualización (su lista de reproducción debe seguir existiendo y estar aprobada), y cada pantalla de la audiencia anterior y de la nueva vuelve a resolverse, salvo que la campaña estuviera pausada y siga pausada.

Las revisiones anteriores se conservan tal como estaban. If-Match es obligatorio y nombra la revisión actual (invalid_request si falta, revision_conflict si está obsoleta). Una revisión cuyo contenido es el contenido actual no cambia nada y responde con la campaña actual. El mismo acceso que PATCH.

Publica una prueba. Una publicación de prueba es un PATCH de un borrador con paused false y una audiencia que es una carpeta de prueba o unas pocas pantallas; promote copia entonces la audiencia de revision (la revisión pausada del propio borrador) a la campaña en una sola escritura (change promoted, restored_from la revisión copiada) y cada pantalla de la audiencia anterior y de la nueva vuelve a resolverse.

Se rechaza (invalid_request, nombrando revision) cuando esa revisión no estaba pausada, pues no es un borrador, y cuando la campaña está pausada ahora, pues no hay ninguna prueba que promover. If-Match es obligatorio y nombra la revisión actual. Una revisión cuya audiencia es la actual no cambia nada. El mismo acceso que PATCH.

Promover corresponde al control de cambios de la programación, que incluye el plan Enterprise; un proyecto cuyo plan no lo incluye se rechaza con feature_not_in_plan (402). El historial de revisiones, la restauración y las vistas previas están abiertos en todos los planes.

El alcance de la campaña. counts cubre todas las pantallas activas de su audience (audience, luego un conteo por estado); items es una página de esas pantallas en orden de id de pantalla con el estado de la campaña en cada una (véase CampaignStatus).

Un llamador limitado a pantallas (docs/screen-scope.md) ve y cuenta solo las pantallas de la audiencia que están dentro de su alcance; los recuentos y la paginación abarcan ese conjunto.