> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zixflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Data Journey

> End-to-end flow of event data from SDK capture to availability in Zixflow.

Ever wonder what happens when you track an event in your app? This guide explains how events flow from your application to Zixflow's platform, where they become available for analytics, targeting, and campaigns.

***

## The Big Picture

When a user takes an action in your app, here's what happens:

```
1. User Action → Your app detects it (button click, page view, purchase)
                     ↓
2. SDK Captures → Zixflow SDK records the event with user info and context
                     ↓
3. Sent Securely → Event sent to Zixflow over encrypted connection
                     ↓
4. Processed → System validates, enriches, and links to user profile
                     ↓
5. Available → Event is now searchable and ready for campaigns/analytics
                     ↓
Total time: 2-5 seconds
```

**What this means for you:** Events you track are available almost instantly for triggering campaigns, building segments, or running reports.

***

## What Happens at Each Stage

### 1. Event Capture (In Your App)

**What happens:** The Zixflow SDK in your app detects a user action and captures it as an event.

**Example:**

```javascript theme={null}
// User clicks "Add to Cart" button
Zixflow.track('Product Added', {
  product_id: 'prod_123',
  product_name: 'Red Sneakers',
  price: 89.99,
  currency: 'USD'
});
```

**Behind the scenes:**

* SDK adds timestamp (down to the millisecond)
* Adds device information (phone model, OS version, screen size)
* Adds user identification (their user ID if logged in, or anonymous ID if not)
* Adds location context (timezone, country, language)

**Time taken:** Less than 1 millisecond (instant, doesn't slow down your app)

***

### 2. Smart Batching (Battery & Performance)

**The challenge:** Sending every single event immediately would drain phone batteries and use lots of data.

**The solution:** The SDK intelligently batches events before sending them.

**How batching works:**

* SDK collects events in memory (holds up to 20 events)
* Sends the batch when:
  * 20 events collected (batch is full)
  * 30 seconds passed since last send (time limit)
  * User closes/backgrounds the app (immediate flush)

**Why this matters:**

* **Battery life:** 90% less network activity = longer battery life
* **Data usage:** Batching multiple events in one request uses less data
* **Performance:** App stays responsive, no lag from network calls

**Important events get special treatment:**

```javascript theme={null}
// High-priority event = send immediately
Zixflow.track('Purchased', { order_id: 'ord_123', total: 499.99 });
Zixflow.flush();  // Forces immediate send, don't wait for batch
```

***

### 3. Offline Support (Works Without Internet)

**What happens when there's no internet?**

* SDK saves events locally on the device (in secure storage)
* When internet returns, SDK automatically sends all saved events
* Events are sent in the correct chronological order
* Nothing is lost!

**Retry logic:**

* If send fails, SDK waits 1 second and tries again
* If it fails again, waits 2 seconds, then 4, then 8, then 16 seconds
* Maximum 10 retry attempts before giving up
* This prevents battery drain from infinite retry loops

**Real-world example:**

```
9:00 AM: User opens app in subway (no signal)
9:05 AM: User adds product to cart → Event saved locally
9:10 AM: User favorites the product → Event saved locally
9:15 AM: User exits subway, gets signal
9:15 AM: SDK automatically sends both events to Zixflow
```

***

### 4. Secure Transmission

**How events reach Zixflow:**

* Sent over HTTPS (encrypted, same security as online banking)
* Your API key authenticates each request (ensures events are really from your app)
* Zixflow validates the request and accepts the events

**Security features:**

* All data encrypted in transit (TLS 1.3)
* API keys are workspace-specific (one compromised key doesn't affect others)
* Invalid or tampered requests are rejected
* You can rotate API keys anytime without downtime

***

### 5. Processing & Enrichment

**What Zixflow does with your events:**

**Validation:**

* Checks required fields are present (user ID, event name, timestamp)
* Validates data types (numbers are numbers, dates are valid dates)
* Rejects malformed events (protects data quality)

**Identity Resolution:**

* If the event is from an anonymous user, Zixflow automatically creates an anonymous profile and links the event to it. This ensures even pre-signup behavior is stored under a consistent profile ID.
* If a device token is registered before sign-up, the device is linked to the anonymous profile and automatically migrated to the identified user when they call `identify()`.
* When a user identifies themselves (signs up or logs in), Zixflow merges their anonymous history into a single identified profile. The original `first_seen_at` timestamp is preserved — it reflects when the user first engaged, not when they signed up.
* Events across multiple devices are linked to the same user profile via their shared `userId`.

**Enrichment:**

* Adds server-side timestamp (to detect clock skew on devices)
* Adds geolocation data (country, region, city from IP address)
* Tags events with campaign attribution (which ad/email drove this action)

**Deduplication:**

* Detects if the same event was sent twice (network retry)
* Keeps only one copy (prevents double-counting in reports)

***

### 6. Storage & Availability

**Where events go:**
Events are stored in Zixflow's data platform optimized for two things:

1. **Fast queries:** Run complex reports without waiting
2. **Scalability:** Handle millions of events per day

**What you can do with stored events:**

**Analytics (Fast Queries):**

```
Run a report: "Conversion funnel from Viewed Product → Added to Cart → Purchased"
→ Results in seconds, even across millions of events
```

**Campaign Triggers (Automated):**

```
Set up trigger: "If user adds to cart + doesn't purchase within 2 hours → Send reminder push"
→ Zixflow automatically watches for these conditions
```

***

**Next:** See real-world implementation examples → [E-commerce Tracking](/documentation/events/scenarios/ecommerce)