# Track Metrics





The SideKit SDK provides multiple ways to send analytics signals. This data powers your dashboard charts and allows you to build targeted version gates based on user behavior.

<InfoBox variant="info">
  Make sure you've configured the SDK with your API key before sending any signals to ensure they are tracked correctly.
</InfoBox>

## Add Your Custom Signal in the Dashboard

<img alt="Signals UI" src={__img0} placeholder="blur" />

Navigate to the `Settings` page for your app and add your signal in the `Custom Signals` section. Here `purchases` is a custom signal we've chosen to track for this app. This whitelists the signal name and SideKit will accept data for this signal.

## Sending Signals

:::ios
You can track events in your app using three primary methods, depending on how much detail you need.
:::

### 1. Simple Key

The simplest way to send a signal is with just a key string. This is perfect for binary events (like "session\_start").

:::ios
```swift
SideKit.shared.sendSignal("user_login")
```
:::

### 2. Key-Value Pairs

Send a signal with both a key and a value. SideKit automatically generates pie charts in your dashboard for the distribution of these values.

:::ios
```swift
SideKit.shared.sendSignal(key: "purchase_amount", value: "99.99")
```
:::

:::ios
### 3. Signal Objects

For more complex scenarios, you can use the `SideKit.Signal` struct. This is especially useful when building arrays of signals.

```swift
SideKit.shared.sendSignal(
    SideKit.Signal(name: "button_click", value: "checkout")
)
```
:::

***

## Bulk Tracking

If you have multiple events that happen simultaneously, you can batch them into a single call:

:::ios
```swift
let signals = [
    SideKit.Signal(name: "page_view", value: "home"),
    SideKit.Signal(name: "interaction", value: "header_clicked")
]

SideKit.shared.sendSignal(signals)
```
:::

## Best Practices

<div style={{ display: 'flex', flexDirection: 'column', gap: '1rem', marginTop: '1rem' }}>
  <StepItem step={1}>
    <strong>Batch when possible</strong>

    : If sending multiple signals in a loop, batch them into an array to reduce network requests.
  </StepItem>

  <StepItem step={2}>
    <strong>Use descriptive keys</strong>

    : Choose clear, consistent names (e.g., 

    <code>onboarding_step_1</code>

    ) to keep your dashboard organized.
  </StepItem>

  <StepItem step={3}>
    <strong>Analytics state</strong>

    : SideKit respects the user's analytics preference. If analytics is disabled, signals will be silently ignored.
  </StepItem>
</div>


# Feature Flags



Feature flags let you turn features on or off from the SideKit dashboard, instantly, without submitting a new build for App Store review. Ship code behind a flag, then flip it live when you're ready — or kill a broken feature in seconds.

<InfoBox variant="info">
  A flag is a simple boolean: it's either <code>ON</code> or <code>OFF</code> for everyone using your app. For string or numeric values you want to tune remotely, use [Remote Config](/ios/feature-flags/remote-config) instead.
</InfoBox>

## Create a Flag in the Dashboard

Open the **Feature Flags** panel for your app. Every flag is a key and an `ON`/`OFF` switch.

<DocImage src="/sk_flags.png" alt="The Feature Flags panel in the SideKit dashboard" maxWidth="800px" />

<div style={{ display: 'flex', flexDirection: 'column', gap: '1rem', marginTop: '1rem' }}>
  <StepItem step={1}>
    Type a key (for example 

    <code>multiplayer_enabled</code>

    ) and press enter to create it.
  </StepItem>

  <StepItem step={2}>
    Flip the switch to set the flag 

    <code>ON</code>

     or 

    <code>OFF</code>

    . The toggle has a safety cover — click the cover to open it, then hit the switch to avoid accidental changes in production.
  </StepItem>

  <StepItem step={3}>
    Done tuning a flag? Archive it with the archive icon. Archived flags are still served to clients — their value is just locked, so old callers keep getting the last value you set.
  </StepItem>
</div>

<InfoBox variant="tip">
  Use clear, descriptive keys like <code>evil\_difficulty</code> or <code>community\_goal\_enabled</code>. The key you set here is exactly the string you'll read from the SDK.
</InfoBox>

## Read a Flag in Your App

Flags are fetched automatically when you call [`configure`](/ios/getting-started/configure-sidekit) and cached on device. Read a flag anywhere with `SideKit.shared.flag(_:default:)`:

```swift
if SideKit.shared.flag("multiplayer_enabled") {
    showMultiplayerButton()
}
```

Always pass a `default` value that represents the "safe" fallback. It's returned when the flag doesn't exist yet, hasn't been fetched, or the device is offline with no cached value:

```swift
let hardMode = SideKit.shared.flag("evil_difficulty", default: false)
```

The `default` parameter is optional — if you omit it, it's `false`. So `SideKit.shared.flag("evil_difficulty")` returns `false` for a missing, unfetched, or offline flag. Pass an explicit `default` whenever `false` isn't the safe fallback for that feature.

<InfoBox variant="info">
  <code>flag(\_:default:)</code> only returns boolean flags. If the key belongs to a Remote Config entry (a string value), the default is returned instead — use [`config(_:default:)`](/ios/feature-flags/remote-config) for those.
</InfoBox>

## Reacting to Flags in SwiftUI

`SideKit.shared` is an `ObservableObject` and its `flags` array is `@Published`. Observe it to have your UI update automatically when flags refresh:

```swift
struct ContentView: View {
    @ObservedObject private var sideKit = SideKit.shared

    var body: some View {
        VStack {
            if sideKit.flag("multiplayer_enabled") {
                MultiplayerLobby()
            }
        }
    }
}
```

## Refreshing Flags

SideKit fetches the latest flags on launch (inside `configure`) and again whenever the app returns to the foreground. To pull the newest values on demand — for example after a specific user action — call `refreshFlags`:

```swift
await SideKit.shared.refreshFlags()
```

If the network request fails, SideKit falls back to the last set of flags it cached on device, so your app keeps behaving predictably offline.

<InfoBox variant="info">
  <strong>What if there's no cache?</strong> If a fetch fails and nothing has been cached yet — a first launch with no connection, for example — SideKit simply keeps an empty flag set. It never throws, crashes, or blocks your UI. Every <code>flag(\_:default:)</code> call just returns the <code>default</code> you passed, so your app behaves exactly as if the flag were off (or whatever fallback you chose).
</InfoBox>

## How Flags Behave

<PropertyList
  properties={[
{ name: 'Instant', description: 'Changes take effect the next time the SDK fetches flags — on the next launch or foreground, no App Store release required.' },
{ name: 'Cached', description: 'The last fetched flags are stored on device and reused when the server is unreachable.' },
{ name: 'Global', description: 'A flag is ON or OFF for everyone. It is not per-user targeting.' },
{ name: 'Safe defaults', description: 'Any unknown or not-yet-fetched key returns the default you pass, so your app never crashes on a missing flag.' }
]}
/>

<InfoBox variant="tip">
  Wrap risky launches behind a flag that defaults to <code>false</code>. Ship the code dark, verify everything works, then flip the flag <code>ON</code> from the dashboard — and flip it back <code>OFF</code> instantly if something breaks.
</InfoBox>


# Remote Config



Remote Config delivers string values to your app at runtime. Unlike [feature flags](/ios/feature-flags/feature-flags) — which are on/off booleans — config entries hold text you can change on the fly: a goal number, a leaderboard payload, a promo message, or a JSON blob your app parses itself.

<InfoBox variant="info">
  Use a <strong>flag</strong> when the answer is yes/no (<em>is this feature enabled?</em>). Use <strong>config</strong> when you need an actual value (<em>what's the target score?</em>, <em>who's on the leaderboard?</em>).
</InfoBox>

## Add a Config Value in the Dashboard

Open the **Remote Config** panel for your app. Each entry is a key paired with a string value that's delivered to clients at runtime.

<DocImage src="/sk_config.png" alt="The Remote Config panel in the SideKit dashboard" maxWidth="800px" />

<div style={{ display: 'flex', flexDirection: 'column', gap: '1rem', marginTop: '1rem' }}>
  <StepItem step={1}>
    Type a key (for example 

    <code>game_played_goal</code>

    ), enter its value, and save.
  </StepItem>

  <StepItem step={2}>
    Click any value to edit it inline. Changes are delivered on the next fetch — no rebuild needed.
  </StepItem>

  <StepItem step={3}>
    Archive an entry with the archive icon to lock its value. Archived entries are still served to clients — old callers keep getting the last value you set — you just can't change it anymore.
  </StepItem>
</div>

<InfoBox variant="tip">
  Values are always stored as strings. For structured data — like <code>top\_player\_history</code> or <code>top\_player\_runners\_up</code> in the example above — store a JSON string and parse it on the client.
</InfoBox>

## Read a Config Value in Your App

Config entries are fetched automatically during [`configure`](/ios/getting-started/configure-sidekit) and cached on device. Read one with `SideKit.shared.config(_:default:)`:

```swift
let goal = SideKit.shared.config("game_played_goal", default: "1000")
```

The `default` is returned whenever the key doesn't exist, hasn't been fetched yet, or the device is offline with no cached value — so always provide a sensible fallback.

The `default` parameter is optional — if you omit it, it's an empty string (`""`). So `SideKit.shared.config("game_played_goal")` returns `""` for a missing, unfetched, or offline key. Because an empty string is rarely useful, pass an explicit `default` you can actually fall back on.

### Converting Values

Because every value is a string, convert to the type you need at the call site:

```swift
// Numbers
let goalCount = Int(SideKit.shared.config("game_played_goal", default: "1000")) ?? 1000
let streak = Int(SideKit.shared.config("goal_streak_val", default: "0")) ?? 0
```

### Parsing JSON Config

For structured values, decode the string with `JSONDecoder`:

```swift
struct TopPlayer: Codable {
    let name: String
    let count: Int
}

let raw = SideKit.shared.config("top_player_runners_up", default: "[]")
let runnersUp = (try? JSONDecoder().decode(
    [TopPlayer].self,
    from: Data(raw.utf8)
)) ?? []
```

<InfoBox variant="info">
  <code>config(\_:default:)</code> only returns Remote Config entries. If a key belongs to a boolean feature flag, the default is returned instead — read those with [`flag(_:default:)`](/ios/feature-flags/feature-flags).
</InfoBox>

## Reacting to Config in SwiftUI

`SideKit.shared` is an `ObservableObject`, so a view that reads config re-renders when values refresh:

```swift
struct GoalBanner: View {
    @ObservedObject private var sideKit = SideKit.shared

    var body: some View {
        Text("Goal: \(sideKit.config("game_played_goal", default: "1000"))")
    }
}
```

## Refreshing Config

Config and flags share one system, so [`refreshFlags`](/ios/feature-flags/feature-flags) pulls the latest of both:

```swift
await SideKit.shared.refreshFlags()
```

SideKit refreshes automatically on launch and when the app returns to the foreground, and falls back to the last cached values when the network is unavailable.

<InfoBox variant="info">
  <strong>What if there's no cache?</strong> If a fetch fails and nothing has been cached yet — a first launch with no connection, for example — SideKit simply keeps an empty config set. It never throws, crashes, or blocks your UI. Every <code>config(\_:default:)</code> call just returns the <code>default</code> you passed, so your app always has a value to work with.
</InfoBox>

## How Config Behaves

<PropertyList
  properties={[
{ name: 'Strings only', description: 'Every value is delivered as a string. Convert or decode it on the client.' },
{ name: 'Runtime delivery', description: 'Values update on the next fetch — launch or foreground — with no App Store release.' },
{ name: 'Cached', description: 'The last fetched values are stored on device and reused when the server is unreachable.' },
{ name: 'Safe defaults', description: 'Unknown or not-yet-fetched keys return the default you pass.' }
]}
/>


# Add an App



<div style={{ display: 'flex', flexDirection: 'column', gap: '1.5rem', marginTop: '1.5rem' }}>
  <div>
    <StepItem step={1}>
      Select 

      <strong>Add new app</strong>

       from the app switcher in the top left of the dashboard.
    </StepItem>

    <DocImage src="/sk_setup_1.png" alt="Add App option from the dashboard" maxWidth="800px" />
  </div>

  <div>
    <StepItem step={2}>
      Enter your app's name as well as an App Store and/or Play Store URL if your app is currently live.
    </StepItem>

    <InfoBox variant="info">
      If your app is already live on the App Store, SideKit will automatically pull your app icon from your store URL. If it's not live yet, don't worry—you can always update the icon URL later.
    </InfoBox>
  </div>
</div>

## What's a Signal?

A signal is an analytics metric that you'd like to track with SideKit. Any time the event you'd like to track takes place in your app you can [record it with the SideKit SDK](../analytics/track-a-signal).

<DocImage src="/ios_signal.png" alt="The signals menu in the SideKit dashboard" maxWidth="800px" />

### Default Signals

SideKit automatically records three essential signals out-of-the-box so you can start seeing data immediately:

<PropertyList
  properties={[
{ name: 'first_launch', description: 'Triggered when a user opens your app for the very first time.' },
{ name: 'app_open', description: 'Triggered every time your app enters the foreground.' },
{ name: 'gate_enforced', description: 'Triggered whenever a version gate is displayed to your users.' }
]}
/>

<InfoBox variant="info">
  We keep default signals to a minimum, you get to decide what you want to track.
</InfoBox>


# Configure SideKit



## Add SideKit to your Project

:::ios
To add the SideKit iOS SDK to your Xcode project, follow these steps:

<div style={{ display: 'flex', flexDirection: 'column', gap: '1.5rem', marginTop: '1.5rem' }}>
  <div>
    <StepItem step={1}>
      In Xcode, go to 

      <strong>File</strong>

       \> 

      <strong>Add Package Dependencies...</strong>
    </StepItem>

    <DocImage src="/ios_setup_1.png" alt="Add Package Dependencies menu" maxWidth="800px" />
  </div>

  <div>
    <StepItem step={2}>
      In the search bar, enter the GitHub URL:
    </StepItem>

    <div style={{ marginTop: '0.5rem', marginBottom: '1rem' }}>
      ```
      https://github.com/appsidekit/ios-sdk
      ```
    </div>

    <DocImage src="/ios_setup_2.png" alt="Package search dialog" maxWidth="800px" />
  </div>

  <div>
    <StepItem step={3}>
      Select the 

      <strong>ios-sdk</strong>

       package from the results
    </StepItem>
  </div>

  <div>
    <StepItem step={4}>
      Configure the dependency rule:
    </StepItem>

    <ul style={{ marginLeft: '1.5rem', marginTop: '0.5rem', fontSize: '0.95rem', color: 'hsl(0, 0%, 30%)' }}>
      <li>
        Set 

        <strong>Dependency Rule</strong>

         to "Up to Next Major Version"
      </li>

      <li>
        This will use versions 

        <code>1.0.0</code>

         up to (but not including) 

        <code>2.0.0</code>
      </li>
    </ul>
  </div>

  <div>
    <StepItem step={5}>
      Click 

      <strong>Add Package</strong>

       to complete the installation.
    </StepItem>
  </div>

  <div>
    <StepItem step={6}>
      Ensure 

      <strong>SideKit</strong>

       appears in your project settings under 

      <strong>General</strong>

       \> 

      <strong>Frameworks, Libraries, and Embedded Content</strong>

      .
    </StepItem>
  </div>
</div>
:::

## Configure SideKit in your app

:::ios
<Tabs items={['SwiftUI', 'UIKit']}>
  <Tab value="SwiftUI">
    In your `ContentView`, add the configuration in a `.task` modifier with your [API key](/ios/helpers/find-api-key):

    ```swift
    .task {
        await SideKit.shared.configure(
            apiKey: "YOUR-API-KEY",
            verbose: true // Optional: enables detailed logs
        )
    }
    ```
  </Tab>

  <Tab value="UIKit">
    In your `AppDelegate` or `SceneDelegate`, call configure in `application(_:didFinishLaunchingWithOptions:)` or `scene(_:willConnectTo:options:)`:

    ```swift
    Task {
        await SideKit.shared.configure(
            apiKey: "YOUR-API-KEY",
            verbose: true // Optional: enables detailed logs
        )
    }
    ```
  </Tab>
</Tabs>
:::

<InfoBox variant="tip">
  Set <code>verbose = true</code> during development to see all SideKit logs in your console.
  This is helpful for verifying that your signals are being tracked successfully.
</InfoBox>

The SideKit SDK will now be available in your app, and you can start sending signals!


# Find Your API Key



Your API key is a unique identifier used to authenticate your app's requests to SideKit.

## Locating your API Key

<div style={{ display: 'flex', flexDirection: 'column', gap: '1.5rem', marginTop: '1.5rem' }}>
  <div>
    <StepItem step={1}>
      Navigate to your app in the SideKit dashboard.
    </StepItem>
  </div>

  <div>
    <StepItem step={2}>
      Select 

      <strong>Settings</strong>

       from the sidebar navigation menu.
    </StepItem>
  </div>

  <div>
    <StepItem step={3}>
      Scroll down to the 

      <strong>Danger Zone</strong>

       section to find your key.
    </StepItem>

    <DocImage src="/sk_settings.png" alt="Finding the API Key in App Settings" maxWidth="800px" />
  </div>
</div>

## Rotating Your API Key

If your API key is compromised, you can generate a new one by clicking the **Rotate** button.

<InfoBox variant="warning">
  Rotating your API key is <strong>irreversible</strong>. Once rotated:

  <ul style={{ marginTop: '0.5rem', marginLeft: '1.25rem' }}>
    <li>
      Older app versions using the old key will stop sending signals.
    </li>

    <li>
      Version gates will no longer be enforced on those versions.
    </li>

    <li>
      You must release an update with the new key immediately.
    </li>
  </ul>
</InfoBox>


# Find Your Bundle ID



:::ios
A **Bundle ID** (Bundle Identifier) is a unique identifier that represents your app on the App Store. They typically follow a reverse-DNS format, such as `com.yourcompany.appname`. Read more [here](https://developer.apple.com/documentation/appstoreconnectapi/bundle-ids).

## Locating the Bundle ID in Xcode

You can find your Bundle ID in your project settings.

<div style={{ display: 'flex', flexDirection: 'column', gap: '1.5rem', marginTop: '1.5rem' }}>
  <div>
    <StepItem step={1}>
      Open your project in Xcode and select the project file at the top of the 

      <strong>Project Navigator</strong>

      .
    </StepItem>
  </div>

  <div>
    <StepItem step={2}>
      Select your app target under the 

      <strong>Targets</strong>

       list.
    </StepItem>
  </div>

  <div>
    <StepItem step={3}>
      Go to the 

      <strong>General</strong>

       tab and look for the 

      <strong>Identity</strong>

       section.
    </StepItem>

    <DocImage src="/ios_bundle_id.png" alt="Finding the Bundle ID in the Xcode Identity section" maxWidth="800px" />
  </div>
</div>
:::

<InfoBox variant="tip">
  Bundle IDs are case-sensitive! Double-check for any accidental capital letters or spaces.
</InfoBox>


# Collect Feedback



SideKit gives you a complete in-app feedback loop: send a report with one line of code, and it flows into a shared inbox in the dashboard where it's automatically grouped, triaged, and answerable.

<InfoBox variant="info">
  Make sure you've [configured the SDK](/ios/getting-started/configure-sidekit) with your API key before sending feedback, so reports are attributed to the right app.
</InfoBox>

## Send Feedback from Your App

Call `sendFeedback` with the user's message. That's the only required argument — SideKit collects the device metadata for you:

```swift
SideKit.shared.sendFeedback("The timer keeps resetting when I background the app.")
```

Hook it up to a text field and a submit button, and you have a working feedback form:

```swift
struct FeedbackView: View {
    @State private var text = ""

    var body: some View {
        VStack {
            TextEditor(text: $text)
            Button("Send") {
                SideKit.shared.sendFeedback(text)
                text = ""
            }
        }
    }
}
```

<InfoBox variant="tip">
  Feedback sends fire-and-forget — there's no need to <code>await</code>. Clear your input and show a thank-you the moment the user taps send.
</InfoBox>

## What Gets Collected Automatically

You only pass the message. SideKit attaches the context you need to reproduce and triage a report:

<PropertyList
  properties={[
{ name: 'platform', description: 'The platform the report came from (iOS).' },
{ name: 'appVersion', description: "Your app's version and build number." },
{ name: 'osVersion', description: 'The OS version running on the device.' },
{ name: 'deviceModel', description: 'The device model the user is on.' },
{ name: 'country', description: 'The country, derived from device region.' },
{ name: 'language', description: "The device's language." }
]}
/>

This metadata shows up next to every report in the dashboard arrives tagged with `iOS`, `v3.7.2`, `Version 26.5.1 (Build 23F81)`, `PL`, and `iPhone` without you writing any extra code. No begging users for context.

## Attributing Feedback to a User

You can also attach arbitrary key-value context about the user with `userAttributes`:

```swift
SideKit.shared.sendFeedback(
    "Crash on the stats screen.",
    endUserId: "user_12345",
    userAttributes: [
        "plan": "pro",
        "signup_date": "2026-01-15"
    ]
)
```

<InfoBox variant="info">
  A recipient must have an <code>endUserId</code> for you to reply to their feedback. Anonymous reports still land in your inbox — you just can't message back.
</InfoBox>

## Triage in the Dashboard

Every report lands in a shared inbox. SideKit organizes it so you can act instead of sort.

<DocImage src="/sk_feedback.png" alt="The feedback inbox in the SideKit dashboard, with auto-grouped reports" maxWidth="800px" />

<div style={{ display: 'flex', flexDirection: 'column', gap: '1rem', marginTop: '1rem' }}>
  <StepItem step={1}>
    <strong>Auto-grouping</strong>

    : SideKit clusters related reports into themes like "Leaderboard Issues" or "UI customization and haptics" so duplicates collapse into one actionable group. Hit 

    <strong>Auto-group</strong>

     to file the ungrouped backlog.
  </StepItem>

  <StepItem step={2}>
    <strong>Labels</strong>

    : Each report and group is tagged as a 

    <strong>Bug</strong>

     or 

    <strong>Feature</strong>

     request, so you can filter to exactly what you're working on.
  </StepItem>

  <StepItem step={3}>
    <strong>Status</strong>

    : Move items through 

    <code>Open</code>

    , 

    <code>In Progress</code>

    , 

    <code>Resolved</code>

    , and 

    <code>Won't Do</code>

     to track what's handled.
  </StepItem>

  <StepItem step={4}>
    <strong>Reply</strong>

    : Respond to a single report or reply to everyone in a group at once. Replies reach any user who came in with an 

    <code>endUserId</code>

    .
  </StepItem>
</div>

<InfoBox variant="tip">
  Reply to a whole group in one action to close the loop with every user who reported the same issue — a great way to tell people a fix has shipped.
</InfoBox>


# Track Metrics





The SideKit SDK provides multiple ways to send analytics signals. This data powers your dashboard charts and allows you to build targeted version gates based on user behavior.

<InfoBox variant="info">
  Make sure you've configured the SDK with your API key before sending any signals to ensure they are tracked correctly.
</InfoBox>

## Add Your Custom Signal in the Dashboard

<img alt="Signals UI" src={__img0} placeholder="blur" />

Navigate to the `Settings` page for your app and add your signal in the `Custom Signals` section. Here `purchases` is a custom signal we've chosen to track for this app. This whitelists the signal name and SideKit will accept data for this signal.

## Sending Signals

:::react-native
You can track events in your app using two primary methods, depending on how much detail you need.
:::

### 1. Simple Key

The simplest way to send a signal is with just a key string. This is perfect for binary events (like "session\_start").

:::react-native
```ts
const { sendSignal } = useSideKit();

sendSignal("user_login")
```
:::

### 2. Key-Value Pairs

Send a signal with both a key and a value. SideKit automatically generates pie charts in your dashboard for the distribution of these values.

:::react-native
```ts
sendSignal("purchase_amount", "99.99")

```
:::

***

## Bulk Tracking

If you have multiple events that happen simultaneously, you can batch them into a single call:

:::react-native
```ts
const { sendSignals } = useSideKit();

sendSignals([
  { key: "page_view", value: "home" },
  { key: "interaction", value: "header_clicked" }
])
```
:::

## Best Practices

<div style={{ display: 'flex', flexDirection: 'column', gap: '1rem', marginTop: '1rem' }}>
  <StepItem step={1}>
    <strong>Batch when possible</strong>

    : If sending multiple signals in a loop, batch them into an array to reduce network requests.
  </StepItem>

  <StepItem step={2}>
    <strong>Use descriptive keys</strong>

    : Choose clear, consistent names (e.g., 

    <code>onboarding_step_1</code>

    ) to keep your dashboard organized.
  </StepItem>

  <StepItem step={3}>
    <strong>Analytics state</strong>

    : SideKit respects the user's analytics preference. If analytics is disabled, signals will be silently ignored.
  </StepItem>
</div>


# Add an App



<div style={{ display: 'flex', flexDirection: 'column', gap: '1.5rem', marginTop: '1.5rem' }}>
  <div>
    <StepItem step={1}>
      Select 

      <strong>Add new app</strong>

       from the app switcher in the top left of the dashboard.
    </StepItem>

    <DocImage src="/sk_setup_1.png" alt="Add App option from the dashboard" maxWidth="800px" />
  </div>

  <div>
    <StepItem step={2}>
      Enter your app's name as well as an App Store and/or Play Store URL if your app is currently live.
    </StepItem>

    <InfoBox variant="info">
      If your app is already live on the App Store, SideKit will automatically pull your app icon from your store URL. If it's not live yet, don't worry—you can always update the icon URL later.
    </InfoBox>
  </div>
</div>

## What's a Signal?

A signal is an analytics metric that you'd like to track with SideKit. Any time the event you'd like to track takes place in your app you can [record it with the SideKit SDK](../analytics/track-a-signal).

<DocImage src="/ios_signal.png" alt="The signals menu in the SideKit dashboard" maxWidth="800px" />

### Default Signals

SideKit automatically records three essential signals out-of-the-box so you can start seeing data immediately:

<PropertyList
  properties={[
{ name: 'first_launch', description: 'Triggered when a user opens your app for the very first time.' },
{ name: 'app_open', description: 'Triggered every time your app enters the foreground.' },
{ name: 'gate_enforced', description: 'Triggered whenever a version gate is displayed to your users.' }
]}
/>

<InfoBox variant="info">
  We keep default signals to a minimum, you get to decide what you want to track.
</InfoBox>


# Configure SideKit



## Add SideKit to your Project

:::react-native
To add the SideKit React Native SDK to your project, just install the NPM package:

```sh
npm install @sidekit/react-native @react-native-async-storage/async-storage
# or
yarn add @sidekit/react-native @react-native-async-storage/async-storage
```
:::

## Configure SideKit in your app

:::react-native
To initialize SideKit, wrap your app's contents with `SideKitProvider`:

```ts
import { SideKitProvider } from '@sidekit/react-native';

function App() {
  return (
    <SideKitProvider apiKey="YOUR-API-KEY" verbose={__DEV__}>
      <YourAppContent />
    </SideKitProvider>
  );
}
```
:::

<InfoBox variant="tip">
  Set <code>verbose = true</code> during development to see all SideKit logs in your console.
  This is helpful for verifying that your signals are being tracked successfully.
</InfoBox>

The SideKit SDK will now be available in your app, and you can start sending signals!


# Find Your API Key



Your API key is a unique identifier used to authenticate your app's requests to SideKit.

## Locating your API Key

<div style={{ display: 'flex', flexDirection: 'column', gap: '1.5rem', marginTop: '1.5rem' }}>
  <div>
    <StepItem step={1}>
      Navigate to your app in the SideKit dashboard.
    </StepItem>
  </div>

  <div>
    <StepItem step={2}>
      Select 

      <strong>Settings</strong>

       from the sidebar navigation menu.
    </StepItem>
  </div>

  <div>
    <StepItem step={3}>
      Scroll down to the 

      <strong>Danger Zone</strong>

       section to find your key.
    </StepItem>

    <DocImage src="/sk_settings.png" alt="Finding the API Key in App Settings" maxWidth="800px" />
  </div>
</div>

## Rotating Your API Key

If your API key is compromised, you can generate a new one by clicking the **Rotate** button.

<InfoBox variant="warning">
  Rotating your API key is <strong>irreversible</strong>. Once rotated:

  <ul style={{ marginTop: '0.5rem', marginLeft: '1.25rem' }}>
    <li>
      Older app versions using the old key will stop sending signals.
    </li>

    <li>
      Version gates will no longer be enforced on those versions.
    </li>

    <li>
      You must release an update with the new key immediately.
    </li>
  </ul>
</InfoBox>


# Find Your Bundle ID



:::react-native
A **Bundle ID** (Bundle Identifier) is a unique identifier that represents your app on the App Store/Play Store. They typically follow a reverse-DNS format, such as `com.yourcompany.appname`. Read more [here](https://developer.apple.com/documentation/appstoreconnectapi/bundle-ids).

## Locating the Bundle ID in your Expo Project

You can find your Bundle IDs for both iOS and Android in your app's `app.json` file:

```json
{
  "expo": {
    ...
    "ios": {
      "bundleIdentifier": "com.sidekit.example"
    },
    "android": {
      "package": "com.sidekit.example"
    },
    ...
  }
}

```
:::

<InfoBox variant="tip">
  Bundle IDs are case-sensitive! Double-check for any accidental capital letters or spaces.
</InfoBox>


# Block an App Version





## In the Dashboard

<img alt="Manage Versions UI" src={__img0} placeholder="blur" />
Navigate to `Versions` in the Dashboard under your app. SideKit will use analytics data to automatically infer the most popular app versions from the last 7 days. Tap configure to add an app version to SideKit's tracking.

On an existing version you can set the status as forced or dismissible to block the version. Forced gates require users to update their app to proceed whereas dismissible gates can be skipped.

## In Your App

### Automatic ✨

<div
  style={{
background: 'linear-gradient(135deg, rgba(216, 109, 74, 0.08) 0%, rgba(234, 134, 76, 0.12) 100%)',
border: '1px solid rgba(216, 109, 74, 0.25)',
borderRadius: '12px',
padding: '1.25rem 1.5rem',
marginBottom: '1rem'
}}
>
  <div style={{display: 'flex', gap: '1.5rem', alignItems: 'flex-start', flexWrap: 'wrap'}}>
    <div style={{flex: '0 0 auto', maxWidth: '240px'}}>
      <DocImage
        src="/ios_gate_1.png"
        style={{
        width: '100%',
        height: 'auto',
        borderRadius: '8px',
        boxShadow: '0 4px 12px rgba(0, 0, 0, 0.1)'
      }}
      />
    </div>

    <div style={{flex: '1 1 300px', minWidth: '250px'}}>
      <h4 style={{marginTop: '2rem', marginBottom: '0rem', fontSize: '1.2rem', fontWeight: '600'}}>
        Zero Code Required
      </h4>

      <div style={{marginBottom: '1rem', lineHeight: '1.6'}}>
        SideKit automatically presents a beautiful version gate when users need to update.
        No setup, no code, no maintenance required.
      </div>

      <CheckList>
        <CheckListItem>
          Latest version pulled from App Store automatically
        </CheckListItem>

        <CheckListItem>
          "What's New" text synced from your App Store submission
        </CheckListItem>

        <CheckListItem>
          Works out-of-the-box with zero configuration
        </CheckListItem>
      </CheckList>
    </div>
  </div>
</div>

### Custom View for Blocked App Versions

For custom version gates, see [Showing Custom Version Gates](./showing-custom-version-gates).


# Set a Minimum Version





## In the Dashboard

<img alt="Manage Versions UI" src={__img0} placeholder="blur" />
Navigate to `Versions` in the Dashboard under your app, set `MIN` from the dropdown to set an app version as a floor. Users on that app version or above will be able to access the app and any users below it will be shown a forced version gate which will require them to update their app to proceed.

## In Your App

### Automatic ✨

<div
  style={{
background: 'linear-gradient(135deg, rgba(216, 109, 74, 0.08) 0%, rgba(234, 134, 76, 0.12) 100%)',
border: '1px solid rgba(216, 109, 74, 0.25)',
borderRadius: '12px',
padding: '1.25rem 1.5rem',
marginBottom: '1rem'
}}
>
  <div style={{display: 'flex', gap: '1.5rem', alignItems: 'flex-start', flexWrap: 'wrap'}}>
    <div style={{flex: '0 0 auto', maxWidth: '240px'}}>
      <DocImage
        src="/ios_gate_1.png"
        style={{
        width: '100%',
        height: 'auto',
        borderRadius: '8px',
        boxShadow: '0 4px 12px rgba(0, 0, 0, 0.1)'
      }}
      />
    </div>

    <div style={{flex: '1 1 300px', minWidth: '250px'}}>
      <h4 style={{marginTop: '2rem', marginBottom: '0rem', fontSize: '1.2rem', fontWeight: '600'}}>
        Zero Code Required
      </h4>

      <div style={{marginBottom: '1rem', lineHeight: '1.6'}}>
        SideKit automatically presents a beautiful version gate when users need to update.
        No setup, no code, no maintenance required.
      </div>

      <CheckList>
        <CheckListItem>
          Latest version pulled from App Store automatically
        </CheckListItem>

        <CheckListItem>
          "What's New" text synced from your App Store submission
        </CheckListItem>

        <CheckListItem>
          Works out-of-the-box with zero configuration
        </CheckListItem>
      </CheckList>
    </div>
  </div>
</div>

<InfoBox variant="warning">
  Version gates triggered by minimum version requirements are <strong>never dismissible</strong>.
  Users must update to continue using the app. The "Skip for now" button only appears in dismissible version gates.
</InfoBox>

### Custom View for Blocked App Versions

For custom version gates, see [Showing Custom Version Gates](./showing-custom-version-gates).


# Showing Custom Version Gates



## Setup

:::react-native
To use custom version gates, configure SideKit with `presentationMode: "manual"`:

```ts
import { SideKitProvider } from '@sidekit/react-native';

function App() {
  return (
    <SideKitProvider apiKey="YOUR-API-KEY" presentationMode="manual">
      <YourAppContent />
    </SideKitProvider>
  );
}
```
:::

<InfoBox variant="info">
  When using manual presentation mode, you're responsible for displaying the version gate UI.
  SideKit will still fetch and manage version requirements, but won't automatically show the update screen.
</InfoBox>

## GateInformation Struct

Use the `GateInformation` struct to access version gate data and build your custom UI:

:::react-native
```ts
class GateInformation {
    gateType: VersionGateType;
    lastGateUpdate: string;
    latestVersion: string | null;
    whatsNew: string | null;
    storeUrl: string | null;
}
```
:::

:::react-native
<PropertyList
  properties={[
{ name: 'gateType', description: 'How the gate should be presented' },
{ name: 'lastGateUpdate', description: 'Timestamp of when the gate information was last updated' },
{ name: 'latestVersion', description: 'The latest available version from the App Store/Play Store' },
{ name: 'whatsNew', description: 'Release notes from your App Store/Play Store submission' },
{ name: 'storeUrl', description: 'Direct link to your app on the App Store/Play Store' }
]}
/>
:::

## Gate Types

The `VersionGateType` enum defines version gate behavior:

:::react-native
```ts
enum VersionGateType {
  Live = -1,
  Forced = 0,
  Dismissible = 1,
}
```
:::

### Understanding Gate Types

<FeatureCard>
  <div style={{display: 'flex', flexDirection: 'column', gap: '0.75rem'}}>
    <div>
      <strong style={{fontSize: '1rem', color: 'hsl(18, 61%, 45%)'}}>
        Live
      </strong>

      <div style={{margin: '0.25rem 0 0 0', fontSize: '0.9rem', lineHeight: '1.5'}}>
        The user's app version is not blocked by a version gate. You should not show an update screen in this case.
      </div>
    </div>

    <div>
      <strong style={{fontSize: '1rem', color: 'hsl(18, 61%, 45%)'}}>
        Forced
      </strong>

      <div style={{margin: '0.25rem 0 0 0', fontSize: '0.9rem', lineHeight: '1.5'}}>
        User must update to continue. The gate cannot be dismissed. Used for critical updates or minimum version enforcement.
      </div>
    </div>

    <div>
      <strong style={{fontSize: '1rem', color: 'hsl(18, 61%, 45%)'}}>
        Dismissible
      </strong>

      <div style={{margin: '0.25rem 0 0 0', fontSize: '0.9rem', lineHeight: '1.5'}}>
        User can dismiss the gate and continue using the app. Your custom view should include a close/skip button.
      </div>
    </div>
  </div>
</FeatureCard>

<InfoBox variant="warning">
  If the gate type is <code>dismissible</code>, your custom view must include UI to close or skip the update.
  Failing to do so will trap users in the update screen.
</InfoBox>

## Displaying Your Custom Gate

:::react-native
```ts
const { showUpdateScreen, gateInformation } = useSideKit();

<SideKitProvider apiKey="YOUR-API-KEY" presentationMode='manual'>
  <YourAppContent />
  {showUpdateScreen && gateInformation && (
    {/* Show your custom update UI */}
  )}
</SideKitProvider>
```
:::

:::react-native
<InfoBox variant="tip">
  Access <code>gateInformation</code> to get the current gate data, including version requirements,
  release notes, and App Store/Play Store URL.
</InfoBox>
:::


# Block an App Version





## In the Dashboard

<img alt="Manage Versions UI" src={__img0} placeholder="blur" />
Navigate to `Versions` in the Dashboard under your app. SideKit will use analytics data to automatically infer the most popular app versions from the last 7 days. Tap configure to add an app version to SideKit's tracking.

On an existing version you can set the status as forced or dismissible to block the version. Forced gates require users to update their app to proceed whereas dismissible gates can be skipped.

## In Your App

### Automatic ✨

<div
  style={{
background: 'linear-gradient(135deg, rgba(216, 109, 74, 0.08) 0%, rgba(234, 134, 76, 0.12) 100%)',
border: '1px solid rgba(216, 109, 74, 0.25)',
borderRadius: '12px',
padding: '1.25rem 1.5rem',
marginBottom: '1rem'
}}
>
  <div style={{display: 'flex', gap: '1.5rem', alignItems: 'flex-start', flexWrap: 'wrap'}}>
    <div style={{flex: '0 0 auto', maxWidth: '240px'}}>
      <DocImage
        src="/ios_gate_1.png"
        style={{
        width: '100%',
        height: 'auto',
        borderRadius: '8px',
        boxShadow: '0 4px 12px rgba(0, 0, 0, 0.1)'
      }}
      />
    </div>

    <div style={{flex: '1 1 300px', minWidth: '250px'}}>
      <h4 style={{marginTop: '2rem', marginBottom: '0rem', fontSize: '1.2rem', fontWeight: '600'}}>
        Zero Code Required
      </h4>

      <div style={{marginBottom: '1rem', lineHeight: '1.6'}}>
        SideKit automatically presents a beautiful version gate when users need to update.
        No setup, no code, no maintenance required.
      </div>

      <CheckList>
        <CheckListItem>
          Latest version pulled from App Store automatically
        </CheckListItem>

        <CheckListItem>
          "What's New" text synced from your App Store submission
        </CheckListItem>

        <CheckListItem>
          Works out-of-the-box with zero configuration
        </CheckListItem>
      </CheckList>
    </div>
  </div>
</div>

### Custom View for Blocked App Versions

For custom version gates, see [Showing Custom Version Gates](./showing-custom-version-gates).


# Set a Minimum Version





## In the Dashboard

<img alt="Manage Versions UI" src={__img0} placeholder="blur" />
Navigate to `Versions` in the Dashboard under your app, set `MIN` from the dropdown to set an app version as a floor. Users on that app version or above will be able to access the app and any users below it will be shown a forced version gate which will require them to update their app to proceed.

## In Your App

### Automatic ✨

<div
  style={{
background: 'linear-gradient(135deg, rgba(216, 109, 74, 0.08) 0%, rgba(234, 134, 76, 0.12) 100%)',
border: '1px solid rgba(216, 109, 74, 0.25)',
borderRadius: '12px',
padding: '1.25rem 1.5rem',
marginBottom: '1rem'
}}
>
  <div style={{display: 'flex', gap: '1.5rem', alignItems: 'flex-start', flexWrap: 'wrap'}}>
    <div style={{flex: '0 0 auto', maxWidth: '240px'}}>
      <DocImage
        src="/ios_gate_1.png"
        style={{
        width: '100%',
        height: 'auto',
        borderRadius: '8px',
        boxShadow: '0 4px 12px rgba(0, 0, 0, 0.1)'
      }}
      />
    </div>

    <div style={{flex: '1 1 300px', minWidth: '250px'}}>
      <h4 style={{marginTop: '2rem', marginBottom: '0rem', fontSize: '1.2rem', fontWeight: '600'}}>
        Zero Code Required
      </h4>

      <div style={{marginBottom: '1rem', lineHeight: '1.6'}}>
        SideKit automatically presents a beautiful version gate when users need to update.
        No setup, no code, no maintenance required.
      </div>

      <CheckList>
        <CheckListItem>
          Latest version pulled from App Store automatically
        </CheckListItem>

        <CheckListItem>
          "What's New" text synced from your App Store submission
        </CheckListItem>

        <CheckListItem>
          Works out-of-the-box with zero configuration
        </CheckListItem>
      </CheckList>
    </div>
  </div>
</div>

<InfoBox variant="warning">
  Version gates triggered by minimum version requirements are <strong>never dismissible</strong>.
  Users must update to continue using the app. The "Skip for now" button only appears in dismissible version gates.
</InfoBox>

### Custom View for Blocked App Versions

For custom version gates, see [Showing Custom Version Gates](./showing-custom-version-gates).


# Showing Custom Version Gates



## Setup

:::ios
To use custom version gates, configure SideKit with `presentationMode: .manual`:

```swift
SideKit.shared.configure(apiKey: "YOUR-API-KEY", presentationMode: .manual)
```
:::

<InfoBox variant="info">
  When using manual presentation mode, you're responsible for displaying the version gate UI.
  SideKit will still fetch and manage version requirements, but won't automatically show the update screen.
</InfoBox>

## GateInformation Struct

Use the `GateInformation` struct to access version gate data and build your custom UI:

:::ios
```swift
struct GateInformation {
    let gateType: VersionGateType
    let lastGateUpdate: String
    let latestVersion: String?
    let whatsNew: String?
    let storeURL: String?
}
```
:::

:::ios
<PropertyList
  properties={[
{ name: 'gateType', description: 'How the gate should be presented' },
{ name: 'lastGateUpdate', description: 'Timestamp of when the gate information was last updated' },
{ name: 'latestVersion', description: 'The latest available version from the App Store' },
{ name: 'whatsNew', description: 'Release notes from your App Store Connect submission' },
{ name: 'storeURL', description: 'Direct link to your app on the App Store' }
]}
/>
:::

## Gate Types

The `VersionGateType` enum defines version gate behavior:

:::ios
```swift
enum VersionGateType: Int, Codable {
    case live = -1
    case forced = 0
    case dismissible = 1
}
```
:::

### Understanding Gate Types

<FeatureCard>
  <div style={{display: 'flex', flexDirection: 'column', gap: '0.75rem'}}>
    <div>
      <strong style={{fontSize: '1rem', color: 'hsl(18, 61%, 45%)'}}>
        Live
      </strong>

      <div style={{margin: '0.25rem 0 0 0', fontSize: '0.9rem', lineHeight: '1.5'}}>
        The user's app version is not blocked by a version gate. You should not show an update screen in this case.
      </div>
    </div>

    <div>
      <strong style={{fontSize: '1rem', color: 'hsl(18, 61%, 45%)'}}>
        Forced
      </strong>

      <div style={{margin: '0.25rem 0 0 0', fontSize: '0.9rem', lineHeight: '1.5'}}>
        User must update to continue. The gate cannot be dismissed. Used for critical updates or minimum version enforcement.
      </div>
    </div>

    <div>
      <strong style={{fontSize: '1rem', color: 'hsl(18, 61%, 45%)'}}>
        Dismissible
      </strong>

      <div style={{margin: '0.25rem 0 0 0', fontSize: '0.9rem', lineHeight: '1.5'}}>
        User can dismiss the gate and continue using the app. Your custom view should include a close/skip button.
      </div>
    </div>
  </div>
</FeatureCard>

<InfoBox variant="warning">
  If the gate type is <code>dismissible</code>, your custom view must include UI to close or skip the update.
  Failing to do so will trap users in the update screen.
</InfoBox>

## Displaying Your Custom Gate

:::ios
Bind your custom gate view to `SideKit.shared.showUpdateScreen` to control when it appears:

<Tabs items={['SwiftUI', 'UIKit']}>
  <Tab value="SwiftUI">
    ```swift
    struct ContentView: View {
        var body: some View {
            YourAppContent()
                .fullScreenCover(isPresented: SideKit.shared.$showUpdateScreen) {
                    if let gateInfo = SideKit.shared.gateInformation {
                        CustomVersionGateView(gateInfo: gateInfo)
                    }
                }
        }
    }
    ```
  </Tab>

  <Tab value="UIKit">
    ```swift
    class ViewController: UIViewController {
        override func viewDidLoad() {
            super.viewDidLoad()
            
            // Observe showUpdateScreen changes
            SideKit.shared.$showUpdateScreen
                .sink { [weak self] shouldShow in
                    if shouldShow, let gateInfo = SideKit.shared.gateInformation {
                        self?.presentCustomGate(gateInfo)
                    }
                }
                .store(in: &cancellables)
        }
        
        func presentCustomGate(_ gateInfo: GateInformation) {
            let gateVC = CustomVersionGateViewController(gateInfo: gateInfo)
            gateVC.modalPresentationStyle = .fullScreen
            present(gateVC, animated: true)
        }
    }
    ```
  </Tab>
</Tabs>
:::

:::ios
<InfoBox variant="tip">
  Access <code>SideKit.shared.gateInformation</code> to get the current gate data, including version requirements,
  release notes, and App Store URL. This data is automatically synced from your App Store listing.
</InfoBox>
:::