13

Screen tracking

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 title representing the title of the screen or page that a person visited in your app.

Screen view events let you trigger campaignsCampaigns are automated workflows that send people messages and perform other actions when people meet certain criteria. 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 they use. Screen events also update your audience’s “Last Visited” attribute, which can help you track how recently people used your app.

Automatic screen tracking

We can automatically track screens for UIKit-based apps with the .autoTrackUIKitScreenViews configuration option. When you enable automatic screen tracking, the SDK sends a screen call every time a person visits a screen in your app. For apps not using UIKit, like SwiftUI apps, you should manually track screen events.

To enable automatic screen tracking, you can simply pass .autoTrackUIKitScreenViews() to the SDKConfigBuilder or you can customize the behavior for automatic screen tracking if you want to filter the screens the SDK sends events for or add additional properties to the screen events.

When you’re done, we recommend you test that automatic screen tracking works for your app. If you encounter issues, you can always send screen events manually.

import CioDataPipelines

let config = SDKConfigBuilder(cdpApiKey: "CDP_API_KEY")
  .autoTrackUIKitScreenViews()
  .build()

If you don’t use UIKit, or otherwise need to send your own screen events, you can send screen events manually.

Screen names

When you enable automatic screen views, 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.

Customize automatic screen tracking

You can also set additional parameters to customize the behavior of automatic screen tracking.

• autoScreenViewBody: (optional) Closure that returns a dictionary of properties that you want to send with each automatic screen call.
• filterAutoScreenViewEvents: (optional) Closure that returns a boolean—true to send an automatic screen call; false to prevent an automatic call.

import CioDataPipelines

let config = SDKConfigBuilder(cdpApiKey: "CDP_API_KEY")
  .autoTrackUIKitScreenViews(
    autoScreenViewBody: {
      return [:]
    },  // optional
    filterAutoScreenViewEvents: { (viewController: UIViewController) in
      return true
    }  // optional
  )
  .build()

CustomerIO.initialize(withConfig: config)

Test automatic screen tracking for your app

The automatic screen tracking feature is designed to work with most UIKit-based apps, but it may not work with especially complex navigation structures. If you’ve got a significantly complex UIKit-based navigation structure, you may need to send screen events manually.

When you enable automatic screen tracking, you may want to enable info-level logging and walk through your app to make sure screen events come through as expected. If you encounter issues, you probably need to send events manually for problematic screens.

import CioDataPipelines

let config = SDKConfigBuilder(cdpApiKey: "YOUR_CDP_API_KEY")
            .migrationSiteId("YOUR_SITE_ID")
            .autoTrackUIKitScreenViews(true)
            .logLevel("info")

CustomerIO.initialize(withConfig: config.build()) 

Manually track screen events

Screen events use the .screen method. Like other event types, you can add a properties object containing additional information about the event or the currently-identified person.

import CioDataPipelines

// You can send an event with or without `properties`.
CustomerIO.shared.screen(title: "DailyBaseballScores")
// `properties` accepts [String: Any] or an `Encodable` object 
// 1. [String: Any]:
let data = ["prev_screen": "homescreen", "seconds_in_app": "120"]
CustomerIO.shared.screen(title: "DailyBaseballScores", properties: data)

// 2. A custom `Encodable` type:
struct Screen: Encodable {
  let prevScreen: String
  let secondsInApp: Int
}
CustomerIO.shared.screen(title: "DailyBaseballScores", properties: Screen(prevScreen: "homescreen", secondsInApp: 120))