Pubblicità: comandi CLI

Acquirente: elenca le reti a cui questo progetto è stato invitato e ispeziona l’inventario e gli slot consentiti di una rete.

ads networks list
ads networks show <seller-project-id>

screenrig ads networks list

Venditore: ispeziona o crea la rete di questo progetto e imposta la tariffa predefinita.

ads network show
ads network create --name NAME
ads network rate --rate-mcr-per-15s MCR --expect-rev REVISION

screenrig ads network rate --rate-mcr-per-15s 1000 --expect-rev 3

--name ha al massimo 120 caratteri. --rate-mcr-per-15s è un numero intero positivo di mcr per 15 secondi di riproduzione completata, e --expect-rev è la revision della rete letta da ads network show. Un cambio della tariffa effettiva mette in pausa le campagne interessate finché ogni acquirente non accetta un preventivo aggiornato.

Venditore: includi o escludi uno schermo di proprietà dalla pubblicità e descrivilo agli acquirenti invitati.

ads inventory list
ads inventory update <screen-id> [--enabled | --disabled] [--site-name NAME]
    [--city CITY] [--region REGION] [--venue-type TYPE] [--audience-tags TOKENS]
    [--placement TEXT] [--public-description TEXT]
    [--rate-mcr-per-15s MCR | --clear-rate]
    [--impressions-per-hour N | --clear-impressions-per-hour] [--expect-rev REVISION]

screenrig ads inventory update scr_LOBBY --enabled --venue-type cafe

I flag omessi mantengono i valori correnti. Una nuova riga inventario necessita --enabled o --disabled. --impressions-per-hour registra la tua stima delle impression che lo schermo genera in un’ora: ogni riproduzione completata conta quindi quella stima per i secondi riprodotti diviso 3600 come estimated_impressions in ads reports spend, ads reports delivery e ads direct report.

update richiede almeno un flag. --audience-tags accetta fino a 20 tag separati da virgole, ciascuno di al massimo 32 lettere, cifre o trattini bassi. --clear-rate riporta lo schermo alla tariffa predefinita del progetto e --clear-impressions-per-hour rimuove la stima. --expect-rev sostituisce la revisione memorizzata della riga come precondizione e viene rifiutato per uno schermo che non ha ancora una riga.

Venditore: definisci slot pubblicitari riutilizzabili. Uno slot non cambia nulla sullo schermo finché la sua pagina adslot non viene inserita in una playlist.

ads slots list
ads slots create --name NAME --accepted-media image,video
    [--max-image-duration-ms MS] [--max-video-duration-ms MS]
    [--rate-mcr-per-15s MCR | --clear-rate] [--enabled | --disabled] [--vast-tag-url URL]
ads slots update <slot-id> --expect-rev REVISION [--name NAME]
    [--accepted-media image,video] [--max-image-duration-ms MS] [--max-video-duration-ms MS]
    [--rate-mcr-per-15s MCR | --clear-rate] [--enabled | --disabled]
    [--vast-tag-url URL | --clear-vast-tag-url]

screenrig ads slots create --name "Lobby break" --accepted-media image,video
screenrig ads slots create --name "Lobby video" --accepted-media video --vast-tag-url https://ads.example.com/vast.xml
screenrig ads slots update ads_LOBBY --clear-vast-tag-url --expect-rev 2

Un nuovo slot è abilitato a meno che sia indicato --disabled. --accepted-media è image, video o entrambi, separati da virgole. I limiti di durata omessi sono 30000 ms; il limite di un’immagine va da 5000 a 30000 ms e quello di un video da 5000 a 120000 ms. --rate-mcr-per-15s è un numero intero positivo che sostituisce la tariffa dello schermo o del progetto per questo slot, e --clear-rate rimuove la sostituzione. update mantiene ogni campo omesso, e un cambio della tariffa effettiva mette in pausa le campagne interessate finché ogni acquirente non accetta un preventivo aggiornato. --vast-tag-url è un URL HTTPS di al massimo 2048 caratteri.

--vast-tag-url imposta il proprio tag pubblicitario VAST 2-4 del venditore, provato quando nessuna campagna invitata riempie lo slot sugli schermi propri; lo slot deve accettare video. L’URL è HTTPS sulla porta 443 o 8443 verso un host pubblico. Il backend lo recupera, segue fino a cinque Wrapper, acquisisce l’MP4 o WebM progressivo scelto nei contenuti del progetto, e attiva Impression, creativeView e start all’inizio accettato, complete alla fine accettata, e Error in caso di errore; non ci sono tracker quartili. Le macro [CACHEBUSTING], [TIMESTAMP], [SCREENRIG_SCREEN_ID], [SCREENRIG_SLOT_ID] e [SCREENRIG_PAGE_ID] sono espanse, e gli acquirenti non vedono mai il tag. Su update, --vast-tag-url sostituisce il tag e --clear-vast-tag-url lo rimuove; i due non si combinano, e omettere entrambi mantiene il tag memorizzato. ads slots list mostra vast_tag_url al venditore proprietario. Uno slot che nulla può riempire su uno schermo (nessun tag VAST e, su uno schermo che aderisce alla pubblicità, nessuna campagna diretta non ancora terminata e nessuna campagna invitata attiva, in attesa o in pausa che lo nomini) viene escluso dal manifest di quello schermo, e screen show lo elenca in ad_quiet_slots, così il Player smette di richiederlo. Una campagna, un tag o un’adesione che potrebbe riempirlo lo riporta.

Usa i comandi condivisi invitations sopra:

screenrig invitations create --kind ad-buyer --email owner@bakery.example --screen-id scr_LOBBY --policy review_required
screenrig invitations list --kind ad-buyer
screenrig invitations revoke ID

Un invito per acquirenti pubblicitari avviene via email, mai tramite link, e richiede almeno un --screen-id o un --slot-id (separati da virgole). --policy è trusted (predefinito) o review_required.

La persona invitata accetta nel dashboard. Una persona con accesso seleziona il progetto di acquisto e conferma con una nuova prova passkey. Una persona senza login ne crea uno e un progetto solo per inserzionisti durante l’accettazione.

Venditore: modifica o revoca la politica di revisione e l’ambito dell’inventario di un acquirente ammesso.

ads memberships list
ads memberships update <membership-id> --expect-rev REVISION
    [--policy trusted|review_required] [--screen-id IDS] [--slot-id IDS]
ads memberships revoke <membership-id>

screenrig ads memberships list

update mantiene la policy e l’ambito memorizzati per i flag omessi. trusted riproduce le creatività dell’acquirente senza revisione; review_required trattiene ogni versione della creatività per la tua decisione. --screen-id e --slot-id accettano id separati da virgole e sostituiscono l’intero elenco; un valore vuoto non consente nulla.

La revoca interrompe nuove riproduzioni pubblicitarie e mantiene la storia finanziaria.

Acquirente: associa media pronti di proprietà a una creatività immutabile con copia approvata.

ads creatives list
ads creatives create --media-id ID --copy TEXT
ads creatives show <creative-id>

screenrig ads creatives create --media-id med_123 --copy "Fresh bread daily"

Associare una creatività non costa nulla e non ricarica il media. Una creatività approvata non cambia mai sul posto: modifica il media di origine e associa una nuova creatività. --copy ha al massimo 500 caratteri. show elenca la revisione della creatività da parte di ogni rete venditore (pending, approved, rejected o changes_requested) con il motivo del venditore.

Acquirente: crea una campagna, definisci il prezzo e attivala accettando il preventivo.

ads campaigns list
ads campaigns show <campaign-id>
ads campaigns create <file>
ads campaigns update <campaign-id> <file> --expect-rev REVISION
ads campaigns preview <campaign-id> [--expect-rev REVISION]
ads campaigns activate <campaign-id> --quote-id ID --expect-rev REVISION
ads campaigns pause <campaign-id> --expect-rev REVISION
ads campaigns resume <campaign-id> --expect-rev REVISION
ads campaigns accept-rates <campaign-id> --quote-id ID --expect-rev REVISION

screenrig ads campaigns preview cmp_123

Una bozza non riserva nulla. preview restituisce un preventivo a tempo limitato e non spende nulla; activate richiede quel preventivo esatto. Dopo un cambio di tariffa venditore, solo accept-rates con un preventivo aggiornato riprende la campagna.

<file> è un file JSON, oppure - per lo standard input, e update sostituisce una bozza con l’intero documento. La bozza indica name, daily_cap_mcr, lifetime_cap_mcr (almeno il limite giornaliero), flight_start e flight_end (RFC 3339) e networks, una voce per ogni rete venditore a cui il progetto ha aderito, ciascuna con seller_project_id, screen_ids, slot_ids, creative_ids e, facoltativamente, venue_types, cities, tags, dayparts e network_cap_mcr. I campi monetari sono stringhe mcr decimali, mai numeri. image_duration_ms (da 5000 a 30000, dieci secondi se omesso) imposta per quanto tempo viene mostrata un’immagine, e max_play_price_mcr limita il prezzo di una riproduzione; omettilo per non avere alcun tetto.

Una bozza di campagna accetta una category facoltativa dall'elenco delle categorie di inserzionisti. Due annunci della stessa categoria non vanno mai in onda nella stessa interruzione pubblicitaria su uno schermo.

preview legge la revisione corrente della campagna, a meno che --expect-rev ne indichi una. pause interrompe le nuove prenotazioni; le riproduzioni già avviate terminano e vengono regolate al prezzo prenotato. resume riprende una campagna messa in pausa manualmente e non può rimuovere una pausa dovuta a un cambio di prezzo.

Venditore: prenota i tuoi accordi con inserzionisti esterni a screenRIG sui tuoi schermi.

ads direct list
ads direct show <campaign-id>
ads direct create <file>
ads direct update <campaign-id> <file> --expect-rev REVISION
ads direct pause <campaign-id> --expect-rev REVISION
ads direct resume <campaign-id> --expect-rev REVISION
ads direct end <campaign-id> --expect-rev REVISION
ads direct availability <file>
ads direct report <campaign-id> [--from TIME] [--to TIME]
    [--format json|csv|xlsx|pdf] [--output FILE|-]

screenrig ads direct create campaign.json

Una bozza indica name, advertiser, una category facoltativa, flight_start e flight_end, media_ids (da 1 a 20 delle tue immagini o dei tuoi video pronti), un goal_plays facoltativo, un price facoltativo (model cpm per mille riproduzioni o flat, con un amount e una currency ISO 4217), un image_duration_ms facoltativo (da 5000 a 30000, dieci secondi se omesso) e il targeting: screen_ids, slot_ids, venue_types, cities, tags e dayparts (come {"days": ["mon"], "start": "11:00", "end": "14:00"}), dove un elenco vuoto indica ogni schermo o spazio abilitato. Una campagna diretta riempie un’interruzione pubblicitaria prima degli acquirenti invitati. Un obiettivo è distribuito uniformemente sul periodo di programmazione e va in onda per primo finché è in ritardo; una campagna senza obiettivo occupa ogni spazio idoneo durante il suo periodo. Non passa denaro tramite screenRIG: fatturi tu l’inserzionista e il prezzo dà valore al rapporto.

<file> è un file JSON, oppure - per lo standard input. category, qui e in una bozza di campagna, è uno tra alcohol, apparel, automotive, beauty, cannabis, consumer_electronics, education, entertainment, financial_services, food_and_beverage, gambling, government, grocery, health_and_pharma, home_and_garden, insurance, jobs, legal, media, political, quick_service_restaurants, real_estate, restaurants, retail, sports_and_fitness, technology, telecom, tobacco_and_vaping, travel o utilities. update sostituisce ogni campo scrivibile, quindi invia l’intero documento. pause impedisce a una campagna di occupare gli spazi pubblicitari e resume la ripristina; una campagna con obiettivo che è rimasta indietro durante la pausa va in onda per prima finché non recupera. end è definitivo: una campagna terminata non va più in onda, non può essere ripresa e conserva il suo report.

availability legge una query con lo stesso targeting e lo stesso periodo di programmazione e stima le riproduzioni che puoi ancora prenotare: le occorrenze recenti degli spazi pubblicitari degli schermi selezionati, meno le riproduzioni di cui hanno ancora bisogno gli altri tuoi obiettivi diretti. Risponde con estimated_plays, booked_plays e available_plays, e exclude_campaign_id lascia fuori da booked_plays la campagna che stai modificando. Un obiettivo superiore alla stima restituisce goal_overbooked, a meno che la bozza non imposti "overbook": true.

report elenca le riproduzioni rispetto all’obiettivo, il ritmo, il valore, le riproduzioni non andate in onda e le righe per giorno UTC, schermo, spazio e media. --from e --to accettano un istante RFC 3339, now o un’età come 7d, 12h o 30m, e per impostazione predefinita coprono il periodo di programmazione. --format csv, xlsx o pdf scrive le righe in --output (predefinito ./direct-report-CAMPAIGN_ID.FORMAT) e risponde con percorso, byte e SHA-256; con --format csv, --output - scrive invece il CSV sullo standard output. Le colonne del CSV sono day, screen_id, slot_id, media_id, plays, played_ms e estimated_impressions. Un report JSON o CSV elenca al massimo 5000 righe e riporta l’avviso direct_report_truncated quando ce ne sono altre: restringi --from e --to per ottenere il resto.

Creare, sostituire e riprendere una campagna diretta, availability e report richiedono un piano che includa le campagne dirette; gli altri piani vengono rifiutati con feature_not_in_plan. screenrig project capabilities elenca le funzionalità del piano.

Venditore: approva, rifiuta o richiedi modifiche alle versioni creative esatte inviate dagli acquirenti su review_required.

ads reviews list
ads reviews show <review-id>
ads reviews approve <review-id>
ads reviews reject <review-id> --reason TEXT
ads reviews request-changes <review-id> --note TEXT

screenrig ads reviews request-changes arv_123 --note "Use the new logo"

request-changes invia la tua nota all’acquirente. Per inviare la revisione, associa il contenuto multimediale aggiornato a una nuova creatività, aggiungila a una nuova campagna ed esegui preview e activate con il nuovo preventivo. La campagna sostitutiva ha un budget e una cronologia delle revisioni propri. Metti in pausa la campagna originale prima di attivare quella sostitutiva per evitare pubblicazioni sovrapposte. Le persone decidono sulle creatività pubblicitarie nella pagina Revisioni della dashboard, insieme alle modifiche a playlist e schermi.

list mostra le versioni della creatività in attesa della tua decisione e show un invio con la sua creatività esatta. --reason e --note sono obbligatori e di al massimo 500 caratteri; l’acquirente li legge sulla creatività (ads creatives show). Decidere richiede l’accesso Gestisci.

Leggi la spesa come acquirente o la consegna come venditore.

ads reports spend --campaign-id ID [--format json|csv|xlsx|pdf] [--output FILE]
ads reports delivery --from TIMESTAMP --to TIMESTAMP
    [--format json|csv|xlsx|pdf] [--output FILE]
ads reports fill [--from TIME] [--to TIME] [--format json|csv|xlsx|pdf] [--output FILE]

screenrig ads reports delivery --from 2026-09-01T00:00:00Z --to 2026-10-01T00:00:00Z

I rapporti di consegna mostrano lordo, commissioni di servizio e netto per il periodo. Un rapporto acquirente non mostra mai altri introiti del venditore. fill mostra, per un massimo di 35 giorni, quante occorrenze di spazi pubblicitari hanno richiesto i tuoi schermi, quante ne hanno riempite le campagne dirette, gli acquirenti invitati e il tuo tag VAST, e perché le restanti sono rimaste vuote: no_demand, ineligible, separated o capped.

--format csv, xlsx o pdf scrive il report come file in --output (predefinito ./ad-spend.FORMAT, ./ad-delivery.FORMAT o ./ad-fill.FORMAT) e risponde con percorso, byte e SHA-256; json è il valore predefinito e stampa la busta. delivery richiede --from e --to come istanti RFC 3339 ed elenca una riga per occorrenza completata, al massimo 5000, con truncated impostato quando ce ne sono altre; i totali coprono ogni regolamento. fill accetta un istante RFC 3339, now o un’età come 7d, 12h o 30m: --from vale per impostazione predefinita 7 giorni prima di --to, --to vale adesso, con al massimo 35 giorni di distanza, estesi a ore UTC intere.