Getting Started with Catalyst iOS SDK

Table of Contents:

  1. Overview
  2. Prerequisites
  3. Setup


The Catalyst SDK for iOS is the easiest way to integrate your iOS app with Catalyst. It enables accessing various catalyst components in your iOS app.


  1. Install XCode 10.2 or later
  2. Open your project in XCode
    • Your Project target should be iOS 9 or later
    • Swift projects should use Swift 4.0 or later
  3. If your project uses Push notifications, you'll need
    • An apple developer account
    • A physical iOS device running iOS 9 or later


Create a Catalyst Project

Before adding Catalyst SDK to your iOS app, you will need to create a Catalyst project.

  1. In the Catalyst console, click Create New Project and enter a Project name in the pop-up window. Read and accept the terms and conditions, click Create.
  2. If you have an existing Catalyst project, you can access the same from the Catalyst home.
  3. Once your project has been created, click Access Project that redirects you to the home page of the project components.

Register your iOS app with Catalyst

After creating a Catalyst project, you can add your iOS app to it.

  1. From your Catalyst project home, click Settings located in the top right corner.
  2. In the Settings Page, select Developer Tools.
  3. Click the iOS option from the above screen which opens an iOS SDK pop-up window.
  4. Provide the Bundle Id , URL Schema and click Download. This will download Appconfiguration.plist and Catalyst.framework files which you will be using in your Xcode Project.
Note: Make sure that you enter the Bundle ID that your app is actually using.

Setup your XCode Project

Create a New Project in Xcode or open an existing project, and enter the same Bundle Identifier value used in the previous section.

Add the Catalyst SDK to your app

  1. Move the Appconfiguration.plist file(already downloaded) to the root of your Xcode project.
  2. From your project's root, select the General Tab located on the adjacent side.
  3. Drag and drop the Catalyst.framework(already downloaded) to the Embedded Binary Section of the General​ Tab.
Note: You can download these files any number of times, but make sure the config file or Catalyst.framework is not appended with additional characters, like (2) before adding to the XCode project.

Configure URL Scheme

In case, if you haven't configured URL Scheme on your info.plist, configure it as given below,

  1. In Xcode, right-click your project's Info.plist file and select Open As -> Source Code.
  2. Insert the following XML snippet into the body of your file just before the final </dict> element.
<key>CFBundleURLTypes</key> <array>
   <key>CFBundleURLSchems</key> <array>
   <string>{your- url scheme}</string>

In the above code snippet, replace the same Bundle-Identifier and your url schema which you used in the Catalyst project.

Initialize Catalyst in your App

To initialize Catalyst in your app,

  1. Open the AppDelegate.swift from your Xcode project directory.
  2. Import the Catalyst module in your UIApplicationDelegate:
    import Catalyst
  3. Configure a Catalyst instance, typically in your app's application:didFinishLaunchingWithOptions: method:
    // Use Catalyst to configure APIs