> ## 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.

# Devices & Push Notifications

> Device tracking, push notification tokens, and multi-device user profiles.

Every interaction with your product happens on a physical device—a phone, tablet, or computer. Zixflow tracks these devices so you can understand cross-device behavior, send timely push notifications, and deliver personalized experiences on the right screen at the right time.

This guide explains what devices are in the Zixflow system, how device tracking works, and how to leverage push notifications to re-engage users.

To register device tokens and configure push in your app, use the [SDK](/documentation/sdk/flutter/introduction) integration guides for [Flutter](/documentation/sdk/flutter/push-notifications), [React Native](/documentation/sdk/react-native/push-notifications), [iOS](/documentation/sdk/ios/push-notifications), [Android](/documentation/sdk/android/push-notifications), or [JavaScript (Web Push)](/documentation/sdk/javascript/web-push-notifications).

***

## What is a Device?

In Zixflow, a **device** represents a specific physical piece of hardware or browser that a user interacts with your product on. Think of it as one "endpoint" where your app or website runs.

### Examples of Devices:

* **Mobile phones**: iPhone 15 Pro, Samsung Galaxy S24, Google Pixel 8
* **Tablets**: iPad Pro, Samsung Tab, Amazon Fire Tablet
* **Desktop/Laptop browsers**: Chrome on MacBook, Firefox on Windows PC, Safari on iMac
* **Wearables** (if your app supports them): Apple Watch, Android smartwatches

### Why Track Devices?

Understanding devices gives you powerful capabilities:

1. **Cross-device user journey**: See how users move between phone, tablet, and desktop
2. **Device-specific experiences**: Optimize onboarding for small screens vs large screens
3. **Push notification delivery**: Reach users wherever they are, on any device
4. **Platform-specific analytics**: Compare iOS vs Android engagement
5. **App version tracking**: Know who's on old versions (for deprecation planning)
6. **Device health monitoring**: Identify devices that haven't been active (potential churn signals)

### How Zixflow Identifies Devices

Each device is uniquely identified by combining:

* **Platform**: iOS, Android, or Web
* **Device token**: A unique string from Apple (APNs), Google (FCM), or browser (Web Push)
* **User association**: Which user (`userId`) is currently logged in on this device — or, before login, which `anonymousId` belongs to this device

Zixflow accepts push tokens under any of the following property names, so your SDK doesn't need to use a specific field name:

| Property name        | Description                       |
| -------------------- | --------------------------------- |
| `device_token`       | Standard Flutter/mobile SDK field |
| `notification_token` | Alternative field name            |
| `token`              | Short-form fallback               |
| `fcm_token`          | Explicit FCM token field          |

**Example:**

```json theme={null}
{
  "deviceId": "dev_abc123",
  "userId": "sarah@example.com",
  "platform": "ios",
  "deviceToken": "eA5w7X8yZ9K2...",
  "model": "iPhone 15 Pro",
  "osVersion": "17.4.1",
  "appVersion": "2.1.0",
  "lastSeen": "2026-06-24T14:30:00Z"
}
```

This device belongs to Sarah, runs on iOS, and can receive push notifications at token `eA5w7X8yZ9K2...`.

### Device Characteristics

Every device has attributes that help you understand and target it:

**System attributes** (automatically captured):

* **Platform**: iOS, Android, Web
* **Device model**: iPhone 15 Pro, Pixel 8, MacBook Pro
* **OS version**: iOS 17.4.1, Android 14, macOS 14.2
* **App version**: 2.1.0 (which version of your app they're using)
* **Screen size**: Useful for optimizing layouts
* **Timezone**: Send notifications at the right local time
* **Language**: Localize content appropriately
* **First seen**: When device was first registered
* **Last seen**: Last time device was active

**Custom attributes** (you can set):

* **Notification preferences**: Which types of notifications user wants
* **Device nickname**: "Sarah's iPhone", "Work Laptop"
* **Quiet hours**: Don't notify between 10 PM and 7 AM
* **Beta tester status**: Is this device part of your beta program?

### One User, Multiple Devices

Modern users interact with your product across multiple devices throughout the day:

**Morning**: Check your app on their phone while commuting\
**Afternoon**: Use your web app on their work computer\
**Evening**: Browse on their tablet on the couch

Zixflow tracks all of these as separate devices but links them to the same user profile. This gives you:

* **Complete activity timeline**: See what they did across all devices
* **Smart notification routing**: Send push to the device they use most
* **Cross-device continuity**: "Continue where you left off" experiences
* **Platform comparison**: Does iOS or Android engage more?

***

## What are Push Notifications?

Push notifications are messages that appear on a user's device **even when your app isn't open**. They're the dings, buzzes, and banners that grab attention and bring users back to your product.

### Anatomy of a Push Notification

A push notification has several components:

**On iOS:**

```
┌────────────────────────────────┐
│  📱 YourApp              5:45 PM │
│  Your trial expires in 3 days   │ ← Title
│  Upgrade now to keep using     │ ← Body
│  premium features              │
└────────────────────────────────┘
```

**Components:**

* **App icon**: Your app's logo (automatic)
* **Title**: Main headline (bold, 40-50 chars)
* **Body**: Supporting message (120-150 chars)
* **Image** (optional): Thumbnail or hero image
* **Action buttons** (optional): "Yes" / "No", "View" / "Dismiss"
* **Deep link**: Where to take user when they tap
* **Badge count**: Number on your app icon (iOS)
* **Sound**: Alert sound (can be custom)

### How Push Notifications Work

The push notification journey involves several systems:

**Step 1: User grants permission**

```
Your App: "YourApp would like to send you notifications"
User: [Taps "Allow"]
```

**Step 2: Platform generates device token**

* iOS: Apple Push Notification service (APNs) generates token
* Android: Firebase Cloud Messaging (FCM) generates token
* Web: Browser generates subscription endpoint

**Step 3: Your app registers token with Zixflow**

```dart theme={null}
// Your app calls Zixflow SDK
Zixflow.registerDeviceToken('eA5w7X8yZ9K2...');
```

**Step 4: Zixflow stores device information**

* Links token to user profile
* Saves platform type (iOS/Android/Web)
* Records device attributes (model, OS version)

**Step 5: You trigger a notification campaign**

* Create campaign in Zixflow dashboard
* Define audience: "Users who signed up 7 days ago and haven't purchased"
* Craft message: "Your trial is ending soon! 🎉"

**Step 6: Zixflow sends to platform**

* iOS devices → APNs (Apple's servers)
* Android devices → FCM (Google's servers)
* Web devices → Web Push service (browser-specific)

**Step 7: Platform delivers to device**

* Device receives notification
* Shows banner/badge/sound based on user settings
* User sees notification

**Step 8: User interacts**

* **Taps notification** → Opens your app at specified deep link → Zixflow tracks "Push Opened"
* **Dismisses** → Notification goes away → Zixflow tracks "Push Dismissed"
* **Ignores** → Notification expires → No interaction tracked

### Why Push Notifications Matter

Push notifications are incredibly powerful for engagement:

**Immediate reach**: Messages arrive in seconds, even if app is closed\
**High visibility**: Appear on lock screen, notification center, top of screen\
**Action-oriented**: Users can respond with one tap\
**Personalized**: Tailored to each user's behavior and preferences\
**Timely**: Triggered by user actions or schedules\
**Cross-platform**: Works on mobile, tablet, desktop, smartwatch

### Types of Push Notifications

**1. Transactional (time-sensitive, always sent)**

* "Your order has shipped!"
* "Payment failed, please update your card"
* "Someone mentioned you in a comment"
* **Characteristic**: User expects these, usually can't opt out

**2. Marketing (promotional, user can opt out)**

* "50% off this weekend only!"
* "New products you might like"
* "Your abandoned cart is waiting"
* **Characteristic**: User must opt in, respect preferences

**3. Lifecycle (product usage, educational)**

* "Complete your profile to unlock features"
* "Your trial expires in 3 days"
* "You haven't visited in a while—here's what's new"
* **Characteristic**: Help user get value, timing matters

**4. Alert/Monitoring (important updates)**

* "Your server is down"
* "Suspicious login detected"
* "Price drop on item you're watching"
* **Characteristic**: Time-critical, requires immediate attention

### Push Notification Best Practices

**✅ DO:**

* Ask for permission at the right moment (not immediately on first app open)
* Explain the value: "Get notified when your friends share photos"
* Personalize messages: Use names, reference their actions
* Respect time zones: Send during waking hours
* Make it actionable: Include clear next steps
* Test on real devices before sending

**❌ DON'T:**

* Spam users with too many notifications (leads to opt-outs)
* Send generic broadcasts: "Check out our app!"
* Forget to segment: Not everyone wants every notification
* Ignore user preferences: Respect opt-outs and quiet hours
* Use ALL CAPS or excessive emojis 🎉🔥💯 (looks spammy)
* Send without testing (broken deep links = bad experience)

***

## Device Registration Flow

### Step 1: SDK Initialization

When your app launches, the Zixflow SDK automatically:

1. Creates a unique ID for this device (for anonymous tracking before signup)
2. Collects device information (phone model, OS version, app version)
3. Tracks the device's timezone and language preferences

**Platform detection is automatic.** Zixflow infers the platform from context in this priority order:

1. `context.device.type` set by the SDK (`"ios"` / `"android"` / `"web"`)
2. `context.os.name` (e.g. `"iOS"`, `"Android"` → mapped to platform)
3. `context.library.name` (e.g. `"analytics.js"` or `"@zixflow/analytics-browser"` → `"web"`)
4. Presence of a browser `userAgent` → `"web"`

You do not need to manually set the platform — it is resolved automatically.

**What gets captured automatically:**

```json theme={null}
{
  "device": {
    "manufacturer": "Apple",
    "model": "iPhone 14 Pro",
    "name": "John's iPhone"
  },
  "os": {
    "name": "iOS",
    "version": "17.4.1"
  },
  "app": {
    "version": "2.1.0",
    "build": "403"
  },
  "locale": "en-US",
  "timezone": "America/New_York"
}
```

**Why this matters:** You can segment users by device type, target specific app versions, and send messages at the right time in their timezone.

***

### Step 2: Push Token Registration (Mobile Only)

For push notifications, you need to register the device:

**Flutter SDK:**

```dart theme={null}
// Register for push notifications
Zixflow.registerDeviceToken('push_token_abc123...');

// Set device preferences (optional)
Zixflow.setDeviceAttributes({
  'notification_categories': ['promotions', 'transactional'],
  'preferred_language': 'en',
  'quiet_hours_start': '22:00',
  'quiet_hours_end': '08:00'
});
```

**What happens:**

* Device is registered in Zixflow with its push token
* You can now send push notifications to this specific device
* Device preferences are saved (so you can respect quiet hours, notification categories, etc.)

***

## Multi-Device Tracking

### Anonymous User with Multiple Devices

**Scenario:** User browses your website on desktop, then installs your mobile app (pre-signup).

**Device 1 (Web):**

```javascript theme={null}
// Browser generates anonymousId
anonymousId: "anon_web_abc-123"

// Events tracked
track('Viewed Product', { product_id: 'prod_456' });
track('Added to Cart', { product_id: 'prod_456' });
```

**Device 2 (Mobile):**

```dart theme={null}
// Mobile SDK generates different anonymousId
anonymousId: "anon_mobile_xyz-789"

// Events tracked
track('App Opened');
track('Viewed Product', { product_id: 'prod_456' });
```

**State:** Two separate anonymous profiles until the user identifies themselves. Once they sign up or log in, Zixflow automatically links both devices to the same user profile and enables push notifications on all of them.

***

### Device Registration Before Sign-Up

Devices do **not** need to be registered after sign-up. If the SDK registers a push token while the user is still anonymous, that device is fully active — you can send push notifications to it right away, just like any identified device. When `identify()` is later called, the device is automatically migrated to the identified user with no re-registration required.

```
Anonymous flow:
  App opens → Device token registered (anonymous_id: anon_123)
  ← Push notifications can be sent to this device immediately

Sign-up (later):
  identify(userId: "sarah", anonymousId: "anon_123")
  ← Device migrated to sarah's profile automatically
  ← Push notifications continue working — nothing changes for the device
```

This works automatically with no extra code in your app.

***

### Identified User with Multiple Devices

**Scenario:** User signs up on mobile, later logs in on desktop.

**Step 1: User signs up on mobile**

```dart theme={null}
// Mobile app
identify({
  userId: 'user_12345',
  anonymousId: 'anon_mobile_xyz-789',
  traits: { email: 'user@example.com' }
});

// Register push token
registerDeviceToken('apns_token_mobile');
```

**Result:**

* Mobile device linked to this user
* Mobile anonymous history merged to user profile
* Device can now receive push notifications

**Step 2: User logs in on desktop**

```javascript theme={null}
// Web app
identify({
  userId: 'user_12345',
  anonymousId: 'anon_web_abc-123',
  traits: { email: 'user@example.com' }
});
```

**Result:**

* Desktop anonymous history merged to user profile
* Both devices now linked to same user
* You can see complete cross-device journey

**What you can see for each user:**

* All registered devices (phone, tablet, desktop)
* Platform for each device (iOS/Android/Web)
* App version on each device
* When each device was last active
* Push notification status for each device

***

## Device System Events

The SDK and system automatically fire a set of predefined track events related to device activity. These are routed to the `device_logs` table (separate from your business events) with a 30-day retention window.

### Device Lifecycle Events (Auto-Tracked)

| Event Name                  | Triggered by                                                       |
| --------------------------- | ------------------------------------------------------------------ |
| `Application Installed`     | SDK on first launch after install                                  |
| `Application Opened`        | App comes to foreground (cold start)                               |
| `Application Foregrounded`  | App returns from background (warm open)                            |
| `Application Backgrounded`  | App moves to background                                            |
| `Application Crashed`       | SDK detects unhandled crash on next launch                         |
| `Device Created or Updated` | SDK registers or refreshes device info                             |
| `Device Registered`         | Push token successfully registered with Zixflow                    |
| `Device Updated`            | Device attributes changed (OS upgrade, app update, token rotation) |

You do not need to call `track()` for any of these — the SDK fires them automatically.

Device lifecycle events are processed even when the user is **not yet identified** (anonymous). The device is registered and linked to the `anonymousId`, push notifications can be sent to it immediately, and it is automatically migrated to the user's profile when `identify()` is called.

### Device Deletion

`Device Deleted` is a server-side lifecycle event (not an auto-tracked SDK event). When triggered, it soft-deletes the device record:

* `active` is set to `false`
* `push_enabled` is set to `false`
* The device record is preserved (not removed) for audit purposes

This stops all push notifications to that device without destroying historical data.

***

**Next:** Learn about profile attributes and how to enrich user data → [Profile Attributes](/documentation/events/attributes)