Screen-View Tracking (UIKit)

Automatically track screen views whenever a UIViewController becomes visible.

Overview

Sees360 can automatically emit a system analytics event whenever a UIViewController becomes visible.

Event name: sees_screen_view (predefined/system)
Primary param: screen_name — a stable screen name, derived automatically or set explicitly (see below)

The API lowercases all payload keys and values before persisting/exporting. Emit lowercase for consistency ("home", "settings"), or don’t worry about casing at all and let the backend normalize it for you.

Requirements

iOS 15+
SDK initialized: Sees360.initialize(apiKey: apiKey, identifier: identifier)
No extra permissions required. Screen-view events do not need location, usage-stats, or any other host-app permission.

Tracking starts automatically when you initialize the SDK — no further wiring needed, unless you opt out (see below).

How it works

Sees360.initialize swizzles UIViewController.viewDidAppear(_:) once, globally, the first time the SDK is initialized. Only view controllers that live inside the app’s own bundle or an embedded framework are tracked.

For each screen, the SDK determines a screen_name using this order:

If the view controller conforms to ScreenNameProviding, use screenName().
Else, use the view controller’s class name.

Quick start

1. Initialize the SDK

Sees360.initialize(apiKey: apiKey, identifier: identifier)

2. (Recommended) Provide explicit names

import Sees360SDK

class HomeViewController: UIViewController, ScreenNameProviding {
    func screenName() -> String? { "home" }
}

If you don’t implement ScreenNameProviding, the class name is used as-is — e.g. HomeViewController — which is why implementing it is recommended for any screen you care about in reporting.

If you want to keep screens out of reporting entirely, for example a custom navigation controller, return nil from screenName():

class CustomNavigationController: UINavigationController, ScreenNameProviding {
    func screenName() -> String? { nil }
}

Returning nil from screenName() opts that view controller out of automatic screen-view tracking entirely.

Best practices

Stable keys only. No IDs or ephemeral UI state ("profile", not "profile:42").
Prefer ScreenNameProviding. It’s explicit and avoids the class-name fallback producing names like unregistereddealsviewcontroller.
Opt out containers. Navigation controllers, tab bar controllers, and other pure containers should usually return nil from screenName() — their child view controllers are already tracked individually when they appear.
PII-free. Never include user data in screen_name.

Troubleshooting

No events firing: Make sure the SDK is initialized before your screens are shown, and that automaticScreenTracking wasn’t passed as false to initialize.
Unexpected names: Implement ScreenNameProviding to override the class-name fallback.
Third-party or system screens showing up: The SDK already filters to view controllers inside the app’s own bundle or an embedded framework — if something still appears that shouldn’t, conform it to ScreenNameProviding and return nil.
Duplicate events: Consecutive re-appearances of the same screen name are deduped internally; if you’re still seeing duplicates, check whether the same view controller class is being reused for genuinely different screens without distinguishing names.
Composing with another analytics SDK’s own screen tracking: Pass automaticScreenTracking: false to initialize to rely on the other SDK’s tracking instead of running both.

Event reference

Name: sees_screen_view
Payload (lowercased by backend):
- screen_name: String

{
  "event_name": "sees_screen_view",
  "payload": { "screen_name": "settings" }
}

Privacy & security

Keep keys generic and stable (e.g., "settings", "checkout", "search_results").
If you support analytics opt-out, call setAnalyticsConsent(granted: false) — this applies to screen-view events too, since they’re delivered through the same analytics pipeline as trackAnalyticsEvent.

Do not include PII in screen_name.