Shopify Checkout Kit - Swift

Shopify Checkout Kit is a Swift Package library that enables Swift apps to provide the world’s highest converting, customizable, one-page checkout within the app. The presented experience is a fully-featured checkout that preserves all of the store customizations: Checkout UI extensions, Functions, branding, and more. It also provides platform idiomatic defaults such as support for light and dark mode, and convenient developer APIs to embed, customize, and follow the lifecycle of the checkout experience. Check out our blog to learn how and why we built the Checkout Kit.

Note: We're in the process of renaming "Checkout Sheet Kit" to "Checkout Kit." The dev docs and README already use the new name, while the package itself will be updated in an upcoming version.

• Requirements
• Getting Started
  • Package.swift
  • Xcode
  • CocoaPods
• Programmatic Usage
• SwiftUI Usage
• Configuration
  • colorScheme
  • tintColor
  • backgroundColor
  • title
  • closeButtonTintColor
  • SwiftUI Configuration
• Preloading
  • Important considerations
  • Flash Sales
  • When to preload
  • Cache invalidation
  • Lifecycle management for preloaded checkout
  • Additional considerations for preloaded checkout
• Monitoring the lifecycle of a checkout session
  • Integrating with Web Pixels, monitoring behavioral data
• Error handling

Requirements

• Swift 5.7+
• iOS 13.0+ for Checkout Sheet, iOS 16+ for Accelerated Checkouts

Getting Started

The SDK is an open-source Swift Package library. As a quick start, see sample projects or use one of the following ways to integrate the SDK into your project:

Package.swift

dependencies: [
  .package(url: "https://github.com/Shopify/checkout-sheet-kit-swift", from: "3")
]

Xcode

1. Open your Xcode project
2. Navigate to File > Add Package Dependencies...
3. Enter https://github.com/Shopify/checkout-sheet-kit-swift into the search box
4. Click Add Package

For more details on managing Swift Package dependencies in Xcode, please see Apple's documentation.

CocoaPods

pod "ShopifyCheckoutSheetKit", "~> 3"

For more information on CocoaPods, please see their getting started guide.

Programmatic Usage

Once the SDK has been added as a dependency, you can import the library:

import ShopifyCheckoutSheetKit

To present a checkout to the buyer, your application must first obtain a checkout URL. The most common way is to use the Storefront GraphQL API to assemble a cart (via cartCreate and related update mutations) and load the checkoutUrl. Alternatively, a cart permalink can be provided. You can use any GraphQL client to obtain a checkout URL and we recommend Shopify's Mobile Buy SDK for iOS to simplify the development workflow:

import Buy

let client = Graph.Client(
  shopDomain: "yourshop.myshopify.com",
  apiKey: "<storefront access token>"
)

let query = Storefront.buildQuery { $0
  .cart(id: "myCartId") { $0
    .checkoutUrl()
  }
}

let task = client.queryGraphWith(query) { response, error in
  let checkoutURL = response?.cart.checkoutUrl
}
task.resume()

The checkoutURL object is a standard web checkout URL that can be opened in any browser. To present a native checkout sheet in your application, provide the checkoutURL alongside optional runtime configuration settings to the present(checkout:) function provided by the SDK:

import UIKit
import ShopifyCheckoutSheetKit

class MyViewController: UIViewController {
  func presentCheckout() {
    let checkoutURL: URL = // from cart object
    ShopifyCheckoutSheetKit.present(checkout: checkoutURL, from: self, delegate: self)
  }
}

SwiftUI Usage

import SwiftUI
import ShopifyCheckoutSheetKit

struct ContentView: View {
  @State var isPresented = false
  @State var checkoutURL: URL?

  var body: some View {
    Button("Checkout") {
      isPresented = true
    }
    .sheet(isPresented: $isPresented) {
      if let url = checkoutURL {
        CheckoutSheet(url: url)
           /// Configuration
           .title("Checkout")
           .colorScheme(.automatic)
           .tintColor(.blue)
           .backgroundColor(.white)
           .closeButtonTintColor(.red)

           /// Lifecycle events
           .onCancel {
             isPresented = false
           }
           .onComplete { event in
             handleCompletedEvent(event)
           }
           .onFail { error in
             handleError(error)
           }
           .onPixelEvent { event in
             handlePixelEvent(event)
           }
           .onLinkClick { url in
              if UIApplication.shared.canOpenURL(url) {
                UIApplication.shared.open(url)
              }
           }
           .edgesIgnoringSafeArea(.all)
      }
    }
  }
}

[!TIP] To help optimize and deliver the best experience, the SDK also provides a preloading API which can be used to initialize the checkout session ahead of time.

Configuration

The SDK provides a way to customize the presented checkout experience via the ShopifyCheckoutSheetKit.configuration object.

colorScheme

By default, the SDK will match the user's device color appearance. This behavior can be customized via the colorScheme property:

// [Default] Automatically toggle idiomatic light and dark themes based on device preference (`UITraitCollection`)
ShopifyCheckoutSheetKit.configuration.colorScheme = .automatic

// Force idiomatic light color scheme
ShopifyCheckoutSheetKit.configuration.colorScheme = .light

// Force idiomatic dark color scheme
ShopifyCheckoutSheetKit.configuration.colorScheme = .dark

// Force web theme, as rendered by a mobile browser
ShopifyCheckoutSheetKit.configuration.colorScheme = .web

tintColor

If the checkout session is not ready and being initialized, a progress bar is shown and can be customized via the tintColor property:

// Use a custom UI color
ShopifyCheckoutSheetKit.configuration.tintColor = UIColor(red: 0.09, green: 0.45, blue: 0.69, alpha: 1.00)

// Use a system color
ShopifyCheckoutSheetKit.configuration.tintColor = .systemBlue

Note: use preloading to optimize and deliver an instant buyer experience.

backgroundColor

While the checkout session is being initialized, the background color of the view can be customized via the backgroundColor property:

// Use a custom UI color
ShopifyCheckoutSheetKit.configuration.backgroundColor = UIColor(red: 0.09, green: 0.45, blue: 0.69, alpha: 1.00)

// Use a system color
ShopifyCheckoutSheetKit.configuration.backgroundColor = .systemBackground

title

By default, the Checkout Kit will look for a shopify_checkout_sheet_title key in a Localizable.xcstrings file to set the sheet title, otherwise it will fallback to "Checkout" across all locales.

The title of the sheet can be customized by either setting a value for the shopify_checkout_sheet_title key in the Localizable.xcstrings file for your application or by configuring the title property of the ShopifyCheckoutSheetKit.configuration object manually.

// Hardcoded title, applicable to all languages
ShopifyCheckoutSheetKit.configuration.title = "Custom title"

Here is an example of a Localizable.xcstrings containing translations for 2 locales - en and fr.

{
  "sourceLanguage": "en",
  "strings": {
    "shopify_checkout_sheet_title": {
      "extractionState": "manual",
      "localizations": {
        "en": {
          "stringUnit": {
            "state": "translated",
            "value": "Checkout"
          }
        },
        "fr": {
          "stringUnit": {
            "state": "translated",
            "value": "Caisse"
          }
        }
      }
    }
  }
}

closeButtonTintColor

The color of the close button in the navigation bar can be customized via the closeButtonTintColor property. When set to a custom color, the close button will use a custom SF Symbol (xmark.circle.fill) with the specified tint color. When set to nil (default), the standard system close button appearance is used.

// Use a custom UI color
ShopifyCheckoutSheetKit.configuration.closeButtonTintColor = UIColor(red: 0.09, green: 0.45, blue: 0.69, alpha: 1.00)

// Use a system color
ShopifyCheckoutSheetKit.configuration.closeButtonTintColor = .systemRed

SwiftUI Configuration

Similarly, configuration modifiers are available to set the configuration of your checkout when using SwiftUI:

CheckoutSheet(checkout: checkoutURL)
  .title("Checkout")
  .colorScheme(.automatic)
  .tintColor(.blue)
  .backgroundColor(.black)
  .closeButtonTintColor(.red)

[!NOTE] Note that if the values of your SwiftUI configuration are variable and you are using preload(), you will need to call preload() each time your variables change to ensure that the checkout cache has been invalidated, for checkout to be loaded with the new configuration.

Preloading

Initializing a checkout session requires communicating with Shopify servers,