> 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/integration/it/reporting/reporting-faq.md). # Domande frequenti ### L'API di reporting è sicura? Tutti i dati archiviati in BigQuery sono crittografati a riposo e in transito. Ciò significa che quando i dati sono archiviati sui server di Google e quando vengono trasmessi tra tali server e il client, sono protetti da una crittografia avanzata. Inoltre, BigQuery dispone di controlli di accesso integrati che consentono di limitare l'accesso ai dati in base ai ruoli e alle autorizzazioni dell'utente. Ciò significa che specifichiamo esattamente chi ha accesso ai dati e quali azioni è autorizzato a eseguire su di essi. BigQuery supporta anche l'autenticazione e l'autorizzazione tramite meccanismi standard come OAuth 2.0 e chiavi API. L'infrastruttura di Google è progettata per proteggere da minacce comuni come attacchi denial of service, violazioni dei dati e accessi non autorizzati. Questo viene fatto utilizzando varie misure di sicurezza come firewall, sistemi di rilevamento delle intrusioni e audit di sicurezza regolari, e l'API di BigQuery è progettata tenendo conto della sicurezza e impiega una serie di misure per garantire che i tuoi dati siano sempre protetti. ### Con quale frequenza vengono aggiornati i dati? Quotidianamente. L'aggiornamento inizia a mezzanotte UTC+0 con un tempo massimo di aggiornamento di 12 ore. L'aggiornamento copre tutti i dati ricevuti fino alla mezzanotte (UTC+0) del giorno precedente. ### A quanto tempo fa risalgono i dati? Saranno disponibili tutti i dati storici approvati per una determinata organizzazione. ### Se sono un utente Direct Access, come mi connetto? Essendo già in GCP, sarà semplicissimo. Basta accedere e provare a interrogare le tabelle pertinenti tramite l'interfaccia utente o l'API.
Insights IAM UI
#### Ricevo l'errore "User does not have bigquery.jobs.create permission in project" – cosa sto sbagliando? Per gli account che ci hai fornito, Epsilon Retail Media ha concesso i privilegi di visualizzatore BigQuery ai dataset pertinenti. Questo ti permetterà di leggere le tabelle al loro interno. Nel tuo progetto, devono accadere alcune cose per poter interrogare effettivamente queste tabelle remote. Assumiamo quanto segue: * Il tuo progetto = "client-project-123456" * Il tuo utente = * Epsilon Retail Media dataset: "insight-platform-external-iam.client\_insight\_reporting" Devi: 1. Concedere a l'autorizzazione bigquery.jobs.create all'interno del progetto client-project-123456 (non del progetto Epsilon Retail Media ). Puoi farlo assegnando il ruolo Utente job BigQuery. 2. Durante l'esecuzione di una query, devi eseguire la query all'interno del tuo progetto (poiché disponi solo delle autorizzazioni per leggere il dataset all'interno del progetto Epsilon Retail Media , non per eseguire query al suo interno). Ecco come potrebbe accadere utilizzando un semplice esempio di comando cloud shell (in esecuzione come ): ```bash bq query --use_legacy_sql=false --project_id client-project-123456 'SELECT * FROM insight-platform-external-iam.client_insight_reporting.campaign limit 10;' ``` Nota che il progetto client è impostato sul tuo progetto, non su insight-platform-external-iam. Un approccio simile deve essere adottato con qualsiasi altro strumento utilizzato. Fai riferimento alla documentazione dello strumento fornito per ulteriori informazioni e alla documentazione online di GCP per suggerimenti! #### I dati Epsilon Retail Media non sono nella mia posizione, come posso portare i dati nella mia posizione? Ci sono molte possibilità, ma è facile creare semplicemente dataset nella stessa posizione dei nostri, quindi eseguire trasformazioni, query ecc., in tabelle all'interno di tali dataset, e poi copiarli nella posizione preferita.
Location Guide
Esistono molti modi per copiare tra posizioni utilizzando l'interfaccia utente, lo strumento da riga di comando BQ e l'API stessa. Per ulteriori informazioni, fai riferimento a queste pagine della documentazione di Google Cloud: * [Manage datasets | BigQuery](https://cloud.google.com/bigquery/docs/managing-datasets) * [Riferimento per lo strumento da linea di comando bq](https://cloud.google.com/bigquery/docs/bq-command-line-tool) * [Copia una tabella da sorgente singola](https://cloud.google.com/bigquery/docs/copying-datasets) ### Se sono un utente API non GCP, come mi connetto? Epsilon Retail Media ti fornirà le credenziali pertinenti in un JSON che potrai incorporare nel tuo meccanismo di autenticazione. ### Posso eseguire il debug delle query utilizzando solo l'API di reporting (non l'interfaccia utente di BigQuery)? Sì, l'API di BigQuery restituirà un codice che indica se si è verificato un problema e saranno disponibili anche i messaggi di errore. ### Posso stimare quanto sarà costosa una query? Sì, l'API dispone di un meccanismo per ottenere una stima dei byte che la query scansionerà se eseguita. Puoi utilizzare tale stima moltiplicata per la frequenza con cui chiami la query per capire quanto ti avvicinerai alla quota. Maggiori informazioni sono disponibili nella documentazione di GCP. [Dry run query | BigQuery | Google Cloud](https://cloud.google.com/bigquery/docs/samples/bigquery-query-dry-run) ### E se supero il limite di quota? Fai riferimento al tuo contratto con Epsilon Retail Media per capire qual è la tua quota. Se non specificamente definita, verrà impostata di default su 10 TB di scansioni dati query al mese. Il tuo contratto potrebbe anche prevedere un numero massimo di chiamate API al giorno. Se non è specificamente definito, verrà impostato di default su 100 chiamate API al giorno. Nel caso in cui superi la quota (sia per la scansione dei dati sia per il numero di chiamate), ti contatteremo per comprendere i tuoi casi d'uso. Potrebbero essere applicati costi per eccedenza a seconda del tuo contratto. In caso di grave abuso al di fuori dei termini del contratto (o dei limiti predefiniti), ci riserviamo il diritto di sospendere l'accesso. ### Qual è un esempio di utilizzo dell'API di reporting? Di seguito sono riportati alcuni esempi che utilizzano metodi comuni. #### Google SDK per Python Questo esempio permetterà di: 1. Connettersi a BigQuery 2. Eseguire la query 3. Inviare il risultato a un file csv ```python import google.cloud.bigquery as bq import pandas as pd bq_client = bq.Client.from_service_account_json(".json") job_config = bq.QueryJobConfig(allow_large_results=True) query_job = bq_client.query( 'SELECT count(1) FROM insight-platform-external-iam._insight_reporting.campaign LIMIT 1000', job_config=job_config) df = query_job.to_dataframe(create_bqstorage_client=False) df.to_csv(r"C:\Users\\.csv", index=False) print("Run Complete") ``` Sono disponibili altri metodi per stimare i byte scansionati ecc. prima di eseguire la query. Fai riferimento alla documentazione di BigQuery [BigQuery API | Google Cloud](https://cloud.google.com/bigquery/docs/reference/rest) Se non ci si trova in GCP, è possibile fare riferimento a un file di credenziali JSON tramite una variabile di ambiente. #### API generica per Python ```python import csv import requests from google.oauth2 import service_account PROJECT_ID = "insight-platform-external-iam" DATASET = "" END_POINT = f"https://bigquery.googleapis.com/bigquery/v2/projects/{PROJECT_ID}/queries" QUERY = f""" SELECT supplier_id, campaign_id, sum(ad_spend) as ad_spend, sum(clicks) as clicks FROM `{PROJECT_ID}.{DATASET}.realised_ad_agg` WHERE ingressed_at BETWEEN '2022-09-01' and '2022-12-31' group by 1,2 """ def get_token(): # With service account credentials = service_account.Credentials.from_service_account_file('./secrets/service-account.json') scoped_credentials = credentials.with_scopes(['https://www.googleapis.com/auth/cloud-platform']) # Do token request def req( method, url, headers, body, **kwargs): resp = requests.post(url, headers=headers, data=body) return type('obj', (object,), {'data' : resp.text, 'status': 200}) scoped_credentials.refresh(req) return scoped_credentials.token def run_job(token): resp = requests.post( END_POINT, json={ "query": QUERY, "useLegacySql": False }, headers={ "Content-Type": "application/json", "Authorization": f"Bearer {token}" } ) return resp.json()['jobReference']['jobId'] def get_query_results(job_id, token): status_endpoint = f'{END_POINT}/{job_id}?location=australia-southeast1' completed = False while not completed: response = requests.get(status_endpoint, headers={ "Content-Type": "application/json", "Authorization": f"Bearer {token}" }) completed = response.json()['jobComplete'] data = response.json() rows = data['rows'] columns = [c['name'] for c in data['schema']['fields']] return rows, columns def extract(): token = get_token() job_id = run_job(token) rows, columns = get_query_results(job_id, token) with open('results.csv', 'w', newline='') as f: writer = csv.writer(f) writer.writerow(columns) for row in rows: writer.writerow([i['v'] for i in row['f']]) extract() ``` ### E se sono in AWS ecc. e non in Google Cloud, posso comunque autenticarmi e utilizzare l'API? Sì, funzionerà. Forniremo le credenziali dell'account di servizio e potrai farvi riferimento nella tua applicazione. Ecco un esempio. ```python # TODO(developer): Set key_path to the path to the service account key # file. # key_path = "path/to/service_account.json" credentials = service_account.Credentials.from_service_account_file( key_path, scopes=["https://www.googleapis.com/auth/cloud-platform"], ) token = credentials.token # use the token to do the API calls # ... # headers: Bearer ${token} # ... ``` ### Come posso determinare qual è la posizione di ciascun dataset condiviso con me? Questa chiamata API ti dirà in quale posizione si trova ciascun dataset. `GET https://bigquery.googleapis.com/bigquery/v2/projects/insight-platform-external-iam/datasets` ```json { "kind": "bigquery#datasetList", "etag": "RLU1Ww9C5FdhlcIuRHjW0A==", "datasets": [ { "kind": "bigquery#dataset", "id": "insight-platform-external-iam:acme_insight_reporting", "datasetReference": { "datasetId": "acme_insight_reporting", "projectId": "insight-platform-external-iam" }, "location": "australia-southeast1" }, { "kind": "bigquery#dataset", "id": "insight-platform-external-iam:acme_acme_analytics", "datasetReference": { "datasetId": "acme_acme_analytics", "projectId": "insight-platform-external-iam" }, "location": "us-central1" } ] } ``` ### Qualche consiglio sulle migliori pratiche? In generale, se intendi fare un uso frequente dei dati, in particolare se disponi dell'accesso ai dati non aggregati (richieste/annunci realizzati/ordini/attribuzione avanzata ecc.), è consigliabile copiare (effettuare lo staging de) le tabelle nel tuo data warehouse, QUINDI implementare su tali copie le query per la logica di business richiesta. Gli utenti con esigenze minori possono semplicemente scegliere di interrogare direttamente le tabelle per risultati specifici. È importante rimanere al di sotto della quota consentita per garantire un funzionamento ottimale. Nota anche che ogni query può scaricare un massimo di 1 GB, altrimenti verrà ricevuto un messaggio di errore. Nel caso in cui sia necessario un download di dimensioni molto elevate, esegui una serie di query più piccole (ad es. un sottoinsieme di dati al giorno o per fornitore ecc.). ### E se ho bisogno di aiuto per creare istruzioni SQL appropriate? Apri un ticket specificando la query che stai tentando di eseguire e potremo aiutarti a revisionarla: ti risponderemo con eventuali commenti. ### Qualche consiglio per l'uso del pacchetto Pandas? Pandas è uno degli strumenti di analisi più popolari. Per farlo funzionare, è necessario installare le dipendenze pandas-gbq e pydata-google-auth. Lo snippet seguente è un esempio funzionante di come leggere i dati da una tabella BigQuery. ```python import pandas as pd from google.oauth2 import service_account credentials = service_account.Credentials.from_service_account_file('path/to/the/credential/file') query = 'select * from project.dataset.table' dat = pd.read_gbq( query, project_id='project_id', credentials=credentials ) ``` Maggiori informazioni sulla funzione Pandas sono disponibili [qui](https://pandas.pydata.org/docs/reference/api/pandas.read_gbq.html). ### Qualche consiglio per l'uso del pacchetto PySpark? Presupponendo che tu disponga di un ambiente PySpark funzionante, devi fornire il file jar corretto per il connettore BigQuery appropriato alla tua versione di PySpark. Ad esempio, PySpark 3.2.\* richiede spark-3.2-bigquery-0.30.0.jar. L'elenco dei file jar, nonché snippet di codice pratici e parametri, sono disponibili [qui](https://github.com/GoogleCloudDataproc/spark-bigquery-connector). Lo snippet di codice sottostante fornisce un esempio di come eseguire una query. ```python from pyspark.sql import SparkSession spark = SparkSession.builder.appName('BigNumeric').config('spark.jars', 'spark-3.2-bigquery-0.30.0.jar').getOrCreate() spark.conf.set('credentialsFile', 'path/to/the/credential/file') spark.conf.set('viewsEnabled', 'true') spark.conf.set('materializationProject', 'yourMaterializationProject') spark.conf.set('materializationDataset', 'yourMaterializationDataset') query = 'select * from project.dataset.table' df = spark.read.format('bigquery').option('query', query).load() df.show() ``` IMPORTANTE: il parametro viewsEnabled deve essere true. I dati nelle viste vengono materializzati in tabelle temporanee prima di essere letti da PySpark, dove è autorizzata la permessa bigquery.tables.create. Pertanto è necessario fornire materializationProject e materializionDataset in cui l'utente disponga dell'accesso in scrittura. ### Ricevo un errore che richiede un filtro nella query? Per una tabella partizionata il filtro è obbligatorio, senza il quale verrà restituito un messaggio di errore come quello sottostante: > Impossibile eseguire la query sulla tabella 'dataset\_id.table\_id' senza un filtro sulla/e colonna/e 'partitioned\_column' che possa essere utilizzato per l'eliminazione della partizione Per risolvere l'errore, aggiungi semplicemente un filtro ragionevole che copra l'intervallo target, ad es. ```sql -- this query returns all records available since yesterday select * from dataset_id.table_id where ingressed_at >= date_sub(current_date, interval 1 day) ``` Per individuare rispetto a quale colonna la tabella è partizionata (come ingressed\_at nell'esempio sopra), consulta la descrizione della tabella data. ### Come posso richiedere l'accesso? #### Procedura È necessario aprire un ticket e accettare per iscritto i criteri di idoneità. Lavoreremo con il potenziale Candidato per identificare il livello di accesso e le impostazioni di sicurezza richiesti e determinare quali quote e costi potrebbero essere applicati. #### Criteri di idoneità Un Candidato deve soddisfare i seguenti Criteri per essere considerato idoneo all'accesso alla Reporting API: - **Generale** 1. Il Candidato può richiedere l'accesso solo ai dati per Epsilon Retail Media namespace e team di cui è già membro o a cui ha accesso generale. Il Candidato deve specificare per quale dei seguenti scenari sta presentando domanda (e fornire prova dell'accesso esistente): 1. Livello ambiente (un'intera implementazione della Epsilon Retail Media piattaforma è dedicata al Candidato). 2. Livello Namespace (il Candidato ha il permesso di visualizzare tutti i team, sia retailer che fornitore, all'interno di un singolo Namespace o elenco di Namespace). 3. Livello ID team Retailer specifico o livello gruppo. 4. Livello ID team Fornitore specifico o livello gruppo. 1. inoltre, un Integratore può accedere a uno specifico ID team Fornitore o livello gruppo PIÙ i Cataloghi Prodotti Retailer completi, ove concordato con un Retailer caso per caso. 2. I dati Transazionali Fact possono essere forniti solo ai Candidati idonei per i Criteri Generali 1a o 1b. 3. Ai Candidati che non si qualificano per i dati transazionali Fact verrà fornito l'accesso solo ai dati Fact pre-aggregati. I dati saranno aggregati in riepiloghi giornalieri (con UTC+0 come fuso orario di aggregazione). 4. I Candidati idonei solo per i Criteri Generali 1d non possono ricevere dati sulle Ad Request (a differenza dei dati sulle Realised Ad che verranno forniti). I dati sui Prodotti verranno forniti per i Prodotti specifici pubblicizzati nelle Realised Ad dal Fornitore ECCETTO per gli Integratori che potrebbero ricevere i Cataloghi Prodotti Retailer ove concordato con un Retailer caso per caso. 5. È garantito che i dati Dimensionali includano solo le versioni correnti dei record in questione. Si prevede che il tracciamento delle modifiche storiche venga implementato dal Candidato in base alle proprie esigenze. 6. I dati vengono aggiornati quotidianamente ed entro e non oltre le 12:00 UTC+0 per i dati fino al giorno UTC+0 precedente completato incluso. 7. Resta inteso che l'accesso è di sola lettura per sua natura. L'API non deve essere utilizzata per creare oggetti nel nostro data warehouse per alcuno scopo. 8. Qualsiasi combinazione con altre fonti di dati deve essere effettuata nell'ambiente del Candidato. 9. Il Candidato deve avere a disposizione un SDK (o equivalente) per accedere all'API Google BigQuery. 10. Il Candidato ha una buona conoscenza di SQL. 11. Il Candidato avrà familiarità con i concetti di Epsilon Retail Media e, in caso contrario, prenderà accordi affinché la formazione standard sul prodotto venga fornita tramite il proprio Customer Support Manager o Technical Account Manager. 12. In base ai documenti forniti, si prevede che il Candidato sviluppi le proprie soluzioni. Se si riscontra un problema con un SQL che non si comporta come previsto secondo la documentazione, è necessario aprire un ticket tramite i consueti canali di supporto. Devono essere fornite le seguenti informazioni. 1. L'account tramite il quale viene effettuata la connessione. 2. L'esatto SQL richiamato. 3. Una descrizione dettagliata dei messaggi di errore riscontrati. 13. Se il Candidato è un Retailer, è necessario che Impression/Click/Ordini vengano forniti alla Epsilon Retail Media piattaforma in modo da poter stabilire un quadro completo del ciclo di vita dell'Annuncio. 14. Di tanto in tanto, Epsilon Retail Media si riserva il diritto di modificare lo schema. In genere, queste modifiche comportano l'aggiunta di nuove colonne a tabelle e viste esistenti e saranno retrocompatibili. I candidati devono strutturare il proprio codice SQL specificando i nomi delle colonne anziché utilizzare caratteri jolly, ecc. Nel caso in cui una modifica comporti la deprecazione di una colonna o tabella, Epsilon Retail Media fornirà un preavviso di almeno 12 settimane prima che la modifica venga implementata. Le notifiche avverranno tramite le comunicazioni standard sulle release inviate agli utenti della piattaforma. Non è obbligatorio che un candidato sia già un utente di Google Cloud Platform (GCP); tuttavia, sussistono ulteriori criteri a seconda che il candidato sia un utente GCP o non GCP. **Candidato non GCP** Salvo diversamente concordato, Epsilon Retail Media fornirà al candidato le credenziali per un singolo account di servizio all'interno del nostro ambiente. Salvo diversamente concordato, si applicano le seguenti condizioni predefinite: 1. Un massimo di 100 chiamate API al giorno. 2. Non più di 10 TB di scansioni dati al mese (nota: l'API dispone di un modo per stimare la dimensione della scansione della query prima dell'esecuzione, fare riferimento alla documentazione di Google [Dry run query | BigQuery | Google Cloud](https://cloud.google.com/bigquery/docs/samples/bigquery-query-dry-run)). 3. Se i Criteri 1 e/o 2 del candidato non GCP vengono superati, Epsilon Retail Media si riserva il diritto di sospendere l'accesso a propria esclusiva discrezione. 4. Nessuna singola chiamata API può scaricare più di 1 GB di dati alla volta. #### Come si decodifica il file dell'account di servizio? Le credenziali dell'account di servizio ti verranno fornite in un formato codificato in base64 per una trasmissione sicura. Dovrai decodificarle prima di utilizzarle. Ecco alcuni esempi su come decodificare il file: Utilizzando bash: ```bash # Replace encoded-credentials.txt with the file containing your base64 encoded credentials base64 -d encoded-credentials.txt > service-account.json ``` Utilizzando Python: ```python import base64 # Replace encoded_credentials with your base64 encoded string with open('encoded-credentials.txt', 'r') as f: encoded_credentials = f.read() decoded_credentials = base64.b64decode(encoded_credentials) with open('service-account.json', 'wb') as f: f.write(decoded_credentials) ``` Dopo la decodifica, avrai un `service-account.json` file che potrai utilizzare con le librerie client di BigQuery come mostrato negli esempi precedenti. **Candidato GCP** Salvo diversamente concordato, il candidato fornirà Epsilon Retail Media i dettagli di non più di 5 account GCP in modo che possiamo assegnare l'accesso richiesto. Tieni presente che all'account deve essere assegnato il ruolo Utente job BigQuery (roles/bigquery.jobUser). Si applicano le seguenti restrizioni: 1. Un massimo di 100 chiamate API al giorno. 2. Se il Criterio 1 del candidato GCP viene superato, Epsilon Retail Media si riserva il diritto di sospendere l'accesso a propria esclusiva discrezione. 3. Nessuna singola chiamata API può scaricare più di 1 GB di dati. ### Glossario #### Ambiente Il nome dell'ambiente fisico in cui la Epsilon Retail Media piattaforma è distribuita. Ciascuno ospita uno o più namespace. #### Namespace Un raggruppamento logico di tutte le entità che fanno parte di un'implementazione della Epsilon Retail Media soluzione. Include i team e tutti gli oggetti di proprietà dei team. In genere, un namespace può essere composto da un retailer (team) e da più fornitori (team) insieme agli utenti per ciascun team e ad altre configurazioni correlate (i retailer possiedono i cataloghi, i fornitori configurano le campagne, ecc.). I team (e ciò che possiedono) appartengono esclusivamente a un singolo namespace (nessun team può esistere su più namespace). #### Utente Identificativo univoco di un utente nel Epsilon Retail Media sistema. Una singola e-mail può avere più userId. Ciascun userId è univoco per namespace. Ogni utente avrà un nome, un cognome, un'e-mail e un ID. Un utente può essere membro e accedere a più team nella Epsilon Retail Media piattaforma. #### Team Un team all'interno del Epsilon Retail Media sistema. Può essere un fornitore (inserzionista) o un retailer. I team di fornitori creano in genere campagne, i retailer le esaminano ed eseguono funzioni amministrative. Un utente nel Epsilon Retail Media sistema può essere membro di molti team o di uno solo. Un team avrà in genere utenti, campagne e wallet associati. #### Fornitore Un team di fornitori all'interno del Epsilon Retail Media sistema. Un fornitore potrebbe essere tipicamente una società madre di un brand o una serie di team per ogni singolo brand. I fornitori di solito gestiscono campagne, amministrano i saldi dei wallet, ecc. #### Retailer Un team di retailer all'interno del Epsilon Retail Media sistema. La maggior parte dei namespace avrà un solo team di retailer. I retailer di solito mantengono i cataloghi dei prodotti, esaminano le campagne, ecc. #### Campagna Una singola campagna univoca configurata con un posizionamento e una strategia di targeting per una specifica selezione di prodotti. Ad esempio, una campagna nel Epsilon Retail Media sistema potrebbe promuovere i prodotti A e B indirizzandosi ai termini di ricerca 'cioccolato' e 'cioccolatini' con un'offerta massima di $ 0.60. Un singolo team ha in genere molte campagne. #### Catalogo Un catalogo prodotti univoco di un retailer nel Epsilon Retail Media sistema. È tipico per un retailer sincronizzare un solo catalogo prodotti con Epsilon Retail Media in un singolo namespace. Un catalogo conterrà un elenco di tutti i prodotti presenti nel catalogo del retailer, il loro nome, brand, categorie e altri attributi rilevanti che vengono inseriti nel Epsilon Retail Media sistema. #### Prodotto Un singolo prodotto univoco nel Epsilon Retail Media sistema. Un prodotto avrà un codice prodotto univoco sincronizzato nel catalogo prodotti. Un prodotto può avere attributi quali categoria, tassonomia, brand, ecc. #### Wallet Un wallet nel Epsilon Retail Media sistema memorizza i fondi di un inserzionista allo scopo di effettuare pagamenti (ad es. per pagare gli annunci realizzati). Ogni wallet ha un unico codice valuta e può spendere solo per i cataloghi della stessa valuta. Un wallet è di proprietà di un team. Un team può avere un qualsiasi numero di wallet. Un wallet può essere archiviato. L'archiviazione di un wallet lo mostrerà/nasconderà soltanto nella piattaforma; un wallet archiviato può ancora spendere crediti. #### Registro Un registro di eventi che hanno portato a una transazione nel Epsilon Retail Media sistema. Più comunemente si tratta di eventi pubblicitari come impression o clic per prodotti sponsorizzati o annunci banner (che comportano un addebito). Possono essere anche ricariche e modifiche ai saldi da parte di un fornitore (accrediti). Ogni evento avrà una 'causale' come Prodotti Sponsorizzati, Annunci Banner, Ricarica. #### Richiesta Una richiesta inviata al Epsilon Retail Media sistema per gli annunci. Nella richiesta il retailer specifica un posizionamento e un contesto, come ad esempio il contesto di un cliente sessionId o filtri rilevanti per la richiesta. A seconda della richiesta, Epsilon Retail Media invierà al retailer annunci di un AdType pertinente (ad es. Categoria o Termine di ricerca) da mostrare al cliente. #### Annuncio (realizzato) Un annuncio è un singolo evento pubblicitario inviato a un retailer affinché lo mostri al proprio cliente. Diventa un annuncio realizzato quando il retailer restituisce la conferma che l'annuncio ha ricevuto almeno un'impression (conferma esplicita che l'annuncio è stato effettivamente utilizzato, ovvero realizzato). Nel Epsilon Retail Media sistema, ogni annuncio avrà un ID realisedad univoco che funge da riferimento per quel singolo evento univoco. #### Categoria Una categoria è una pagina sul sito del retailer che fa parte della tassonomia del sito web, come 'Panetteria' o 'Latticini'. In genere, un retailer richiede annunci su una pagina di categoria e specifica questo attributo rilevante nella sua richiesta a Epsilon Retail Media. If Epsilon Retail Media ha campagne attive e valide per la Categoria, verranno restituiti degli annunci. #### SearchTerm Un termine di ricerca inserito da un cliente sul sito web del retailer. Questo termine di ricerca viene poi inviato a Epsilon Retail Media per richiedere annunci pertinenti. Se Epsilon Retail Media ha campagne attive e valide per il termine di ricerca, verranno restituiti degli annunci. #### Ordine Un ordine univoco nel sistema del retailer sincronizzato con Epsilon Retail Media. Un singolo ordine può contenere più articoli (proprio come il carrello di un cliente può contenere più articoli). Una volta completato l'ordine del cliente, questi dati vengono inviati a Epsilon Retail Media per alimentare l'attribuzione di Epsilon Retail Media. Il ritorno sulla spesa pubblicitaria (ROAS) e altri KPI importanti possono quindi essere forniti a retailer e inserzionisti. #### Attribuzione L'attribuzione è un processo gestito nel sistema Epsilon Retail Media che assegna gli annunci erogati a un cliente a un ordine inviato. Il percorso tipo di un cliente prevede la visualizzazione di un annuncio (impression), il clic su di esso (clic), l'aggiunta al carrello e l'acquisto dell'articolo (conversione). L'ordine viene 'attribuito' all'annuncio univoco su cui il cliente ha fatto clic. Affinché un ordine venga attribuito nel sistema Epsilon Retail Media , il cliente deve aver interagito con l'annuncio (visto o cliccato a seconda dell'integrazione) e deve aver successivamente acquistato un articolo pertinente all'annuncio. Epsilon Retail Media utilizza in genere un 'sessionId' per attribuire gli ordini agli annunci, in cui il retailer specifica un 'sessionId' in tutti i touchpoint rilevanti del percorso di un annuncio. È così che Epsilon Retail Media è in grado di identificare che un singolo annuncio, erogato a un singolo cliente, ha generato uno specifico ordine. #### Date Tutti i dati vengono convertiti nel fuso orario UTC+0 se aggregati. #### Cap Le implementazioni della piattaforma Epsilon Retail Media comportano spesso che il retailer richieda più annunci di quanti ne verrebbero realisticamente mai visualizzati (realizzati). Da una prospettiva di analisi, ciò potrebbe fornire un'impressione imprecisa delle reali prestazioni di determinate metriche. Ad esempio, se è stata effettuata una richiesta per 20 annunci (AdType=Product) e la piattaforma ha erogato 2 annunci in risposta, ciò rappresenta un 'fill rate' del 10% sulla richiesta (2 su 20). Tuttavia, se si comprende che nella pratica è probabile che verranno mai utilizzati (realizzati) solo 4 annunci, sarebbe preferibile interpretarlo come coperto al 50% (2 su 4). Da qui la nozione di capping all'interno del reporting. Il capping viene impostato per retailer, con un cap disponibile per gli annunci di prodotto e un altro per gli annunci banner (poiché le richieste di annunci di prodotto in genere richiedono e utilizzano molti più annunci rispetto ai banner). Tornando all'esempio, se il cap di prodotto = 4 per il retailer, le metriche della richiesta verrebbero riportate come segue:- NumAdRequests = 1 NumAdsRequested = 20 CappedNumAdsRequested = 4 NumAdsServed = 2 CappedNumAdsServed = 2 Nota: nel caso in cui venissero erogati 5 annunci (ovvero gli annunci erogati superano il cap stesso), le ultime 2 metriche verrebbero riportate come:- NumAdsServed = 5 CappedNumAdsServed = 4 (ridotto al cap) I cap non sono obbligatori. Nel caso in cui non vengano specificati, i risultati con cap e senza cap saranno identici. #### Attribuzione avanzata La piattaforma Epsilon Retail Media esegue le attribuzioni come descritto nella sezione Attribuzione (vedi sopra). Il sottosistema di reporting può anche rilevare e segnalare altri scenari di attribuzione a seconda del retailer (attribuzione avanzata). Gli scenari sono: * Attribuzione View-Through dell'Impression * Un ordine è stato attribuito a un annuncio che è stato visualizzato per lo stesso prodotto nello stesso ID sessione (ovvero si è trattato di un'impression e non di un clic). * Attribuzione Clic Halo * Un ordine è stato attribuito a un annuncio su cui è stato fatto clic per un prodotto appartenente allo stesso livello Halo nello stesso ID sessione. Il livello Halo più comune è il Brand (ovvero il prodotto dell'annuncio e il prodotto dell'ordine sono diversi, ma appartengono allo stesso Brand). Altri tipi di halo sono possibili a seconda dell'implementazione. Ad esempio, l'halo può essere più specifico e richiedere che l'annuncio e l'ordine si riferiscano a prodotti che hanno una Categoria comune oltre a un Brand comune. La tassonomia del retailer impostata per ciascun Prodotto nel Catalogo viene utilizzata per definire questo livello extra di dettaglio nell'Halo. Versione: 1ace13f --- # 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/integration/it/reporting/reporting-faq.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.