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
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 sending all of the following sub-fields of the session_attributes field, even though only 4 of the 6 are required:
gad_source(required): An aggregate parameter served in the URL to identify the source of traffic originating from ads. Learn more about gad_* URL parameters.- Example value:
"1"
Guideline: These are aggregate parameters appended to the ad click URL (for example:&gad_source=1). You should capture the value present in the landing page URL.
- Example value:
gad_campaignid(required): The ID of the specific ad campaign that drove the ad click. Learn more about gad_* URL parameters.- Example value:
"1234567890"
Guideline: This is also a URL parameter (for example:&gad_campaignid=1234567890) and should be captured from the landing page URL.
- Example value:
session_start_time_usec(required): 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.- Example value:
"1678886400000000"(Represents a specific time in microseconds)
Guideline: Ensure a consistent time format (UNIX timestamp epoch microseconds). This helps track the duration of user visits.
- Example value:
landing_page_user_agent(required): A string that identifies the user's browser and operating system. This information can be useful for understanding the technical environment of your users.- Example value:
"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.0.0 Safari/537.36"
Guideline: This should be captured from the user-agent header of the incoming landing page HTTP request. Avoid generic or hardcoded values.
- Example value:
landing_page_url: The full URL of the landing page on your website. This indicates the specific page the user first arrived on.- Example value:
"https://www.example.com/product/deluxe-widget?gad_source=1&gad_campaignid=1234567890"
Guideline: Provide the accurate, full URL. Do not use placeholder strings, internal application paths (e.g., "/productdetailscreen"), or incomplete URLs. It is better to omit this field if the full, accurate URL is not available.
- Example value:
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.-
Example value:
"https://www.google.com/"or"https://www.socialmedia.com/referral"
Guideline: This reflects the immediate previous page the user was on before landing on your site.
-
Best practices for data quality
- Avoid bad
landing_page_urldata: Incorrect or partiallanding_page_urlvalues are detrimental to modeling; it's better to leave it out if you can't provide the full, accurate URL. - Prevent duplicate uploads: Do not send the same conversion event multiple times. Use a unique identifier like order ID to deduplicate.
The recommended storage size for the session_attributes field is 5 KB, which most use cases won’t exceed. If session_attributes exceeds 5 KB, we recommend working with your CRM provider to modify the field size. You can also remove the landing_page_url and landing_page_referrer parameters from the JavaScript helper function.
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
- You need to modify each form submission page to add a hidden field for
session_attributes. This is howsession_attributeswill 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> - Sample script to capture
session_attributes_encodedand 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_attributesfield 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.
