ShipKit documentation

ShipKit is a Swift package plus a hosted dashboard. You configure what happens in the dashboard and publish; apps pick up the new configuration on their next refresh.

Install

Add the package in Xcode with File → Add Package Dependencies, paste the repository URL below, then add the ShipKit library to your app target. Requires iOS 16 or later.

https://github.com/shipkit-cloud/shipkit-ios.git

In a Package.swift: .package(url: "https://github.com/shipkit-cloud/shipkit-ios.git", from: "1.1.2"). The source is on GitHub under the MIT license.

Create a project in the dashboard. Each project has a Production and a Staging environment, each with its own client key (skc_…). Client keys are safe to ship in your app.

Or let the CLI do it: npx @shipkit-cloud/cli login signs in with the browser, then npx @shipkit-cloud/cli guide ./MyApp prints the setup steps for your project with your keys filled in. See CLI and MCP server.

Configure

import SwiftUI
import ShipKit

@main
struct MyApp: App {
    init() {
        ShipKit.configure(with: "skc_prod_…") { options in
            options.signingKey = "base64 key from the Integration page"
            options.defaults = ["max_upload_mb": 25, "promo_banner": ""]
        }
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
                .shipKitGate()
        }
    }
}

Configuration is read from memory, then the on-disk cache, then your defaults, so reads never wait for the network. ShipKit refreshes in the background on launch and when the app returns to the foreground.

The gate

.shipKitGate() on your root view takes care of everything version related:

SituationWhat the user sees
Below the minimum version, or on a blocked buildFull-screen update screen that cannot be dismissed
Maintenance mode onFull-screen maintenance screen with your message
Below the recommended versionDismissible reminder sheet, at the cadence you set
First launch of a new version with What's New itemsWhat's New sheet, once

If you prefer your own UI, call await ShipKit.versionStatus() and use the building blocks ShipKit.UpdateRequiredView, ShipKit.UpdateReminderSheet and ShipKit.MaintenanceView.

Offline behaviour: with no network and no cached config, nobody is ever blocked. If the app already received a block, it stays in place offline.

Version rules

In Versions set a minimum version (optionally a minimum build for the same version number), a recommended version, blocked versions, maintenance mode and an OS notice. The impact banner shows how many of the last 7 days' active installs each change affects. Version and build comparisons are numeric (2.10.0 is newer than 2.9.0).

With a bundle ID set, ShipKit checks the App Store hourly for your latest version. An automatic ramp can raise the recommended and minimum versions a number of days after a release goes live, and hold the ramp if the new version's in-app rating is low.

Projects can require a second team member to approve changes to the minimum version, blocked versions and maintenance mode.

Update reminders

Cadence options: every N launches, at most every N days, a maximum number of times per version, and an optional “Skip this version”. Titles, release notes and What's New items can be localized; ShipKit picks the user's language and falls back to English.

If a user reported a problem that you marked fixed in the new version, or voted for a request you shipped in it, the reminder tells them so.

Remote settings

let limit = ShipKit.setting("max_upload_mb", default: 25)
let banner = ShipKit.setting("promo_banner", default: "")

struct BannerView: View {
    @ShipKitSetting("promo_banner", default: "") var banner: String
    var body: some View { Text(banner) }
}

Types: boolean, integer, number, text, JSON, color (#RRGGBB) and URL. Each environment has its own value, and rules can serve different values to different users.

Feature flags

if ShipKit.isEnabled("new_onboarding") { … }
let layout = ShipKit.variant("paywall_layout", default: "A")

@ShipKitFlag("new_onboarding") var newOnboarding

Flags are boolean or multivariate. Each environment has an on/off switch, targeting rules, a fallthrough (one variant or a percentage rollout), an optional schedule and an optional rating guardrail. Rollouts are sticky: a user keeps the same bucket across launches (by user ID when identified, otherwise by install).

A rating guardrail watches in-app ratings from users who get a non-off variant. If the 3-day average drops below your threshold it alerts you, or turns the flag off.

Targeting rules

Rules are checked top to bottom; the first rule whose conditions all match wins.

AttributeNotes
appVersion, osVersionCompared as versions with < ≤ > ≥
buildCompared numerically
locale, language, region, deviceFrom the device
userId, email, paymentMonthlyFrom ShipKit.identify
attr.<name>Custom attributes you pass to identify
segmentSaved audiences
flag.<key>Another flag's value, for prerequisites

Feedback

ShipKit never asks users for feedback on its own. You place the entry points where people look for help:

Section("Support") {
    ShipKit.FeedbackLink()        // opens the feedback form
    ShipKit.FeedbackInboxLink()   // their conversations, with an unread badge
    ShipKit.RequestBoardLink()    // feature request board
}

// Or from your own button
.sheet(isPresented: $showFeedback) { ShipKit.FeedbackView(category: .bug) }

The form has a category, an optional 1–5 star rating, a message, optional email and screenshots with a redaction tool. App version, device, OS, locale and the user's current flag values are attached. Submissions are queued offline.

Replies you send from the dashboard show up in the user's inbox. Mark a thread fixed in a version and the user sees it in the app and in their next update reminder. Similar reports are grouped automatically, and a spike in reports about one topic raises an alert.

Shake to report is available and off by default: ShipKit.config.feedback.shakeToReport = true.

Ratings

ShipKit.RatingRow(feature: "new_editor")

A static thumbs up/down row you place in your UI, plus the optional stars in the feedback form. Ratings are private to you and never sent to the App Store. The dashboard shows them by day, version, feature, platform, paying vs free, and flag variant.

Feature requests

Users post and vote on ideas. New posts stay hidden until you approve them. Sort by votes or by the monthly revenue of voters, merge duplicates, comment publicly, and set a status. When you mark a request done in a version, voters on older versions see it in their update reminder.

Store reviews

Set the App Store ID in project settings and ShipKit imports recent reviews hourly from the public App Store feed for the countries you choose. Connect an App Store Connect API key (Customer Support role) under Webhooks & stores to import through the API and reply from the dashboard. 1–2 star reviews can be sent to Slack or Discord, and the release summary lists the most common complaint and praise terms per version.

Push campaigns

Send a push to ask users a question, invite them to send feedback, or announce something. Campaigns are written and targeted in the dashboard and delivered through APNs with your own key.

Set up

  1. In the Apple Developer portal create a key with Apple Push Notifications service (APNs). Add the Team ID, Key ID, bundle ID and the .p8 file under Push campaigns → Setup. ShipKit checks the key with Apple right away.
  2. Turn on the Push Notifications capability in Xcode.
  3. Forward the device token and let ShipKit handle its notifications:
final class AppDelegate: NSObject, UIApplicationDelegate {
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions options: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
        UNUserNotificationCenter.current().delegate = ShipKit.notificationDelegate
        return true
    }

    func application(_ application: UIApplication,
                     didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        ShipKit.setPushToken(deviceToken)
    }
}

// SwiftUI app
@UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

Already have a notification delegate? Forward to ShipKit and keep handling your own pushes:

func userNotificationCenter(_ center: UNUserNotificationCenter,
                            didReceive response: UNNotificationResponse,
                            withCompletionHandler completionHandler: @escaping () -> Void) {
    if ShipKit.handleNotificationResponse(response, completionHandler: completionHandler) { return }
    // your own handling, then:
    completionHandler()
}

func userNotificationCenter(_ center: UNUserNotificationCenter,
                            willPresent notification: UNNotification,
                            withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
    completionHandler(ShipKit.notificationPresentationOptions(for: notification) ?? [.banner, .sound])
}

Use the completion-handler forms of these two methods, not the async ones: with the async forms iOS finishes off the main thread and the app is terminated when someone answers from a notification while it is open.

Asking for permission

ShipKit never asks for notification permission by itself. Call await ShipKit.requestPushPermission() at a moment that makes sense in your app, for example after a user finishes onboarding. If you already ask for permission yourself, just forward the token.

Letting users opt out

Apple requires a way to opt out of promotional pushes inside the app (App Review Guideline 4.5.4). Drop ShipKitPushAsksToggle() into your settings screen. It shows a “Questions from the developer” switch; users who turn it off are skipped by every campaign, while your own transactional pushes are unaffected.

Campaign types

Audience and limits

Pick users with the same conditions as flags (app version, language, region, device, custom attributes, segments), plus recent activity, their in-app rating and whether they have sent feedback. Send to a percentage or cap the number of devices, check the estimate, and send a test to your own device first. A frequency cap (default: one campaign per user every 7 days) protects users from too many pushes. Send now or schedule; scheduled campaigns start within 15 minutes of the chosen time.

Results show delivery, opens and answers per campaign and per app version. Devices Apple reports as gone are removed automatically.

Never use push to ask for App Store ratings or to offer something in exchange for an answer. ShipKit keeps answers private to your team.

Identifying users

ShipKit.identify(
    userID: "u_123",
    email: "ana@example.com",
    name: "Ana",
    paymentMonthly: 9.99,
    attributes: ["plan": "pro", "beta": true]
)

All parameters are optional. Identified users keep their rollout buckets and their feedback across devices.

Signed config

Every config response is signed with an Ed25519 key unique to your project. Set options.signingKey to the public key from the Integration page and the SDK rejects responses that do not verify, so a proxy cannot strip a forced update.

Privacy

No advertising identifiers and no tracking. The install ID is a random UUID kept in the keychain. Version check-ins are sent at most once a day and stored with a hashed ID. Owners can delete all data for a user from the Users page. The package ships a privacy manifest.

App Store privacy labels

Adding ShipKit means updating your app's privacy answers in App Store Connect (App Privacy). The privacy manifest feeds Xcode's privacy report, but App Store Connect does not read it, so you fill in the answers yourself. To see the manifests of every package in your app, open an archive in the Organizer, right-click it and choose Generate Privacy Report.

Declare the rows for the features you use. npx @shipkit-cloud/cli privacy ./MyApp reads your project and prints the answers for the features it finds.

WhenData typeLinked to the userPurposes
Always (the install ID is sent with every config refresh; the APNs token too if you use push)Identifiers → Device IDNo¹App Functionality, Analytics²
Telemetry on (the default: a daily version check-in and flag exposure counts), ratings, or push campaigns (opens and answers)Usage Data → Product InteractionNo¹App Functionality, Analytics
Feedback form or feature requestsUser Content → Customer SupportYes with the email field³, otherwise No¹App Functionality
Screenshots attached to feedback (attachScreenshot, on by default)User Content → Photos or VideosYes with the email field³, otherwise No¹App Functionality
Email field in feedback or requests (asksForEmail, on by default), or identify(email:)Contact Info → Email AddressYesApp Functionality
identify(userID:)Identifiers → User IDYesApp Functionality
identify(name:)Contact Info → NameYesApp Functionality
identify(paymentMonthly:)Purchases → Purchase HistoryYesApp Functionality

¹ If you call identify(userID:) or identify(email:), ShipKit ties the install, its usage and its feedback to that user, so answer Yes for every row.

² With options.telemetry = .off, Device ID is used for App Functionality only and Product Interaction drops out unless you use ratings or push.

³ The optional email field lets people attach their address to a thread. Set ShipKit.config.feedback.asksForEmail = false to remove it.

Answer No to tracking for every row. ShipKit does not use advertising identifiers, does not share data with data brokers and does not combine your data with other companies' data.

Since 1.1.1 the package's privacy manifest marks every data type as linked, because each one can be once you identify users. Xcode's privacy report therefore shows the most your app could collect through ShipKit; your App Store Connect answers follow the table above.

Your answers cover your whole app, not just ShipKit. Update them before you submit the first build that includes ShipKit.

Management API

For CI, release scripts and developer tools. Create management keys (skm_…) on the Integration page. Each key belongs to one environment and is either read only or read and write. Changes publish right away; add ?publish=false to keep them in the draft. Send X-Actor to label calls in the audit log. Limit: 120 requests per minute per key.

CallAccess
GET /mgmt/v1/whoami, GET /mgmt/v1/auditread
GET /mgmt/v1/version-policy, GET /mgmt/v1/versionsread
PATCH /mgmt/v1/version-policywrite
GET /mgmt/v1/flags[/:key], GET /mgmt/v1/settings[/:key]read
POST /mgmt/v1/flags, PUT /mgmt/v1/flags/:key, POST /mgmt/v1/settings, PUT /mgmt/v1/settings/:keywrite
GET /mgmt/v1/releases[/:version], GET /mgmt/v1/draft, POST /mgmt/v1/previewread
POST /mgmt/v1/publish, POST /mgmt/v1/rollbackwrite
GET /mgmt/v1/feedback[/:id], GET /mgmt/v1/summary, GET /mgmt/v1/ratings, GET /mgmt/v1/reviews, GET /mgmt/v1/requestsread
POST /mgmt/v1/feedback/:id/messages, PATCH /mgmt/v1/feedback/:id, PATCH /mgmt/v1/requests/:idwrite

POST /mgmt/v1/preview takes {"context": {...}, "source": "published" | "draft"} and returns the snapshot that user would get. Version policy changes that need approval return 202 with a change request to approve in the dashboard.

# .github/workflows/release.yml (excerpt)
- name: Recommend the new version
  run: |
    curl -fsS -X PATCH https://YOUR-WORKER/mgmt/v1/version-policy \
      -H "Authorization: Bearer ${{ secrets.SHIPKIT_MGMT_KEY }}" \
      -H "X-Actor: github-actions" \
      -H "Content-Type: application/json" \
      -d "{\"latest\": \"$VERSION\", \"recommended\": \"$VERSION\"}"

CLI and MCP server

The shipkit command sets up the SDK and wraps the management API for your terminal and scripts, and shipkit mcp serves the same tools to any MCP client over stdio. Requires Node 20 or later.

Guided setup

npx @shipkit-cloud/cli login              # opens the dashboard to approve this machine
npx @shipkit-cloud/cli inspect ./MyApp    # package, configure call, bundle ID, leaked keys
npx @shipkit-cloud/cli guide ./MyApp      # setup steps with your keys filled in
npx @shipkit-cloud/cli privacy ./MyApp    # App Store privacy answers

login shows a code and opens the dashboard. Check the code, pick the project (or create one with your app's bundle ID) and choose read-only or read and write. It saves one management key per environment to ~/.config/shipkit/config.json (readable only by you). Only owners can approve. On a machine without a browser, open the printed link anywhere you are signed in.

guide covers the Swift package (Xcode, Package.swift, XcodeGen or Tuist), a ShipKitKeys.swift file that uses the Staging key in Debug builds and the Production key in Release (--xcconfig for build settings instead), the configure call and code for the features your project uses. Client keys and the signing key are public. Management keys, APNs keys and App Store Connect keys never go in the app or the repo; inspect flags any it finds.

Managing config

npx @shipkit-cloud/cli flags                   # list flags
npx @shipkit-cloud/cli flags on new_onboarding # shows a dry run, then asks
npx @shipkit-cloud/cli preview --app-version 2.3.0 --locale de_DE --draft
npx @shipkit-cloud/cli publish -m "Spring sale"

Every change prints a dry run first; pass --yes in scripts and --no-publish to keep it in the draft. Use --env staging to target another saved environment. In CI, set SHIPKIT_KEY (or login --key skm_...) with a key from the Integration page instead of signing in. npm install -g @shipkit-cloud/cli gives you a plain shipkit command.

MCP server

Add this to your MCP client's server config. It uses the keys saved by login; without any, it starts with setup tools only and offers browser sign-in itself.

{
  "mcpServers": {
    "shipkit": {
      "command": "npx",
      "args": ["-y", "@shipkit-cloud/cli", "mcp"]
    }
  }
}

Setup tools: start_login and complete_login (browser sign-in), get_sdk_credentials, inspect_app_project, get_setup_guide, get_privacy_labels and verify_integration (checks that the app's first check-in arrived). The setup_shipkit prompt runs them in order. Project files are only read locally; nothing from your project is uploaded.

Management tools cover flags, settings, version policy, releases, feedback, ratings, reviews and feature requests. Read tools are marked read-only. Write tools return a dry run (for version policy changes, how many active installs are affected) and apply only when called again with confirm: true. With read-only keys, write tools are not offered at all. Calls appear in the audit log under the key's name. To pass keys directly, add "env": { "SHIPKIT_KEYS": "production=skm_...,staging=skm_..." }, but keep that config out of your repo.

Client API

The SDK talks to these endpoints. You only need them to build your own client.

EndpointPurpose
POST /v1/snapshotResolved settings, flags and version status for a context. Supports If-None-Match.
POST /v1/eventsDaily version check-in and flag exposure counts
POST /v1/identifyUser details and custom attributes
POST /v1/uploads, GET /v1/uploads/:idScreenshots (JPEG/PNG, 5 MB)
POST /v1/feedback, GET /v1/feedback/threads[/:id], POST …/messagesFeedback threads
POST /v1/ratings, GET /v1/ratings/mineRatings
GET/POST /v1/requests, POST/DELETE …/vote, GET/POST …/commentsFeature requests

Every request sends Authorization: Bearer skc_… and X-ShipKit-Stable-Id. Errors look like {"error": {"code", "message"}}.