Track events
UpdatedThere's a new version available!
These pages cover version 2 of our SDK, but a newer version is available. In general, we suggest that you update to the latest version to take advantage of new features and fixes.
- Are you new to our SDKs? Check out the latest docs.
- Otherwise, learn about updating to the latest version
Events represent things people do in your app so that you can track your audience’s activity and metrics. Use events to segment your audience, trigger campaigns, and capture usage metrics in your app.
This page is part of a setup flow for the SDK. Before you continue, make sure you've implemented previous features—i.e. you can't send events before you identify people!
Device Token) register-token -.-> push(Receive push) register-token -.-> rich-push(Receive Rich Push) track-events --> test-support(Write tests) push --> test-support rich-push --> test-support identify -.-> in-app(Receive in-app) in-app --> test-support click getting-started href "/sdk/ios/getting-started/#install" click B href "/sdk/ios/getting-started/#initialize-the-sdk" click identify href "/sdk/ios/identify" click track-events href "/sdk/ios/track-events/" click register-token href "/sdk/ios/push" click push href "/sdk/ios/push" click rich-push href "/sdk/ios/rich-push" click in-app href "/sdk/ios/in-app" click test-support href "/sdk/ios/test-support" style track-events fill:#B5FFEF,stroke:#007069
Track a custom event
After you identify a person, you can use the track
method to send events representing their activities to Customer.io. When you send events, you can include event data
—information about the person or the event that they performed.
In Customer.io, you can use events to trigger campaigns and broadcasts. Those campaigns might send someone a push notification or manipulate information associated with the person in your workspace.
Events include the following:
name
: the name of the event. Most event-based searches in Customer.io hinge on the name, so make sure that you provide an event name that will make sense to other members of your team.data
(Optional): Additional information that you might want to reference in a message. You can reference data attributes in messages and other campaign actionsA block in a campaign workflow—like a message, delay, or attribute change. using liquidA syntax that supports variables, letting you personalize messages for your audience. For example, if you want to reference a person’s first name, you might use the variable{{customer.first_name}}
. in the format{{event.<attribute>}}
.
import CioTracking
CustomerIO.shared.track(name: "logged_in", data: ["ip": "127.0.0.1"])
// The `data` parameter can be optionally skipped
CustomerIO.shared.track(name: "played_game")
// `data` accepts [String: Any] or an `Encodable` object
// 1. [String: Any]:
let data = ["product": "socks", "price": "23.45"]
CustomerIO.shared.track(name: "purchase", data: data)
// 2. A custom `Encodable` type:
struct Purchase: Encodable {
let product: String
let price: Double
}
CustomerIO.shared.track(name: "purchase", data: Purchase(product: "socks", price: 23.45))
Screen view events
Screen views are events that record the pages that your audience visits in your app. They have a type
property set to screen
, and a name
representing the title of the screen or page that a person visited in your app.
Screen view events let you trigger campaignsA series of actions that you perform for each person who matches criteria. Campaigns typically send people a series of messages, but you can also use campaigns to send webhooks, update attributes, etc. or add people to segmentsA group of people who match a series of conditions. People enter and exit the segment automatically when they match or stop matching conditions. based on the parts of your app your audience uses. Screen view events also update your audience’s “Last Visited” attribute, which can help you track how recently people used your app.
Enable automatic screen tracking
When you enable automatic screen tracking, the SDK sends an event every time a person visits a screen in your UIKit-based app. You can turn on automatic screen tracking in the SDK’s configuration.
CustomerIO.initialize(...) { config in
config.autoTrackScreenViews = true
// Optional function to filter out certain view controllers from automatic screenview events.
// Setting your own function will skip the SDK's filtering logic.
config.filterAutoScreenViewEvents = { viewController in
return true // return `true` to send screenview event for this view controller
}
// Optional configuration where you can modify the `data` being sent for
// automatic screenview events.
config.autoScreenViewBody = {
return ["seconds_on_screen": SecondsOnScreenManager.getTimeInScreen()]
}
}
Apple framework views are filtered out by default
(iOS SDK version >= 2.8.0) By default, the SDK filters all Views that belong to an Apple framework (SwiftUI, UIKit). You should expect Views from your app and any third-party frameworks to be sent as screenview events. You can override this default behavior by providing a custom filter function.
For automatic screenview tracking, the SDK automatically names the screen as the class name of the UIViewController
, minus ViewController
. For example, if you have a class EditProfileViewController
in your code base, the SDK will automatically send a screenview event with the screen name EditProfile
.
If you want to send more data with screen events, or you don’t want to send events for every individual screen that people view in your app, you can disable automatic screen tracking and send screen events manually.
Send your own screen events
Screen events use the .screen
method. Like other event types, you can add a data
object containing additional information about the event or the currently-identified person.
import CioTracking
// You can send an event with or without `data`.
CustomerIO.shared.screen(name: "BaseballDailyScores")
// `data` accepts [String: Any] or an `Encodable` object
// 1. [String: Any]:
let data = ["prev_screen": "homescreen", "seconds_in_app": "120"]
CustomerIO.shared.screen(name: "BaseballDailyScores", data: data)
// 2. A custom `Encodable` type:
struct Screen: Encodable {
let prevScreen: String
let secondsInApp: Int
}
CustomerIO.shared.screen(name: "BaseballDailyScores", data: Screen(prevScreen: "homescreen", secondsInApp: 120))