Riferimento completo del CLI

Questo è il riferimento completo del CLI di Ads Uploader. Per un'introduzione e una guida alla configurazione, consulta Configurazione via CLI.

Comandi

Autenticazione

Un token di accesso dura 30 giorni. Dopo, esegui di nuovo ads login.

Navigazione

Build salvati

I build salvati sono gli stessi build che vedi nella finestra Saved Builds dell'uploader web. Consulta Build salvati per capire come funzionano.

Passa - al posto del nome di un file per leggere il JSON da stdin. Per lanciare un build, usa ads create --build <buildId> (oppure create:preview).

Caricamento media

Gli argomenti HTTPS, inclusi i link pubblici ai file di Google Drive, vengono rilevati automaticamente. Puoi combinare percorsi locali e URL: i file locali vengono caricati per primi, poi il server importa gli URL nello stesso batch, così il raggruppamento funziona su tutti gli input. Le cartelle pubbliche di Drive devono essere condivise come Anyone with the link (Viewer).

I file locali vengono preparati in parallelo e gli errori di rete temporanei vengono riprovati automaticamente con backoff. Le importazioni da URL e da cartelle Drive usano pipeline di file parallele con un limite, in un job in background, mentre il CLI mostra un contatore completati/totale e ogni file in lavorazione. Raramente devi toccare questi flag, ma sono disponibili:

Regole di caricamento:

• Ogni file può arrivare fino a 4 GB.
• Immagini: .jpg, .jpeg, .png, .gif, .bmp, .webp. Video: .mp4, .mov, .avi, .mkv, .webm, .m4v.
• I link devono usare https://. Tutto il resto viene trattato come percorso locale.
• Un'immagine con lo stesso nome del suo video più _thumbnail (ad esempio promo_thumbnail.jpg per promo.mp4) viene associata a quel video come miniatura personalizzata, invece di essere caricata come media separato.
• Se premi Ctrl-C durante un'importazione da link o da Drive, viene chiesto al server di interrompere l'importazione. I file già completati restano nel batch.

Creazione delle inserzioni

Duplicazione tramite Post ID

Gestione dei job

Flag di creazione

Questi flag valgono per ads create, ads create:preview e ads create:interactive (e per ads create:test, riservato agli admin). Puoi usarli al posto di un file di specifica oppure insieme a esso.

Flag di duplicazione tramite Post ID

Questi flag valgono per ads duplicator:post-id e ads duplicator:post-id:preview. Puoi usarli al posto di un file di specifica per la duplicazione tramite Post ID oppure insieme a esso. Questa è la modalità di duplicazione tramite Post ID; in futuro potrebbero arrivare altre modalità di duplicazione.

File di specifica per la duplicazione tramite Post ID

Questa specifica v1 seleziona un'inserzione di origine esatta, clona un gruppo di inserzioni e crea inserzioni in pausa:

{
  "adIds": ["120200000000000001"],
  "campaignId": "120200000000000000",
  "adSetId": "120200000000000002",
  "newAdSet": { "name": "Winners {AdName}" },
  "adNamePattern": "{AdName} - {Index}",
  "paused": true,
  "useCreativeId": false
}

Usa postIds per la ricerca oppure adIds in ordine per una selezione esatta, mai entrambi. L'anteprima restituisce sourceCandidates con gli ID di inserzione, campagna e gruppo di inserzioni. Quando le corrispondenze sono ambigue, requiresSourceSelection è true e resolvedRequest è null: scegli gli ID delle inserzioni e ripeti l'anteprima. Con una selezione esatta, resolvedRequest contiene ID di inserzioni e nessun Post ID. Serve un campaignId esistente; le nuove campagne non sono supportate.

Scegli una modalità di destinazione per il gruppo di inserzioni:

Per le esecuzioni reali con avvisi sui creativi, controlla l'anteprima e passa --acknowledge-warnings (acknowledgeWarnings: true in JSON/MCP) per proseguire. Anche un useCreativeId: true esplicito vale come scelta. L'anteprima non richiede conferma.

La campagna di destinazione, il gruppo di inserzioni selezionato e le inserzioni di origine devono appartenere allo stesso account pubblicitario. Un gruppo di inserzioni selezionato deve appartenere a campaignId, anche quando lo usi come template per un nuovo gruppo. Scegli newAdSet oppure newAdSetPerAd; se li combini, la richiesta viene rifiutata. Con una sola inserzione di origine, newAdSetPerAd crea un solo clone condiviso e mantiene {Index} a 1.

L'anteprima e la Test Mode web leggono la configurazione reale di ogni inserzione di origine e del template selezionato, senza creare oggetti su Meta. Le origini successive possono quindi far emergere dati mancanti e avvisi sui creativi; il targeting viene validato su ogni template usato per creare un nuovo gruppo di inserzioni. I nuovi gruppi di inserzioni simulati usano le impostazioni di budget e di offerta della campagna di destinazione, quando disponibili. Le inserzioni sono attive per impostazione predefinita; paused riguarda solo le inserzioni, mentre i nuovi gruppi di inserzioni restano attivi.

{AdName} inserisce il nome dell'inserzione di origine. {Index} inserisce la sua posizione, a partire da 1, nei nomi delle inserzioni duplicate e dei gruppi di inserzioni per inserzione. Quando un solo nuovo gruppo di inserzioni contiene più inserzioni di origine, {AdName} nel nome di quel gruppo diventa Multiple Ads.

Come la ricerca per post sceglie le inserzioni: una ricerca per Post ID esamina fino a circa 2.000 inserzioni recenti dell'account. Non sceglie mai al posto tuo la corrispondenza più recente. Quando più inserzioni corrispondono, il CLI e l'MCP si fermano e ti chiedono di scegliere; si fermano anche in presenza di avvisi che non hai confermato. Un'esecuzione reale duplica sempre ID di inserzioni esatti, quindi invia il resolvedRequest dell'anteprima. Per rieseguire una selezione che hai già controllato, salva e riutilizza resolvedRequest (l'MCP richiede anche accountId) invece di ripetere la ricerca basata solo sul post. Gli ID delle inserzioni restano fissi, ma le impostazioni attuali di Meta vengono lette e controllate di nuovo al lancio.

I nuovi gruppi di inserzioni ereditano targeting, budget, programmazione e impostazioni di offerta dal --adset o adSetId selezionato, con la stessa pulizia e lo stesso allineamento del budget di destinazione del Duplicator web. Senza un template selezionato, un nuovo gruppo condiviso usa il gruppo di inserzioni della prima inserzione di origine; la modalità per inserzione usa il gruppo di inserzioni di ciascuna inserzione di origine.

Le inserzioni di origine con creativo dinamico riutilizzano il proprio ID del creativo e non possono mantenere l'engagement sincronizzato. Il CLI mostra lo stesso avviso del Duplicator web.

Le esecuzioni reali di duplicazione tramite Post ID mostrano l'avanzamento per gruppo di inserzioni e per inserzione, compresi i messaggi di errore di Meta, e terminano con Duplicated X of Y.

Flag di navigazione

Questi flag sono disponibili su campaigns, adsets, adset e campaign:

Ricerca del targeting

Il targeting per città, per CAP e il targeting dettagliato usano identificatori di Meta invece dei nomi. Cerca tramite Ads Uploader per ottenere valori da incollare in una specifica:

ads targeting:search "Austin" --type city
ads targeting:search "90210" --type zip
ads targeting:search "advertising" --type detailed

I risultati del targeting dettagliato includono id, name, type, un intervallo di dimensione del pubblico e il percorso della categoria. Il campo type identifica la categoria del targeting dettagliato, ad esempio interests, behaviors, work_employers o work_positions. Cerca sempre questi identificatori; non tirarli mai a indovinare.

Flag di dettaglio

Questi flag sono disponibili su ad:

Flag comuni

Variabili d'ambiente e aggiornamenti

Il CLI controlla una volta al giorno se c'è una nuova versione e mostra un avviso quando è disponibile. Aggiorna con npm update -g @adsuploader/cli.

Formato del file di specifica

Il file di specifica JSON controlla ogni aspetto della creazione delle inserzioni. Indica una fonte di template (adPresetId o copyFromAd) più un uploadId oppure dei mediaItems acquisiti con un mediaHash di Facebook per ogni immagine e un mediaId per ogni video. I video standard, carosello, flessibili e di posizionamento richiedono anche thumbnailHash; i video Multi Media usano l'URL pubblico della miniatura acquisito.

Per i video, mediaItems[].mediaId deve essere l'ID numerico del video su Facebook: usa il videoId della risposta di caricamento, non il suo id interno. videoId è accettato come alias, e linkedAssets[] segue la stessa regola. Gli ID di caricamento interni vengono risolti al salvataggio solo se appartengono all'utente autenticato e all'account selezionato. Senza un ID numerico o un collegamento al batch, un video non risolto rende il build non lanciabile. Vedi l'elemento canonico per i video di posizionamento.

Specifica minima

{
  "adPresetId": "your_preset_id",
  "uploadId": "batch_abc123"
}

Esempio completo

{
  "adPresetId": "preset_id_here",
  "uploadId": "batch_abc123",
  "adSet": {
    "name": "My New Ad Set",
    "dailyBudget": 50
  },
  "adNamePattern": "{filename}",
  "texts": {
    "perAd": {
      "hero.jpg": {
        "headlines": ["Main Headline"],
        "bodies": ["Ad copy here."],
        "descriptions": ["Short description"],
        "cta": "SHOP_NOW",
        "link": "https://example.com/landing"
      }
    }
  },
  "creativeEnhancements": "none",
  "options": {
    "status": "PAUSED",
    "pauseAt": "adSet"
  }
}

Fonte del template

Ti serve uno di questi campi per dire al CLI quale configurazione di inserzione usare come base.

Quando usi copyFromAd, indica il batch di caricamento, oppure lancia un build web salvato in cui le immagini acquisite hanno mediaHash e i video hanno mediaId. Facoltativamente puoi impostare campagna e gruppo di inserzioni:

{
  "copyFromAd": "120233848667930472",
  "uploadId": "batch_abc123",
  "campaign": { "id": "120233848666410472" },
  "adSet": { "id": "120233848666620472" }
}

Per trovare l'ID giusto dell'inserzione, scendi nella struttura del tuo account: ads campaigns, poi ads campaign <id>, poi ads adset <id>, poi ads ad <id>.

Opzioni del profilo

Per impostazione predefinita, le nuove inserzioni ereditano la Pagina Facebook, l'account Instagram e il profilo Threads dall'inserzione template o dal preset. È lo stesso controllo Profile Options disponibile nel pannello Defaults dell'app web. Puoi sostituire uno qualsiasi di questi valori con un blocco profile (oppure con i flag --page / --instagram / --use-page-identity / --threads, che hanno la precedenza sul file di specifica):

{
  "copyFromAd": "120233848667930472",
  "uploadId": "batch_abc123",
  "profile": {
    "pageId": "123456789012345",
    "instagramId": "17841400000000000",
    "threadsId": "987654321098765"
  }
}

Esegui ads pages per elencare gli ID delle Pagine che puoi usare, insieme all'account Instagram collegato a ciascuna Pagina.

Se sostituisci solo la Pagina, Ads Uploader usa automaticamente l'account Instagram collegato. Se non è collegato alcun account Instagram, usa la Pagina Facebook come identità Instagram. Threads viene comunque azzerato, perché potrebbe appartenere alla Pagina precedente; impostalo esplicitamente quando serve.

Per scegliere esplicitamente la Pagina come identità, usa --use-page-identity oppure imposta "useFacebookPage": true dentro profile. Non combinarlo con --instagram o instagramId. Puoi anche cambiare solo il profilo Instagram o Threads senza toccare la Pagina, impostando solo quei campi.

Per i lanci su più campagne, assegna le identità in modo indipendente con profile.campaigns. Associa ogni sostituzione all'id della campagna corrispondente (consigliato) oppure a un nome di campagna non ambiguo:

{
  "campaign": {
    "mode": "duplicate",
    "campaigns": [
      { "id": "prospecting", "name": "Prospecting" },
      { "id": "retargeting", "name": "Retargeting" }
    ]
  },
  "profile": {
    "campaigns": {
      "prospecting": { "pageId": "page_1", "instagramId": "ig_1", "threadsId": null },
      "retargeting": { "pageId": "page_2", "useFacebookPage": true, "threadsId": "threads_2" }
    }
  }
}

profile.campaigns funziona solo quando campaign.mode è "duplicate" o "split" con almeno due voci in campaign.campaigns. Ogni chiave deve corrispondere a una di quelle campagne; le chiavi senza corrispondenza o ambigue vengono rifiutate prima del lancio.

Struttura della campagna

Per impostazione predefinita, le inserzioni vanno nella campagna dell'inserzione template. Puoi creare una nuova campagna indicando campaign.name.

Per le modalità con più campagne, usa campaign.mode con un array campaigns:

{
  "campaign": {
    "mode": "duplicate",
    "campaigns": [
      { "name": "Campaign A" },
      { "name": "Campaign B" }
    ]
  }
}

Modalità del gruppo di inserzioni

Per impostazione predefinita, le inserzioni vanno nel gruppo di inserzioni esistente dell'inserzione template. Le modalità seguenti ti permettono di controllare come le inserzioni vengono distribuite tra i gruppi di inserzioni.

Crea un nuovo gruppo di inserzioni:

{ "adSet": { "name": "My Ad Set" } }

Usa un gruppo di inserzioni esistente tramite ID:

{ "adSet": { "id": "120233848666620472" } }

Un gruppo di inserzioni per ogni file caricato:

{ "adSet": { "mode": "perUpload" } }

Raggruppamento automatico in gruppi di inserzioni di dimensione fissa:

{ "adSet": { "mode": "autoGroup", "adsPerAdSet": 5 } }

Gruppi personalizzati, con pieno controllo su quali file vanno dove:

{
  "adSet": {
    "groups": [
      { "name": "Images - April 10", "media": ["hero.jpg", "banner.jpg"] },
      { "name": "Videos - April 10", "media": ["promo.mp4"] }
    ]
  }
}

Pattern di denominazione dei gruppi di inserzioni per le modalità con più gruppi di inserzioni:

{ "adSet": { "mode": "perUpload", "namePattern": "Ad Set {index:01}" } }

Raggruppamento per variante: raggruppa le inserzioni nello stesso gruppo di inserzioni in base all'identificatore di variante:

{ "adSet": { "mode": "autoGroup", "groupVariations": true, "variationIdentifier": "-" } }

Sostituzione di budget e controllo delle offerte

Sostituisci il budget giornaliero e/o l'importo dell'offerta sui nuovi gruppi di inserzioni. I valori sono nelle unità della valuta del tuo account (ad es. 50 per 50 $ o 50 euro).

dailyBudget e bidAmount usano le unità di valuta dell'account. minimumRoas è un rapporto, quindi 1.5 significa un obiettivo di ROAS di 1,5x.

• Campagne ABO (il budget è sul gruppo di inserzioni): combina dailyBudget con bidAmount per le strategie con limite di offerta o di costo, oppure con minimumRoas per LOWEST_COST_WITH_MIN_ROAS.
• Campagne CBO (il budget è sulla campagna): non impostare dailyBudget sul gruppo di inserzioni. Imposta campaign.dailyBudget oppure campaign.lifetimeBudget (si escludono a vicenda) per sostituire il budget della campagna di origine, oppure ometti entrambi per ereditarlo. I limiti di spesa minima e massima del gruppo di inserzioni possono usare importi in unità intere oppure dal 5 al 100% del budget della campagna, a passi del 5%; i limiti in percentuale funzionano anche con una campagna CBO esistente. Imposta bidAmount o minimumRoas sul gruppo di inserzioni quando la sua strategia di origine usa quel controllo.

bidAmount e minimumRoas si escludono a vicenda, perché appartengono a strategie di offerta diverse.

{ "adSet": { "dailyBudget": 50 } }
{ "adSet": { "bidAmount": 5 } }
{ "adSet": { "minimumRoas": 1.5 } }
{ "adSet": { "dailyBudget": 50, "bidAmount": 5 } }

Per i limiti di spesa CBO in una specifica, imposta questi campi su adSet:

{
  "campaign": { "dailyBudget": 200 },
  "adSet": { "minSpend": 20, "maxSpendPercentage": 50 }
}

Disponibili anche come flag del CLI: --daily-budget 50, --bid-amount 5, --minimum-roas 1.5, --campaign-daily-budget 100, --campaign-lifetime-budget 1000, --adset-min-spend 20, --adset-max-spend 80, --adset-min-spend-pct 20 e --adset-max-spend-pct 80.

Targeting del gruppo di inserzioni

Il targeting si applica ai nuovi gruppi di inserzioni. Ometti il blocco targeting di primo livello per ereditare senza modifiche il pubblico del gruppo di inserzioni di origine. Qualsiasi modalità può usare adSet.targetingPerAdSet, con chiavi come in texts.perAdset: nome finale del gruppo di inserzioni, ID del gruppo di inserzioni oppure campaign::key per evitare collisioni. La modalità personalizzata supporta anche adSet.groups[].targeting. L'ordine di precedenza è targetingPerAdSet, poi groups[].targeting, poi il valore predefinito del build, poi il pubblico di origine. Il targeting per gruppo di inserzioni è disponibile solo nella specifica, perché i flag del CLI non possono indicare uno specifico gruppo di inserzioni pianificato.

Con più campagne, la copia di un gruppo di inserzioni in ciascuna campagna riceve un targeting separato; usa "Campaign name::Ad set name" come chiave per una copia specifica.

{
  "targeting": {
    "countries": ["US"],
    "cities": [
      {
        "key": "2525495",
        "name": "Austin",
        "region": "Texas",
        "countryCode": "US",
        "radius": 25,
        "distance_unit": "mile"
      }
    ],
    "zips": [
      {
        "key": "US:90210",
        "name": "90210",
        "region": "California",
        "countryCode": "US"
      }
    ],
    "selectionVersion": 4,
    "ageSelected": true,
    "ageMin": 21,
    "ageMax": 55,
    "genderSelected": true,
    "genders": "women",
    "detailedTargetingSelected": true,
    "detailedTargetingGroups": [[
      {
        "id": "112002898811624",
        "name": "Advertising agency",
        "type": "work_employers"
      }
    ]]
  }
}

{
  "targeting": { "countries": ["US"], "ageMin": 21, "ageMax": 55 },
  "adSet": {
    "mode": "perUpload",
    "namePattern": "Ad Set {index:01}",
    "targetingPerAdSet": {
      "Ad Set 02": { "countries": ["CA"], "genders": "women" },
      "Ad Set 01": { "countries": ["GB"] }
    }
  }
}

In modalità personalizzata, groups[].targeting resta valido e tiene la sostituzione accanto al suo gruppo di media:

{
  "adSet": {
    "mode": "custom",
    "groups": [{
      "name": "Canada Women",
      "media": ["canada.jpg"],
      "targeting": { "countries": ["CA"], "genders": "women" }
    }]
  }
}

Regole del targeting:

• Età e genere vanno attivati esplicitamente. Imposta ageSelected: true o genderSelected: true, altrimenti i valori di età o genere vengono ignorati.
• Il targeting dettagliato sostituisce, non unisce. detailedTargetingGroups diventa l'intero pubblico dettagliato, quindi tutto ciò che lasci fuori viene eliminato.
• Il raggio della città resta tra 10 e 50 miglia, oppure tra 17 e 80 chilometri. Un valore fuori da questo intervallo viene portato al limite più vicino, e un raggio mancante usa il minimo.

Usa ads targeting:search per trovare la key della città (tipo city), la key del CAP come US:90210 (tipo zip) e id, name e type di ogni selezione dettagliata (tipo detailed). Ometti paesi, città e CAP per ereditare le località di origine. Paesi, città e CAP vengono combinati come alternative, quindi aggiungere Austin o un CAP a countries: ["US"] continua a indirizzare tutti gli Stati Uniti; ometti i paesi per indirizzare solo la città o il CAP. I CAP non hanno un raggio.

Configurazione dei testi

Il testo comune applica lo stesso copy a tutte le inserzioni:

{
  "texts": {
    "common": {
      "headlines": ["Headline 1", "Headline 2"],
      "bodies": ["Primary text"],
      "descriptions": ["Description"]
    },
    "strategy": "flexible"
  }
}

Il testo per inserzione ti permette di impostare un copy diverso per ogni file:

{
  "texts": {
    "perAd": {
      "hero.jpg": {
        "headlines": ["Hero Headline"],
        "bodies": ["Hero copy"],
        "descriptions": ["Hero desc"],
        "cta": "LEARN_MORE",
        "link": "https://example.com/hero",
        "urlTags": "utm_content=hero"
      },
      "banner.jpg": {
        "headlines": ["Banner Headline"],
        "bodies": ["Banner copy"]
      }
    }
  }
}

Le chiavi per inserzione sono nomi di file (non percorsi completi). Ogni voce supporta: headlines, bodies, descriptions, cta, link, displayUrl, urlTags. I campi che non indichi vengono ereditati dall'inserzione template.

Il testo per gruppo di inserzioni applica un blocco di testo a tutte le inserzioni di un gruppo di inserzioni di destinazione. Usa semplicemente il nome o l'ID del gruppo di inserzioni quando è unico, oppure una voce campaign::key quando lo stesso nome di gruppo di inserzioni compare in più campagne:

{
  "texts": {
    "perAdset": {
      "Prospecting::prospecting_set": {
        "headlines": ["Prospecting headline"],
        "bodies": ["Prospecting copy"],
        "descriptions": ["Prospecting description"],
        "cta": "SHOP_NOW",
        "link": "https://example.com/prospecting",
        "displayUrl": "example.com/prospecting",
        "urlTags": "utm_campaign=prospecting",
        "aiDisclosure": false
      }
    }
  }
}

Ogni chiave di texts.perAdset deve corrispondere a un gruppo di inserzioni pianificato. Le chiavi senza corrispondenza vengono rifiutate, invece di ripiegare sul testo comune.

I preset di testo ti permettono di caricare una configurazione di testo salvata:

{ "textPresetId": "preset_id_here" }

Non puoi combinare textPresetId con texts.

Dichiarazione IA

Dichiara volontariamente che il creativo di un'inserzione è stato creato o modificato in modo significativo con l'IA (l'autodichiarazione dei contenuti IA di Meta). È disattivata per impostazione predefinita e non viene mai attivata al posto tuo.

{ "aiDisclosure": true }

Il campo aiDisclosure di primo livello (o il flag --ai-disclosure) si applica a tutte le inserzioni del lancio. Puoi anche impostare aiDisclosure a true o false su una voce di texts.perAd o texts.perAdset; il valore della singola voce vince sempre, anche un false esplicito.

Le opzioni di strategia controllano come vengono gestite più varianti di testo:

• "flexible" (predefinita) lascia che Meta ottimizzi tra le tue varianti di testo. Più titoli e testi principali diventano opzioni che Facebook combina tra loro.
• "separate" crea un'inserzione separata per ogni combinazione di testo.

CTA e link

Una CTA di primo livello si applica a tutte le inserzioni. Le CTA per inserzione in texts.perAd e quelle per gruppo di inserzioni in texts.perAdset la sostituiscono.

{
  "cta": {
    "type": "SHOP_NOW",
    "link": "https://example.com",
    "displayUrl": "example.com"
  },
  "urlTags": "utm_source=facebook&utm_medium=paid"
}

Tipi di CTA standard: LEARN_MORE, SHOP_NOW, SIGN_UP, SUBSCRIBE, GET_OFFER, GET_QUOTE, CONTACT_US, GET_IN_TOUCH, BOOK_TRAVEL (mostrato come Book Now), ORDER_NOW, BUY_NOW, APPLY_NOW, DOWNLOAD, SEE_DETAILS, WATCH_MORE, LISTEN_NOW, PLAY_GAME, DONATE_NOW, OPEN_LINK

Usa il valore di Meta (come SHOP_NOW), non l'etichetta del pulsante.

Le CTA specifiche per obiettivo vengono ereditate dall'inserzione template e non vanno impostate a mano. Impostarle sul tipo di campagna sbagliato causa un errore dell'API di Facebook.

Split test degli URL (Split Destination)

Indica da 2 a 5 URL di destinazione in texts.urlVariants e ogni gruppo di inserzioni generato viene duplicato una volta per URL, così Meta ottimizza in modo indipendente ogni combinazione di inserzione e landing page.

{
  "texts": {
    "common": { "headlines": ["Hero"], "bodies": ["Copy"] },
    "urlVariants": [
      { "link": "https://example.com/homepage", "label": "homepage" },
      { "link": "https://example.com/quiz", "label": "quiz-v2" }
    ]
  }
}

• label è facoltativo. Se lo ometti, viene usato l'ultimo slug del percorso dell'URL (/quiz-v2 diventa quiz-v2), con il nome host come ripiego per gli URL della radice.
• In modalità con un solo gruppo di inserzioni, l'etichetta di ogni variante diventa il nome completo del gruppo di inserzioni.
• Nelle modalità perUpload e autoGroup, al nome di ogni gruppo di inserzioni duplicato viene aggiunto -{label} alla fine (ad esempio Ad Set 01-quiz-v2), oppure l'etichetta sostituisce un token {destination} se lo includi.
• Il token {date} in un'etichetta diventa la data di oggi (ad esempio, launch-{date} diventa launch-2026-04-27).
• Ogni URL di destinazione deve essere unico. URL identici (o varianti dello stesso URL con barra finale o maiuscole diverse) vengono ridotti a una sola voce, quindi assicurati di avere almeno 2 destinazioni distinte.
• Il budget del gruppo di inserzioni viene moltiplicato per il numero di varianti, perché ogni duplicato è un gruppo di inserzioni a sé.
• Non è compatibile con inserzioni di origine con destinazioni speciali (modulo per contatti, Messenger, WhatsApp, Instagram Direct, chiamata). Il CLI rifiuta questa combinazione con un errore chiaro, perché quei formati non usano cta.link.
• Le sostituzioni di link per inserzione in texts.perAd perdono contro l'URL della variante quando sono impostati entrambi.

Miglioramenti creativi

Controlla i miglioramenti creativi di Advantage+:

{ "creativeEnhancements": "none" }

Funzioni disponibili: text_translation, inline_comment, enhance_cta, text_optimizations, reveal_details_over_time, show_destination_blurbs, image_brightness_and_contrast, image_touchups, video_auto_crop, video_filtering, pac_relaxation, image_animation, image_templates, adapt_to_placement, product_extensions, product_tags, description_automation, add_text_overlay, music, carousel_to_video, carousel_dynamic_description, multi_share_end_card, multi_share_optimized

La chiave show_destination_blurbs viene mostrata come Show spotlights, e pac_relaxation come Flex media.

Quando scegli le funzioni una per una, elenca solo quelle pertinenti al tipo di media. Le funzioni video (video_auto_crop, video_filtering) si applicano solo alle inserzioni video. Le funzioni carosello (carousel_to_video, carousel_dynamic_description, multi_share_end_card, multi_share_optimized) si applicano solo alle inserzioni carosello.

product_tags si applica alle inserzioni con immagini e video ed è disponibile solo quando cloni. Può essere attivata solo se l'inserzione di origine ha un catalogo associato e tag prodotto posizionati esplicitamente; tutti i tag di origine e le loro posizioni vengono mantenuti. "all" la include solo per un'origine idonea e non inventa mai un tag prodotto.

Inserzioni carosello

Raggruppa i file caricati in inserzioni carosello, con testo per ogni scheda e un testo generale del carosello facoltativo. cardTexts controlla le singole schede. Il testo generale del carosello può stare sull'oggetto carosello oppure in texts.perAd, usando il name del carosello; se sono presenti entrambi, vincono i campi sull'oggetto carosello.

{
  "carousel": [
    {
      "name": "My Carousel",
      "cards": ["slide1.jpg", "slide2.jpg", "slide3.jpg"],
      "headlines": ["Overall Carousel Headline"],
      "bodies": ["Overall primary text"],
      "descriptions": ["Overall description"],
      "cta": "SHOP_NOW",
      "link": "https://example.com/carousel",
      "urlTags": "utm_content=my_carousel",
      "cardTexts": [
        { "headline": "Slide 1", "description": "First card", "link": "https://example.com/1" },
        { "headline": "Slide 2", "description": "Second card", "link": "https://example.com/2" }
      ]
    }
  ]
}

Forma alternativa per il testo generale:

{
  "texts": {
    "perAd": {
      "My Carousel": {
        "headlines": ["Overall Carousel Headline"],
        "bodies": ["Overall primary text"],
        "descriptions": ["Overall description"],
        "cta": "SHOP_NOW",
        "link": "https://example.com/carousel",
        "urlTags": "utm_content=my_carousel"
      }
    }
  },
  "carousel": [
    {
      "name": "My Carousel",
      "cards": ["slide1.jpg", "slide2.jpg", "slide3.jpg"]
    }
  ]
}

Le schede devono fare riferimento a nomi di file del batch di caricamento o a media acquisiti in un build salvato. Ogni carosello richiede da 2 a 10 schede. I file assegnati a un carosello vengono tolti dall'elenco delle inserzioni standard.

Inserzioni flessibili

Raggruppa più asset in un'unica inserzione flessibile, in cui Meta sceglie l'asset migliore per ogni posizionamento:

{
  "flexible": [
    {
      "name": "Multi-Asset Ad",
      "assets": ["hero.jpg", "promo.mp4", "banner.jpg"]
    }
  ]
}

Ogni gruppo flessibile richiede da 2 a 10 asset. I file assegnati a un gruppo flessibile vengono tolti dall'elenco delle inserzioni standard.

Inserzioni Multi Media

Raggruppa da 2 a 10 immagini o video caricati in un'inserzione Multi Media di Meta:

{
  "multimedia": [
    {
      "name": "Mixed Media Ad",
      "assets": ["hero.jpg", "promo.mp4", "banner.jpg"],
      "assetTexts": [
        {
          "headline": "Hero headline",
          "primaryText": "Hero primary text",
          "description": "Hero description",
          "link": "https://example.com/hero",
          "displayUrl": "example.com/hero"
        }
      ]
    }
  ]
}

Gli asset devono fare riferimento a nomi di file del batch di caricamento o a media acquisiti in un build salvato. assetTexts è facoltativo e corrisponde ad assets per indice; ogni campo è una singola sostituzione per quell'asset, e i campi vuoti ripiegano sul testo principale e sugli URL dell'inserzione. L'asset principale mostrato usa il testo principale e l'URL dell'inserzione, e qualsiasi sostituzione di testo dell'asset principale diventa la prima opzione di testo principale. I video richiedono un URL pubblico della miniatura acquisito e in cache. I file assegnati a un gruppo Multi Media vengono tolti dall'elenco delle inserzioni standard.

Denominazione delle inserzioni

Personalizza il modo in cui vengono chiamate le tue inserzioni:

{ "adNamePattern": "{filename} - {date}" }

Le trasformazioni avvolgono un valore. Un valore vuoto indica il nome del file:

Le trasformazioni si possono annidare, ad esempio {titlecase:{split:_:2}}. Un pattern può contenere fino a 200 caratteri. Consulta Pattern di denominazione annunci per altri esempi.

Opzioni

{
  "options": {
    "status": "PAUSED",
    "pauseAt": "adSet",
    "schedule": {
      "startTime": "2026-04-01T09:00:00",
      "endTime": "2026-04-30T23:59:59"
    }
  }
}

Quando le inserzioni vanno in un gruppo di inserzioni esistente, options.schedule funziona solo per le campagne Vendite e Promozione dell'app, perché Meta supporta la programmazione per singola inserzione solo per questi obiettivi. Per gli altri obiettivi, crea un nuovo gruppo di inserzioni oppure rimuovi options.schedule.

Limiti della specifica

Caricamento e rilevamento delle varianti

I gruppi di varianti vengono rilevati automaticamente dalle convenzioni sui nomi dei file, proprio come nell'applicazione web. Consulta Variazioni di proporzione per tutti i dettagli sulle convenzioni di denominazione.

Suffissi di proporzione: hero_1x1.jpg + hero_4x5.jpg + hero_9x16.jpg + hero_16x9.jpg + hero_1.91x1.jpg vengono raggruppati in un'unica inserzione con varianti. Fino a 5 proporzioni per gruppo.

Posizione del token: il token di proporzione può trovarsi alla fine (hero_4x5.jpg), nel mezzo (hero_4x5_v2.jpg) o all'inizio (4x5_hero.jpg).

Suffissi testuali legacy: hero.jpg + hero_vertical.jpg + hero_horizontal.jpg funzionano ancora e corrispondono a 9x16 e 16x9.

Il delimitatore predefinito è _. Puoi cambiarlo (o accettarne più di uno) in Account > Defaults > Placements > Filename Separator.

Pattern comuni

Carica e crea con un preset

ads upload ./creatives/hero.jpg ./creatives/banner.jpg
ads create:preview spec.json
ads create spec.json

Dove spec.json contiene:

{ "adPresetId": "PRESET_ID", "uploadId": "BATCH_ID" }

Copia le impostazioni da un'inserzione esistente

Naviga nel tuo account per trovare l'inserzione:

ads campaigns
ads campaign 120233848666410472
ads adset 120233848666620472
ads ad 120233848667930472

Poi crea una specifica che la richiama:

{
  "copyFromAd": "120233848667930472",
  "uploadId": "BATCH_ID"
}

L'inserzione di origine deve avere impostazioni del creativo inline. Se è stata creata da un post esistente di una Pagina, il CLI la rifiuta prima di inviare la richiesta di creazione.

Salva un preset API da un'inserzione esistente

ads presets:save --from-ad 120233848667930472 --name "Spring Purchase Template"
ads create --preset PRESET_ID --upload BATCH_ID

Questo salva un preset API con la stessa struttura usata dall'app web. L'inserzione di origine deve avere impostazioni del creativo inline; le inserzioni basate su un post di una Pagina non possono essere salvate come preset API.

Testo per inserzione con un copy diverso per ogni file

{
  "adPresetId": "PRESET_ID",
  "uploadId": "BATCH_ID",
  "texts": {
    "perAd": {
      "hero.jpg": {
        "headlines": ["Summer Sale Now On"],
        "bodies": ["Save up to 50% on all items"],
        "cta": "SHOP_NOW",
        "link": "https://example.com/summer"
      },
      "banner.jpg": {
        "headlines": ["New Collection Available"],
        "bodies": ["Browse our latest styles"],
        "cta": "LEARN_MORE",
        "link": "https://example.com/new"
      }
    }
  }
}

Raggruppamento automatico in più gruppi di inserzioni

{
  "adPresetId": "PRESET_ID",
  "uploadId": "BATCH_ID",
  "adSet": { "mode": "autoGroup", "adsPerAdSet": 3 }
}

Note importanti

1. Fai sempre prima un'anteprima. create:preview individua gli errori di configurazione prima di toccare Facebook.
2. Le inserzioni sono attive per impostazione predefinita. Usa --status PAUSED oppure "status": "PAUSED" nella specifica per crearle in pausa.
3. uploadId arriva dall'output del caricamento. È l'ID del batch restituito da ads upload.
4. I caricamenti sono legati a un account pubblicitario. I file vengono caricati direttamente nella libreria media Facebook dell'account selezionato. L'ID del batch si può usare solo con lo stesso account.
5. copyFromAd richiede media risolvibili. Indica uploadId, oppure lancia un build salvato in cui le immagini acquisite hanno mediaHash e i video hanno mediaId. Facoltativamente indica campaign.id e adSet.id per controllare dove finiscono le inserzioni.
6. Le chiavi del testo per inserzione sono nomi di file. Usa "hero.jpg", non "/path/to/hero.jpg".
7. textPresetId e texts si escludono a vicenda. Usa l'uno o l'altro, non entrambi.
8. Le CTA specifiche per obiettivo vengono ereditate dal template. Non impostare a mano MESSAGE_PAGE, WHATSAPP_MESSAGE e simili.

Inserzioni in partnership con i tuoi media

Il CLI e l'MCP possono lanciare inserzioni in partnership con media caricati su Facebook e Instagram. Usa la tua normale specifica per immagini/video, carosello, flessibile, Multi Media o varianti di posizionamento e aggiungi profile.partnership.enabled: true. I media caricati seguono l'assemblaggio normale con una Second Identity. Ometti uploaderMode oppure impostalo a false; true seleziona i post importati e non si può usare con i caricamenti.

Scegli la tua First Identity con profile.pageId e profile.instagramId. Il partner condiviso è la Second Identity:

{
  "accountId": "act_123",
  "copyFromAd": "SOURCE_AD_ID",
  "adSet": { "id": "EXISTING_AD_SET_ID" },
  "mediaItems": [
    { "mediaName": "one.jpg", "mediaType": "image", "mediaHash": "UPLOADED_IMAGE_HASH_ONE" },
    { "mediaName": "two.jpg", "mediaType": "image", "mediaHash": "UPLOADED_IMAGE_HASH_TWO" }
  ],
  "profile": {
    "pageId": "111",
    "instagramId": "222",
    "partnership": {
      "enabled": true,
      "sponsorPageId": "333",
      "sponsorInstagramId": "444",
      "displayMode": "both"
    }
  },
  "options": { "status": "PAUSED" }
}

Per avere partner diversi per ogni inserzione, aggiungi questo blocco texts alla stessa specifica. La seconda riga usa esplicitamente No Partner:

{
  "texts": {
    "mode": "perAd",
    "perAd": {
      "one.jpg": { "sponsorPageId": "555", "sponsorInstagramId": "666" },
      "two.jpg": { "sponsorPageId": null, "sponsorInstagramId": null }
    }
  }
}

Per l'ambito per gruppo di inserzioni, usa texts.mode: "perAdset" e texts.perAdset, con chiavi basate sul nome o ID finale del gruppo di inserzioni oppure su campaign::key. Nei lanci su più campagne, usa profile.campaigns[<id or unambiguous name>] per sostituire lo sponsor a livello di campagna. L'ordine di risoluzione è partner condiviso, poi campagna, poi la riga attiva. I campi sponsor omessi vengono ereditati in modo indipendente; imposta esplicitamente entrambi gli ID a null per No Partner. Cambiare solo la Pagina del partner non azzera un ID Instagram ereditato sui media caricati; imposta esplicitamente quell'ID quando cambi la coppia. I campi First Identity della riga (pageId, instagramId, threadsId) restano indipendenti.

Per una Second Identity solo Instagram, imposta sponsorPageId: null, sponsorInstagramId all'ID dell'account approvato e sponsorPageUseInstagramAccount: true. Per i media caricati è supportata anche una Pagina Facebook partner. La restrizione sulle importazioni di post da Facebook non si applica ai media caricati.

displayMode vale per tutto il lancio: both (predefinito), first o dynamic. Ogni partner effettivo deve essere diverso dalla First Identity e avere l'accesso approvato alla pubblicità in partnership. Un'approvazione in attesa o mancante viene rifiutata indicando l'identità interessata. Ogni riga ha bisogno di un partner completo, ereditato o esplicito, oppure di una sostituzione No Partner esplicita. Attivare le partnership senza alcuno sponsor viene rifiutato. L'approvazione viene ricontrollata in anteprima e alla creazione; un build salvato non memorizza le autorizzazioni concesse.

ads create:preview e ads_preview mostrano per ogni inserzione il partner effettivo, l'approvazione e la modalità dell'intestazione, raggruppati per gruppo di inserzioni. ads create:test (riservato agli admin) o ads_create con options.testMode: true validano con Meta le chiamate idonee senza creare inserzioni e riportano il numero di controlli superati, falliti e non eseguiti. I build web salvati completi di inserzioni in partnership con media caricati possono essere lanciati tramite il CLI e l'MCP; i build modificati con questi strumenti ripristinano nell'uploader web Partnership Ads, identità, partner per riga e modalità dell'intestazione.

Specifica per partnership con post Instagram esistenti

Le specifiche JSON del CLI e gli strumenti MCP ads_preview / ads_create accettano post Instagram con mediaItems[].kind: "partnershipPost". L'inserzione di origine o il preset forniscono le impostazioni; il post importato fornisce la sua identità creator fissa e la didascalia organica. Scegli lo sponsor condiviso in profile.partnership, oppure imposta lo sponsor e le eventuali sostituzioni di testo in texts.perAdset o texts.perAd. Titolo, CTA, URL del sito web e testimonianza possono essere vuoti. Una CTA non vuota richiede un URL del sito web. Le importazioni di post da Facebook non sono supportate.

L'anteprima controlla contenuti e autorizzazioni tramite chiamate di lettura e di sola validazione a Meta, senza creare inserzioni né salvare codici. Il suo resolvedSpec senza codici può essere salvato, ma i codici vanno forniti di nuovo alla creazione. La creazione ricontrolla le autorizzazioni.

Usa mediaItems[].kind: "partnershipPost" con platform: "instagram". Scegli esattamente un localizzatore: sourceInstagramMediaId, import.postUrl oppure import.instagramShortcode. Un import.adCode corrispondente può accompagnare un localizzatore oppure essere usato da solo. L'inserzione di origine o il preset forniscono le impostazioni, non il post. I campi facoltativi creator.pageId e creator.instagramId confermano il creator risolto.

{
  "accountId": "act_123",
  "copyFromAd": "456",
  "adSet": { "mode": "single", "id": "789" },
  "mediaItems": [{ "kind": "partnershipPost", "mediaName": "creator-post-one", "platform": "instagram", "import": { "postUrl": "https://www.instagram.com/p/POST_SHORTCODE/" } }],
  "profile": { "partnership": { "enabled": true, "uploaderMode": true, "sponsorPageId": "111", "sponsorInstagramId": "222", "displayMode": "both" } },
  "texts": { "mode": "common", "common": { "headline": "Discover the collection", "callToAction": "LEARN_MORE", "link": "https://example.com/", "multiAdvertiserAds": false } },
  "options": { "status": "PAUSED", "pauseAt": "ad" }
}

Per un'importazione solo tramite codice, usa questo corpo di richiesta completo con i tuoi ID e un codice inserito da un generatore di segreti in memoria. Non salvare il codice reale in un file:

{
  "accountId": "act_123",
  "copyFromAd": "456",
  "adSet": { "mode": "single", "id": "789" },
  "mediaItems": [{ "kind": "partnershipPost", "mediaName": "creator-post-one", "platform": "instagram", "import": { "adCode": "REPLACE_IN_MEMORY" } }],
  "profile": { "partnership": { "enabled": true, "uploaderMode": true, "sponsorPageId": "111", "sponsorInstagramId": "222", "displayMode": "both" } },
  "texts": { "mode": "common", "common": { "headline": "Discover the collection", "callToAction": "LEARN_MORE", "link": "https://example.com/", "multiAdvertiserAds": false } },
  "options": { "status": "PAUSED", "pauseAt": "ad" }
}

Usa da 1 a 250 post per richiesta, ciascuno con un mediaName unico di massimo 200 caratteri. sponsorPageId deve corrispondere a una vera Pagina Facebook del brand per ogni inserzione pianificata; sponsorInstagramId è facoltativo. La displayMode dell'intestazione vale per tutto il lancio: both, first o dynamic. Per i post importati, first indica l'intestazione con il solo creator, etichettata Partner identity only in the header nell'uploader, non un'intestazione con il solo brand.

Gli sponsor per campagna usano profile.campaigns, con chiavi basate sull'ID della campagna o su un nome di campagna non ambiguo, con sponsorPageId e sponsorInstagramId facoltativo. L'ordine di risoluzione è sponsor condiviso, poi campagna, poi la sostituzione attiva per gruppo di inserzioni o per inserzione. Metti i campi dello sponsor condiviso in profile.partnership, mai in texts.common; un adCode va nell'import della riga oppure in un blocco attivo per inserzione o per gruppo di inserzioni. I valori pageId / instagramId del creator sono verifiche, non un modo per cambiare l'autore del post.

multiAdvertiserAds è true per impostazione predefinita; impostalo esplicitamente a false per disattivarlo. I valori delle CTA devono essere enum di Meta come SHOP_NOW o LEARN_MORE, non etichette come Shop Now, e una CTA non vuota richiede una destinazione http:// o https://. La didascalia organica non si può modificare. I blocchi di testo dei post importati supportano un titolo, CTA, link, tag URL, testimonianza, dichiarazione IA e la scelta multi-inserzionista. Ogni mappa di sostituzioni per inserzione o per gruppo di inserzioni supporta al massimo 200 voci.

Per i post importati, il CLI e l'MCP rifiutano le importazioni di post da Facebook, i batch che mescolano post importati e media caricati, le strutture carosello, flessibili e Multi Media, il raggruppamento per variazioni di posizionamento e le identità Threads. I media caricati supportano i normali formati creativi e i partner per riga. Anche nell'uploader web le nuove importazioni di post da Facebook al momento non sono supportate. Nell'uploader non c'è un browser dei post approvati; importa un URL Instagram autorizzato, un ID del post o un codice.

Per texts.mode: "perAd", usa come chiave di texts.perAd il mediaName. Per texts.mode: "perAdset", usa come chiave di texts.perAdset il nome o ID finale del gruppo di inserzioni oppure campaign::key. Il testo condiviso usa texts.common. adSet.groups[].media contiene quei nomi dei media; riutilizza una stessa riga di media in più gruppi invece di importare due volte la stessa origine.

Usa ads create:preview /dev/stdin --account act_123 per l'anteprima, poi ads create /dev/stdin --account act_123 --status PAUSED per creare. Passa i codici sensibili solo tramite stdin, mai come argomenti, stringhe di query o file salvati su disco. Fornisci di nuovo i codici alla creazione; i build salvati e l'output dell'anteprima li omettono. Usa --account oppure esegui prima ads account act_123, anche quando il JSON contiene accountId.

Gli admin possono eseguire ads create:test /dev/stdin --account act_123 --status PAUSED. Non crea inserzioni su Meta e riporta le chiamate metaValidation come superate, fallite o non controllate. Un rifiuto di Meta termina con codice di uscita 1. Le chiamate che richiedono ID simulati non vengono controllate; una validazione superata non garantisce la pubblicazione né l'aspetto finale. La Test Mode può salvare codici di autorizzazione crittografati e registri dei lanci.