Screen Events

Screen events record which screens a contact opens, so you can segment contacts and start automations by screen name. General rules for events: Sending Events.

---

Requirements

• A successful ping() in this installation, see Contacts.

warning

The SDK does not track screens automatically. The shouldTrackActivities parameter has no effect and is deprecated since 1.1.0. Call trackScreen(name:_:) or use a Trackable view controller for every screen you want to see in the panel.

---

Setup

Choose one of two ways for each screen.

Call trackScreen(name:_:)

Call it when the screen appears. You choose the screen name.

Swift

override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    UserSDK.default?.trackScreen(name: "Home")
}

Objective-C

- (void)viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];
    [[UserSDK default] trackScreenWithName:@"Home" completion:nil];
}

In SwiftUI, call it from .onAppear of the screen's view.

Subclass a Trackable view controller

These base classes send a screen event in viewDidLoad, using the class name as the screen name, for example HomeViewController.

Your base class	Use instead
UIViewController	TrackableViewController
UITableViewController	TrackableTableViewController
UICollectionViewController	TrackableCollectionViewController
UIPageViewController	TrackablePageViewController
UISplitViewController	TrackableSplitViewController

class HomeViewController: TrackableViewController {
    // sends a screen event named "HomeViewController" in viewDidLoad
}

The screen name of a Trackable view controller is always the class name. To use another name, call trackScreen(name:_:) instead.

Check

The screen event appears on the contact's timeline with the screen name you expect.

---

Methods

trackScreen(name:_:)

Queues a screen event for the current contact. Renamed in 1.3.0: trackScreen(with:_:) still works and is deprecated until 2.0.

Name	Type	Required	Description
name	String	Yes	The screen name, up to 128 characters. Segments and automations match on this value.
completion	((Bool, Error?) -> Void)?	No	Called with the result on the main thread. See Completion thread.

Returns nothing. Without a contact (no successful ping yet), the completion reports notIdentified and the event is not queued. An empty name or a name over 128 characters ends with invalidName without a request.

UserSDK.default?.trackScreen(name: "Checkout")

trackScreen()

Available on every UIViewController. Sends a screen event named after the view controller's class. The Trackable view controllers call it in viewDidLoad.

trackScreen()  // inside a view controller

---

Common errors

Symptom	Cause	Fix
No screen events at all	Screens are not tracked automatically.	Add trackScreen(name:_:) calls or Trackable base classes.
The first screen at launch is missing	It was tracked before the first successful ping.	Track it after ping() completes, or accept that the first screen of a fresh install is not recorded.
Completion reports invalidName	The screen name is empty or longer than 128 characters.	Use a name of 1 to 128 characters.
An automation does not start	The screen name in the automation differs from the name sent.	Use the exact same name, including letter case.

---

Related

• Sending Events
• Events