Impression tracking for UIKit and SwiftUI, with configurable visibility thresholds and cooldowns. Receive callbacks and connect them to your analytics.
- UIKit: Track table and collection view cells, or provide custom targets.
- SwiftUI: Track views with modifiers and optional exit callbacks.
- iOS 17 or later
- Swift tools 6.1 or later (Swift 5 language mode)
Swift Package Manager resolves RxSwift and RxCocoa automatically, from 6.8.0 up to the next major version.
Add the package using Swift Package Manager. For a local checkout, choose File → Add Package Dependencies → Add Local in Xcode and select the repository directory. Add the KarrotImpression product to your app target.
import KarrotImpressionKeep one tracker per scroll view, register it once, and subscribe to impressions.
Use stable model IDs and update ProductCell.impressionID when configuring a cell.
import UIKit
import KarrotImpression
final class ProductCell: UICollectionViewCell {
var impressionID: String?
}
final class ProductListViewController: UIViewController {
@IBOutlet private weak var collectionView: UICollectionView!
private let tracker = ImpressionEventTrackerBuilder().build()
override func viewDidLoad() {
super.viewDidLoad()
let factory = DefaultDetectorItemFactory { view in
guard let cell = view as? ProductCell,
let id = cell.impressionID else {
return nil
}
return VisibleStateDetectorItem(
id: id,
target: cell,
ratio: 0.5,
cooltime: ImpressionCooltime(key: id, coolingTime: 30)
)
}
tracker.subscribe { item in
print("Impression: \(item.id)")
}
tracker.register(
viewController: self,
scrollView: collectionView,
detectorItemFactory: factory,
trackingRect: { [weak self] in
guard let scrollView = self?.collectionView else { return .zero }
return scrollView.convert(scrollView.bounds, to: nil)
}
)
}
}ratio: 0.5 requires at least half of the target's area to intersect the tracking
area. Both trackingRect and the target's frameInWindow use window
coordinates. The closure above uses the scroll view's bounds; adjust it if a
fixed header or another overlay should reduce the tracking area. The library
does not infer occlusion by other views.
DefaultDetectorItemFactory maps visible cells in UITableView and
UICollectionView. It does not include supplementary views or arbitrary
UIScrollView subviews. Implement DetectorItemFactory for those cases; any
UIView already conforms to ImpressionDetectorTarget.
The view-controller registration observes appearance, app activation, and user
scrolling. For programmatic scrolling or data reloads, call
trackManually(shouldResetCache:) after layout has updated the visible cells and
their frames.
| Method | Behavior |
|---|---|
trackManually(shouldResetCache: false) |
Evaluate items with existing tracking state. |
trackManually(shouldResetCache: true) |
Clear tracking state, then evaluate items. |
clearCache() |
Clear tracking state without evaluating items. |
setFilter(_:) |
Suppress callbacks when the filter returns false. |
A callback fires when an eligible item first meets its threshold. It can fire again after the item leaves the tracked set or tracking state is cleared, subject to its cooldown. UIKit's public API provides entry callbacks only.
A tracker registered while its view controller is already onscreen reports no
impression until that view controller appears again, and it stays silent when the
app returns from the background. Pass usesInitialVisibility: true to the builder
to take the visibility at registration time from the window attachment of the
view.
let tracker = ImpressionEventTrackerBuilder(usesInitialVisibility: true).build()For a nested scroll view, use the register overload without a view controller.
It does not observe screen or app lifecycle events. A parent tracking target can
conform to ImpressionInnerScrollable and forward its tracking and clearing
requests to the nested tracker.
Set ImpressionCooltime to limit repeated impressions, as in the 30-second
example above. Omit cooltime to disable cooldown checking for an item.
Each build() call creates a separate in-memory cooldown cache. To share a
cooldown across trackers, inject the same cache and use the same cooldown keys:
let cache = InMemoryImpressionCooltimeCacheImpl(dateProvider: { Date() })
let builder = ImpressionEventTrackerBuilder()
let firstTracker = builder.build(cooltimeCache: cache)
let secondTracker = builder.build(cooltimeCache: cache)The tracker applies its filter before checking the cooldown. The default cache records an expiration when a check allows an impression.
tracker.clearCache() and shouldResetCache: true preserve cooldowns. Use
cache.clear() to reset them. Implement ImpressionCooltimeCache for custom storage.
Mark each item with impressionTrackable and wrap the list in
impressionTrackableContainer. Add impressionPolicy after the container
modifier so the policy is available to it through the environment.
import SwiftUI
import KarrotImpression
struct ProductList: View {
let productIDs: [String]
var body: some View {
ScrollView {
LazyVStack {
ForEach(productIDs, id: \.self) { id in
Text(id)
.frame(maxWidth: .infinity, minHeight: 120)
.impressionTrackable(
id: id,
visibilityThreshold: 0.5,
tracksExit: true,
onImpressionEnter: { print("Enter: \(id)") },
onImpressionExit: { print("Exit: \(id)") }
)
}
}
}
.impressionTrackableContainer(visibleArea: .safeArea)
.impressionPolicy(.cooldown(interval: 30))
}
}An item is visible when its intersection with the container has positive area
and its visible-area ratio is at least visibilityThreshold. The default
threshold is 0.0, meaning any positive intersection. IDs must be unique within
the container and remain stable across view updates.
Set tracksExit: true to pair accepted entries with exits when an item falls
below its threshold or leaves the visible set. Lifecycle exits are best-effort
when the container becomes inactive or disappears. Entries blocked by a policy
do not produce exits. By default, only entry callbacks are delivered.
The container's default is .ignoringSafeArea(). Use .safeArea to respect
safe-area insets, or .ignoringSafeArea(regions: .container, edges: .bottom) to ignore
only selected insets.
Without a policy, entries are allowed whenever an item newly qualifies as
visible. .cooldown(interval:) suppresses repeated entries for the same ID.
Policy storage belongs to the modifier's SwiftUI state: it survives body
recomputations but is recreated when the policy ID changes or the modifier's
state is destroyed. Implement ImpressionPolicy for another rule.
With unchanged item configuration, cooldown expiration alone does not trigger a
callback. A blocked item must leave and reenter the visible set, or the container
must reactivate, before it can be considered again. SwiftUI policy storage is
independent of UIKit's ImpressionCooltimeCache.
For item diagnostics, call tracker.enableDebugging() from a
#if DEBUG block. For tracking-area and safe-area overlays, present the settings
controller from your own debug menu:
#if DEBUG
let settings = ImpressionDebugOverlaySettingsViewController()
present(settings, animated: true)
#endifThe settings controller is available only in DEBUG builds. Orange outlines
show reported UIKit tracking areas; the cyan dashed outline shows the topmost
screen's safe area. Enable the toggle, then scroll or reenter the screen to
refresh tracking-area reports.
Add .showsChildrenImpressionRect() after .impressionTrackableContainer() to
show item overlays in debug builds. It has no effect in release builds.
Green outlines indicate items in the last processed visible snapshot, including items blocked by a policy; they do not confirm callback delivery.
The repository remains named SushiBelt; the package and import are
KarrotImpression. Replace the previous tracker and delegate APIs with the UIKit
builder and factory API or SwiftUI modifiers.
See the migration guide for API mappings and behavior changes.
The Example/ project uses the previous SushiBelt API.
KarrotImpression is distributed under the Apache License, Version 2.0, except for third-party code with its own license notices. The RxViewController-derived lifecycle extensions retain their MIT license. See LICENSE.