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 and the repository URL you were given, then add the ShipKit library to your app target. Requires iOS 16 or later.

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.

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.

Management API

For CI and scripts. Create a management key (skm_…) per environment on the Integration page. Every call publishes immediately.

CallBody
GET /mgmt/v1/version-policy—
PATCH /mgmt/v1/version-policy{"min","minBuild","recommended","latest","maintenance"}
PUT /mgmt/v1/flags/:key{"enabled": true}
PUT /mgmt/v1/settings/:key{"value": …}
POST /mgmt/v1/publish{"note"}
# .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\"}"

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"}}.