Session Management & Attribution

Understanding how Alpha Insights manages sessions is crucial for accurate attribution and data analysis. This guide explains session lifecycle, cookie management, timeout handling, and how orders are attributed to traffic sources.

What is a Session?

A session represents a continuous period of visitor activity on your website. It includes all pages viewed, events triggered, and actions taken from arrival to departure.

Key characteristics:

• Starts when visitor lands on any page of your site
• Continues as long as visitor is active
• Expires after 30 minutes of inactivity
• Each session has a unique ID
• Multiple sessions can belong to same visitor (returning visits)
• Sessions tracked in localStorage, with first-party cookies written at cart/checkout (or immediately)

Example session:

10:00 AM - Visitor lands on homepage (session starts)
10:02 AM - Views product category page
10:05 AM - Clicks on product
10:06 AM - Views product page
10:08 AM - Adds to cart
10:10 AM - Leaves site
10:40 AM - Session expires (30 minutes after last activity)

If visitor returns at 10:45 AM, a NEW session starts.

Session Lifecycle

1. Session Start (First Page View)

What happens:

1. Visitor lands on your site
2. Alpha Insights checks localStorage for an existing session ID and last-activity timestamp
3. None found (or older than 30 minutes) → New session created
4. Unique session ID generated in the browser
5. Values stored in localStorage (wpd_ai_v2_* keys). Cookies are written on cart/checkout in Checkout Only mode:
   • wpd_ai_session_id - Session identifier (30-minute inactivity expiry)
   • wpd_ai_landing_page - Landing URL with query params (attribution window)
   • wpd_ai_referral_source - Document referrer (attribution window)
6. Session data written to database (wp_wpd_ai_session_data table)
7. Device info captured (browser, OS, device type)
8. Traffic source determined from referrer and query parameters

Database record created:

{
  "session_id": "wpd5f4dcc3b5aa765a123456789",
  "ip_address": "192.168.1.1",
  "landing_page": "https://store.com/products?utm_source=facebook&utm_campaign=spring",
  "referral_url": "https://www.facebook.com/...",
  "user_id": 0,
  "date_created_gmt": "2024-03-15 10:00:00",
  "date_updated_gmt": "2024-03-15 10:00:00",
  "device_category": "mobile",
  "operating_system": "iOS",
  "browser": "Safari",
  "device": "mobile",
  "additional_data": "{...}"
}

2. Session Continuation (Subsequent Pages)

What happens:

1. Visitor navigates to another page
2. Alpha Insights checks localStorage for a session ID
3. Recent activity found → Continue existing session
4. Session ID read from localStorage
5. Last-activity timestamp refreshed
6. Database record updated:
   • date_updated_gmt set to current time
   • Indicates session is still active
7. New event (page view) recorded with same session_id

Important: Landing page and referral URL do NOT change during a session. They are set once at the start of the attribution period. A later session can reset them if you use Session Only, the window expires, or Override Attribution on New UTM Visit is on and the URL has campaign parameters. See Attribution Window.

3. Session Activity

During session, events are tracked:

• Page views
• Product clicks
• Add to cart
• Checkout initiation
• Form submissions
• WooCommerce events

All events share the same session_id:

// Example events in same session
session_id: wpd5f4dcc3b5aa765a...
  - page_view (homepage) - 10:00:00
  - page_view (products) - 10:02:15
  - product_click (item 123) - 10:05:22
  - page_view (product 123) - 10:05:23
  - add_to_cart (product 123) - 10:08:14
  - page_view (checkout) - 10:09:45
  - init_checkout - 10:09:45
  - transaction (order 789) - 10:11:30

4. Session End (Expiration)

Session expires when:

• 30 minutes pass with no page loads or activity
• User clears site data (localStorage / cookies) manually
• Browser is closed (cookies may persist; localStorage typically persists)

What happens at expiration:

• Last-activity timestamp is older than the session timeout (passive expiration)
• No server action needed
• Session record remains in database with last date_updated_gmt
• Session duration calculated as: date_updated_gmt - date_created_gmt

If visitor returns after expiration:

• New session starts (new session ID generated)
• New landing page and referrer captured
• Treated as separate visit
• Both sessions link to same IP (but different session IDs)

Session Timeout: Why 30 Minutes?

Reasons for 30-minute timeout:

1. Industry standard: Matches the Google Analytics default session timeout
2. Balance accuracy and privacy: Long enough to capture a shopping journey, short enough to separate distinct visits
3. Prevents abandoned session inflation: A user who leaves for lunch does not show a 2-hour session
4. Accurate conversion tracking: Clear separation between visits

What 30 minutes means:

• Active browsing: Session continues (last-activity timestamp refreshes each page)
• Idle for 30 minutes: Session expires automatically
• Example: Browse for 45 minutes = 1 session (as long as no 30-minute gaps)

Developer note: Timeout can be customized via filter:

// Change to 60 minutes
add_filter('wpd_session_timeout_seconds', function($timeout) {
  return 60 * 60; // 60 minutes
});

Browser Storage & Cookie Management

Session identity lives in localStorage first (keys prefixed with wpd_ai_v2_). Cookies below are written on cart/checkout in Checkout Only mode, or on first visit in Immediate mode. See Cache-Safe Event Tracking.

Cookie Details

1. wpd_ai_session_id

Generation (JavaScript):

function generateSessionId() {
  return 'wpd' + Date.now() + Math.random().toString(36).substring(2, 12);
}

2. wpd_ai_landing_page

Why full URL with query params?

• Captures UTM parameters for campaign tracking
• Captures campaign IDs (meta_cid, google_cid) for profit attribution
• Shows exact entry point with context
• Enables landing page analysis

3. wpd_ai_referral_source

Special handling:

• Own domain referrers ignored (set to empty)
• Empty referrer = Direct traffic
• Captured from document.referrer in the browser
• Social platforms often strip referrers (use UTMs instead)

Cookie Lifecycle Example

10:00:00 - Visitor lands on site
         → Cookies set with expiry 10:10:00
         
10:03:00 - Visitor views another page
         → Cookie expiry updated to 10:13:00
         
10:07:00 - Visitor adds to cart
         → Cookie expiry updated to 10:17:00
         
10:10:00 - Visitor leaves site
         → Cookies still valid until 10:20:00
         
10:15:00 - Visitor returns
         → Cookies still exist (within 10 min)
         → SAME session continues
         → Cookie expiry updated to 10:25:00
         
10:25:00 - Visitor idle
         → Cookies expire at 10:25:00
         
10:30:00 - Visitor returns
         → Cookies gone (expired)
         → NEW session starts

Cookie Privacy & Compliance

For complete privacy and GDPR compliance information, see the Privacy & Security guide.

First-party cookies:

• Set by your own domain (not third-party)
• Used for essential site functionality
• Required for accurate analytics
• Generally allowed by privacy laws for analytics

GDPR considerations:

• First-party analytics cookies often exempt from consent (check your jurisdiction)
• No personal data stored in cookies (just IDs)
• IP addresses stored in database (may need consent)
• Consider cookie consent banner if in EU
• Provide opt-out mechanism (exclude user roles)

Best practice:

• Include tracking in privacy policy
• Explain what cookies are set
• Provide opt-out instructions
• Consider cookie consent plugin

Order Attribution

When a visitor places an order, Alpha Insights permanently links the order to the session's traffic source. This enables profit tracking by source in reports. To understand profit calculations, see How Alpha Insights Works.

Attribution Process

Step-by-step:

1. Visitor arrives:
   • Session starts
   • Landing page with UTMs saved to cookie
   • Referrer saved to cookie
2. Visitor browses:
   • Session continues
   • Events tracked
   • Cookies refresh each page
3. Visitor adds to cart:
   • Add to cart event recorded
   • Session ID links event
4. Visitor checks out:
   • Begins checkout process
   • Init checkout event
5. Order created:
   • WooCommerce creates order
   • woocommerce_checkout_order_processed hook fires
   • Alpha Insights reads cookies
   • Saves to order meta:
     • _wpd_ai_landing_page = landing URL
     • _wpd_ai_referral_source = referrer URL
     • _wpd_ai_meta_campaign_id = FB campaign ID (if present)
     • _wpd_ai_google_campaign_id = Google campaign ID (if present)
6. Transaction event:
   • Order status changes to paid status
   • Transaction event recorded with session_id
   • Links event to session

Result: Order permanently attributed to traffic source, even if cookies expire or session ends.

Attribution window

How long does attribution last?

Alpha Insights supports a configurable attribution window (Session Only, or 1–30 days). Referral URL and landing page are stored when the visitor first arrives and expire after that period from first set. Multi-day options can extend beyond a single session. Session Only resets them whenever a new session starts.

• Setting: Alpha Insights → Settings → General Settings → Attribution Window (under Alpha Analytics & Event Tracking)
• Default: 3 days
• Override Attribution on New UTM Visit: True by default. A new session with UTM tags or click IDs replaces stored landing page and referral even if the window has not expired.
• Effect: Orders and sessions are attributed to the stored traffic source and landing page until the window expires or a reset rule applies.

For full details, see Attribution Window.

Example scenarios:

Scenario 1: Quick purchase (within session)

Day 1, 10:00 AM - Click Facebook ad → Land on product page
Day 1, 10:05 AM - Add to cart → Checkout → Complete purchase
Result: Order attributed to Facebook (original landing page)

Scenario 2: Later purchase inside a 3-day window

Day 1, 10:00 AM - Click Facebook ad → Browse → Leave
Day 3, 2:00 PM - Direct visit (type URL) → Complete purchase
Result: Order attributed to Facebook (first-touch still inside the window)

Scenario 3: New session with campaign parameters (Override on)

Day 1, 10:00 AM - Facebook ad → Browse → Leave (session expires)
Day 2, 9:00 AM - Google ad with gclid → Purchase
Result: Order attributed to Google (new session + tracking params replaced first-touch)

Attribution Model

Alpha Insights uses first-touch within the Attribution Window:

• Landing page and referral are stored at first visit and reused until the window expires
• Session Only resets them on every new session
• Override Attribution on New UTM Visit (default True) replaces stored values when a new session arrives with UTM tags or click IDs
• The order copies whatever landing page and referral are stored at checkout

Why this model?

• Deterministic and easy to explain
• Based on stored landing page at time of purchase
• Keeps paid-click credit across return visits inside the window
• Optional last-touch when a later campaign URL starts a new session

Limitations:

• Does not split credit across multiple assisting channels
• Direct return visits can keep an earlier campaign’s credit until the window expires
• A later UTM visit can overwrite first-touch when Override is on

Workaround: Multi-session analysis

Use Website Sessions report to see full customer journey:

1. Filter sessions by IP address or customer email
2. View all sessions from same visitor
3. See complete journey across multiple visits
4. Understand which channels assisted conversion

Example multi-session analysis:

Session 1 (Day 1):
- Source: Facebook
- Landing: product page
- Events: product_page_view, left site
- Order: No

Session 2 (Day 2):
- Source: Organic (Google search)
- Landing: product page
- Events: page_view, add_to_cart, left site
- Order: No

Session 3 (Day 3):
- Source: Direct
- Landing: cart page
- Events: viewed_cart, init_checkout, transaction
- Order: Yes (Order #789)

Attribution with a 3-day first-touch window: Facebook (unless a later UTM session overrode it)
Reality: Facebook awareness → Google consideration → Direct conversion

Only track engaged sessions

When Only Track & Report On Engaged Sessions is enabled (Alpha Insights → Settings → General Settings → Alpha Analytics & Event Tracking), Alpha Insights treats a session as “engaged” only after the visitor has interacted with the page (e.g. click, touch, or scroll). This reduces noise from bots and accidental page loads.

What “engaged” means

Engagement is detected on the frontend by the event tracking script:

• Click – Any mouse click on the page
• Pointer/touch – Touch or pointer interaction (improves mobile detection)
• Scroll – User scrolls the page (with a short delay to avoid false triggers)

As soon as one of these occurs, the session is marked as engaged for the rest of that visit.

How it affects tracking

• Page views: The first page_view event is not sent until the user has engaged. Once they click, touch, or scroll, the page view is sent and the session is marked engaged.
• Cookie: The cookie wpd_ai_engaged_session is set when engagement is detected (value 1).
• Database: The session record has an engaged_session flag (0 or 1). It is set when the first page view is stored (after engagement) and can be updated later if engagement is detected on a subsequent request.
• Other events: Product clicks, add to cart, checkout, etc. are still sent as usual; only the initial page view is delayed until engagement.

How it affects reporting

When the setting is True:

• Website Traffic / Analytics reports can filter or focus on engaged sessions only (sessions where engaged_session = 1 or duration > 0).
• Bounce rate and session counts may change because non-engaged single-page visits are excluded or not counted as full sessions.
• Use this when you want metrics that reflect real user interaction rather than all page loads (including bots and quick bounces).

When the setting is False, every page load sends a page view immediately and all sessions are tracked regardless of interaction.

Summary

Session Duration Calculation

Formula:

session_duration = date_updated_gmt - date_created_gmt

Measured in: Seconds (converted to minutes in reports)

Example:

date_created_gmt: 2024-03-15 10:00:00
date_updated_gmt: 2024-03-15 10:08:30
session_duration: 510 seconds (8 minutes 30 seconds)

Important notes:

• Minimum duration: 0 seconds (single page view, immediate exit)
• Maximum practical duration: Limited by the 30-minute inactivity timeout
• Last page time unknown: Duration ends at last page load, not when user actually leaves
• Example: User spends 5 minutes on last page → not counted in duration

Calculating average session duration:

SELECT AVG(TIMESTAMPDIFF(SECOND, date_created_gmt, date_updated_gmt)) as avg_duration_seconds
FROM wp_wpd_ai_session_data
WHERE date_created_gmt >= DATE_SUB(NOW(), INTERVAL 30 DAY);

Session Identification

Unique Visitors vs Sessions

Unique visitors (users):

• Counted by unique IP addresses
• Approximate measure (not 100% accurate)
• Same IP = same user (even across sessions)
• Different IPs = different users (even if same person)

Sessions:

• Counted by unique session IDs
• Precise and accurate
• One visitor can have multiple sessions
• Each visit after a 30-minute gap = new session

Relationship:

Users ≤ Sessions

Example:
- 1 user visiting 3 times = 3 sessions
- 10 users visiting once = 10 sessions
- 5 users visiting twice = 10 sessions

Logged-in User Tracking

If user is logged in:

• user_id field populated in session data
• Links all sessions to WordPress user account
• Enables cross-device tracking (if same account)
• More accurate user identification

Benefit for repeat customers:

• Track lifetime behavior across sessions
• Link orders to user account
• Calculate customer lifetime value
• Analyze returning customer patterns

Cross-Device Tracking

Limitation: Alpha Insights does NOT track cross-device by default

Example:

User on phone:
- Session 1 (mobile, IP: 192.168.1.100)
- Browse, add to cart, leave

User on laptop:
- Session 2 (desktop, IP: 10.0.0.50)
- Different IP, different cookies
- Treated as separate user

Result: Two sessions, two "users" - no connection

Exception: Logged-in users

• If user logs in on both devices
• Both sessions link to same user_id
• Can be connected in analysis by user_id
• Still separate sessions, but same user

Session Data Retention

How long is session data stored?

• Session and event data stored indefinitely by default
• Can configure retention period in settings
• Recommended: 90-365 days for analytics
• Order attribution always preserved (in order meta)

Cleanup strategies:

1. Manual cleanup:

   DELETE FROM wp_wpd_ai_session_data
      WHERE date_created_gmt < DATE_SUB(NOW(), INTERVAL 365 DAY);

2. Automated cleanup: Configure in General Settings (if available)
3. Archive old data: Export to CSV before deletion

What to keep:

• Keep at least 1 year for year-over-year analysis
• Keep sessions with orders (transaction events) indefinitely
• Archive very old data (2+ years) for long-term trends

Session Filtering in Reports

Available filters:

• Date range: Filter by session start date
• Traffic source: Filter by acquisition source
• Device type: Mobile, desktop, tablet
• Browser: Chrome, Safari, Firefox, etc.
• Operating system: Windows, Mac, iOS, Android, etc.
• Session contains event: Filter sessions with specific events
• Landing page: Filter by entry URL
• UTM parameters: Filter by campaign, source, medium
• IP address: Filter by specific IP (for debugging)
• User ID: Filter by logged-in user

Use cases:

• Analyze mobile vs desktop conversion rates
• Compare traffic sources by device
• Find sessions with checkout errors
• Identify high-value sessions (multiple products viewed)
• Track individual customer journeys

Technical Details

Session Storage

Database table: wp_wpd_ai_session_data

Key fields:

session_id VARCHAR(255) - Unique identifier
ip_address VARCHAR(100) - Visitor IP
landing_page TEXT - First page URL
referral_url TEXT - Where they came from
user_id BIGINT - WordPress user ID (0 = guest)
date_created_gmt DATETIME - Session start
date_updated_gmt DATETIME - Last activity
device_category VARCHAR(50) - mobile/desktop/tablet
operating_system VARCHAR(100) - OS name
browser VARCHAR(100) - Browser name
additional_data LONGTEXT - JSON metadata

Session vs Event Relationship

One-to-Many relationship:

Session (1)
  ├── Event 1 (page_view)
  ├── Event 2 (product_click)
  ├── Event 3 (page_view)
  ├── Event 4 (add_to_cart)
  └── Event 5 (transaction)

All events share same session_id
JOIN events to sessions via session_id

Hooks & Filters

// Modify session timeout
add_filter('wpd_session_timeout_seconds', function($timeout) {
  return 60 * 60; // 60 minutes
});

// Modify session data before storage
add_filter('wpd_session_data_before_storage', function($session_data) {
  // Custom modifications
  return $session_data;
});

// Action after session created/updated
add_action('wpd_session_updated', function($session_data) {
  // Custom logic
});

Best Practices

• Respect the 30-minute timeout: Long idle gaps start a new session
• Use UTM parameters: Ensure accurate attribution across sessions
• Monitor session duration: Very short = possible UX issues
• Analyze multi-session journeys: Understand full customer path
• Configure data retention: Balance storage and historical analysis
• Test attribution: Place test orders from different sources
• Document custom events: Track important actions within sessions
• Regular cleanup: Archive and delete old sessions
• Privacy compliance: Disclose session tracking in privacy policy

Troubleshooting Sessions

Sessions not being created:

• Check if analytics is enabled
• Verify cookies and localStorage are enabled in the browser
• Check if user role is excluded from tracking
• Verify bot detection isn't filtering legitimate users

Sessions too short:

• Check site speed (slow pages = users leave)
• Review bounce rate (1 page view = short session)
• Check if timeout is too short (30 minutes default)

Sessions not linking to orders:

• Check Application → Local Storage for wpd_ai_v2_landing_page (cookies may be absent until cart/checkout)
• Verify site data is not being cleared prematurely
• Check if purchase happens after the attribution window expired
• Review order meta fields for attribution data

Multiple sessions for same user:

• Expected behavior if 30+ minutes between visits
• Check if the user is clearing site data
• Verify timeout setting
• Consider if browser/device switching

Next Steps

• Review Technical Architecture for implementation details
• Read Privacy & Security for GDPR compliance
• Check Troubleshooting Guide for common issues
• See UTM Campaign Tracking for accurate attribution
• Learn about Traffic Source Analysis for optimization strategies
• Understand Website Analytics Overview for tracking basics