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:

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:25 AM - Session expires (15 minutes after last activity)

If visitor returns at 10:30 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 for existing session cookie
  3. No cookie found → New session created
  4. Unique session ID generated
  5. Three cookies set (10-minute expiry):
  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 for session cookie
  3. Cookie found → Continue existing session
  4. Session ID read from cookie
  5. Cookie expiry refreshed (+10 minutes from now)
  6. Database record updated:
  7. New event (page view) recorded with same session_id

Important: Landing page and referral URL do NOT change during a session. They're set once at session start.

3. Session Activity

During session, events are tracked:

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:

What happens at expiration:

If visitor returns after expiration:

Session Timeout: Why 10 Minutes?

Reasons for 10-minute timeout:

  1. Industry standard: Google Analytics uses 30 minutes, but 10 is common for eCommerce
  2. Balance accuracy and privacy: Long enough to capture shopping journey, short enough to respect privacy
  3. Prevents abandoned session inflation: User who leaves for lunch doesn't show 2-hour session
  4. Accurate conversion tracking: Clear separation between visits
  5. Performance: Shorter sessions = less cookie renewal overhead

What 10 minutes means:

Developer note: Timeout can be customized via filter:

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

Cookie Management

Cookie Details

1. wpd_ai_session_id

Property Value
Purpose Unique session identifier
Format wpd + MD5 hash + timestamp
Example wpd5f4dcc3b5aa765a1234567890
Expiry 10 minutes from last activity
Domain Your site domain
Path / (site-wide)
Secure No (works on HTTP and HTTPS)
HttpOnly No (accessible to JavaScript)
SameSite Lax (default)

Generation algorithm:

function generate_unique_session_id() {
  $random_token = md5($_SERVER['HTTP_USER_AGENT'] . time());
  return 'wpd' . $random_token . time();
}

2. wpd_ai_landing_page

Property Value
Purpose Store first page visited
Format Full URL including query parameters
Example https://store.com/shop?utm_source=facebook
Expiry 10 minutes from last activity
Set once Yes (only on first page, value doesn't change)
Used for Order attribution, UTM tracking

Why full URL with query params?

3. wpd_ai_referral_source

Property Value
Purpose Store where visitor came from
Format Full referrer URL
Example https://www.google.com/search?q=...
Expiry 10 minutes from last activity
Set once Yes (only on first page)
Used for Traffic source classification

Special handling:

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:

GDPR considerations:

Best practice:

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:
  2. Visitor browses:
  3. Visitor adds to cart:
  4. Visitor checks out:
  5. Order created:
  6. Transaction event:

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 (1–30 days). Referral URL and landing page are stored when the visitor first arrives and expire after that many days from first set—they are not updated by later activity. So attribution can extend beyond a single session: if a visitor returns within the window, the original referrer and landing page are still used.

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 (session expired)

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 Direct (new session, new attribution)

Scenario 3: Multiple sessions

Day 1, 10:00 AM - Facebook ad → Browse → Leave (session expires)
Day 1, 3:00 PM - Google search → Browse → Leave (new session, session expires)
Day 2, 9:00 AM - Direct visit → Purchase (new session)
Result: Order attributed to Direct (last session wins - last-click attribution)

Attribution Model: Last-Click

Alpha Insights uses last-click attribution:

Why last-click?

Limitations of last-click:

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: Direct (last-click)
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:

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

How it affects tracking

How it affects reporting

When the setting is True:

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

Summary

SettingFirst page viewReporting
Only track engaged = FalseSent on page loadAll sessions included
Only track engaged = TrueSent after first click/scroll/touchOnly engaged sessions (or sessions with duration > 0) included

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:

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):

Sessions:

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:

Benefit for repeat customers:

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

Session Data Retention

How long is session data stored?

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:

Session Filtering in Reports

Available filters:

Use cases:

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 30 * 60; // 30 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

Troubleshooting Sessions

Sessions not being created:

Sessions too short:

Sessions not linking to orders:

Multiple sessions for same user:

Next Steps