Informazioni su session_attributes

L'importazione delle conversioni offline (OCI) monitora le conversioni offline provenienti dalle importazioni utilizzando il parametro GCLID. Negli scenari in cui il parametro GCLID non è disponibile, gli utenti che utilizzano OCI possono adottare altri identificatori, come i dati sottoposti ad hashing forniti dagli utenti, wbraid/gbraid o session_attributes.

In questa pagina

• Informazioni su session_attributes
• Come acquisire session_attributes
• Come inviare i dati a Google Ads

---

Informazioni su session_attributes

session_attributes è un campo che fornisce ulteriore contesto e indicatori aggiuntivi sull'interazione dell'utente con il tuo sito web, il che può migliorare la misurazione delle conversioni, la generazione di report (inclusa la suddivisione in base allo stesso dispositivo/cross-device) e l'accuratezza delle offerte. Puoi utilizzare il nostro script front-end riportato di seguito per creare la stringa codificata in Base64 di session_attributes, trasmetterla al tuo database/CRM e inviarla a Google nelle importazioni dell'API. Se non puoi avvalerti dello script front-end, utilizza il campo session_attributes_key_value_pairs per inviare singolarmente ogni coppia chiave/valore.

Ti consigliamo di inviare tutti i seguenti campi secondari del campo session_attributes, anche se solo 4 dei 6 sono obbligatori:

• gad_source (obbligatorio): un parametro aggregato utilizzato nell'URL per identificare la sorgente del traffico proveniente dagli annunci. Scopri di più sui parametri URL gad_*.
  • Valore di esempio: "1"
    Linee guida: si tratta di parametri aggregati aggiunti all'URL di clic sull'annuncio (ad esempio: &gad_source=1). Devi acquisire il valore presente nell'URL pagina di destinazione.
• gad_campaignid (obbligatorio): l'ID della campagna pubblicitaria specifica che ha generato il clic sull'annuncio. Scopri di più sui parametri URL gad_*.
  • Valore di esempio: "1234567890"
    Linea guida: questo è anche un parametro URL (ad esempio: &gad_campaignid=1234567890) e deve essere acquisito dall'URL pagina di destinazione.
• session_start_time_usec (obbligatorio): il timestamp dell'inizio della sessione dell'utente sul tuo sito web. È utile per monitorare la durata delle visite degli utenti. È importante utilizzare un formato orario coerente in microsecondi dell'epoca del timestamp di UNIX.
  • Valore di esempio: "1678886400000000" (rappresenta un momento specifico in microsecondi)
    Linea guida: assicurati di utilizzare un formato orario coerente (microsecondi dell'epoca del timestamp di UNIX). È utile per monitorare la durata delle visite degli utenti.
• landing_page_user_agent (obbligatorio): una stringa che identifica il browser e il sistema operativo dell'utente. Queste informazioni possono essere utili per comprendere l'ambiente tecnico dei tuoi utenti.
  • Valore di esempio: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, come Gecko) Chrome/117.0.0.0 Safari/537.36"
    Linea guida: questo valore deve essere acquisito dall'intestazione User-Agent della richiesta HTTP della pagina di destinazione in entrata. Evita valori generici o hardcoded.
• landing_page_url: l'URL completo della pagina di destinazione sul tuo sito web. Indica la pagina specifica su cui l'utente è arrivato per la prima volta.
  • Valore di esempio: "https://www.example.com/product/deluxe-widget?gad_source=1&gad_campaignid=1234567890"
    Linea guida: fornisci l'URL completo e preciso. Non utilizzare stringhe segnaposto, percorsi interni dell'applicazione (ad es. "/productdetailscreen") o URL incompleti. È meglio omettere questo campo se l'URL completo e accurato non è disponibile.
• landing_page_referrer: l'URL della pagina web che ha indirizzato l'utente al tuo sito web. È utile per capire le sorgenti di traffico che indirizzano gli utenti al tuo sito. Per scoprire di più sui referrer, consulta questo articolo. Sebbene questo articolo sia incentrato su Analytics, il concetto di referrer è lo stesso in tutto il web.

  • Valore di esempio: "https://www.google.com/" o"https://www.socialmedia.com/referral"
    Linea guida: riflette la pagina precedente immediata in cui si trovava l'utente prima di arrivare sul tuo sito.

Best practice per la qualità dei dati

• Evita dati landing_page_url errati: i valori landing_page_url errati o parziali sono dannosi per la modellazione; è meglio ometterli se non riesci a fornire l'URL completo e accurato.
• Evita caricamenti duplicati: non inviare lo stesso evento di conversione più volte. Utilizza un identificatore univoco come l'ID ordine per eliminare i duplicati.

La dimensione di archiviazione consigliata per il campo session_attributes è 5 kB, che la maggior parte dei casi d'uso non supera. Se session_attributes supera i 5 kB, ti consigliamo di collaborare con il tuo fornitore di CRM per modificare la dimensione del campo. Puoi anche rimuovere i parametri landing_page_url e landing_page_referrer dalla funzione helper di JavaScript.

---

Come acquisire session_attributes

Puoi utilizzare la funzione helper di JavaScript e il modulo HTML riportato di seguito nella pagina di destinazione per acquisire e conservare session_attributes.

Questo codice di esempio conserva i dati in localStorage. Prima di implementare la funzione sul tuo sito web, assicurati inoltre di rispettare tutti i requisiti necessari relativi al consenso e alla conservazione dei dati specifici per il tuo sito web.

Modulo HTML

1. Per aggiungere un campo nascosto per session_attributes, devi modificare ogni pagina di invio del modulo. In questo modo, session_attributes verrà trasmesso al tuo sistema di backend. Di seguito è riportato un codice campione per dimostrare questo concetto.
   <form action="" name="myForm">
Name: <input type="text" name="name">
<input type="hidden" id="session_attributes_field" name="session_attributes_field" value="">
<input type="submit" value="Submit Form" name="btnSubmit">
</form>
2. Script di esempio per acquisire session_attributes_encoded e impostarlo nel campo del modulo. Questo codice di esempio conserva i dati in localStorage.

   <script>
function getSessionAttributes() {
const searchParams = new URLSearchParams(window.location.search);
if (Array.from(searchParams.keys()).some(key => key.startsWith('gad_')) ||
searchParams.has('gclid') || searchParams.has('gbraid')) {
const params = {};
searchParams.forEach((value, key) => {
if (key.startsWith('gad_')) params[key] = value;
});
params['session_start_time_usec'] =
(new Date().getTime() * 1000).toString();
params['landing_page_url'] = window.location.href;
params['landing_page_referrer'] = document.referrer;
params['landing_page_user_agent'] = navigator.userAgent;
const sessionAttributesEncoded = btoa(JSON.stringify(params))
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=+$/, '');
localStorage.setItem('google_session_attributes', sessionAttributesEncoded);
return sessionAttributesEncoded;
}
return localStorage.getItem('google_session_attributes') || '';
}

   
   function addSessionAttributes() {
const sessionAttributesEncoded = getSessionAttributes();
var sessionAttributesFormField =
document.getElementById('session_attributes_field');
if (sessionAttributesFormField && sessionAttributesEncoded != '') {
sessionAttributesFormField.value = sessionAttributesEncoded;
}
}
window.addEventListener('load', addSessionAttributes);
</script>

---

Come inviare i dati a Google Ads

1. Campo session_attributes_encoded nell'API Google Ads

A partire dal 2 febbraio 2026, l'API Google Ads non accetterà più nuovi utenti che utilizzano i dati relativi agli attributi di sessione o agli indirizzi IP nelle importazioni delle conversioni. Per garantire un'esperienza più affidabile e scalabile per la gestione di dati complessi, consigliamo agli sviluppatori dell'API Google Ads di eseguire la transizione all'API Data Manager, in cui sono accettati gli attributi di sessione e l'indirizzo IP, come API principale per l'importazione dei dati sulle conversioni e sugli utenti. Scopri di più sulle modifiche al supporto per gli attributi di sessione e gli indirizzi IP nell'API Google Ads.

Se utilizzi JavaScript per l'importazione delle conversioni offline (OCI), invia questi dati impostando il campo session_attributes codificato acquisito dal codice JavaScript fornito in un nuovo campo denominato ClickConversion.session_attributes_encoded all'interno dello schema di caricamento esistente. Continua a utilizzare il processo OCI attuale, ma imposta questo nuovo campo quando esegui le importazioni. Google Ads utilizzerà session_attributes quando non sono presenti altri identificatori.

Tutti i nuovi utenti devono utilizzare l'API Data Manager. Se un account non è stato incluso nella lista consentita per la trasmissione di indirizzi IP o attributi di sessione tramite l'API Google Ads, riceverai un messaggio di errore per queste conversioni.

Nota: per accedere al nuovo campo nell'API Google Ads è necessario eseguire l'upgrade alla v19 o successiva.

Avanzato

Se non puoi utilizzare JavaScript, puoi acquisire le singole coppie chiave/valore e inviarle con le importazioni delle conversioni offline.

Se non utilizzi JavaScript per l'importazione delle conversioni offline (OCI), potresti anche impostare il campo coppia chiave/valore denominato ClickConversion.session_attributes_key_value_pairs nello schema di caricamento esistente. Ti consigliamo di inviare coppie chiave/valore con questi campi quando chiami l'API. Consulta la documentazione per lo sviluppo, che spiega come aggiungere singole coppie chiave-valore a ClickConversion.

Puoi leggere i seguenti consigli e aggiornare l'implementazione per assicurarti che i dati inviati siano validi:

• gad_campaignid (ID campagna): assicurati di inviare in modo coerente l'ID campagna Google Ads valido associato al clic sull'annuncio. Si tratta dell'ID campagna compilato nell'URL di clic sull'annuncio come "gad_campaignid=1234". È un attributo principale, fondamentale per un'attribuzione accurata.
• session_start_time_usec: assicurati di inviare l'attributo in modo coerente (il timestamp dell'inizio della sessione utente).
• landing_page_url (URL): verifica di inviare l'URL completo e preciso della pagina di destinazione. Non inviare stringhe segnaposto, percorsi interni dell'applicazione o URL incompleti.
  • Nota: se non è disponibile l'URL completo e accurato, ti consigliamo di rimuovere l'intero campo, poiché dati errati possono influire negativamente sulla modellazione.
• landing_page_user_agent (user agent): assicurati che la stringa rifletta con accuratezza il browser e il sistema operativo dell'utente ed evita di inviare valori generici o impostati come hardcoded.

2. Campo session_attributes utilizzando Data Manager

Puoi anche inviare il campo session_attributes utilizzando Data Manager.

• UI di Data Manager: utilizza il codice JavaScript fornito per creare il campo session_attributes e caricarlo tramite la UI di Data Manager.
• API Data Manager: puoi eseguire l'integrazione con l'API Data Manager per caricare i dati in modo programmatico. Per istruzioni specifiche e dettagli sullo schema, consulta la documentazione di Data Manager.

Se invii i dati corretti, consenti a Google Ads di utilizzare queste informazioni per attribuire le conversioni alle campagne corrette e fornirti report sulle conversioni più completi.