README.zh-Hans.md

ImpressionKit

这是一个用户行为追踪（UBT）工具。可以方便地检测 UIView 的曝光事件。

原理：用 SwiftHook Hook UIView的didMoveToWindow方法，定时检测此UIView是否在屏幕上。

怎么使用

主要的 API

非常简单.

// UIKit

UIView().detectImpression { (view, state) in
    if state.isImpressed {
        print("This view is impressed to users.")
    }
}

// SwiftUI

Color.red.detectImpression { state in
    if state.isImpressed {
        print("This view is impressed to users.")
    }
}

如果是在 UICollectionView，UITableView 或者其他可复用的视图中，请使用ImpressionGroup。

// UIKit

var group = ImpressionGroup.init {(_, index: IndexPath, view, state) in
    if state.isImpressed {
        print("impressed index: \(index.row)")
    }
}

...

func collectionView(_ collectionView: UICollectionView, cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {
    let cell = collectionView.dequeueReusableCell(withReuseIdentifier: "Cell", for: indexPath) as! Cell
    self.group.bind(view: cell, index: indexPath)
    return cell
}

// SwiftUI

var group = ImpressionGroup.init { (_, index: Int, _, state) in
    if state.isImpressed {
        print("impressed index: \(index)")
    }
}

var body: some View {
    List(0 ..< 100) { index in
        CellView(index: index)
            .frame(height: 100)
            .detectImpression(group: group, index: index)
    }
}

更多 API

更改检测间隔 (秒). 更小的 检测间隔 代表更高的精确性和更高的CPU消耗。

UIView.detectionInterval = 0.1  // 应用于所有 view。
UIView().detectionInterval = 0.1    // 应用于特定 view. 如果为nil，则使用 `UIView.detectionInterval`。
ImpressionGroup().detectionInterval = 0.1   // 应用于特定 group. 如果为nil，则使用 `UIView.detectionInterval`。

更改 view 在屏幕上的持续时间的阈值 (秒)。 如果 view 在屏幕上的持续时间超过此阈值则可能会触发曝光。

UIView.durationThreshold = 2  // 应用于所有 view。
UIView().durationThreshold = 2    // 应用于特定 view. 如果为nil，则使用 `UIView.durationThreshold`。
ImpressionGroup().durationThreshold = 2   // 应用于特定 group. 如果为nil，则使用 `UIView.durationThreshold`。

更改 view 在屏幕上的面积比例的阈值（从 0 到 1）。view 在屏幕上的面积的百分比超过此阈值则可能会触发曝光。

UIView.areaRatioThreshold = 0.4  // 应用于所有 view。
UIView().areaRatioThreshold = 0.4    // 应用于特定 view. 如果为nil，则使用 `UIView.areaRatioThreshold`。
ImpressionGroup().areaRatioThreshold = 0.4   // 应用于特定 group. 如果为nil，则使用 `UIView.areaRatioThreshold` 。

更改 view 透明度的阈值（从 0 到 1）。view 透明度超过此阈值则可能会触发曝光。

UIView.alphaThreshold = 0.4  // 应用于所有 view。
UIView().alphaThreshold = 0.4    // 应用于特定 view. 如果为nil，则使用 `UIView.alphaThreshold`。
ImpressionGroup().alphaThreshold = 0.4   // 应用于特定 group. 如果为nil，则使用 `UIView.alphaThreshold` 。

在某些情况下重新触发曝光事件。

// 当 view 离开屏幕 （页面不变，只是 view 没有显示）时，重新触发曝光。
public static let leftScreen = Redetect(rawValue: 1 << 0)

// 当 view 所在 UIViewController 消失时，重新触发曝光。
public static let viewControllerDidDisappear = Redetect(rawValue: 1 << 1)

// 当 App 进入后台时，重新触发曝光。
public static let didEnterBackground = Redetect(rawValue: 1 << 2)

// 当 App 将要进入非活跃状态时，重新触发曝光。
public static let willResignActive = Redetect(rawValue: 1 << 3)

UIView.redetectOptions = [.leftScreen, .viewControllerDidDisappear, .didEnterBackground, .willResignActive]  // 应用于所有 view。
UIView().redetectOptions = [.leftScreen, .viewControllerDidDisappear, .didEnterBackground, .willResignActive]    // 应用于特定 view. 如果为nil，则使用`UIView.redetectOptions`。
ImpressionGroup().redetectOptions = [.leftScreen, .viewControllerDidDisappear, .didEnterBackground, .willResignActive]   // 应用于特定 group. 如果为nil，则使用 `UIView.redetectOptions`。

查看Demo获取更多详情。

How to integrate ImpressionKit

cocoapods.

pod 'ImpressionKit'

或者使用 Swift Package Manager。 3.1.0 版本之后，SPM被支持。

Requirements

• iOS 12.0+ (UIKit)
• iOS 13.0+ (SwiftUI)
• Xcode 15.1+