# Documentation (/docs)



Privacy-first mobile analytics for modern applications. Track user behavior, sessions, and events without compromising user privacy.

## Get Started

Choose your platform to begin integrating Phase Analytics:

* [**Expo**](/docs/get-started/expo) - Complete setup guide for Expo applications
* [**React Native**](/docs/get-started/react-native) - Integration guide for React Native apps
* [**Swift**](/docs/get-started/swift) - iOS SDK for SwiftUI and UIKit applications
* [**Unity**](/docs/get-started/unity) - Unity SDK for iOS and Android games

## Concepts

Learn about Phase Analytics features and workflows:

* [**Query**](/docs/concepts/query) - Read-only SQL against events, users, and sessions
* [**Team & Billing**](/docs/concepts/team-billing) - Manage team members and subscriptions
* [**Publishing**](/docs/concepts/publishing) - App store privacy requirements and disclosures

## Privacy & Legal

Understand how Phase handles your data:

* [**Stored Data**](/docs/privacy/stored-data) - Data storage, retention, and GDPR rights
* [**Privacy Policy**](/docs/privacy/privacy-policy) - Our privacy commitments
* [**Terms of Service**](/docs/privacy/terms-of-service) - Terms and conditions

## Need Help?

Contact us at [support@phase.sh](mailto:support@phase.sh) for assistance.


# Swift (/docs/get-started/swift)



import { Step, Steps } from 'fumadocs-ui/components/steps';
import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Tab, Tabs, TabsList, TabsTrigger, TabsContent } from 'fumadocs-ui/components/tabs';
import { CodeBlock, Pre } from 'fumadocs-ui/components/codeblock';

## Installation

<Steps>
  <Step>
    ### Add Swift Package

    Add Phase Analytics to your project using Swift Package Manager:

    1. In Xcode, go to **File → Add Package Dependencies**
    2. Enter the repository URL: <p className="font-mono text-sm">[https://github.com/Phase-Analytics/Phase-Swift](https://github.com/Phase-Analytics/Phase-Swift)</p>
    3. Select the latest version
    4. Add to your target

    **Or add to Package.swift:**

    <CodeBlock title="Package.swift" lang="swift" icon={<img src="https://cdn.simpleicons.org/swift/F05138" alt="Swift" className="size-4" />}>
      ```swift
      dependencies: [
          .package(url: "https://github.com/Phase-Analytics/Phase-Swift", from: "0.1.9")
      ]
      ```
    </CodeBlock>

    **Requirements:**

    * iOS 15.0+ or macOS 12.0+
    * Swift 6.0+
  </Step>

  <Step>
    ### Get Your API Key

    1. Sign in to [Phase Dashboard](https://phase.sh/dashboard)
    2. Create a new project or select an existing one
    3. Open API Keys tab
    4. Copy your API Key (starts with `phase_`)
  </Step>
</Steps>

## Setup

<Tabs defaultValue="swiftui" persist>
  <TabsList>
    <TabsTrigger value="swiftui">
      SwiftUI
    </TabsTrigger>

    <TabsTrigger value="uikit">
      UIKit
    </TabsTrigger>
  </TabsList>

  <TabsContent value="swiftui">
    ### SwiftUI

    Wrap your app with the `Phase` view to initialize the SDK:

    <CodeBlock title="MyApp.swift" lang="swift" icon={<img src="https://cdn.simpleicons.org/swift/F05138" alt="Swift" className="size-4" />}>
      ```swift
      import SwiftUI
      import PhaseAnalytics

      @main
      struct MyApp: App {
          var body: some Scene {
              WindowGroup {
                  Phase(apiKey: "phase_xxx") {
                      ContentView()
                  }
              }
          }
      }
      ```
    </CodeBlock>
  </TabsContent>

  <TabsContent value="uikit">
    ### UIKit

    Initialize the SDK in your AppDelegate:

    <CodeBlock title="AppDelegate.swift" lang="swift" icon={<img src="https://cdn.simpleicons.org/swift/F05138" alt="Swift" className="size-4" />}>
      ```swift
      import UIKit
      import PhaseAnalytics

      @main
      class AppDelegate: UIResponder, UIApplicationDelegate {
          func application(
              _ application: UIApplication,
              didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
          ) -> Bool {
              Task {
                  try await PhaseSDK.shared.initialize(apiKey: "phase_xxx")
              }
              return true
          }
      }
      ```
    </CodeBlock>
  </TabsContent>
</Tabs>

The SDK initialization is asynchronous. You must call `identify()` before tracking events.

## Configuration

The `Phase` view and `initialize()` method accept the following parameters:

<TypeTable
  type={{
  apiKey: {
    description: 'Your Phase API key (starts with `phase_`)',
    type: 'String',
    required: true,
  },
  baseURL: {
    description: 'Custom API endpoint for self-hosted deployments',
    type: 'String',
    default: '"https://api.phase.sh"',
  },
  logLevel: {
    description: 'Console logging level for debugging',
    type: 'LogLevel (.info | .warn | .error | .none)',
    default: '.none',
  },
  debugData: {
    description: 'Mark identify/events as debug data',
    type: 'Bool',
    default: 'false',
  },
  deviceInfo: {
    description: 'Collect device metadata (model, OS version, platform, app version as `app_version`)',
    type: 'Bool',
    default: 'true',
  },
  userLocale: {
    description: 'Collect user locale and timezone information',
    type: 'Bool',
    default: 'true',
  },
}}
/>

## Usage

### Identify User

**Required:** Call `identify()` before using any other methods. This registers the device and starts a session.

<CodeBlock title="ContentView.swift" lang="swift" icon={<img src="https://cdn.simpleicons.org/swift/F05138" alt="Swift" className="size-4" />}>
  ```swift
  import SwiftUI
  import PhaseAnalytics

  struct ContentView: View {
      var body: some View {
          Text("Hello, World!")
              .onAppear {
                  Task {
                      // Initialize analytics - no PII collected by default
                      await PhaseSDK.shared.identify()
                  }
              }
      }
  }
  ```
</CodeBlock>

**Privacy by default:**

* No personal data is collected without explicit properties
* Device ID is auto-generated and stored locally
* Only technical metadata is collected (OS version, platform, locale, app version)

**Adding custom properties:**

You can optionally attach user properties. **Important:** If you add PII (personally identifiable information), ensure you have proper user consent:

<CodeBlock lang="swift" icon={<img src="https://cdn.simpleicons.org/swift/F05138" alt="Swift" className="size-4" />}>
  ```swift
  // After user login and consent
  await PhaseSDK.shared.identify([
      "user_id": "123",
      "plan": "premium",
      "beta_tester": true
  ])

  // ⚠️ If adding PII, get consent first
  let hasConsent = await customGetUserConsent()
  if hasConsent {
      await PhaseSDK.shared.identify([
          "email": "user@example.com",
          "name": "John Doe"
      ])
  }
  ```
</CodeBlock>

Properties must be primitives: `String`, `Int`, `Double`, `Bool`, or `nil`.

### Track Events

Track custom events with optional parameters. **Note:** `identify()` must be called first.

<CodeBlock lang="swift" icon={<img src="https://cdn.simpleicons.org/swift/F05138" alt="Swift" className="size-4" />}>
  ```swift
  // Event without parameters
  track("app_opened")

  // Event with parameters
  track("purchase_completed", [
      "amount": 99.99,
      "currency": "USD",
      "product_id": "premium_plan"
  ])

  // Using instance method
  PhaseSDK.shared.track("button_clicked", params: ["button_id": "submit"])
  ```
</CodeBlock>

**Event naming rules:**

* Alphanumeric characters, underscores (`_`), hyphens (`-`), periods (`.`), forward slashes (`/`), and spaces
* 1-256 characters
* Examples: `purchase`, `user.signup`, `payment/success`, `Button Clicked`

**Event parameters:**

* Flat primitive dictionary only
* Values must be `String`, `Int`, `Double`, `Bool`, or `nil`
* Max 32 keys
* Key max 32 characters
* String value max 256 characters
* Serialized payload max 8 KB
* Empty dictionaries are normalized away

### Screen Tracking

<Tabs defaultValue="swiftui" persist>
  <TabsList>
    <TabsTrigger value="swiftui">
      SwiftUI
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="swiftui">
    Use the `.phaseScreen()` modifier to automatically track screen views:

    <CodeBlock title="ProfileView.swift" lang="swift" icon={<img src="https://cdn.simpleicons.org/swift/F05138" alt="Swift" className="size-4" />}>
      ```swift
      import SwiftUI
      import PhaseAnalytics

      struct ProfileView: View {
          let userID: String

          var body: some View {
              VStack {
                  Text("Profile")
              }
              .phaseScreen("ProfileView", params: ["user_id": userID])
          }
      }
      ```
    </CodeBlock>

    **How it works:**

    Tracks screen view when the view first appears. Screen names are normalized automatically (e.g., `"ProfileView"` → `"/profile-view"`) with CamelCase converted to kebab-case. Supports optional parameters.
  </TabsContent>

  <TabsContent value="manual">
    Manually track screens using `trackScreen()`:

    <CodeBlock lang="swift" icon={<img src="https://cdn.simpleicons.org/swift/F05138" alt="Swift" className="size-4" />}>
      ```swift
      // Using global function
      trackScreen("/profile", ["user_id": "123"])

      // Using instance method
      PhaseSDK.shared.trackScreen("/settings", params: nil)
      ```
    </CodeBlock>
  </TabsContent>
</Tabs>

## Type Reference

### DeviceProperties

Custom user/device attributes passed to `identify()`:

<TypeTable
  type={{
  '[String: Any]': {
    description: 'Dictionary of custom properties',
    type: 'String | Int | Double | Bool | nil',
  },
}}
/>

### EventParams

Event parameters passed to `track()`:

<TypeTable
  type={{
  '[String: Any]': {
    description: 'Custom parameter name. Max 32 keys. Key max 32 chars. String values max 256 chars. Empty dictionaries are omitted.',
    type: 'String | Int | Double | Bool | nil',
  },
}}
/>

## How It Works

### Offline Support

Events are queued locally using `UserDefaults` when offline. The queue automatically syncs when connection is restored.

### Privacy

* No personal data is collected by default
* Device IDs are generated locally and stored persistently
* Geolocation is resolved server-side from IP address (disable with properties)
* All data collection is optional via configuration

### Performance

* Offline events are batched and sent asynchronously
* Network state is monitored automatically
* Failed requests retry with exponential backoff
* Maximum batch size: 1000 events
* Thread-safe with Swift 6 concurrency


# React Native (/docs/get-started/react-native)



import { Step, Steps } from 'fumadocs-ui/components/steps';
import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Tab, Tabs, TabsList, TabsTrigger, TabsContent } from 'fumadocs-ui/components/tabs';
import { CodeBlock, Pre } from 'fumadocs-ui/components/codeblock';

## Installation

<Steps>
  <Step>
    ### Install the SDK

    <Tabs defaultValue="bun" groupId="pkg" persist>
      <TabsList>
        <TabsTrigger value="npm" className="gap-2">
          <img src="https://cdn.simpleicons.org/npm/71717a" alt="npm" className="size-4 dark:brightness-200" />

          npm
        </TabsTrigger>

        <TabsTrigger value="bun" className="gap-2">
          <img src="https://cdn.simpleicons.org/bun/71717a" alt="bun" className="size-4 dark:brightness-200" />

          bun
        </TabsTrigger>

        <TabsTrigger value="yarn" className="gap-2">
          <img src="https://cdn.simpleicons.org/yarn/71717a" alt="yarn" className="size-4 dark:brightness-200" />

          yarn
        </TabsTrigger>

        <TabsTrigger value="pnpm" className="gap-2">
          <img src="https://cdn.simpleicons.org/pnpm/71717a" alt="pnpm" className="size-4 dark:brightness-200" />

          pnpm
        </TabsTrigger>
      </TabsList>

      <TabsContent value="npm">
        <CodeBlock lang="bash" allowCopy={true}>
          ```bash
          npm install phase-analytics
          ```
        </CodeBlock>
      </TabsContent>

      <TabsContent value="bun">
        <CodeBlock lang="bash" allowCopy={true}>
          ```bash
          bun add phase-analytics
          ```
        </CodeBlock>
      </TabsContent>

      <TabsContent value="yarn">
        <CodeBlock lang="bash" allowCopy={true}>
          ```bash
          yarn add phase-analytics
          ```
        </CodeBlock>
      </TabsContent>

      <TabsContent value="pnpm">
        <CodeBlock lang="bash" allowCopy={true}>
          ```bash
          pnpm add phase-analytics
          ```
        </CodeBlock>
      </TabsContent>
    </Tabs>
  </Step>

  <Step>
    ### Install Required Peer Dependencies

    Phase Analytics requires the following React Native packages to function properly:

    <Tabs defaultValue="bun" groupId="pkg" persist>
      <TabsList>
        <TabsTrigger value="npm" className="gap-2">
          <img src="https://cdn.simpleicons.org/npm/71717a" alt="npm" className="size-4 dark:brightness-200" />

          npm
        </TabsTrigger>

        <TabsTrigger value="bun" className="gap-2">
          <img src="https://cdn.simpleicons.org/bun/71717a" alt="bun" className="size-4 dark:brightness-200" />

          bun
        </TabsTrigger>

        <TabsTrigger value="yarn" className="gap-2">
          <img src="https://cdn.simpleicons.org/yarn/71717a" alt="yarn" className="size-4 dark:brightness-200" />

          yarn
        </TabsTrigger>

        <TabsTrigger value="pnpm" className="gap-2">
          <img src="https://cdn.simpleicons.org/pnpm/71717a" alt="pnpm" className="size-4 dark:brightness-200" />

          pnpm
        </TabsTrigger>
      </TabsList>

      <TabsContent value="npm">
        <CodeBlock lang="bash" allowCopy={true}>
          ```bash
          npm install @react-native-async-storage/async-storage @react-native-community/netinfo react-native-device-info react-native-localize @react-navigation/native
          ```
        </CodeBlock>
      </TabsContent>

      <TabsContent value="bun">
        <CodeBlock lang="bash" allowCopy={true}>
          ```bash
          bun add @react-native-async-storage/async-storage @react-native-community/netinfo react-native-device-info react-native-localize  @react-navigation/native
          ```
        </CodeBlock>
      </TabsContent>

      <TabsContent value="yarn">
        <CodeBlock lang="bash" allowCopy={true}>
          ```bash
          yarn add @react-native-async-storage/async-storage @react-native-community/netinfo react-native-device-info react-native-localize @react-navigation/native
          ```
        </CodeBlock>
      </TabsContent>

      <TabsContent value="pnpm">
        <CodeBlock lang="bash" allowCopy={true}>
          ```bash
          pnpm add @react-native-async-storage/async-storage @react-native-community/netinfo react-native-device-info react-native-localize @react-navigation/native
          ```
        </CodeBlock>
      </TabsContent>
    </Tabs>

    These dependencies are **required** for the SDK to work correctly. The SDK uses:

    * `@react-native-async-storage/async-storage` - Local storage for offline event queuing
    * `@react-native-community/netinfo` - Network state monitoring
    * `react-native-device-info` - Device information collection
    * `react-native-localize` - Locale and timezone detection
    * `@react-navigation/native` - Automatic screen tracking (only needed if using `trackNavigation`)
  </Step>

  <Step>
    ### Install iOS Dependencies

    For iOS, install CocoaPods dependencies:

    <CodeBlock lang="bash" allowCopy={true}>
      ```bash
      cd ios && pod install
      ```
    </CodeBlock>
  </Step>

  <Step>
    ### Get Your API Key

    1. Sign in to [Phase Dashboard](https://phase.sh/dashboard)
    2. Create a new project or select an existing one
    3. Open API Keys tab
    4. Copy your API Key (starts with `phase_`)
  </Step>
</Steps>

## Setup

Wrap your app with the `PhaseProvider` component to initialize the SDK:

<CodeBlock title="App.tsx" lang="tsx" icon={<img src="https://cdn.simpleicons.org/react/61DAFB" alt="React" className="size-4" />}>
  ```tsx
  import { PhaseProvider } from 'phase-analytics/react-native';
  import { NavigationContainer } from '@react-navigation/native';

  export default function App() {
    return (
      <NavigationContainer>
        <PhaseProvider apiKey="phase_xxx">
          <YourApp />
        </PhaseProvider>
      </NavigationContainer>
    );
  }
  ```
</CodeBlock>

The `PhaseProvider` only initializes the SDK. You must call `Phase.identify()` before tracking events.

## Configuration

The `PhaseProvider` component accepts the following props:

<TypeTable
  type={{
  apiKey: {
    description: 'Your Phase API key (starts with `phase_`)',
    type: 'string',
    required: true,
  },
  navigationRef: {
    description: 'Navigation container ref for automatic screen tracking',
    type: 'NavigationContainerRef',
    required: false,
  },
  trackNavigation: {
    description: 'Automatically track screen views with React Navigation',
    type: 'boolean',
    default: 'false',
  },
  debugData: {
    description: 'Mark identify/events as debug data',
    type: 'boolean',
    default: 'false',
  },
  baseUrl: {
    description: 'Custom API endpoint for self-hosted deployments',
    type: 'string',
    default: '"https://api.phase.sh"',
  },
  logLevel: {
    description: 'Console logging level for debugging',
    type: '"info" | "warn" | "error" | "none"',
    default: '"none"',
  },
  deviceInfo: {
    description: 'Collect device metadata (model, OS version, platform, app version as `app_version`)',
    type: 'boolean',
    default: 'true',
  },
  userLocale: {
    description: 'Collect user locale and timezone information',
    type: 'boolean',
    default: 'true',
  },
}}
/>

## Usage

### Identify User

**Required:** Call `Phase.identify()` before using any other methods. This registers the device and starts a session.

<CodeBlock title="App.tsx" lang="tsx" icon={<img src="https://cdn.simpleicons.org/react/61DAFB" alt="React" className="size-4" />}>
  ```tsx
  import { Phase } from 'phase-analytics/react-native';
  import { useEffect } from 'react';

  export default function App() {
    useEffect(() => {
      // Initialize analytics - no PII collected by default
      Phase.identify();
    }, []);

    return <YourApp />;
  }
  ```
</CodeBlock>

**Privacy by default:**

* No personal data is collected without explicit properties
* Device ID is auto-generated and stored locally
* Only technical metadata is collected (OS version, platform, locale)

**Adding custom properties:**

You can optionally attach user properties. **Important:** If you add PII (personally identifiable information), ensure you have proper user consent:

<CodeBlock lang="tsx" icon={<img src="https://cdn.simpleicons.org/typescript/3178C6" alt="TypeScript" className="size-4" />}>
  ```tsx
  // After user login and consent
  await Phase.identify({
    user_id: '123',
    plan: 'premium',
    beta_tester: true
  });

  // ⚠️ If adding PII, get consent first
  const hasConsent = await customGetUserConsent();
  if (hasConsent) {
    await Phase.identify({
      email: 'user@example.com',
      name: 'John Doe'
    });
  }
  ```
</CodeBlock>

Properties must be primitives: `string`, `number`, `boolean`, or `null`.

### Track Events

Track custom events with optional parameters. **Note:** `Phase.identify()` must be called first.

<CodeBlock lang="tsx" icon={<img src="https://cdn.simpleicons.org/typescript/3178C6" alt="TypeScript" className="size-4" />}>
  ```tsx
  // Event without parameters
  Phase.track('app_opened');

  // Event with parameters
  Phase.track('purchase_completed', {
    amount: 99.99,
    currency: 'USD',
    product_id: 'premium_plan'
  });
  ```
</CodeBlock>

**Event naming rules:**

* Alphanumeric characters, underscores (`_`), hyphens (`-`), periods (`.`), forward slashes (`/`), and spaces
* 1-256 characters
* Examples: `purchase`, `user.signup`, `payment/success`, `Button Clicked`

**Event parameters:**

* Flat primitive object only
* Values must be `string`, `number`, `boolean`, or `null`
* Max 32 keys
* Key max 32 characters
* String value max 256 characters
* Serialized payload max 8 KB
* Empty objects are normalized away

### Automatic Screen Tracking

Enable automatic screen tracking by setting `trackNavigation` to `true` and passing a `navigationRef`:

<CodeBlock title="App.tsx" lang="tsx" icon={<img src="https://cdn.simpleicons.org/react/61DAFB" alt="React" className="size-4" />}>
  ```tsx
  import { PhaseProvider } from 'phase-analytics/react-native';
  import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native';
  import { createNativeStackNavigator } from '@react-navigation/native-stack';

  const Stack = createNativeStackNavigator();

  export default function App() {
    const navigationRef = useNavigationContainerRef();

    return (
      <NavigationContainer ref={navigationRef}>
        <PhaseProvider
          apiKey="phase_xxx"
          trackNavigation={true}
          navigationRef={navigationRef}
        >
          <Stack.Navigator>
            <Stack.Screen name="Home" component={HomeScreen} />
            <Stack.Screen name="Settings" component={SettingsScreen} />
          </Stack.Navigator>
        </PhaseProvider>
      </NavigationContainer>
    );
  }
  ```
</CodeBlock>

**How it works:**

* Requires `navigationRef` from `useNavigationContainerRef()` hook
* Pass the ref to both `NavigationContainer` and `PhaseProvider`
* Automatically tracks screen views on navigation state changes
* Screen names are converted from route names
* Works with nested navigators and dynamic routes

**Important:** The `navigationRef` must be passed to both `NavigationContainer` and `PhaseProvider` for automatic tracking to work.

## Type Reference

### DeviceProperties

Custom user/device attributes passed to `Phase.identify()`:

<TypeTable
  type={{
  '[key: string]': {
    description: 'Any custom property name',
    type: 'string | number | boolean | null',
  },
}}
/>

### EventParams

Event parameters passed to `Phase.track()`:

<TypeTable
  type={{
  '[key: string]': {
    description: 'Custom parameter name. Max 32 keys. Key max 32 chars. String values max 256 chars. Empty objects are omitted.',
    type: 'string | number | boolean | null',
  },
}}
/>

## How It Works

### Offline Support

Events are queued locally using `@react-native-async-storage/async-storage` when offline. The queue automatically syncs when connection is restored.

### Privacy

* No personal data is collected by default
* Device IDs are generated locally and stored persistently
* Geolocation is resolved server-side from IP address (disable with properties)
* All data collection is optional via configuration

### Performance

* Offline events are batched and sent asynchronously
* Network state is monitored via `@react-native-community/netinfo`
* Failed requests retry with exponential backoff
* Maximum batch size: 1000 events


# Unity (/docs/get-started/unity)



import { Step, Steps } from 'fumadocs-ui/components/steps';
import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Tab, Tabs, TabsList, TabsTrigger, TabsContent } from 'fumadocs-ui/components/tabs';
import { CodeBlock, Pre } from 'fumadocs-ui/components/codeblock';

## Installation

Phase Analytics ships as a **Unity Package Manager (UPM)** package from the [Phase monorepo](https://github.com/Phase-Analytics/Phase). There is no `.unitypackage` download.

<Steps>
  <Step>
    ### Add the UPM package

    <Tabs defaultValue="manifest" persist>
      <TabsList>
        <TabsTrigger value="manifest">
          manifest.json
        </TabsTrigger>

        <TabsTrigger value="ui">
          Package Manager UI
        </TabsTrigger>
      </TabsList>

      <TabsContent value="manifest">
        Add to `Packages/manifest.json` (recommended for teams and CI):

        <CodeBlock title="Packages/manifest.json" lang="json" allowCopy={true}>
          ```json
          {
            "dependencies": {
              "com.phase.analytics": "https://github.com/Phase-Analytics/Phase.git?path=packages/phase-unity#v0.1.11"
            }
          }
          ```
        </CodeBlock>

        Return to Unity and let Package Manager resolve the dependency.
      </TabsContent>

      <TabsContent value="ui">
        1. **Window → Package Manager**
        2. **+ → Add package from git URL…**
        3. Paste:

        <CodeBlock lang="text" allowCopy={true}>
          ```
          https://github.com/Phase-Analytics/Phase.git?path=packages/phase-unity#v0.1.11
          ```
        </CodeBlock>

        4. Select **Add**
      </TabsContent>
    </Tabs>

    Pin the release tag:

    ```
    #v0.1.11
    ```
  </Step>

  <Step>
    ### Install required dependency

    The package declares `com.unity.nuget.newtonsoft-json` in `package.json`. Unity should install it automatically when you add Phase Analytics.

    If Package Manager shows a missing dependency warning:

    1. Open **Package Manager**
    2. Select **Packages: Unity Registry**
    3. Search **Newtonsoft Json**
    4. Install **com.unity.nuget.newtonsoft-json** (3.2.1+)

    The SDK uses Newtonsoft.Json for batch payloads and offline queue serialization. `Runtime/link.xml` preserves the assembly for IL2CPP builds.
  </Step>

  <Step>
    ### Verify the import

    After resolution, confirm the package is healthy **before** wiring game code:

    1. **Package Manager** lists `Phase Analytics` (`com.phase.analytics`)
    2. **Console** has **no** warnings like `has no meta file, but it's in an immutable folder`
    3. **Console** has **no** `CS8773` (file-scoped namespace) errors
    4. Assembly **`Phase.Analytics`** appears under **Project → Assemblies** (or compiles without errors)

    If any check fails, upgrade to `#v0.1.11` or newer, remove `Library/PackageCache/com.phase.analytics@*`, and re-import. Do not patch files inside `PackageCache` by hand.
  </Step>

  <Step>
    ### Get Your API Key

    1. Sign in to [Phase Dashboard](https://phase.sh/dashboard)
    2. Create a new project or select an existing one
    3. Open **API Keys** tab
    4. Copy your API Key (starts with `phase_`)
  </Step>
</Steps>

## Setup

Initialize once at startup, then call `IdentifyAsync` before tracking. Call `InitializeAsync` and `IdentifyAsync` from the Unity main thread (`Start`, `Awake`, or a coroutine started there). With `AutoBootstrap` enabled (default), the SDK spawns a `DontDestroyOnLoad` `PhaseLifecycleHook` that flushes on pause/quit and resumes sessions when the app returns.

<Tabs defaultValue="bootstrap" persist>
  <TabsList>
    <TabsTrigger value="bootstrap">
      Bootstrap script
    </TabsTrigger>

    <TabsTrigger value="sample">
      Package sample
    </TabsTrigger>

    <TabsTrigger value="editor">
      Editor / dev
    </TabsTrigger>
  </TabsList>

  <TabsContent value="bootstrap">
    Attach a bootstrap `MonoBehaviour` to a GameObject in your first scene (or a persistent loader scene):

    <CodeBlock title="GameBootstrap.cs" lang="csharp" icon={<img src="https://cdn.simpleicons.org/unity/FFFFFF" alt="Unity" className="size-4 dark:invert" />}>
      ```csharp
      using Phase.Analytics;
      using Phase.Analytics.Config;
      using Phase.Analytics.Models;
      using UnityEngine;

      public sealed class GameBootstrap : MonoBehaviour
      {
          [SerializeField] private string apiKey = "phase_xxx";

          private async void Start()
          {
              var ok = await PhaseAnalytics.InitializeAsync(new PhaseConfig
              {
                  ApiKey = apiKey,
                  LogLevel = LogLevel.Info,
              });

              if (!ok)
              {
                  Debug.LogWarning("[Phase] Initialize failed. Check API key and network.");
                  return;
              }

              await PhaseAnalytics.IdentifyAsync();
              PhaseAnalytics.Track("app_opened");
          }
      }
      ```
    </CodeBlock>

    `InitializeAsync` is idempotent. `IdentifyAsync` must succeed before events are sent. Both must run on the main thread so Unity APIs and the lifecycle hook stay safe after `await`.
  </TabsContent>

  <TabsContent value="sample">
    Import the bundled sample from Package Manager:

    1. **Window → Package Manager**
    2. Select **Phase Analytics** in the left list
    3. Open **Samples**
    4. Import **Phase Analytics Sample**
    5. Add `PhaseAnalyticsBootstrap` to a scene and set your API key in the Inspector

    The sample lives under `Samples~/PhaseAnalyticsSample` in the package (not copied into your `Assets/` until imported).
  </TabsContent>

  <TabsContent value="editor">
    For day-to-day Editor work without hitting production:

    <CodeBlock lang="csharp" icon={<img src="https://cdn.simpleicons.org/unity/FFFFFF" alt="Unity" className="size-4 dark:invert" />}>
      ```csharp
      await PhaseAnalytics.InitializeAsync(new PhaseConfig
      {
          ApiKey = "phase_xxx",
          DisableInEditor = true,
          DebugData = true,
          LogLevel = LogLevel.Info,
      });
      ```
    </CodeBlock>

    **DisableInEditor** skips network I/O in the Unity Editor (calls still queue logic where applicable).

    **DebugData** sends `x-phase-debug-data: 1` so events are marked as debug in the dashboard.

    **Always** validate on a **physical device** with an IL2CPP **Release** build before shipping.
  </TabsContent>
</Tabs>

## Configuration

`PhaseConfig` is passed to `PhaseAnalytics.InitializeAsync()`:

<TypeTable
  type={{
  ApiKey: {
    description: 'Your Phase API key (starts with `phase_`)',
    type: 'string',
    required: true,
  },
  BaseUrl: {
    description: 'Custom API endpoint for self-hosted deployments',
    type: 'string',
    default: '"https://api.phase.sh"',
  },
  LogLevel: {
    description: 'Console logging level for debugging',
    type: 'LogLevel (`Info` | `Warn` | `Error` | `None`)',
    default: 'None',
  },
  DebugData: {
    description: 'Mark identify/events as debug data (`x-phase-debug-data: 1`)',
    type: 'bool',
    default: 'false',
  },
  DeviceInfo: {
    description: 'Collect device metadata (`app_version`, `engine`, `unity_version`, OS, model)',
    type: 'bool',
    default: 'true',
  },
  UserLocale: {
    description: 'Collect locale; server may geolocate from IP when enabled',
    type: 'bool',
    default: 'true',
  },
  AutoBootstrap: {
    description: 'Create `PhaseLifecycleHook` (`DontDestroyOnLoad`) on initialize for pause/resume and flush-on-quit',
    type: 'bool',
    default: 'true',
  },
  DisableInEditor: {
    description: 'Skip network calls while running in the Unity Editor',
    type: 'bool',
    default: 'false',
  },
  UseUnityWebRequestTransport: {
    description: 'Use `UnityWebRequest` instead of `System.Net.Http` (main-thread marshaled). Leave `false` unless you need UWR specifically.',
    type: 'bool',
    default: 'false',
  },
  AllowInsecureDev: {
    description: 'Allow `http` `BaseUrl` (development only; production must use HTTPS)',
    type: 'bool',
    default: 'false',
  },
}}
/>

**Platform:** on iOS/Android player builds, identify sends `platform: "ios"` or `"android"`. In the Editor it is `null`.

### Threading and HTTP

Call `InitializeAsync` and `IdentifyAsync` from the Unity main thread (`Start`, `Awake`, or a coroutine started there). The SDK uses `ConfigureAwait(false)` internally so continuations often run on the thread pool.

Unity-only APIs (`GameObject`, `Application`, `UnityWebRequest`) are gated to the main thread: lifecycle hook creation, device info snapshot, network reachability polling, and optional `UnityWebRequest` transport.

Default HTTP is **`System.Net.Http`** (`SystemNetHttpTransport`), which is safe from pool threads. Set `UseUnityWebRequestTransport = true` only if you need `UnityWebRequest`; those calls are queued to `PhaseLifecycleHook.Update`.

## Usage

### Identify User

**Required:** Call `IdentifyAsync()` before `Track()`. This registers the device and starts a session.

<CodeBlock title="GameBootstrap.cs" lang="csharp" icon={<img src="https://cdn.simpleicons.org/unity/FFFFFF" alt="Unity" className="size-4 dark:invert" />}>
  ```csharp
  // No PII by default
  await PhaseAnalytics.IdentifyAsync();

  // Optional properties after login
  await PhaseAnalytics.IdentifyAsync(new DeviceProperties
  {
      ["user_id"] = "123",
      ["plan"] = "premium",
      ["beta_tester"] = true,
  });
  ```
</CodeBlock>

**Privacy by default:**

* No personal data is collected without explicit properties
* Device ID is generated locally (ULID) and stored under `Application.persistentDataPath`
* Only technical metadata is collected when enabled (OS, model, app version, locale)

**Adding custom properties:**

You can attach user/device properties. **Important:** If you add PII (personally identifiable information), ensure you have proper user consent:

<CodeBlock lang="csharp" icon={<img src="https://cdn.simpleicons.org/unity/FFFFFF" alt="Unity" className="size-4 dark:invert" />}>
  ```csharp
  // After user login and consent
  await PhaseAnalytics.IdentifyAsync(new DeviceProperties
  {
      ["user_id"] = accountId,
      ["plan"] = "premium",
  });

  // If adding PII, get consent first
  if (userHasConsentedToAnalytics)
  {
      await PhaseAnalytics.IdentifyAsync(new DeviceProperties
      {
          ["email"] = user.Email,
          ["display_name"] = user.DisplayName,
      });
  }
  ```
</CodeBlock>

Properties must be flat primitives: `string`, `number`, `bool`, or `null`.

### Track Events

Track custom events with optional parameters. **Note:** `IdentifyAsync()` must complete successfully first.

<CodeBlock lang="csharp" icon={<img src="https://cdn.simpleicons.org/unity/FFFFFF" alt="Unity" className="size-4 dark:invert" />}>
  ```csharp
  // Event without parameters
  PhaseAnalytics.Track("app_opened");

  // Event with parameters
  PhaseAnalytics.Track("purchase_completed", new EventParams
  {
      ["amount"] = 99.99,
      ["currency"] = "USD",
      ["product_id"] = "premium_plan",
  });

  // Level / gameplay
  PhaseAnalytics.Track("level_complete", new EventParams
  {
      ["level"] = 5,
      ["score"] = 1200,
      ["duration_sec"] = 42.5,
  });
  ```
</CodeBlock>

`Track` is **non-blocking** (fire-and-forget). Failures are logged when `LogLevel` is enabled and events are queued for retry when appropriate.

**Event naming rules:**

* Alphanumeric characters, underscores (`_`), hyphens (`-`), periods (`.`), forward slashes (`/`), and spaces
* 1–256 characters
* Examples: `purchase`, `user.signup`, `payment/success`, `Button Clicked`

**Event parameters:**

* Flat primitive object only
* Values must be `string`, `number`, `bool`, or `null`
* Max 32 keys
* Key max 32 characters
* String value max 256 characters
* Serialized payload max 8 KB
* Empty objects are normalized away

### Scenes and levels (manual events)

Model scenes and levels with `Track`:

<CodeBlock title="SceneLoader.cs" lang="csharp" icon={<img src="https://cdn.simpleicons.org/unity/FFFFFF" alt="Unity" className="size-4 dark:invert" />}>
  ```csharp
  using Phase.Analytics;
  using Phase.Analytics.Models;
  using UnityEngine;
  using UnityEngine.SceneManagement;

  public sealed class SceneAnalytics : MonoBehaviour
  {
      private void OnEnable() => SceneManager.sceneLoaded += OnSceneLoaded;
      private void OnDisable() => SceneManager.sceneLoaded -= OnSceneLoaded;

      private void OnSceneLoaded(Scene scene, LoadSceneMode mode)
      {
          PhaseAnalytics.Track("scene_loaded", new EventParams
          {
              ["scene"] = scene.name,
              ["mode"] = mode.ToString(),
          });
      }
  }
  ```
</CodeBlock>

### Clear local data

Wipes persisted SDK storage on device (GDPR-style). Does **not** delete server-side data.

<CodeBlock lang="csharp" icon={<img src="https://cdn.simpleicons.org/unity/FFFFFF" alt="Unity" className="size-4 dark:invert" />}>
  ```csharp
  await PhaseAnalytics.ClearLocalDataAsync();

  // Re-initialize before tracking again
  await PhaseAnalytics.InitializeAsync(new PhaseConfig { ApiKey = "phase_xxx" });
  await PhaseAnalytics.IdentifyAsync();
  ```
</CodeBlock>

### API reference

| Member                             | Description                                                                                              |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `InitializeAsync(PhaseConfig)`     | Sets up storage, HTTP, managers, optional lifecycle hook. Returns `false` on invalid config. Idempotent. |
| `IdentifyAsync(DeviceProperties?)` | Registers device and starts session. Required before reliable tracking.                                  |
| `Track(string, EventParams?)`      | Queues a custom event. Requires prior identify.                                                          |
| `ClearLocalDataAsync()`            | Deletes local Phase storage directory.                                                                   |
| `IsInitialized`                    | `true` after successful `InitializeAsync`.                                                               |
| `IsIdentified`                     | `true` after successful `IdentifyAsync`.                                                                 |

## Type Reference

### DeviceProperties

Custom user/device attributes passed to `IdentifyAsync()`:

<TypeTable
  type={{
  '[string]': {
    description: 'Any custom property name. Flat primitives only.',
    type: 'string | number | bool | null',
  },
}}
/>

### EventParams

Event parameters passed to `Track()`:

<TypeTable
  type={{
  '[string]': {
    description: 'Custom parameter name. Max 32 keys. Key max 32 chars. String values max 256 chars. Empty objects are omitted.',
    type: 'string | number | bool | null',
  },
}}
/>

## How It Works

### Lifecycle and sessions

When `AutoBootstrap` is `true`, `PhaseLifecycleHook` is created at the start of `InitializeAsync` (before async I/O):

* Listens for `OnApplicationPause` / focus changes
* Flushes the offline queue when the app backgrounds or quits
* Resumes session handling when the app returns
* Polls network reachability on the main thread (`Update`)

Session pings run on a timer while identified. Events sent without a valid session are rejected client-side until `IdentifyAsync` succeeds.

### Offline Support

Events are stored under:

`Application.persistentDataPath/phase-analytics-data/`

When offline or when requests fail, items stay in the queue. The SDK flushes after `IdentifyAsync` when the network is available and on lifecycle boundaries. Large backlogs use gzip batch upload (100+ queued items).

### Privacy

* No personal data is collected by default
* Device IDs are generated locally and stored persistently
* Geolocation is resolved server-side from IP when `UserLocale` is enabled
* No IDFA or advertising identifiers in v1
* All metadata collection is optional via `DeviceInfo` / `UserLocale`

### Performance

* `Track` does not block the game thread
* Rate limit: 15 events per second
* 50 ms deduplication window for identical event name + parameters
* Offline queue capped at 1000 items; batches up to 1000 items per request
* Failed requests retry with exponential backoff (HTTP layer)

## Production builds (IL2CPP)

Editor Play Mode is **not** enough to validate analytics. Ship only after a device smoke test.

<Steps>
  <Step>
    ### Project settings

    * **Scripting backend:** IL2CPP (recommended for iOS; typical for Android release)
    * **Target:** iOS 12+ / Android API 21+
    * Do not strip `Phase.Analytics` or Newtonsoft — the package includes `Runtime/link.xml`
  </Step>

  <Step>
    ### Build and smoke test

    1. Build **Release** to a physical device
    2. Cold start → confirm `InitializeAsync` + `IdentifyAsync` in logs (if `LogLevel.Info`)
    3. Trigger a few `Track` calls
    4. Background the app (home button) to force flush
    5. Open [Phase Dashboard](https://phase.sh/dashboard) and confirm events within a few minutes
  </Step>
</Steps>

<Tabs defaultValue="ios" persist>
  <TabsList>
    <TabsTrigger value="ios">
      iOS
    </TabsTrigger>

    <TabsTrigger value="android">
      Android
    </TabsTrigger>
  </TabsList>

  <TabsContent value="ios">
    Use a **Development** or **Release** IL2CPP build on hardware (Simulator can miss networking edge cases).

    Ensure App Transport Security allows your `BaseUrl` (default `https://api.phase.sh` is fine).

    **Offline test:** enable airplane mode, `Track` events, disable airplane mode, background the app, verify flush in the dashboard.
  </TabsContent>

  <TabsContent value="android">
    Use an IL2CPP **Release** build on a physical device.

    Confirm `INTERNET` permission (Unity adds it by default for network builds).

    **Offline test:** same flow as iOS after reconnecting.
  </TabsContent>
</Tabs>

## Troubleshooting

### Package import (git UPM)

| Issue                                               | What to check                                                                                                                                 |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `has no meta file, but it's in an immutable folder` | Upgrade to `#v0.1.0`+. Git UPM cannot generate `.meta` at import time.                                                                        |
| `CS8773` file-scoped namespace                      | Upgrade to `#v0.1.2`+ (`Runtime/csc.rsp`). Asmdef `langVersion` alone is insufficient on Unity 6 git UPM.                                     |
| `CS0246` `Timer` in `UnityNetworkMonitor`           | Upgrade to `#v0.1.3`+ (`using System.Threading`)                                                                                              |
| `CS0103` `ValidationConstants`                      | Upgrade to `#v0.1.4`+                                                                                                                         |
| `CS0104` ambiguous `Logger`                         | Upgrade to `#v0.1.4`+ (`PhaseLifecycleHook`)                                                                                                  |
| `CS0246` / `Phase` not found                        | `Phase.Analytics` assembly did not compile. Fix import/compile errors first; do not enable game `asmdef` references until the package builds. |
| Package stuck on old version                        | Remove `Library/PackageCache/com.phase.analytics@*`, bump hash/tag in `manifest.json`, restart Unity.                                         |

### Runtime

| Issue                                                  | What to check                                                                                          |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| `Internal_CreateGameObject` / main thread              | Fixed in `#v0.1.7+`. Call `InitializeAsync` from main thread (`Start` / coroutine).                    |
| `Create can only be called from the main thread` (UWR) | Upgrade to `#v0.1.9+` (default `System.Net.Http`).                                                     |
| `Session not found` / batch dropped after init         | Failed session/API from UWR off-thread before `#v0.1.9`. Upgrade to `#v0.1.9`.                         |
| `InitializeAsync` returns `false`                      | API key must start with `phase_`; `BaseUrl` must be HTTPS unless `AllowInsecureDev` is `true`          |
| No events in dashboard                                 | Call `IdentifyAsync` before `Track`; test on device, not Editor-only (`DisableInEditor` skips network) |
| HTTP 401                                               | Invalid or revoked API key                                                                             |
| Queue not flushing                                     | Device online, identified, and app backgrounded or session active; check `LogLevel.Info`               |
| Duplicate events                                       | 50 ms dedupe collapses identical name + params; intentional for burst clicks                           |

### IL2CPP / release

| Issue                          | What to check                                                                      |
| ------------------------------ | ---------------------------------------------------------------------------------- |
| Stripping / missing types      | Keep package `link.xml`; do not strip `Phase.Analytics` or Newtonsoft              |
| Newtonsoft errors at runtime   | Ensure `com.unity.nuget.newtonsoft-json` is installed                              |
| Works in Editor, not on device | Run IL2CPP Release on hardware; verify ATS (iOS) and network permissions (Android) |

## Differences from other SDKs

| Feature          | Expo / React Native               | Unity                                         |
| ---------------- | --------------------------------- | --------------------------------------------- |
| Screen tracking  | Automatic (optional, Expo Router) | Manual `Track` events                         |
| `platform` field | Sent (`ios` / `android`)          | Sent on mobile player builds                  |
| Distribution     | npm `phase-analytics`             | Git UPM `#v0.1.11`                            |
| Init pattern     | Provider / hook                   | `InitializeAsync` + `MonoBehaviour` bootstrap |

For the same event schema and dashboard, keep event names and parameter keys aligned across your mobile clients.


# Expo (/docs/get-started/expo)



import { Step, Steps } from 'fumadocs-ui/components/steps';
import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Tab, Tabs, TabsList, TabsTrigger, TabsContent } from 'fumadocs-ui/components/tabs';
import { CodeBlock, Pre } from 'fumadocs-ui/components/codeblock';

## Installation

<Steps>
  <Step>
    ### Install the SDK

    <Tabs defaultValue="bun" groupId="pkg" persist>
      <TabsList>
        <TabsTrigger value="npm" className="gap-2">
          <img src="https://cdn.simpleicons.org/npm/71717a" alt="npm" className="size-4 dark:brightness-200" />

          npm
        </TabsTrigger>

        <TabsTrigger value="bun" className="gap-2">
          <img src="https://cdn.simpleicons.org/bun/71717a" alt="bun" className="size-4 dark:brightness-200" />

          bun
        </TabsTrigger>

        <TabsTrigger value="yarn" className="gap-2">
          <img src="https://cdn.simpleicons.org/yarn/71717a" alt="yarn" className="size-4 dark:brightness-200" />

          yarn
        </TabsTrigger>

        <TabsTrigger value="pnpm" className="gap-2">
          <img src="https://cdn.simpleicons.org/pnpm/71717a" alt="pnpm" className="size-4 dark:brightness-200" />

          pnpm
        </TabsTrigger>
      </TabsList>

      <TabsContent value="npm">
        <CodeBlock lang="bash" allowCopy={true}>
          ```bash
          npm install phase-analytics
          ```
        </CodeBlock>
      </TabsContent>

      <TabsContent value="bun">
        <CodeBlock lang="bash" allowCopy={true}>
          ```bash
          bun add phase-analytics
          ```
        </CodeBlock>
      </TabsContent>

      <TabsContent value="yarn">
        <CodeBlock lang="bash" allowCopy={true}>
          ```bash
          yarn add phase-analytics
          ```
        </CodeBlock>
      </TabsContent>

      <TabsContent value="pnpm">
        <CodeBlock lang="bash" allowCopy={true}>
          ```bash
          pnpm add phase-analytics
          ```
        </CodeBlock>
      </TabsContent>
    </Tabs>
  </Step>

  <Step>
    ### Install Required Peer Dependencies

    Phase Analytics requires the following Expo packages to function properly:

    <Tabs defaultValue="bun" groupId="pkg" persist>
      <TabsList>
        <TabsTrigger value="npm" className="gap-2">
          <img src="https://cdn.simpleicons.org/npm/71717a" alt="npm" className="size-4 dark:brightness-200" />

          npm
        </TabsTrigger>

        <TabsTrigger value="bun" className="gap-2">
          <img src="https://cdn.simpleicons.org/bun/71717a" alt="bun" className="size-4 dark:brightness-200" />

          bun
        </TabsTrigger>

        <TabsTrigger value="yarn" className="gap-2">
          <img src="https://cdn.simpleicons.org/yarn/71717a" alt="yarn" className="size-4 dark:brightness-200" />

          yarn
        </TabsTrigger>

        <TabsTrigger value="pnpm" className="gap-2">
          <img src="https://cdn.simpleicons.org/pnpm/71717a" alt="pnpm" className="size-4 dark:brightness-200" />

          pnpm
        </TabsTrigger>
      </TabsList>

      <TabsContent value="npm">
        <CodeBlock lang="bash" allowCopy={true}>
          ```bash
          npx expo install @react-native-async-storage/async-storage @react-native-community/netinfo expo-application expo-device expo-localization expo-router
          ```
        </CodeBlock>
      </TabsContent>

      <TabsContent value="bun">
        <CodeBlock lang="bash" allowCopy={true}>
          ```bash
          bunx expo install @react-native-async-storage/async-storage @react-native-community/netinfo expo-application expo-device expo-localization expo-router
          ```
        </CodeBlock>
      </TabsContent>

      <TabsContent value="yarn">
        <CodeBlock lang="bash" allowCopy={true}>
          ```bash
          yarn dlx expo install @react-native-async-storage/async-storage @react-native-community/netinfo expo-application expo-device expo-localization expo-router
          ```
        </CodeBlock>
      </TabsContent>

      <TabsContent value="pnpm">
        <CodeBlock lang="bash" allowCopy={true}>
          ```bash
          pnpm dlx expo install @react-native-async-storage/async-storage @react-native-community/netinfo expo-application expo-device expo-localization expo-router
          ```
        </CodeBlock>
      </TabsContent>
    </Tabs>

    These dependencies are **required** for the SDK to work correctly. The SDK uses:

    * `@react-native-async-storage/async-storage` - Local storage for offline event queuing
    * `@react-native-community/netinfo` - Network state monitoring
    * `expo-application` - App version collection (`app_version`)
    * `expo-device` - Device information collection
    * `expo-localization` - Locale and timezone detection
    * `expo-router` - Automatic screen tracking
  </Step>

  <Step>
    ### Get Your API Key

    1. Sign in to [Phase Dashboard](https://phase.sh/dashboard)
    2. Create a new project or select an existing one
    3. Open API Keys tab
    4. Copy your API Key (starts with `phase_`)
  </Step>
</Steps>

## Setup

Wrap your app with the `PhaseProvider` component in your root layout to initialize the SDK:

<CodeBlock title="app/_layout.tsx" lang="tsx" icon={<img src="https://cdn.simpleicons.org/react/61DAFB" alt="React" className="size-4" />}>
  ```tsx
  import { PhaseProvider } from 'phase-analytics/expo';

  export default function RootLayout() {
    return (
      <PhaseProvider
        apiKey="phase_xxx"
      >
        <Stack />
      </PhaseProvider>
    );
  }
  ```
</CodeBlock>

The `PhaseProvider` only initializes the SDK. You must call `Phase.identify()` before tracking events.

## Configuration

The `PhaseProvider` component accepts the following props:

<TypeTable
  type={{
  apiKey: {
    description: 'Your Phase API key (starts with `phase_`)',
    type: 'string',
    required: true,
  },
  trackNavigation: {
    description: 'Automatically track screen views with Expo Router',
    type: 'boolean',
    default: 'false',
  },
  debugData: {
    description: 'Mark identify/events as debug data',
    type: 'boolean',
    default: 'false',
  },
  baseUrl: {
    description: 'Custom API endpoint for self-hosted deployments',
    type: 'string',
    default: '"https://api.phase.sh"',
  },
  logLevel: {
    description: 'Console logging level for debugging',
    type: '"info" | "warn" | "error" | "none"',
    default: '"none"',
  },
  deviceInfo: {
    description: 'Collect device metadata (model, OS version, platform, app version as `app_version`)',
    type: 'boolean',
    default: 'true',
  },
  userLocale: {
    description: 'Collect user locale and timezone information',
    type: 'boolean',
    default: 'true',
  },
}}
/>

## Usage

### Identify User

**Required:** Call `Phase.identify()` before using any other methods. This registers the device and starts a session.

<CodeBlock title="app/index.tsx" lang="tsx" icon={<img src="https://cdn.simpleicons.org/react/61DAFB" alt="React" className="size-4" />}>
  ```tsx
  import { Phase } from 'phase-analytics/expo';
  import { useEffect } from 'react';

  export default function App() {
    useEffect(() => {
      // Initialize analytics - no PII collected by default
      Phase.identify();
    }, []);

    return <YourApp />;
  }
  ```
</CodeBlock>

**Privacy by default:**

* No personal data is collected without explicit properties
* Device ID is auto-generated and stored locally
* Only technical metadata is collected (OS version, platform, locale)

**Adding custom properties:**

You can optionally attach user properties. **Important:** If you add PII (personally identifiable information), ensure you have proper user consent:

<CodeBlock lang="tsx" icon={<img src="https://cdn.simpleicons.org/typescript/3178C6" alt="TypeScript" className="size-4" />}>
  ```tsx
  // After user login and consent
  await Phase.identify({
    user_id: '123',
    plan: 'premium',
    beta_tester: true
  });

  // ⚠️ If adding PII, get consent first
  const hasConsent = await customGetUserConsent();
  if (hasConsent) {
    await Phase.identify({
      email: 'user@example.com',
      name: 'John Doe'
    });
  }
  ```
</CodeBlock>

Properties must be primitives: `string`, `number`, `boolean`, or `null`.

### Track Events

Track custom events with optional parameters. **Note:** `Phase.identify()` must be called first.

<CodeBlock lang="tsx" icon={<img src="https://cdn.simpleicons.org/typescript/3178C6" alt="TypeScript" className="size-4" />}>
  ```tsx
  // Event without parameters
  Phase.track('app_opened');

  // Event with parameters
  Phase.track('purchase_completed', {
    amount: 99.99,
    currency: 'USD',
    product_id: 'premium_plan'
  });
  ```
</CodeBlock>

**Event naming rules:**

* Alphanumeric characters, underscores (`_`), hyphens (`-`), periods (`.`), forward slashes (`/`), and spaces
* 1-256 characters
* Examples: `purchase`, `user.signup`, `payment/success`, `Button Clicked`

**Event parameters:**

* Flat primitive object only
* Values must be `string`, `number`, `boolean`, or `null`
* Max 32 keys
* Key max 32 characters
* String value max 256 characters
* Serialized payload max 8 KB
* Empty objects are normalized away

### Automatic Screen Tracking

Enable automatic screen tracking by setting `trackNavigation` to `true` in your root layout. The SDK uses Expo Router's navigation hooks to track screen changes automatically:

<CodeBlock title="app/_layout.tsx" lang="tsx" icon={<img src="https://cdn.simpleicons.org/react/61DAFB" alt="React" className="size-4" />}>
  ```tsx
  import { PhaseProvider } from 'phase-analytics/expo';
  import { Stack } from 'expo-router';

  export default function RootLayout() {
    return (
      <PhaseProvider
        apiKey="phase_xxx"
        trackNavigation={true}
      >
        <Stack />
      </PhaseProvider>
    );
  }
  ```
</CodeBlock>

**How it works:**

* Wraps any Expo Router component (`Stack`, `Tabs`, `Drawer`, etc.)
* Automatically tracks screen views on route changes
* Screen names are derived from pathname
* Works with nested routes and dynamic segments

No additional setup required, just wrap your navigation structure with `PhaseProvider`.

## Type Reference

### DeviceProperties

Custom user/device attributes passed to `Phase.identify()`:

<TypeTable
  type={{
  '[key: string]': {
    description: 'Any custom property name',
    type: 'string | number | boolean | null',
  },
}}
/>

### EventParams

Event parameters passed to `Phase.track()`:

<TypeTable
  type={{
  '[key: string]': {
    description: 'Custom parameter name. Max 32 keys. Key max 32 chars. String values max 256 chars. Empty objects are omitted.',
    type: 'string | number | boolean | null',
  },
}}
/>

## How It Works

### Offline Support

Events are queued locally using `@react-native-async-storage/async-storage` when offline. The queue automatically syncs when connection is restored.

### Privacy

* No personal data is collected by default
* Device IDs are generated locally and stored persistently
* Geolocation is resolved server-side from IP address (disable with properties)
* All data collection is optional via configuration

### Performance

* Offline events are batched and sent asynchronously
* Network state is monitored via `@react-native-community/netinfo`
* Failed requests retry with exponential backoff
* Maximum batch size: 1000 events


# Usage (/docs/public-api/usage)



import { Callout } from 'fumadocs-ui/components/callout';
import { CodeBlock } from 'fumadocs-ui/components/codeblock';
import { Tab, Tabs, TabsContent, TabsList, TabsTrigger } from 'fumadocs-ui/components/tabs';

Use the Phase API to read analytics reports from your own scripts, dashboards, and backend services.

<Callout type="info">
  API keys are app-scoped and read-only.
</Callout>

## Get your API key

1. Sign in to [Phase Dashboard](https://phase.sh/dashboard).
2. Create a new project or select an existing one.
3. Open **Application → API Keys**.
4. Copy your API key. Keys for this API start with `phase_public_`.
5. Copy the **App ID** from the same screen. You need it in every request path.

## Base URL

<CodeBlock lang="txt" allowCopy={true}>
  ```txt
  https://api.phase.sh/public-api/v1
  ```
</CodeBlock>

## First request

<Tabs defaultValue="curl" groupId="api-first-request" persist>
  <TabsList>
    <TabsTrigger value="curl">
      cURL
    </TabsTrigger>

    <TabsTrigger value="fetch">
      fetch
    </TabsTrigger>
  </TabsList>

  <TabsContent value="curl">
    <CodeBlock lang="bash" allowCopy={true}>
      ```bash
      curl "https://api.phase.sh/public-api/v1/apps/<app_id>/reports/events/overview" \
        -H "Authorization: Bearer phase_public_your_key"
      ```
    </CodeBlock>
  </TabsContent>

  <TabsContent value="fetch">
    <CodeBlock lang="ts" allowCopy={true}>
      ```ts
      const response = await fetch(
        'https://api.phase.sh/public-api/v1/apps/<app_id>/reports/events/overview',
        {
          headers: {
            Authorization: 'Bearer phase_public_your_key',
          },
        }
      );

      if (!response.ok) {
        throw new Error(`Request failed with ${response.status}`);
      }

      const data = await response.json();
      console.log(data);
      ```
    </CodeBlock>
  </TabsContent>
</Tabs>

## Example response

<CodeBlock lang="json" allowCopy={true}>
  ```json
  {
    "totalEvents": 216,
    "events24h": 0,
    "totalEventsChange24h": 0,
    "events24hChange": 0,
    "meta": {
      "generatedAt": "2026-04-06T15:02:52.814Z",
      "consistency": "eventual",
      "identityModel": "user"
    }
  }
  ```
</CodeBlock>

## Request format

### Path parameter

* `appId`
  * Type: `string`
  * Required: yes
  * Value: the App ID shown in **Application → API Keys**

### Header

* `Authorization`
  * Type: `string`
  * Required: yes
  * Format: `Bearer phase_public_your_key`
  * Value: your API key

### Query parameters

* `startDate`
  * Type: `string`
  * Required: no
  * Format: ISO 8601 timestamp
  * Example: `2026-01-15T00:00:00.000Z`
  * Used by: timeseries endpoints, date-filtered breakdown endpoints, and funnel endpoints

* `endDate`
  * Type: `string`
  * Required: no
  * Format: ISO 8601 timestamp
  * Example: `2026-02-15T23:59:59.999Z`
  * Used by: timeseries endpoints, date-filtered breakdown endpoints, and funnel endpoints

* `metric`
  * Type: `string`
  * Required: no
  * Used by: timeseries endpoints
  * Allowed values depend on the endpoint:
    * Sessions: `sessionCount`, `avgSessionDuration`, `bounceRate`
    * Users: `activeUsers`, `totalUsers`, `newUsers`

* `dimension`
  * Type: `string`
  * Required: no
  * Used by: breakdown endpoints
  * Allowed values depend on the endpoint:
    * Events: `eventName`, `screenName`
    * Sessions: `platform`, `country`
    * Users: `platform`, `country`

* `limit`
  * Type: `number`
  * Required: no
  * Used by: breakdown endpoints
  * Range: `1` to `50`
  * Default: `10`

<Callout type="info">
  The maximum supported date range is 365 days.
</Callout>

## Events

Use event reports for headline counts, daily trends, and top events or screens.

### Endpoints

* `GET /apps/:appId/reports/events/overview`
  * Returns total events, 24h events, and change values.

* `GET /apps/:appId/reports/events/timeseries`
  * Returns daily event counts.
  * Supports `startDate` and `endDate`.

* `GET /apps/:appId/reports/events/breakdown`
  * Returns event counts grouped by `eventName` or `screenName`.
  * Supports `dimension`, `startDate`, `endDate`, and `limit`.

### Example: event breakdown

<Tabs defaultValue="curl" groupId="events-breakdown" persist>
  <TabsList>
    <TabsTrigger value="curl">
      cURL
    </TabsTrigger>

    <TabsTrigger value="fetch">
      fetch
    </TabsTrigger>
  </TabsList>

  <TabsContent value="curl">
    <CodeBlock lang="bash" allowCopy={true}>
      ```bash
      curl "https://api.phase.sh/public-api/v1/apps/<app_id>/reports/events/breakdown?dimension=eventName&startDate=2026-01-15T00:00:00.000Z&endDate=2026-02-15T23:59:59.999Z&limit=10" \
        -H "Authorization: Bearer phase_public_your_key"
      ```
    </CodeBlock>
  </TabsContent>

  <TabsContent value="fetch">
    <CodeBlock lang="ts" allowCopy={true}>
      ```ts
      const params = new URLSearchParams({
        dimension: 'eventName',
        startDate: '2026-01-15T00:00:00.000Z',
        endDate: '2026-02-15T23:59:59.999Z',
        limit: '10',
      });

      const response = await fetch(
        `https://api.phase.sh/public-api/v1/apps/<app_id>/reports/events/breakdown?${params}`,
        {
          headers: {
            Authorization: 'Bearer phase_public_your_key',
          },
        }
      );

      const data = await response.json();
      ```
    </CodeBlock>
  </TabsContent>
</Tabs>

## Sessions

Use session reports for totals, duration, bounce rate, and session distribution by platform or location.

### Endpoints

* `GET /apps/:appId/reports/sessions/overview`
  * Returns total sessions, active sessions, average session duration, and bounce rate.

* `GET /apps/:appId/reports/sessions/timeseries`
  * Returns daily session metrics.
  * Supported `metric` values: `sessionCount`, `avgSessionDuration`, `bounceRate`.
  * Supports `startDate`, `endDate`, and `metric`.

* `GET /apps/:appId/reports/sessions/breakdown`
  * Returns session counts grouped by `platform` or `country`.
  * Supports `dimension`, `startDate`, `endDate`, and `limit`.

### Example: session timeseries

<Tabs defaultValue="curl" groupId="sessions-timeseries" persist>
  <TabsList>
    <TabsTrigger value="curl">
      cURL
    </TabsTrigger>

    <TabsTrigger value="fetch">
      fetch
    </TabsTrigger>
  </TabsList>

  <TabsContent value="curl">
    <CodeBlock lang="bash" allowCopy={true}>
      ```bash
      curl "https://api.phase.sh/public-api/v1/apps/<app_id>/reports/sessions/timeseries?metric=sessionCount&startDate=2026-01-15T00:00:00.000Z&endDate=2026-02-15T23:59:59.999Z" \
        -H "Authorization: Bearer phase_public_your_key"
      ```
    </CodeBlock>
  </TabsContent>

  <TabsContent value="fetch">
    <CodeBlock lang="ts" allowCopy={true}>
      ```ts
      const params = new URLSearchParams({
        metric: 'sessionCount',
        startDate: '2026-01-15T00:00:00.000Z',
        endDate: '2026-02-15T23:59:59.999Z',
      });

      const response = await fetch(
        `https://api.phase.sh/public-api/v1/apps/<app_id>/reports/sessions/timeseries?${params}`,
        {
          headers: {
            Authorization: 'Bearer phase_public_your_key',
          },
        }
      );

      const data = await response.json();
      ```
    </CodeBlock>
  </TabsContent>
</Tabs>

## Users

Use user reports for totals, active users, new users, and user distribution by platform or location.

### Endpoints

* `GET /apps/:appId/reports/users/overview`
  * Returns total users, active users, new users, and summary breakdowns.

* `GET /apps/:appId/reports/users/timeseries`
  * Returns daily user metrics.
  * Supported `metric` values: `activeUsers`, `totalUsers`, `newUsers`.
  * Supports `startDate`, `endDate`, and `metric`.

* `GET /apps/:appId/reports/users/breakdown`
  * Returns user counts grouped by `platform` or `country`.
  * Supports `dimension` and `limit`.

### Example: user overview

<Tabs defaultValue="curl" groupId="users-overview" persist>
  <TabsList>
    <TabsTrigger value="curl">
      cURL
    </TabsTrigger>

    <TabsTrigger value="fetch">
      fetch
    </TabsTrigger>
  </TabsList>

  <TabsContent value="curl">
    <CodeBlock lang="bash" allowCopy={true}>
      ```bash
      curl "https://api.phase.sh/public-api/v1/apps/<app_id>/reports/users/overview" \
        -H "Authorization: Bearer phase_public_your_key"
      ```
    </CodeBlock>
  </TabsContent>

  <TabsContent value="fetch">
    <CodeBlock lang="ts" allowCopy={true}>
      ```ts
      const response = await fetch(
        'https://api.phase.sh/public-api/v1/apps/<app_id>/reports/users/overview',
        {
          headers: {
            Authorization: 'Bearer phase_public_your_key',
          },
        }
      );

      const data = await response.json();
      ```
    </CodeBlock>
  </TabsContent>
</Tabs>

## Funnels

Use funnel reports for activation conversion and saved custom funnels from the dashboard.

### Endpoints

* `GET /apps/:appId/reports/funnels/activation`
  * Returns the built-in activation funnel.
  * Steps: First open → Total session ≥10m → Returned day 1 → Returned day 3.
  * Supports `startDate` and `endDate` for the acquisition cohort.

* `GET /apps/:appId/reports/funnels`
  * Lists saved custom funnels for the app.
  * Returns funnel id, name, steps, and window hours.

* `GET /apps/:appId/reports/funnels/:funnelId`
  * Runs a saved custom funnel and returns step conversion.
  * Supports `startDate` and `endDate`.

* `POST /apps/:appId/reports/funnels/run`
  * Runs an ad-hoc funnel without saving it.
  * Body: `steps`, optional `windowHours` (default `168`), optional `startDate` / `endDate`.
  * Step kinds: `first_seen`, `session`, `session_30s`, `session_10m`, `engaged_10m`, `return_d1`, `return_d3`, `event`.
  * Event steps require `name`.

### Example: activation funnel

<Tabs defaultValue="curl" groupId="funnels-activation" persist>
  <TabsList>
    <TabsTrigger value="curl">
      cURL
    </TabsTrigger>

    <TabsTrigger value="fetch">
      fetch
    </TabsTrigger>
  </TabsList>

  <TabsContent value="curl">
    <CodeBlock lang="bash" allowCopy={true}>
      ```bash
      curl "https://api.phase.sh/public-api/v1/apps/<app_id>/reports/funnels/activation?startDate=2026-01-15T00:00:00.000Z&endDate=2026-02-15T23:59:59.999Z" \
        -H "Authorization: Bearer phase_public_your_key"
      ```
    </CodeBlock>
  </TabsContent>

  <TabsContent value="fetch">
    <CodeBlock lang="ts" allowCopy={true}>
      ```ts
      const params = new URLSearchParams({
        startDate: '2026-01-15T00:00:00.000Z',
        endDate: '2026-02-15T23:59:59.999Z',
      });

      const response = await fetch(
        `https://api.phase.sh/public-api/v1/apps/<app_id>/reports/funnels/activation?${params}`,
        {
          headers: {
            Authorization: 'Bearer phase_public_your_key',
          },
        }
      );

      const data = await response.json();
      console.log(data.overallConversion, data.steps);
      ```
    </CodeBlock>
  </TabsContent>
</Tabs>

### Example: run a custom funnel

<Tabs defaultValue="curl" groupId="funnels-run" persist>
  <TabsList>
    <TabsTrigger value="curl">
      cURL
    </TabsTrigger>

    <TabsTrigger value="fetch">
      fetch
    </TabsTrigger>
  </TabsList>

  <TabsContent value="curl">
    <CodeBlock lang="bash" allowCopy={true}>
      ```bash
      curl "https://api.phase.sh/public-api/v1/apps/<app_id>/reports/funnels/run" \
        -H "Authorization: Bearer phase_public_your_key" \
        -H "Content-Type: application/json" \
        -d '{
          "windowHours": 168,
          "steps": [
            { "kind": "first_seen" },
            { "kind": "session" },
            { "kind": "event", "name": "purchase_completed" }
          ]
        }'
      ```
    </CodeBlock>
  </TabsContent>

  <TabsContent value="fetch">
    <CodeBlock lang="ts" allowCopy={true}>
      ```ts
      const response = await fetch(
        'https://api.phase.sh/public-api/v1/apps/<app_id>/reports/funnels/run',
        {
          method: 'POST',
          headers: {
            Authorization: 'Bearer phase_public_your_key',
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            windowHours: 168,
            steps: [
              { kind: 'first_seen' },
              { kind: 'session' },
              { kind: 'event', name: 'purchase_completed' },
            ],
          }),
        }
      );

      const data = await response.json();
      ```
    </CodeBlock>
  </TabsContent>
</Tabs>

## Query

Run the same read-only SQL engine as **Dashboard → Analytics → Query** from your backend.

* `POST /apps/:appId/query`
* Body: JSON with `sql` and optional `page` (default `1`)
* Auth: `Authorization: Bearer phase_public_your_key`

`LIMIT` in SQL sets page size (default **100** if omitted, max **50** on the API). Do not use `OFFSET` in SQL. Pass `page` to fetch the next slice. The response `meta` object includes `hasNextPage`, `hasPreviousPage`, `offset`, and `pageSize`.

<Callout type="info">
  Full table reference, time-range defaults, pagination, and examples are documented in [Query](/docs/concepts/query).
</Callout>

### Example: run a query

<Tabs defaultValue="curl" groupId="query-run" persist>
  <TabsList>
    <TabsTrigger value="curl">
      cURL
    </TabsTrigger>

    <TabsTrigger value="fetch">
      fetch
    </TabsTrigger>
  </TabsList>

  <TabsContent value="curl">
    <CodeBlock lang="bash" allowCopy={true}>
      ```bash
      curl "https://api.phase.sh/public-api/v1/apps/<app_id>/query" \
        -H "Authorization: Bearer phase_public_your_key" \
        -H "Content-Type: application/json" \
        -d '{
          "sql": "SELECT name, count(*) AS events FROM events GROUP BY name ORDER BY events DESC LIMIT 20",
          "page": 1
        }'
      ```
    </CodeBlock>
  </TabsContent>

  <TabsContent value="fetch">
    <CodeBlock lang="ts" allowCopy={true}>
      ```ts
      const response = await fetch(
        'https://api.phase.sh/public-api/v1/apps/<app_id>/query',
        {
          method: 'POST',
          headers: {
            Authorization: 'Bearer phase_public_your_key',
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            sql: `SELECT name, count(*) AS events
      FROM events
      GROUP BY name
      ORDER BY events DESC
      LIMIT 20`,
            page: 1,
          }),
        }
      );

      const data = await response.json();
      console.log(data.result.columns, data.result.rows);
      console.log(data.meta.hasNextPage);
      ```
    </CodeBlock>
  </TabsContent>
</Tabs>

### Example: paginate

<CodeBlock lang="ts" allowCopy={true}>
  ```ts
  let page = 1;
  let hasNextPage = true;

  while (hasNextPage) {
    const response = await fetch(
      'https://api.phase.sh/public-api/v1/apps/<app_id>/query',
      {
        method: 'POST',
        headers: {
          Authorization: 'Bearer phase_public_your_key',
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ sql, page }),
      }
    );

    const data = await response.json();
    // process data.result.rows

    hasNextPage = data.meta.hasNextPage;
    page += 1;
  }
  ```
</CodeBlock>

## Response metadata

Every report response includes a `meta` object.

* `generatedAt` is the server-side timestamp for the response.
* `consistency` is currently `eventual`.
* `identityModel` is currently `user`.

## Security guidance

<Callout type="warn">
  Do not use API keys in mobile apps, browser bundles, or any other untrusted client. Use them from your own backend, jobs, or internal tooling.
</Callout>


# Errors and Limits (/docs/public-api/errors-and-limits)



import { Callout } from 'fumadocs-ui/components/callout';
import { CodeBlock } from 'fumadocs-ui/components/codeblock';

## Error response format

Phase returns structured error responses.

<CodeBlock lang="json" allowCopy={true}>
  ```json
  {
    "code": "VALIDATION_ERROR",
    "detail": "Date range cannot exceed 365 days"
  }
  ```
</CodeBlock>

## Status codes

* `400 Bad Request`
  * Invalid query parameters
  * Unsupported query shapes
  * Date range larger than 365 days

* `401 Unauthorized`
  * Missing `Authorization` header
  * Malformed bearer key
  * Invalid, expired, revoked, or unauthorized key

* `403 Forbidden`
  * The key is valid, but it cannot access the requested app or resource

* `422 Unprocessable Entity`
  * Route-level enum or query validation failed before the request reached the handler

* `429 Too Many Requests`
  * The rate limit was exceeded

* `500 Internal Server Error`
  * An unexpected server error occurred

## Rate limit headers

When rate limiting applies, responses may include these headers:

* `X-RateLimit-Limit`
* `X-RateLimit-Remaining`
* `X-RateLimit-Reset`
* `Retry-After`

## Request limits

Current limits:

* Maximum report range: **365 days**
* Maximum breakdown size: **50 rows**
* Default breakdown size: **10 rows**
* Maximum query page size: **50 rows** (`LIMIT` in SQL, API only)
* Maximum dashboard query page size: **1000 rows**
* Maximum skipped rows per query: **100,000** (pagination cap)

<Callout type="info">
  Build your integration to handle validation and rate-limit responses. If a request exceeds a guardrail, retry with a smaller date range or a smaller breakdown limit.
</Callout>

## Consistency

Phase analytics responses are eventually consistent.

* Recently ingested data may take a short time to appear in reports.
* Every report response includes a `meta` object.
* `meta.generatedAt` tells you when the response was created.
* `meta.identityModel` is currently `user`.


# Team & Billing (/docs/concepts/team-billing)



import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';

## Team Management

Collaborate with your team by inviting members to your Phase project. Team members can view analytics and reports while the project owner maintains full control.

### Roles & Permissions

**Owner**

* Full control over the project
* Rotate API keys
* Delete or rename the project
* Add and remove team members
* Manage all project settings
* Only the owner is billed for the project

**Team Member** (Read-Only)

* View analytics and reports
* Access all data insights
* Cannot modify project settings
* Cannot manage API keys or team members
* Does not affect billing

### Adding Team Members

1. Navigate to **[Dashboard](https://phase.sh/dashboard) → Application → Team**
2. Click **Add Member**
3. Enter the email address of the team member
4. They will receive an invitation to join the project

**No Limits:** You can add unlimited team members to your project at no additional cost.

### Removing Team Members

1. Navigate to **[Dashboard](https://phase.sh/dashboard) → Application → Team**
2. Find the team member you want to remove
3. Click **Remove**
4. Confirm the action

The removed member will immediately lose access to the project.

### Transfer Ownership

Currently, ownership transfer is not supported. If you need to transfer a project to another user, please contact support.

## Billing

Billing is managed through [Polar](https://polar.sh) and is tied to the project owner.

### How Billing Works

* **Only the project owner is billed** for the project
* Team members do not affect billing costs
* Adding team members is free (unlimited)
* Billing is based on your project's usage and plan

### Managing Your Subscription

**For Project Owners:**
The project owner can manage their subscription from the profile sidebar menu by selecting **Billing**.

**For Team Members:**
Team members can also access the Billing section from their profile, but this shows their personal Phase account billing, not the project's billing. Project billing is only visible to and managed by the project owner.

### Billing FAQ

<Accordions>
  <Accordion title="What happens if I add team members?">
    Team members are free and unlimited. Only the project owner is billed.
  </Accordion>

  <Accordion title="Can team members access billing information?">
    Team members can access their own personal Phase account billing, but cannot view or manage the project's billing. Only the project owner can manage project billing.
  </Accordion>

  <Accordion title="What happens if my subscription is cancelled?">
    Your project will be downgraded to the free tier with limited features. Your data remains accessible.
  </Accordion>

  <Accordion title="Can I transfer billing to another team member?">
    Billing is tied to the project owner. To transfer billing, you would need to transfer project ownership (contact support).
  </Accordion>
</Accordions>

## Best Practices

* **Invite trusted team members:** Only invite people who need access to your analytics data
* **Regular audits:** Periodically review your team members and remove those who no longer need access
* **API key security:** Only the owner can rotate API keys - ensure your owner account is secure
* **Billing alerts:** Set up payment method backups to avoid service interruptions


# Publishing (/docs/concepts/publishing)



import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
import { Callout } from 'fumadocs-ui/components/callout';

When submitting your app to the App Store or Google Play, you'll need to disclose how Phase Analytics collects and uses data. This guide helps you accurately complete the required privacy forms.

<Callout type="info">
  Phase is privacy-first and collects no personally identifiable information (PII) by default. All data collection is anonymous unless you explicitly identify users.
</Callout>

## iOS (Apple App Store)

When submitting your app to the App Store, you'll need to complete Apple's App Privacy questionnaire.

<Accordions>
  <Accordion title="Data Collection">
    **Does your app collect data?**
    Select **Yes** - Phase collects anonymous analytics data.

    **Do you or your third-party partners collect data from this app?**
    Select **Yes, we collect data from this app** - Phase SDK collects analytics data.
  </Accordion>

  <Accordion title="Data Types">
    Select the following data types:

    **Product Interaction**

    * How users interact with your app (events, screen views, session duration)

    **Device ID**

    * Anonymous device identifiers for analytics purposes
  </Accordion>

  <Accordion title="Purpose">
    For each data type, select:

    * **Analytics** - To understand app usage and improve performance
  </Accordion>

  <Accordion title="Linking to User Identity">
    **Is this data linked to the user's identity?**
    Select **No** - Phase uses anonymous device IDs by default. Only select "Yes" if you explicitly call `Phase.identify()` with user-specific data like email or user ID.

    <Callout type="warn">
      If you call `Phase.identify()` with personally identifiable information (email, name, user ID), you must select "Yes" for linking data to user identity and disclose which data types you're collecting.
    </Callout>
  </Accordion>

  <Accordion title="Tracking">
    **Do you or your third-party partners use data from this app for tracking purposes?**
    Select **No** - Phase does not track users across apps and websites owned by other companies for targeted advertising or ad measurement purposes.
  </Accordion>
</Accordions>

## Android (Google Play Store)

When submitting your app to Google Play, you'll need to complete the Data Safety form.

<Accordions>
  <Accordion title="Data Collection and Security">
    **Does your app collect or share any of the required user data types?**
    Select **Yes** - Phase collects device and app interaction data.

    **Is all of the user data collected by your app encrypted in transit?**
    Select **Yes** - All data sent to Phase is encrypted using HTTPS.
  </Accordion>

  <Accordion title="Data Types">
    Select the following categories:

    **Device or other IDs**

    * Anonymous device identifiers for analytics

    **App interactions**

    * How users interact with your app (events, screen views, session duration)
  </Accordion>

  <Accordion title="Data Usage">
    For each data type, specify:

    * **Analytics** - To measure app usage and performance
    * **Data is collected but not shared** with third parties
  </Accordion>

  <Accordion title="User Control">
    **Can users request that data be deleted?**
    Select **Yes** - Users can contact support to request data deletion.

    <Callout type="info">
      Phase automatically anonymizes data and does not collect PII by default. If you implement custom user identification with PII, update your disclosures accordingly.
    </Callout>
  </Accordion>
</Accordions>

## Best Practices

* **Review before each release** - Privacy requirements may change with app store policy updates
* **Match your implementation** - Only disclose data types you actually collect through Phase
* **Document custom properties** - If you track custom user properties with PII, update your privacy policy
* **Test before submission** - Review your app's data collection behavior in production builds
* **Keep privacy policy updated** - Ensure your app's privacy policy accurately reflects Phase usage


# Query (/docs/concepts/query)



import { Callout } from 'fumadocs-ui/components/callout';
import { CodeBlock } from 'fumadocs-ui/components/codeblock';
import { Tab, Tabs, TabsContent, TabsList, TabsTrigger } from 'fumadocs-ui/components/tabs';

Query lets you answer product questions with read-only SQL. The dashboard editor and the [Public API](/docs/public-api/usage#query) run the same engine against your app data.

## Where to find it

Open **[Dashboard](https://phase.sh/dashboard) → Analytics → Query**.

Use **Instructions** in the editor for a copyable SQL reference. Save queries as **presets** for your team.

## Virtual tables

Query exposes three virtual tables. App scoping is injected automatically. You never filter by `app_id` yourself.

### `events`

| Column      | Type        | Notes                                     |
| ----------- | ----------- | ----------------------------------------- |
| `timestamp` | timestamptz | Event time                                |
| `user_id`   | text        | Anonymous user identifier                 |
| `name`      | text        | Event name (e.g. `purchase`, `level_win`) |
| `params`    | text        | JSON string of event properties           |

`events` queries run on QuestDB when used alone. Use QuestDB JSON syntax:

<CodeBlock lang="sql" allowCopy={true}>
  ```sql
  json_extract(params, '$.duration_seconds')
  cast(json_extract(params, '$.level_number') as long)
  ```
</CodeBlock>

Modulo is supported: `expr % 5 = 0`

### `users`

| Column       | Type        | Notes                                                                                                                                                         |
| ------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_id`    | text        |                                                                                                                                                               |
| `platform`   | text        | `ios`, `android`, or `unknown`                                                                                                                                |
| `country`    | text        | ISO country code                                                                                                                                              |
| `locale`     | text        |                                                                                                                                                               |
| `model`      | text        | Device model. Apple hardware IDs (e.g. `iPhone17,1`) are resolved to marketing names (e.g. `iPhone 16 Pro`). Android and already-friendly names pass through. |
| `os_version` | text        |                                                                                                                                                               |
| `first_seen` | timestamptz | First seen time                                                                                                                                               |
| `properties` | jsonb       | Custom user properties — use `properties->>'key'`                                                                                                             |

<Callout type="info">
  The virtual table is named `users`. Do not use `devices` or `device_id` in SQL. Those names are rejected.
</Callout>

### `sessions`

| Column             | Type        | Notes                   |
| ------------------ | ----------- | ----------------------- |
| `session_id`       | text        |                         |
| `user_id`          | text        |                         |
| `started_at`       | timestamptz |                         |
| `last_activity_at` | timestamptz |                         |
| `duration_seconds` | number      | Computed session length |

Each query uses **one** virtual table. `events` runs on QuestDB. `users` and `sessions` run on Postgres.

## Time range

If your SQL does not filter on `timestamp`, `started_at`, `last_activity_at`, or `first_seen`, **events** and **sessions** default to the **last 30 days**.

Add your own predicates to control the window:

<CodeBlock lang="sql" allowCopy={true}>
  ```sql
  WHERE timestamp >= '2026-01-01'
  ```
</CodeBlock>

## Pagination

Pagination is **page-based**, not `OFFSET` in SQL.

| Surface    | Page size                    | Max page size | Pagination             |
| ---------- | ---------------------------- | ------------- | ---------------------- |
| Dashboard  | `LIMIT` in SQL (default 100) | 1000          | UI page controls       |
| Public API | `LIMIT` in SQL (default 100) | 50            | `page` in request body |

Rules:

* `LIMIT` sets how many rows each page returns.
* Do **not** write `OFFSET` in SQL. It is rejected.
* Use page controls in the dashboard, or send `page` in the API request.
* Deep pagination is capped at **100,000** skipped rows.
* Export downloads the current page only.

API example with pagination:

<CodeBlock lang="json" allowCopy={true}>
  ```json
  {
    "sql": "SELECT name, count(*) AS events FROM events GROUP BY name ORDER BY events DESC LIMIT 50",
    "page": 2
  }
  ```
</CodeBlock>

The response includes `meta.page`, `meta.pageSize`, `meta.offset`, `meta.hasNextPage`, and `meta.hasPreviousPage` so you can loop programmatically.

## Rules

* **SELECT only.** No `INSERT`, `UPDATE`, `DELETE`, or DDL.
* **Single statement.** No semicolons.
* **Read-only sandbox.** Queries cannot mutate data.
* **Debug events excluded** automatically.
* **One table per query.** No `JOIN` and no multi-table `FROM`.
* **Legacy names rejected:** `devices`, `device_id`.

## Examples

Recent events:

<CodeBlock lang="sql" allowCopy={true}>
  ```sql
  SELECT timestamp, user_id, name AS event_name
  FROM events
  ORDER BY timestamp DESC
  LIMIT 100
  ```
</CodeBlock>

Top events:

<CodeBlock lang="sql" allowCopy={true}>
  ```sql
  SELECT name AS event_name, count(*) AS events
  FROM events
  GROUP BY name
  ORDER BY events DESC
  LIMIT 100
  ```
</CodeBlock>

Users by platform:

<CodeBlock lang="sql" allowCopy={true}>
  ```sql
  SELECT platform, count(*) AS users
  FROM users
  GROUP BY platform
  ORDER BY users DESC
  LIMIT 50
  ```
</CodeBlock>

Average level duration (every 5th level):

<CodeBlock lang="sql" allowCopy={true}>
  ```sql
  SELECT
    count(*) AS level_wins,
    avg(cast(json_extract(params, '$.duration_seconds') AS double)) AS avg_duration_seconds
  FROM events
  WHERE name = 'level_win'
    AND cast(json_extract(params, '$.level_number') AS long) % 5 = 0
  ```
</CodeBlock>

## Presets

Save the current SQL as a preset from the Query page. Presets are per app and shared with your team. Loading a preset replaces the editor contents.

## Automation

Use the same queries from your backend with a [public API key](/docs/public-api/usage). See [Query via API](/docs/public-api/usage#query) for the endpoint and request shape. Full SQL, pagination, and limit details live on this page.