纯SwiftUI集成

3.1 核心封装（QTPageTracker.swift）

import SwiftUI
import QTCommon

/// QTCommon 页面追踪器
public enum QTPageTracker {

  // MARK: - 页面状态
  /// 逻辑上当前正在展示的页面（用于前后台恢复计时）
  private static var currentPageName: String?
  /// 是否处于后台状态
  private static var isInBackground = false

  // MARK: - 页面 PV

  /// 手动开始页面 PV 统计
  public static func beginPage(_ pageName: String) {
    currentPageName = pageName
    QTMobClick.beginLogPageView(pageName)
    #if DEBUG
    print("[QTPageTracker] begin page: \(pageName)")
    #endif
  }

  /// 手动结束页面 PV 统计
  public static func endPage(_ pageName: String) {
    if currentPageName == pageName {
      currentPageName = nil
    }
    QTMobClick.endLogPageView(pageName)
    #if DEBUG
    print("[QTPageTracker] end page: \(pageName)")
    #endif
  }

  /// 更新页面属性，可在任意时机调用
  public static func updateProperties(
    _ properties: [String: Any],
    forPage pageName: String
  ) {
    guard !properties.isEmpty else { return }
    UMSpm.updatePageProperties(pageName, properties: properties)
    #if DEBUG
    print("[QTPageTracker] update properties for page: \(pageName), properties: \(properties)")
    #endif
  }

  // MARK: - 前后台切换

  /// App 进入后台：结束当前页面计时
  public static func appDidEnterBackground() {
    guard !isInBackground else { return }
    isInBackground = true
    if let pageName = currentPageName {
      QTMobClick.endLogPageView(pageName)
      #if DEBUG
      print("[QTPageTracker] end page (background): \(pageName)")
      #endif
    }
  }

  /// App 返回前台：恢复当前页面计时
  public static func appWillEnterForeground() {
    guard isInBackground else { return }
    isInBackground = false
    if let pageName = currentPageName {
      QTMobClick.beginLogPageView(pageName)
      #if DEBUG
      print("[QTPageTracker] begin page (foreground): \\(pageName)")
      #endif
    }
  }
}

// MARK: - View Modifier
struct QTPageTrackModifier: ViewModifier {
  let pageName: String

  func body(content: Content) -> some View {
    content
    .onAppear {
      QTPageTracker.beginPage(pageName)
    }
    .onDisappear {
      QTPageTracker.endPage(pageName)
    }
  }
}

extension View {
  /// 为当前视图绑定一个 QTCommon 页面编码
  public func qtPage(_ name: String) -> some View {
    modifier(QTPageTrackModifier(pageName: name))
  }
}

3.2 普通页面使用方式

非根页面的普通 SwiftUI View，有两个方式

方式一：直接挂 .qtPage(...)

struct HomeView: View {
  var body: some View {  
    VStack {
      Text("首页")
    }
    .qtPage("home_page")
  }
}

方式二：在view的生命周期中 onAppear 和 onDisappear 调对应的界面开始和结束的埋点

struct HomeView: View {
  var body: some View {
    VStack {
      Text("首页")
    }
    .onAppear {
      QTPageTracker.beginPage("AutoTrackViewB")
    }
    .onDisappear {
      QTPageTracker.endPage("AutoTrackViewB")
    }
  }
}

struct ContentView: View {
  @State private var path = NavigationPath()

  var body: some View {
    NavigationStack(path: $path) {
      VStack(spacing: 20) {
        Image(systemName: "globe")
        Text("Hello, world!")

        NavigationLink(value: "AutoTrackViewA") {
          Text("跳转到 AutoTrackViewA")
        }
      }
      .padding()
      .navigationTitle("首页")
      .navigationDestination(for: String.self) { value in
                                                if value == "AutoTrackViewA" {
                                                  AutoTrackViewA()
                                                }
                                               }
    }
    .onChange(of: path, initial: true) { _, newPath in
                                        if newPath.isEmpty {
                                          QTPageTracker.beginPage("homePage")
                                        } else {
                                          QTPageTracker.endPage("homePage")
                                        }
                                       }
  }
}

4.1 接口说明

// 需要引入 <QTCommon/UMSpm.h>
+ (void)updatePageProperties:(NSString *)pageName
properties:(NSDictionary *)pProperties;

4.2 SwiftUI 中使用

struct DetailView: View {
  var body: some View {
    VStack {
      Text("详情页")
    }
    .qtPage("detail_page")
    .onAppear {
      QTPageTracker.updateProperties([
        "referrer": "home_page",
        "visit_type": "detail"
      ], forPage: "detail_page")
    }
  }
}

struct DetailView: View {
  @State private var selectedTag: String = "none"

  var body: some View {
    VStack {
      Button("标记为 VIP") {
        selectedTag = "vip"
        QTPageTracker.updateProperties(
          ["user_tag": "vip"],
          forPage: "detail_page"
        )
      }
    }
    .qtPage("detail_page")
  }
}

5.1 接口说明

+ (void)event:(NSString *)eventCode;
+ (void)event:(NSString *)eventCode attributes:(NSDictionary *)attributes;
+ (void)event:(NSString *)eventId pageName:(NSString *)pageName attributes:(NSDictionary *)attributes;

5.2 SwiftUI 中使用

Button("购买") {
  QTMobClick.event("purchase", attributes: [
    "product_id": "12345",
    "category": "book",
    "quantity": 3
  ])
}