Get Started

Before you can take advantage of our SDK, you need to install the module(s) you want to use, initialize the SDK, and understand the order of operations.

This page is part of an introductory series to help you get started with the essential features of our SDK. The highlighted step(s) below are covered on this page. Before you continue, make sure you've implemented previous features—i.e. you can't identify people before you initialize the SDK!

graph LR getting-started(Install SDK) -->B(Initialize SDK) B --> identify(identify people) identify -.-> track-events(Send events) identify -.-> push(Receive push) identify -.-> rich-push(Receive Rich Push) track-events --> testing-error-handling(handle errors) push --> testing-error-handling rich-push --> testing-error-handling click getting-started href "/docs/sdk/ios/getting-started" click B href "/docs/sdk/ios/getting-started/#initialize-the-sdk" click identify href "/docs/sdk/ios/identify" click track-events href "/docs/sdk/ios/track-events/" click push href "/docs/sdk/ios/push" click rich-push href "/docs/sdk/ios/rich-push" click testing-error-handling href "/docs/sdk/ios/testing-error-handling" style getting-started fill:#B5FFEF,stroke:#007069 style B fill:#B5FFEF,stroke:#007069

Before you begin

If you want to try out our new SDKs, contact!

Before you begin, you should understand that our SDK is in alpha and is subject to change. We're excited about it—and we hope you are too—but it is still a work in progress.

The SDK has only been tested on iOS devices. It might work on other Apple devices—macOS, tvOS, and watchOS—but we have not officially tested, nor do we officially support, non-iOS devices.

SDK package products

To minimize our SDK’s impact on your app’s size, we offer multiple, separate SDKs. You should only install the packages that you need for your project.

You must install the Tracking package. It lets you identify people, which you must do before you can send them messages, track their events, etc.

Package Product Required? Description
Tracking Lets you identify people in
MessagingPushAPIN Lets you receive push notifications

How it works

Our SDKs provide a ready-made integration to identify people who use mobile devices and send them notifications. Before you start using the SDK, you should understand a bit about how the SDK works with

sequenceDiagram participant A as Mobile User participant B as SDK participant C as A--xB: User activity
user not identified A->>B: Logs in (identify method) rect rgb(229, 254, 249) Note over A,C: Now you can Send events and receive messages B-->>C: Person added/updated in CIO A->>B: User activity (track event) B->>C: Event triggers campaign C->>B: Campaign triggered push B->>A: Display push A->>B: Logs out (stopIdentify method) end A--xB: No longer sending events or receiving messages

You must identify a person before you can take advantage of most SDK features. We don’t currently support messages or events for anonymous devices/users, which means that we can’t track or respond to anything your audience does in your app until you identify them.

In, you identify people by id or email, which typically means that you need someone to log in to your app or service before you can identify them.

While someone is “identified”, you can send events representing their activity in your app to You can also send the identified person messages from

You send messages to a person through the campaign builder, broadcasts, etc. These messages are not stored on the device side. If you want send an event-triggered campaign to a mobile device, the mobile device user must be identified and have a connection such that it can send an event back to and receive a message payload.

Install the SDK

You’ll find detailed instructions to install our SDK in our Github repository.

  1. In Xcode, go to File > Swift Packages > Add Package Dependency. Enter the iOS SDK’s GitHub repository:

  2. Select the version that you want to install. While the SDK is its alpha stage, we recommend that you install an exact version of the SDK instead of indicating a range. This prevents you from automatically upgrading to a newer alpha version and possibly installing breaking changes on your code base.

    Select the specific version of SDK packages you want to install
    Select the specific version of SDK packages you want to install

  3. Choose the SDK products that you want to install. You must install the Tracking package to take advantage of other SDK features.

    Select the specific packages you want to install
    Select the specific packages you want to install

Initialize the SDK

Before you can use the SDK, you need to initialize it. Any calls that you make to the SDK before you initialize it are ignored.

There are two ways to initialize the SDK. The method you use depends on how you want to use the SDK:

  • Using a Singleton, shared instance (the quick and easy way).
  • Creating your own instances (which is better for projects using automated tests).


When you use the shared instance, you don’t need to manage your own instances of SDK classes.

  1. To get started, initialize the SDK in the AppDelegate application(_ application: didFinishLaunchingWithOptions) function.

     import CioTracking
     class AppDelegate: NSObject, UIApplicationDelegate {
         func application(
             _ application: UIApplication,
             didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
         ) -> Bool {
             CustomerIO.initialize(siteId: "YOUR SITE ID", apiKey: "YOUR API KEY")
             // You can optionally provide a Region to set the Region for your Workspace:
             CustomerIO.initialize(siteId: "YOUR SITE ID", apiKey: "YOUR API KEY", region: Region.EU)
             return true
  2. When you want to use any of the SDK features, you use the shared instance of the class.


Create your own instances

We recommend that you create your own instances of SDK classes if your project has automated tests. We designed the SDK with first-class support for dependency injection and mocking, which makes it easier to write automated tests. See testing for more information.

 Our code samples use Singleton methods

In general, our code samples use shared instance methods to call the SDK. These samples should also work with your own instances of SDK classes.
  1. Create the instance.

     import CioTracking
     let customerIO = CustomerIO(siteId: "XXX", apiKey: "YYY")
     // You can optionally provide a Region to set the Region for your Workspace:
     let customerIO = CustomerIO(siteId: "XXX", apiKey: "YYY", region: Region.EU)
  2. When you want to use SDK features, use the shared instance of the class:

     let messagingPush = MessagingPush(customerIO: customerIO)
Copied to clipboard!