> For the complete documentation index, see [llms.txt](https://help.citrusad.com/retail-media-interface/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.citrusad.com/retail-media-interface/partner/it/partner-api-overview/campaign-field-definitions.md). # Definizioni dei campi della campagna ## Campi comuni della campagna Questa sezione fornisce brevi descrizioni ed esempi per aiutarti a comprendere i campi comuni della campagna tra diversi tipi, come annunci prodotto, banner e banner X. Ogni voce include lo scopo del campo e un esempio di implementazione rappresentativo per la tua piattaforma. | Campo | Scopo ed esempio | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | Si consiglia di includere dettagli come il prodotto promosso, l'intervallo di tempo o la strategia, come 'Cadbury Chocolate June Clearance', per identificare facilmente la campagna. Il nome può contenere fino a 255 caratteri. | | `namespaceId` |

L'identificatore univoco del tuo namespace, situato nell'URL di base. Ad esempio, in exampleretailer.citrusad.com, il namespaceId is exampleretailer.

Assicurati che la risorsa esista per l'ID fornito come namespace.

| | `approval.state` |

Lo stato di approvazione della campagna può utilizzare solo valori enum specificati. Gli stati supportati sono APPROVAL\_STATE\_APPROVED, APPROVAL\_STATE\_REJECTED, APPROVAL\_STATE\_PENDING.

Nota cheAPPROVAL\_STATE\_UNSPECIFIED non può essere utilizzato.

| | `approval.rejectionReason` | Il motivo per cui una campagna è stata rifiutata. Questo è un campo obbligatorio se lo stato è `APPROVAL_STATE_REJECTED`. | | `campaignState` |

Lo stato attivo della campagna indica se è attiva, in pausa, una bozza o archiviata. Per esempio, CAMPAIGN\_STATE\_ACTIVE, CAMPAIGN\_STATE\_DRAFT, CAMPAIGN\_STATE\_UNSPECIFIED.

Nota che CAMPAIGN\_STATE\_UNSPECIFIED non può essere utilizzato.

| | `teamId` |

Il teamId è l'identificatore univoco del team della campagna.

Assicurati che la risorsa esista per l'ID team dato e non abbia il flag archiviato impostato. Inoltre, l'ID team del modello deve corrispondere all'ID team della campagna.

| | `startTime` |

L'ora di inizio della campagna utilizzando un timestamp ISO-8601 preciso. Per esempio, 2024-09-01T12:00:00Z.

Omettere questo valore per le campagne always on .

| | `endTime` |

L'ora di fine della campagna utilizza un timestamp ISO-8601 preciso e deve essere impostata se startTime è specificato. Per esempio, 2024-09-30T23:59:59Z. L'ora di fine deve essere successiva all'ora di inizio.

Omettere questo valore per le campagnealways on .

| | `walletId` |

L'identificatore univoco del wallet a cui addebitare la campagna, ad esempio, wallet\_123456789.

- If campaignType non è 'Wildcard', deve esistere un oggetto per l'ID.
- L'ID team del wallet deve corrispondere all'ID team della campagna.
- Il codice valuta del wallet deve corrispondere al codice valuta del catalogo della campagna. Se non ne sei sicuro, verifica con il tuo Customer Integration Engineer (CIE).

| | `placementId` |

L'identificatore univoco del posizionamento della campagna. Per esempio, placement\_987654321.

Assicurati che la risorsa esista per l'ID posizionamento dato e che corrisponda alla campagna corretta.

| | `catalogIds` |

L'identificatore univoco dei cataloghi del retailer. Per esempio, \["329f1e08-d3ee-4e04-90c4-068b3ce6b856","6c29a96a-f55a-497f-b03a-2fed85dd7198" ].

Assicurati che la risorsa esista per l'ID catalogo dato e che corrisponda alla campagna corretta.

| | `advertisedProducts.
productsByKey` |

Le combinazioni di codici prodotto e ID catalogo pubblicizzate nella campagna. Se una campagna appare in due cataloghi, fornire due abbinamenti catalogo-prodotto.

Per esempio, \[{"catalogId": "14edbbc5-a7be-4c54-9f35-767b4ee29fd3","productCode": "ABC123"}].

| | `targeting.searchTerms` | I termini di ricerca e i relativi tipi di corrispondenza a cui la campagna si rivolgerà. Includere queste informazioni solo per i posizionamenti di ricerca. Per esempio, `{"matchType": "MATCH_TYPE_EXACT_MATCH","phrase": "string"}`}. | | `targeting.excludeFilters` |

Filtri da escludere durante la fase di targeting, che dovrebbero essere solo filtri di posizione o categoria allineati con il tuo filterClassId. La maggior parte delle integrazioni può omettere questi valori. Se si utilizzano due classi di filtri, specificare un oggetto per classe di filtro:

{"excludeFilters": \[ \
{ \
"catalogId": "76df36b4-45a2-46a5-9308-3dd14861d76e", \
"filter": "category:chocolate" \
}, \
{ \
"catalogId": "76df36b4-45a2-46a5-9308-3dd14861d76e", \
"filter": "location:florida" \
} \
] \
}

| | `targeting.includeFilters` |

Filtri espliciti a cui indirizzare la campagna. Omettere questo campo per le integrazioni standard. Popolare questo campo solo se consigliato o quando si creano campagne a Canone fisso.

{"includeFilters": \[ \
{ \
"catalogId": "76df36b4-45a2-46a5-9308-3dd14861d76e", \
"filter": "category:flavoured-milk" \
} \
] \
}

| | `targeting.negativeSearchTerms` | I termini di ricerca negativi escludono parole o frasi specifiche dalla tua campagna, impedendo che i tuoi annunci vengano visualizzati in ricerche non pertinenti. Questa strategia affina il tuo pubblico, riduce i costi e aumenta l'efficienza della campagna. Ad esempio, aggiungere `used` come termine negativo per l'annuncio di un'auto nuova evita di mostrarlo a chi cerca auto usate. | | `targeting.crossSell` | Specifica il targeting sui posizionamenti di vendita incrociata (cross-sell). | | `targeting.crossSell.
targetProductsByKey` |

Specifica gli abbinamenti espliciti catalogo-prodotto a cui indirizzare la campagna.

\[{"catalogId": "14edbbc5-a7be-4c54-9f35-767b4ee29fd3","productCode": "ABC123"}]

- I cataloghi di prodotti target devono corrispondere ai cataloghi della campagna.
- Un prodotto deve esistere per ogni coppia prodotto-catalogo.
- I prodotti target non possono essere tra i prodotti pubblicizzati.
- I prodotti target e i prodotti pubblicizzati devono condividere categorie corrispondenti.

| | `targeting.upSell.
targetProductsByKey` |

Specifica gli abbinamenti espliciti catalogo-prodotto a cui indirizzare la campagna.

\[{"catalogId": "14edbbc5-a7be-4c54-9f35-767b4ee29fd3","productCode": "ABC123"}]

| | `strategy.auction.maxBid` |

L'offerta massima di costo per clic (CPC) della tua campagna. Per esempio, 2.99.

- Deve essere un BigDecimal valido.
- Deve essere superiore all'offerta minima.

},
"strategy": {
"auction": {
"maxBid": "string",
"spendLimit": {
"daily": "string",
"total": "string"
}
},

| | `strategy.auction.spendLimit` |

Specifica la spesa massima giornaliera o totale per una campagna.

Omettere questo valore per una campagna always on , che continuerà a spendere finché ci sono fondi nel wallet della campagna. Per esempio: "daily": "1000"." Assicurarsi che il limite di spesa sia un valore BigDecimal maggiore di 0.

},
"strategy": {
"auction": {
"maxBid": "string",
"spendLimit": {
"daily": "string",
"total": "string"
}
},

| | `strategy.fixedTenancy.cost` |

Rappresenta il costo totale della campagna, utilizzato solo a scopo di reportistica e non detratto dal wallet. Questo valore può essere aggiornato se il retailer ottimizza l'intero pacchetto o ordine di inserimento (IO). Per esempio: 1000.99.

"fixedTenancy": {
"cost": "1000.99",
"positions": \[
0
],
"catalogCosts": \[
{
"catalogId": "string",
"catalogCostPercentage": 0
}
]
}

| | `strategy.fixedTenancy.
catalogCostPercentage` |

Un valore compreso tra 0 e 1 che indica la porzione del costo allocata a ciascun catalogo. Se si utilizzano più cataloghi, allocare una porzione (ad es. 0.5). Per un singolo catalogo, utilizzare il valore 1.

"fixedTenancy": {
"cost": "string",
"positions": \[
0
],
"catalogCosts": \[
{
"catalogId": "string",
"catalogCostPercentage": 0.5
}
]
}

| | `strategy.fixedTenancy.
fixedCosts` |

Specifica costi aggiuntivi per dati esterni, lavoro grafico/creativo o altri servizi relativi alla campagna. Addebiti applicati una volta approvata la campagna e non modificabili. Omettere a meno che non siano applicabili costi aggiuntivi al tuo inserzionista.

{
"dataCost": "150",
"creativeCost": "200",
"otherCost": "400"
}

| | `fixedCosts.dataCost` | Il costo associato ai dati per la campagna. Ad esempio, $100.00. | | `fixedCosts.creativeCost` | Il costo associato alla produzione del materiale creativo per la campagna. Ad esempio, $200.00. | | `fixedCosts.otherCost` | Il costo associato ad altre spese per la campagna. Ad esempio, $50.00. | | `customFields.customFieldId` |

Specifica il customFieldId univoco in corso di configurazione. I campi personalizzati non sono richiesti in un'integrazione standard ed è probabile che questo campo non venga utilizzato se non consigliato dal Customer Integration Engineer (CIE).

{
"customFieldId": "3e31d3e4-bf15-411b-a18e-5553f08a6122",
"content": "PO-12345"
}

| | `customFields.content` |

Il contenuto del campo personalizzato per la campagna.

{
"customFieldId": "3e31d3e4-bf15-411b-a18e-5553f08a6122",
"content": "PO-12345"
}

| | `customQuestions.customQuestionId` |

Specifica la domanda di targeting personalizzata univoca in corso di configurazione. Le domande personalizzate non sono richieste in un'integrazione standard ed è probabile che questo campo non venga utilizzato se non consigliato dal Customer Integration Engineer (CIE).

{
"answers": \[
"preference:delivery",
"preference:online"
],"customQuestionId": "593a9860-5ce4-4dcc-b6c4-15cf6fb08426"
}

| | `customQuestions.answers` |

Specifica le risposte selezionate dagli inserzionisti per il targeting dei clienti. Deve essere allineato con il cliente targetingData valori.

{
"answers": \[
"preference:delivery",
"preference:online"
],"customQuestionId": "593a9860-5ce4-4dcc-b6c4-15cf6fb08426"
}

| ## Banner X campi campagna | Campo | Scopo ed esempio | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `contentStandardId` |

Un identificatore univoco per lo standard di contenuto. Gli standard di contenuto sono linee guida e parametri tecnici che dettano come un annuncio banner debba essere visualizzato all'interno di uno spazio designato su un sito web o una piattaforma digitale.

Questo identificatore è necessario per verificare che l'asset banner X creato rispetti gli standard di contenuto del rivenditore.

| | `slotId` | Un identificatore univoco per lo slot nella configurazione, come 'homepage\_banner\_slot\_1'. Questo identificatore assicura che il banner utilizzi lo slot corretto definito dal rivenditore, come tile singola, tile doppia o banner. | | `slotType` | Lo slot univoco all'interno dello standard di contenuto in cui verrà posizionata l'immagine. Assicura che l'immagine rispetti i requisiti e le convalide dello slot predefiniti. Gli esempi includono left\_ribbon, top\_banner o side\_panel. | | `headingText` | Il testo dell'intestazione per il banner. | | `bannerText` | Il testo del banner è il testo visualizzato sul tuo annuncio banner. | | `bannerTextColourHex` | Il colore del testo del banner in formato esadecimale. | | `ctaFlag` | Un flag che indica se il banner ha una call-to-action abilitata. | | `ctaText` | Il testo della call-to-action sul banner. Una call-to-action (CTA) è un testo o pulsante cliccabile che invita gli utenti ad agire, come effettuare un acquisto o visitare un'altra pagina. Ad esempio, "Acquista ora". | | `ctaTextAccessibility` | Il testo della call-to-action ai fini dell'accessibilità. | | `ctaLink` | L'URL per il link della call-to-action. | | `backgroundColourHex` | Il colore dell'immagine di sfondo principale del banner X in formato esadecimale. | | `backgroundImageId` | Questo è l'identificatore univoco dell'immagine di sfondo principale. | | `backgroundImagePosition` | L'allineamento o la posizione dell'immagine di sfondo principale all'interno del suo contenitore. | | `secondaryBackgroundImageId` | L'identificatore univoco per l'immagine di sfondo secondaria. | | `secondaryBackgroundImagePosition` | L'allineamento o la posizione dell'immagine di sfondo secondaria all'interno del suo contenitore. | | `heroImageId` | L'identificatore univoco per l'immagine hero. L'immagine hero è l'immagine promozionale principale, in genere utilizzata per mostrare il prodotto o il logo. | | `heroImageAltText` | Il testo alternativo per l'immagine hero, per facilitare l'accessibilità. | | `heroMode` | La modalità o lo stile di visualizzazione della sezione hero. | | `secondaryHeroImageId` | L'identificatore univoco per l'immagine hero secondaria. | | `secondaryHeroImageAltText` | Il testo alternativo per l'immagine hero secondary, per facilitare l'accessibilità. | | `secondaryHeroMode` | La modalità o lo stile di visualizzazione della sezione hero secondaria. | | `trackingTags` | Un array obbligatorio di oggetti utilizzato per specificare i provider di tracciamento e i tag associati per monitorare e analizzare le prestazioni di una campagna banner X. | | `additionalFields` | Un array obbligatorio di oggetti che fornisce opzioni di configurazione aggiuntive per banner X. | ## Campi della campagna banner | Campo | Scopo ed esempio | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `contentStandardId` |

Un identificatore univoco per lo standard di contenuto. Gli standard di contenuto sono linee guida e parametri tecnici che dettano come un annuncio banner debba essere visualizzato all'interno di uno spazio designato su un sito web o una piattaforma digitale.

Questo identificatore è necessario per verificare che l'asset banner creato rispetti gli standard di contenuto del rivenditore.

| | `slotId` | Un identificatore univoco per lo slot nella configurazione, come 'homepage\_banner\_slot\_1'. Questo identificatore assicura che il banner utilizzi lo slot corretto definito dal rivenditore, come tile singola, tile doppia o banner. | | `artworkImageId` | Un identificatore univoco per l'immagine grafica caricata per il banner. Questo ID (fileId) viene restituito dall'API Upload the creative assets. | | `link` | Questo è l'URL collegato allo slot banner, che indirizza gli utenti a una pagina di destinazione quando fanno clic sull'annuncio. Esempio: | | `altText` | Testo alternativo che descrive l'immagine grafica ai fini dell'accessibilità. Esempio: 'Banner promozionale per i saldi estivi'. | | `text` | Testo di visualizzazione sul banner. Il testo di visualizzazione per lo slot, che fornisce informazioni aggiuntive o un messaggio. Esempio: 'Ottieni il 20% di sconto sul tuo primo acquisto!' | | `trackingTags` | Un elenco di tag di tracciamento del provider, utilizzato per monitorare le interazioni con lo slot. Esempio: \[ { provider: 'Google Analytics', tag: 'promo\_click' }, { provider: 'Adobe Analytics', tag: 'banner\_view' } ]. Questi tag sono inclusi nel tuo annuncio per la verifica da parte di terze parti. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.citrusad.com/retail-media-interface/partner/it/partner-api-overview/campaign-field-definitions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.