The Swift SDK

The Swift SDK, CMSOrbit, reads published content from the delivery API in iOS, iPadOS, macOS, tvOS and watchOS apps, and in server-side Swift. It does what the client in the JavaScript SDK does: pages, redirects, menus, site-wide content, lists, banners, popups, products, sitemaps and the schema, with the same retries and errors. It is open source under the MIT licence.

• Built on async/await and URLSession, with no other dependencies.
• Safe under Swift 6 strict concurrency: the client and every model are Sendable.
• Every answer has a Codable model. Fields you have not typed yet arrive as a JSONValue, and you can decode them into your own types at any time.

Install

It needs Swift 5.9 or later, and iOS 15, macOS 12, tvOS 15 or watchOS 8 or later.

In Xcode, choose File › Add Package Dependencies… and enter https://github.com/bifrost-orbit/cms-sdk-swift. In a Package.swift:

1dependencies: [2    .package(url: "https://github.com/bifrost-orbit/cms-sdk-swift", from: "0.1.0"),3],4targets: [5    .target(name: "App", dependencies: [.product(name: "CMSOrbit", package: "cms-sdk-swift")]),6]

Set up

Create a public key in Configuration › API keys. It starts with cms_pk_ and reads published content only, so it may ship in an app.

1import CMSOrbit23let cms = try CMSOrbitClient(4    apiKey: "cms_pk_...",5    region: "germany",6    locale: "de-DE"7)89let page = try await cms.page("/products/hiking-boots")

Create one client and share it across the app.

Methods

Most calls take CMSRequestOptions: region, locale, strict to refuse every fallback, includeReferences to replace Reference fields' ids with the entries, and preview. Anything left out uses the client's defaults.

Call resolve before showing an address, so redirects and removed pages behave correctly:

1switch try await cms.resolve("/offers/winter") {2case .page(let page): show(page)3case .redirect(let redirect): open(redirect.to)4case .gone, .notFound: showNotFound()5}

page.meta compares what answered with what was asked for. When page.meta.fallbackApplied is true, another language answered, so the app can say "This page is not available in English yet." See Regions and languages.

To read another region or language than the client's defaults, or to refuse every fallback:

1let page = try await cms.page(2    "/products/hiking-boots",3    options: CMSRequestOptions(region: "ch", locale: "fr-CH", strict: true)4)

Menus and site-wide content are read by their key:

1let header = try await cms.navigation("header")2for item in header.items {3    print(item.label, item.href ?? "", item.children.count)4}56let footer = try await cms.global("footer")7let copyright = footer.fields["copyright"]?.stringValue

Lists take the same filters as the API:

1let products = try await cms.list(CMSListOptions(2    type: "product",3    include: [.fields],4    filter: ["activity": "hiking"],5    sort: .publishedAtDescending6))

A list has items, total, page and hasMore. perPage is 20 by default and at most 100, so ask for the next page while hasMore is true.

Your own types

Fields arrive as JSONValue, which you can read straight away with page.fields["title"]?.stringValue. For type safety, write Decodable structs. The SDK's models, such as CMSImage, CMSLink, CMSComponent and CMSReference, decode inside them.

1struct PageFields: Decodable, Sendable {2    var title: String3    var heroImage: CMSImage?4}56let fields = try page.fields(as: PageFields.self)

Each component type gets a struct conforming to CMSBlockFields, which names the component's key:

1struct HeroBlock: CMSBlockFields {2    static let blockType = "hero"3    var heading: String4    var image: CMSImage?5    var link: CMSLink?6}

block.decode(HeroBlock.self) gives the fields when the block is a hero, and nil for any other type. Reference fields hold entry ids; read with includeReferences: true and type them as CMSReference<FaqEntry>, which is either .id or .entry. See Field types for what each field type arrives as.

Generate types

Instead of writing the structs yourself, let the type generator in the JavaScript package write them from your space's schema: one Codable struct per component and content type. Run it with Node 20 or later whenever the schema changes:

npx --package @bifrost-orbit-cms/sdk cms-orbit generate --lang swift --out Sources/App/CMSTypes.swift

It reads CMS_API_URL and CMS_PUBLIC_KEY, or --url and --key. Add --include references if you load references with include.

Components in SwiftUI

A page's body is page.components: each block has an id, type, fields, children (the blocks in each slot) and variant. Switch on the type, and draw nothing for types the app does not know yet, so a new component in the CMS never breaks the app:

1struct BlockView: View {2    let block: CMSComponent34    var body: some View {5        if let hero = try? block.decode(HeroBlock.self) {6            HeroView(hero: hero)7        } else if let grid = try? block.decode(CardGridBlock.self) {8            CardGridView(grid: grid, cards: block.children["cards"] ?? [])9        } else {10            EmptyView()11        }12    }13}1415struct PageView: View {16    let page: CMSPage1718    var body: some View {19        ScrollView {20            LazyVStack(spacing: 24) {21                ForEach(page.components) { BlockView(block: $0) }22            }23        }24        .navigationTitle(page.name)25    }26}

• image.url(width: 1280) asks the CMS for a resized copy of an uploaded image, so the app never downloads the original.
• Rich text arrives as HTML. Show it with AttributedString or a web view.
• Blocks in a slot arrive both in block.children[slot] and on the slot's field.

See Render components for how pages are built from components.

Insights Orbit

When the space is connected to Insights Orbit under Settings, each page carries id, the entry's id, and insights, a CMSInsightsSite with the site key, or nil. Both are nil from an older CMS Orbit.

In server-side Swift that renders HTML, CMSInsights.tags writes the Insights Orbit script with the site key and <meta name="insights-content"> with the entry's id, so the page's numbers follow it when its address changes. Without a site key it answers with an empty string:

let head = CMSInsights.tags(page: page)// or with your own key and a first-party address:let head = CMSInsights.tags(page: page, site: "SITE_KEY", src: "/stats/script.js", api: "/stats/collect")

contentId tags page views with another entry, disable switches off automatic events, such as ["scroll"], and campaigns: false stops counting elements marked with data-banner or data-popup. Insights Orbit counts websites, so an app has no use for the script.

Preview

The CMS editor opens your website with ?preview= and a token for one page's draft. If a preview link opens your app, for example as a universal link, read the token and ask which entry it is for. This needs no secret key:

1if let token = CMSOrbitClient.previewToken(from: url) {2    let session = try await cms.verifyPreview(token: token)3    print(session.name, session.url ?? "")4}

Tokens last an hour, and an invalid or expired one throws .unauthorized. session.draft is the editor's saved draft as the CMS stores it, with image ids rather than images.

Reading drafts through the delivery API needs a secret key, which must never be inside an app. In server-side Swift on macOS or Linux, give the client a previewKey and pass CMSRequestOptions(preview: true). An app that needs to show drafts should ask your own server, which holds the key. Secret keys exist for staging environments only. See Keys, permissions and sign-in.

Errors

Every call throws CMSOrbitError, or CancellationError when its task is cancelled.

Every error has status, the HTTP status when there was one, and code, such as not_found or rate_limited.

Connection failures and server errors are retried twice, after 250 and 750 milliseconds, and each attempt times out after 5 seconds. Other errors, including 429, are not retried, so wait retryAfter seconds before asking again:

1do {2    show(try await cms.page(path))3} catch CMSOrbitError.notFound {4    showNotFound()5} catch CMSOrbitError.rateLimited(let retryAfter, _) {6    try await Task.sleep(nanoseconds: UInt64(retryAfter * 1_000_000_000))7    show(try await cms.page(path))8} catch CMSOrbitError.unavailable, CMSOrbitError.server {9    showOfflineCopy()10}

Each key may make 15,000 requests a minute. See Rate limits in the delivery API.

Caching

The client does not keep answers itself. Published answers carry Cache-Control with s-maxage, which is meant for shared caches such as a CDN, so URLSession's own cache should not be relied on to keep them. Keep what the app shows in memory or on disk, show it straight away on the next launch, and read it again when the app returns to the foreground. Drafts are always read fresh. See Caching in the delivery API and Caching and refreshing pages.

Testing

Pass a URLSession whose configuration lists your own URLProtocol in protocolClasses, and answer each request with JSON shaped like the delivery API's answers. The SDK's own tests work this way.