Google enhances gtag.js API with session number tracking capability

Google's gtag.js API has received an enhancement that extends its data retrieval capabilities beyond the previously available session ID access. According to Simo Ahava, "Not to be outdone by Google Tag Manager's custom templates, the gtag.js get() API now also supports parsing the Google Analytics session number from the session cookie. Previously, you could only get the session ID." The update provides developers with additional insights into user engagement patterns.

The enhancement addresses a gap in analytics data access where developers could retrieve session IDs but lacked access to session numbers that indicate how many sessions a particular user has completed. According to industry documentation, session numbers represent "a distinct metric, as it is a increasing integer indicating the number of sessions a particular user has had."

This development expands the existing get() command functionality, which already supported client_id, session_id, and gclid retrieval across different Google platforms. The session_number field joins these established parameters as supported targets for Google Analytics 4 properties.

The timing coincides with broader improvements across Google's measurement infrastructure. Recent readAnalyticsStorage API developments have provided more reliable access to analytics data, while session tracking enhancements have improved measurement accuracy for properties linked to Google Ad Manager.

Technical implementation remains consistent with existing gtag.js patterns. Developers can access session numbers using the standard get command structure: gtag('get', 'G-XXXXXXXXXX', 'session_number', callback). The callback function receives either the session number value or undefined if the data is unset.

Field precedence follows established gtag.js parameter scope rules. Values set using the set command take precedence over built-in field values, allowing developers to override session numbers when necessary. This behavior maintains consistency across all supported field types within the API architecture.

Marketing teams managing complex attribution models benefit from the additional context session numbers provide. Unlike session IDs that serve as unique identifiers, session numbers offer quantitative insights into user return behavior and engagement frequency. This data proves particularly valuable for customer lifetime value calculations and retention analysis.

The session number parameter operates within gtag.js's three-tier scope system: event-level, config-level, and globally scoped set parameters. Event parameters take highest precedence, followed by config parameters, with globally scoped parameters receiving lowest priority. This hierarchy ensures predictable behavior when multiple values exist for the same parameter across different scopes.

Cross-platform measurement scenarios benefit from unified session tracking. The session_number field provides consistent user identification across multiple Google properties, supporting attribution models that span Google Analytics, Google Ads, and other integrated platforms. This consistency reduces data fragmentation in complex measurement implementations.

Implementation requires no changes to existing tracking setups. The session_number field becomes available automatically for properties already using gtag.js with Google Analytics 4. Developers can begin accessing session numbers immediately without modifying existing tag configurations or deployment processes.

Data privacy considerations remain consistent with existing gtag.js functionality. Session numbers follow the same consent requirements and data processing rules as other analytics parameters. The field respects user privacy settings and consent mode configurations established within the broader tracking implementation.

Enterprise organizations running sophisticated customer journey tracking systems can incorporate session numbers into their measurement frameworks. The additional context enables more granular segmentation and analysis of user behavior patterns. This capability proves especially valuable for businesses operating subscription models or services requiring multiple user interactions.

The enhancement reflects ongoing refinements to Google's measurement platform. According to industry observers, these improvements address "the need for more comprehensive data access" in modern marketing technology implementations. Session numbers provide real-time action triggers for marketers implementing dynamic content or personalization strategies.

Development teams should evaluate current implementations to determine how session number access might enhance their measurement capabilities. The parameter offers additional context for user journey analysis without requiring structural changes to existing analytics implementations. Organizations can begin testing session number integration immediately.

The session_number field supports both direct access and integration with custom template implementations. Developers building custom measurement solutions can incorporate session numbers into their data collection strategies, providing enhanced context for downstream analysis and reporting systems.

Quality assurance considerations mirror other gtag.js parameters. Session numbers should be validated within callback functions to handle cases where data might be unavailable. Proper error handling ensures robust implementations that gracefully manage missing or undefined values.

Database integration follows standard patterns for analytics data ingestion. Session numbers can be stored alongside existing user identification fields, providing additional dimensionality for analysis and reporting. The integer format simplifies storage and calculation requirements compared to session ID strings.

Marketing automation platforms can leverage session numbers for user segmentation and campaign targeting. The quantitative nature of session counts enables threshold-based logic for customer lifecycle management and retention campaigns. This capability extends beyond simple new versus returning user classifications.

Performance monitoring shows no significant impact on page load times or processing overhead. Session number retrieval operates through the same mechanisms as existing get() API calls, maintaining consistent performance characteristics across different parameter types.

Future compatibility remains assured through Google's established parameter management system. The session_number field integrates with existing API versioning and deprecation procedures, ensuring long-term stability for implementations incorporating this functionality.

Timeline

• August 1, 2025: Google announces readAnalyticsStorage sandbox API for reliable client and session ID access in custom templates
• June 30, 2025: Google adds Tag Diagnostics to Analytics consent settings hub for streamlined compliance verification
• July 22, 2025: Google Analytics enables direct Reddit Ads cost data tracking integration expanding measurement capabilities
• August 24, 2024: Google Analytics 4 enhances session tracking for Ad Manager-linked properties
• June 13, 2024: GA4 adds Key Event Rate Metrics to User Acquisition and Traffic Acquisition reports
• May 12, 2024: GA4 session timeouts and engaged sessions configuration guidance published

Summary

Who: Web developers and digital marketers using gtag.js for Google Analytics 4 implementations across websites and applications requiring user session analysis.

What: Enhancement to gtag.js get() API that adds session_number field support, enabling retrieval of user session count data from Google Analytics session cookies alongside existing client_id and session_id capabilities.

When: The functionality became available in gtag.js API documentation, with the capability announced through industry channels observing Google Tag Manager's custom templates development.

Where: Implementation occurs within websites and applications using gtag.js for Google Analytics 4 tracking, accessible through the standard get() API command structure across all supported browsers and platforms.

Why: The addition addresses measurement gaps in user engagement analysis by providing session count context that helps marketers understand user return behavior, enables more sophisticated attribution modeling, and supports customer lifecycle analysis beyond simple session identification.

PPC Land explains

gtag.js API: Google's primary JavaScript interface for implementing tracking across Google Analytics, Google Ads, and other Google marketing products. The API provides a unified command structure using the gtag() function with different commands (config, get, set, event, consent) to manage data collection and user consent. This single-function approach simplifies implementation compared to previous tracking methods while offering extensive customization capabilities for complex measurement scenarios.

Session Number: An incremental integer value that tracks how many sessions a particular user has completed on a website or application. Unlike session IDs which serve as unique identifiers for individual sessions, session numbers provide quantitative context about user return behavior and engagement frequency. This metric proves essential for customer lifetime value calculations, retention analysis, and sophisticated attribution modeling that requires understanding user interaction patterns over time.

Session ID: A unique identifier assigned to each user session that distinguishes individual visits within Google Analytics tracking. Session IDs enable analytics platforms to group user interactions within specific time periods and maintain data consistency across page views and events. The identifier works in conjunction with client IDs to provide comprehensive user journey tracking while respecting privacy requirements and consent management protocols.

Google Analytics 4: Google's latest analytics platform that replaced Universal Analytics and provides enhanced measurement capabilities for websites and mobile applications. GA4 offers improved cross-platform tracking, privacy-focused data collection, and machine learning-powered insights. The platform supports advanced attribution modeling, audience building, and integration with Google's advertising ecosystem while maintaining compliance with evolving privacy regulations.

Client ID: A persistent identifier assigned to browsers or devices that visit a website, used by Google Analytics to distinguish between different users across multiple sessions. Client IDs enable long-term user behavior analysis and support attribution models that track customer journeys spanning multiple visits. The identifier respects user privacy settings and consent preferences while providing essential data for marketing measurement and optimization.

Parameter Scope: The hierarchical system within gtag.js that determines which parameter values take precedence when multiple values exist for the same parameter across different implementation levels. Event-scoped parameters receive highest priority, followed by config-scoped parameters, with globally-scoped set parameters having lowest precedence. This system ensures predictable behavior in complex tracking implementations while allowing flexible parameter management.

Callback Function: A JavaScript function passed as an argument to the gtag() get command that executes when the requested data becomes available or when the operation completes. Callback functions receive the requested field value or undefined if the data is unavailable, enabling developers to handle both successful data retrieval and error conditions. This asynchronous approach ensures tracking operations don't block page loading or user interactions.

Attribution Modeling: The process of assigning conversion credit to different marketing touchpoints throughout the customer journey, enabling marketers to understand which channels and campaigns drive desired outcomes. Session numbers enhance attribution modeling by providing context about user engagement frequency and return behavior. This additional dimension allows for more sophisticated analysis of customer lifecycle stages and campaign effectiveness across multiple interactions.

Marketing Technology: The collection of software tools and platforms used to plan, execute, and measure marketing campaigns across digital channels. Session number tracking enhances marketing technology implementations by providing additional user context for customer data platforms, attribution systems, and campaign optimization tools. This expanded data set enables more precise audience segmentation and personalization strategies.

Cross-Platform Measurement: The capability to track user interactions and conversions across multiple websites, applications, and devices to provide comprehensive customer journey analysis. Session numbers support cross-platform measurement by offering consistent user engagement metrics across different Google properties and integrated platforms. This unified approach reduces data fragmentation and enables more accurate attribution in complex digital ecosystems.