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 --> test-support(Write tests) push --> test-support rich-push --> test-support 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 test-support href "/docs/sdk/ios/test-support" style getting-started fill:#B5FFEF,stroke:#007069 style B fill:#B5FFEF,stroke:#007069

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 customer.io.

sequenceDiagram participant A as Mobile User participant B as SDK participant C as Customer.io 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 Customer.io, 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 Customer.io. You can also send the identified person messages from Customer.io.

You send messages to a person through the Customer.io 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 Customer.io and receive a message payload.

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 ProductRequired?Description
Trackingidentify people in Customer.io
MessagingPushAPNReceive push notifications over Apple’s Push Notification Service (APNs)
MessagingPushFCMReceive push notifications over Google Firebase Cloud Messaging (FCM)

Install the SDK

Follow Apple’s instructions to add https://github.com/customerio/customerio-ios.git as a dependency to your project in Xcode and select the individual package products that you want to install.

We recommend that you set the Dependency Rule to Up to Next Major Version. While we encourage you to keep your app up to date with the latest SDK, major versions can include breaking changes or new features that require your attention.

select up to next major version when installing the sdk
select up to next major version when installing the sdk

Install with CocoaPods

We typically recommend that you install the SDK using Swift Package Manager (SPM). However, if your app uses CocoaPods, you can find and install our pods by appending CustomerIO/ to our packages—e.g. CustomerIO/Tracking.

Package ProductRequired?Description
CustomerIO/Trackingidentify people in Customer.io
CustomerIO/MessagingPushAPNReceive push notifications over Apple’s Push Notification Service (APNs)
CustomerIO/MessagingPushFCMReceive push notifications over Google Firebase Cloud Messaging (FCM)

Initialize the SDK

Before you can use the Customer.io 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).

Singleton

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

  1. To get started, initialize the SDK. You’ll usually do this 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.

    CustomerIO.shared.track(...)
    MessagingPush.shared.application(...)
    

 Check out our sample app!

Our Remote Habits app, provides a real-world example and can act as a template to help you implement the SDK.

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 the singleton instance

In general, our code samples use shared singleton 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: "YOUR SITE ID", apiKey: "YOUR API KEY")
     // You can optionally provide a Region to set the Region for your Workspace:
     let customerIO = CustomerIO(siteId: "YOUR SITE ID", apiKey: "YOUR API KEY", region: Region.EU)
    
  2. When you want to use SDK features, use the shared instance of the class.

     let customerIO = CustomerIO(siteId: "YOUR SITE ID", apiKey: "YOUR API KEY")
     customerIO.track(...)
    
     let messagingPush = MessagingPush(customerIO: customerIO)
     messagingPush.application(...)
    

The Processing Queue

The SDK automatically adds all calls to a queue system, and performs these calls when certain criteria is met. This queue makes things easier, both for you and your users: it handles errors and retries for you (even when users lose connectivity), and it saves users' battery life by batching requests.

The queue holds requests until any one of the following criteria is met:

  • There are 10 or more tasks in the queue.
  • 30 seconds have passed since the SDK performed its last task.
  • The app is closed and re-opened.

For example, when you identify a new person in your app using the SDK, you won’t see the created/updated person immediately. You’ll have to wait for the SDK to meet any of the criteria above before the SDK sends a request to the Customer.io API. Then, if the request is successful, you’ll see your created/updated person in your workspace.

How the queue organizes tasks

The SDK typically runs tasks in the order that they were called—unless one of the tasks in the queue fails.

Tasks in the queue are grouped by “type” because some tasks need to run sequentially. For example, you can’t invoke a track call if an identify call hasn’t succeeded first. So, if a task fails, the SDK chooses the next task in the queue depending on whether or not the failed task is the first task in a group.

  • If the failed task is the first in a group: the SDK skips the remaining tasks in the group, and moves to the next task outside the group.
  • If the failed task is 1+n task in a group: the SDK skips the failed task and moves on to the next task in the group.**

The following chart shows how the SDK would process a queue where tasks A, B, and C belong to the same group.

flowchart TD a["Task inventory
[A, B, C], D"]-->b{Is task A
successful} b-.->|Yes|c[Continue to task B] b-.->|No|d[Skip to task D] c-.->|Whether task B
succeeds or fails|E[Continue to task C]
Copied to clipboard!