About session_attributes

Offline Conversion Import (OCI) tracks offline conversions from imports using the GCLID. In scenarios where GCLID is not available, OCI users can rely on other identifiers such as hashed user-provided data, wbraid/gbraid or session_attributes.

On this page

• About session_attributes
• How to capture session_attributes
• How to send the data to Google Ads

About session_attributes

session_attributes is a field that provides further context and signals about the user's interaction with your website, which can enhance conversion measurement, reporting (including same/cross device breakdown) and bidding accuracy. You can use our front-end script below to create the base64 encoded string of session_attributes, pass that to your database/CRM and send to Google in your API imports. If you can't use the front-end script, use the session_attributes_key_value_pairs field to send each key/value pair individually.

We recommend that you send all of the sub-fields, but you can choose to send as few or as many of them as you want. All sub-fields are optional. The recommended storage size for the session_attributes field is 5 KB. Most usage won't exceed this size. If session_attributes is larger than this, either work with your CRM provider to modify the field size (strongly recommended) or remove the landing_page_url and landing_page_referrer parameters from the JavaScript helper function.

Here are the sub-fields inside the session_attributes field:

• gad_source: An aggregate parameter served in the URL to identify the source of traffic originating from ads. Learn more about gad_* URL parameters.
• gad_campaignid: The ID of the specific ad campaign that drove the ad click. Learn more about gad_* URL parameters.
• landing_page_url: The full URL of the landing page on your website. This indicates the specific page the user first arrived on.
• session_start_time_usec: The timestamp of when the user's session began on your website. This helps track the duration of user visits. It's important to use a consistent time format in UNIX timestamp epoch microseconds.
• landing_page_referrer: The URL of the webpage that linked the user to your website. This helps understand the traffic sources leading to your site. For more information on referrers, refer to this article that while focused on Analytics, the concept of a referrer is universal across the web.
• landing_page_user_agent: A string that identifies the user's browser and operating system. This information can be useful for understanding the technical environment of your users.

How to capture session_attributes

You can use the JavaScript helper function and HTML form below on your landing page to capture and persist session_attributes.

This example code persists data to localStorage. Before implementing on your website, please additionally ensure any necessary consent and data retention requirements specific to your website are honored as needed.

HTML Form

1. You need to modify each form submission page to add a hidden field for session_attributes. This is how session_attributes will be passed to your backend system. Below is a sample code to demonstrate this.
   <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. Sample script to capture session_attributes_encoded and set it in the form field. This example code persists data to 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>

How to send the data to Google Ads

1. session_attributes_encoded field in Google Ads API

For existing Offline Conversion Import (OCI) users who use Javascript, send this data by setting the encoded session_attributes captured from the Javascript provided on a new field called ClickConversion.session_attributes_encoded within your existing upload schema. Continue using your current OCI process, but set this new field when making imports. Google Ads will use session_attributes when your other identifiers are not present.

All new users must use the Data Manager API. If an account hasn't been allowlisted to transmit IP addresses or session attributes via the Google Ads API, you'll receive an error message for those conversions.

Advanced

If you can't use JavaScript, you can capture the individual key/value pairs and send them with your Offline Conversion Imports.

For existing Offline Conversion Import (OCI) users who don’t use Javascript, you could also set the key value pair field called ClickConversion.session_attributes_key_value_pairs within your existing upload schema. We suggest you send key value pairs with these fields when calling the API. View the developer documentation explaining how to add individual key value pairs to a ClickConversion.

You can review the following recommendations and update your implementation to ensure valid data is being sent:

• gad_campaignid (Campaign ID): Ensure you are consistently sending the valid Google Ads Campaign ID associated with the ad click. This is the Campaign ID populated in the ad click URL as “gad_campaignid=1234”. This is a core attribute and is crucial for accurate attribution.
• session_start_time_usec: Ensure to consistently send the attribute (the timestamp when the user session began).
• landing_page_url (URL): Ensure you are sending the accurate, full URL of the landing page. Do not send placeholder strings, internal application paths, or incomplete URLs.
  • Note: If the accurate, full URL is not available, it is recommended to remove the entire field, as incorrect data can negatively impact modeling.
• landing_page_user_agent (User agent): Ensure the string accurately reflects the user's browser and operating system, and avoid sending generic or hardcoded values.

2. session_attributes field using Data Manager

You can also send the session_attributes field using Data Manager.

• Data Manager UI: Use the provided JavaScript to create the session_attributes field and upload it through the Data Manager UI.
• Data Manager API: You can integrate with the Data Manager API to programmatically upload your data. Consult the Data Manager documentation for specific instructions and schema details.

By sending the right data, you enable Google Ads to use this information to attribute conversions to the correct campaigns and provide you with more comprehensive conversion reporting.