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


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


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