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

# iOS App Configuration

> Step-by-step guide to configure, brand, and publish the iOS VPN app.

The iOS VPN app is a native Swift / SwiftUI application that connects to the **StartMyVPN backend** over the same REST API used by the web frontend. It supports WireGuard and OpenVPN and ships with Apple Sign-In, reCAPTCHA v3 protection, a guest-mode flow, in-app purchases (StoreKit), and a Network Extension tunnel provider.

<Warning>
  This app is a **client** for the StartMyVPN SaaS platform and will not function without it. You must have the StartMyVPN backend installed and running on your own server before this app can be used:

  **[StartMyVPN — WireGuard & OpenVPN SaaS Platform](https://startmyvpn.com)**
</Warning>

***

## Prerequisites

* macOS with **Xcode 15+** installed
* An **Apple Developer Program** membership (required to sign a Network Extension)
* A deployed copy of the **StartMyVPN backend** reachable over HTTPS
* A **Google reCAPTCHA v3** site key registered for your domain
* The iOS app source code (from your purchase)

***

## Step 1 — Open the Project

Open `VPN.xcodeproj` in Xcode. The project contains two targets:

| Target           | Purpose                                                        |
| ---------------- | -------------------------------------------------------------- |
| **VPN**          | The main iOS application                                       |
| **VPNExtension** | The Network Extension that runs the WireGuard / OpenVPN tunnel |

***

## Step 2 — Set Bundle Identifiers

Select the **VPN** target → **General** tab → **Identity**:

```
com.YOURTEAM.VPN
```

Select the **VPNExtension** target → **General** tab → **Identity**:

```
com.YOURTEAM.VPN.VPNExtension
```

<Note>
  The extension bundle ID must be a sub-identifier of the main app (i.e. it must start with the main app's bundle ID followed by a dot).
</Note>

***

## Step 3 — Configure Signing & Capabilities

For **both** targets, open **Signing & Capabilities**:

1. Set **Team** to your Apple Developer account.
2. Enable **Network Extensions** → check **Packet Tunnel**.
3. Enable **App Groups** → add `group.com.YOURTEAM.VPN` (the same value in both targets).

For the **VPN** target only, also enable:

* **Sign in with Apple** (if you want Apple Sign-In — see Step 8).
* **Associated Domains** → add `applinks:YOURDOMAIN.com` (for password-reset universal links).

***

## Step 4 — Configure `Configuration.swift`

Open `VPN/Utils/Configuration.swift` and fill in:

```swift theme={null}
struct Configuration {
    static let baseURL = "https://vpn.yourdomain.com"
    static let upgradeURL = "https://vpn.yourdomain.com/pricing"
    static let recaptchaSiteKey = "6Lc..."          // your v3 site key
    static let recaptchaDomain = "https://vpn.yourdomain.com"
}
```

| Key                | Description                                                                                                     |
| ------------------ | --------------------------------------------------------------------------------------------------------------- |
| `baseURL`          | Root URL of your VPN backend. No trailing slash.                                                                |
| `upgradeURL`       | Shown as an "Upgrade" link when the user has no active plan.                                                    |
| `recaptchaSiteKey` | Google reCAPTCHA v3 site key. Register at [google.com/recaptcha/admin](https://www.google.com/recaptcha/admin). |
| `recaptchaDomain`  | Must match the domain registered in the reCAPTCHA console. Usually the same as `baseURL`.                       |

***

## Step 5 — Update Hardcoded Identifiers

Several Swift files contain identifiers that must match your bundle ID. Search for `YOURTEAM` and replace:

### Extension bundle ID (2 files)

* `VPN/Services/WireGuardAdapter.swift`
* `VPN/Services/OpenVPNAdapter.swift`

```swift theme={null}
proto.providerBundleIdentifier = "com.YOURTEAM.VPN.VPNExtension"
```

Change this to your VPNExtension bundle ID from Step 2.

### App Group identifier (3 files)

* `VPN/Services/KeychainHelper.swift` → `private let service = "com.YOURTEAM.vpn"`
* `VPN/Views/MyAccountView.swift` → `let appGroupIdentifier = "group.com.YOURTEAM.VPN"`
* `VPNExtension/PacketTunnelProvider.swift` → `let appGroupIdentifier = "group.com.YOURTEAM.VPN"`

***

## Step 6 — Update Entitlements

### VPN/VPN.entitlements

```xml theme={null}
<key>com.apple.security.application-groups</key>
<array>
    <string>group.com.YOURTEAM.VPN</string>
</array>
<key>com.apple.developer.associated-domains</key>
<array>
    <string>applinks:YOURDOMAIN.com</string>
</array>
```

### VPNExtension/VPNExtension.entitlements

```xml theme={null}
<key>com.apple.security.application-groups</key>
<array>
    <string>group.com.YOURTEAM.VPN</string>
</array>
```

Both files are XML plists — you can edit them directly in Xcode via the **Signing & Capabilities** pane or in any text editor.

***

## Step 7 — Add Your App Logo & Icon

### Splash screen logo

1. Prepare a square PNG at **1024×1024 px** (transparent background recommended).
2. Name it `AppLogo.png` and place it in:
   ```
   VPN/Assets.xcassets/AppLogo.imageset/AppLogo.png
   ```
3. The `Contents.json` in that folder already references this filename.

### App Icon

Replace the images inside `VPN/Assets.xcassets/AppIcon.appiconset/` with your own icons at the required sizes. Use [appicon.co](https://www.appicon.co) or similar to generate all sizes from a 1024×1024 master.

***

## Step 8 — App Name & Tagline

Open `VPN/Views/SplashView.swift` and update:

```swift theme={null}
Text("Your VPN App")          // change to your app name
Text("Private. Secure. Free.") // change to your tagline
```

You should also update the **Display Name** in Xcode:

* Select the **VPN** target → **General** → **Display Name**.

***

## Step 9 — Apple Sign-In (optional)

Apple Sign-In is controlled server-side. Your backend's `/api/v1/app-config` endpoint returns:

```json theme={null}
{ "apple_login_enabled": true }
```

Set this to `false` on the backend to hide the button without any code changes.

If you do **not** want to offer Apple Sign-In at all, remove the `com.apple.developer.applesignin` entitlement from `VPN/VPN.entitlements` and remove the capability from Xcode.

***

## Step 10 — Universal Links (Password Reset)

The app handles password-reset deep links sent by the backend in the form:

```
https://YOURDOMAIN.com/reset-password/{token}?email=user@example.com
```

For these to open the app automatically, your web server must serve the **Apple App Site Association** file at:

```
https://YOURDOMAIN.com/.well-known/apple-app-site-association
```

The Laravel backend serves this file automatically. Ensure the `applinks:` value in `VPN.entitlements` matches your domain exactly.

***

## Step 11 — Build & Archive

1. Select a real device or **Any iOS Device (arm64)** as the build target.
2. **Product → Archive**.
3. In the Organizer, click **Distribute App** → **App Store Connect** (or **Ad Hoc** for testing).
4. Follow the prompts to upload to App Store Connect.

***

## Quick Checklist

<Steps>
  <Step title="Bundle IDs">Set unique bundle IDs for both targets in Xcode.</Step>
  <Step title="Signing">Set your Team and enable required capabilities (Network Extension, App Groups).</Step>
  <Step title="Configuration.swift">Fill in `baseURL`, `upgradeURL`, `recaptchaSiteKey`, and `recaptchaDomain`.</Step>
  <Step title="Hardcoded identifiers">Update extension bundle ID in `WireGuardAdapter.swift` and `OpenVPNAdapter.swift`.</Step>
  <Step title="App group">Update `group.com.YOURTEAM.VPN` in `KeychainHelper.swift`, `MyAccountView.swift`, and `PacketTunnelProvider.swift`.</Step>
  <Step title="Entitlements">Update app group and associated domain in both `.entitlements` files.</Step>
  <Step title="Logo & icon">Add your `AppLogo.png` and replace App Icon assets.</Step>
  <Step title="App name">Update display name in Xcode and the `Text("Your VPN App")` line in `SplashView.swift`.</Step>
  <Step title="Archive & submit">Build for a device, archive, and upload to App Store Connect.</Step>
</Steps>