DevRev iOS SDK

DevRev SDK，用于将 DevRev 服务集成到您的 iOS 应用中。

• DevRev iOS SDK
  • 目录
  • 要求
  • 集成
    • Swift Package Manager (推荐)
    • CocoaPods
      • UIKit 应用
      • SwiftUI 应用
  • 功能
    • 身份验证
      • 匿名身份验证
      • 未验证的身份验证
      • 已验证的身份验证
      • 更新用户
      • 注销
      • 示例
    • PLuG 支持聊天
      • UIKit
        • 示例
      • SwiftUI
      • 创建新对话
      • 新对话闭包
        • 示例
    • 应用内链接处理
    • 分析 - 示例
    • 会话分析
      • 选择加入或退出
      • 会话录制
      • 会话属性
      • 屏蔽敏感数据
      • 计时器
        • 示例
      • 屏幕追踪
        • 示例
    • 推送通知
      • 配置
      • 注册推送通知
        • 示例
      • 取消注册推送通知
        • 示例
      • 处理推送通知
        • 示例
  • 示例应用
  • 故障排除

• Xcode 16.0 或更高版本（App Store 上提供的最新稳定版本）
• Swift 5.9 或更高版本
• 将 iOS 应用程序的最低部署目标设置为 iOS 15

DevRev SDK 可以使用 Swift Package Manager (SPM) 或 CocoaPods 进行集成。

您可以将 DevRev SDK 作为 Swift Package Manager (SPM) 包集成到您的项目中。

要使用 SPM 将 DevRev SDK 集成到您的项目中

1. 在 Xcode 中打开您的项目，然后导航到 Add Package Dependency（添加包依赖项）。
2. 在 Enter Package URL（输入包 URL）下输入 DevRev SDK URL
   • 对于 HTTPS：https://github.com/devrev/devrev-sdk-ios
   • 对于 SSH：git@github.com:devrev/devrev-sdk-ios.git
3. 在您的应用目标的 Build Phases（构建阶段）部分中，找到 Link Binary With Libraries（将二进制文件与库链接）阶段，并确认 DevRevSDK 已链接。 如果未链接，请单击 + 并从列表中选择 DevRevSDK 以添加它。

现在您应该能够在您的项目中导入和使用 DevRev SDK。

要使用 CocoaPods 集成 DevRev SDK

1. 将以下内容添加到您的 Podfile 中

   pod 'DevRevSDK', '~> 1.0.0'

2. 在您的项目目录中运行 pod install。

这会将 DevRev SDK 安装到您的项目中，使其可以随时使用。

1. 在 https://app.devrev.ai 打开 DevRev Web 应用程序，然后转到 Settings（设置）页面。
2. 在 PLuG settings（PLuG 设置）下，复制 Your unique App ID（您的唯一应用 ID）下的值。
3. 获取凭据后，您可以在您的应用程序中配置 DevRev SDK。

一旦您执行以下配置方法，SDK 就可以使用了。

DevRev.configure(appID:)

使用此属性检查 DevRev SDK 是否已配置

await DevRev.isConfigured

例如

DevRev.configure(appID: "abcdefg12345")

在 AppDelegate.application(_:didFinishLaunchingWithOptions:) 方法中配置 SDK。

根据您的应用程序的架构，在应用程序的入口点或初始视图中配置 SDK。

要访问 DevRev SDK 的某些功能，需要用户身份验证。

身份验证函数应在用户登录后适当放置在您的应用程序中。 如果您在应用程序启动时有可用的用户信息，请在 DevRev.configure(appID:) 方法之后调用该函数。

匿名身份验证方法允许您创建一个具有可选用户标识符的匿名用户，确保没有其他数据存储或与用户关联。

DevRev.identifyAnonymousUser(userID:)

未验证的身份验证方法使用唯一标识符来标识用户，但不会通过 DevRev 后端验证他们的身份。

DevRev.identifyUnverifiedUser(_:)

该函数接受 DevRev.Identity 结构，其中用户标识符 (userID) 是唯一必需的属性，所有其他属性都是可选的。

已验证的身份验证方法用于使用唯一标识符来标识用户，并通过 DevRev 后端验证用户的身份。

DevRev.identifyVerifiedUser(_:sessionToken:)

您可以使用以下方法更新用户的信息

DevRev.updateUser(_:)

使用此属性检查当前会话中是否已识别用户

await DevRev.isUserIdentified

该函数接受 DevRev.Identity 结构。

您可以通过调用以下方法来注销当前用户

DevRev.logout(deviceID:)

用户将被注销，方式是清除他们的凭据、取消设备接收推送通知的注册，并停止会话录制。

// Identify an anonymous user without a user identifier.
await DevRev.identifyAnonymousUser()

// Identify an unverified user using their email address as the user identifier.
await DevRev.identifyUnverifiedUser(Identity(userID: "foo@example.org"))

// Identify a verified user using their email address as the user identifier.
await DevRev.identifyVerifiedUser("foo@example.org", sessionToken: "bar-1337")
// Update the user's information.
await DevRev.updateUser(Identity(organizationID: "foo-bar-1337"))

支持聊天功能可以作为模态屏幕从特定的视图控制器或最顶层的视图控制器显示，也可以推送到导航堆栈上。

要在您的应用程序中显示支持聊天屏幕，您可以使用以下重载方法

await DevRev.showSupport(from:isAnimated:)

• 当 UIViewController 作为 from 参数传递时，屏幕将以模态方式显示。
• 当 UINavigationController 作为 from 参数传递时，屏幕将被推送到导航堆栈上。

如果您想从最顶层的视图控制器显示支持聊天屏幕，请使用以下方法

await DevRev.showSupport(isAnimated:)

/// Push the support chat screen to a navigation stack.
await DevRev.showSupport(from: mainNavigationController)

/// Show the support chat screen modally from a specific view controller.
await DevRev.showSupport(from: settingsViewController)

/// Show the support chat screen from the top-most view controller, without an animation.
await DevRev.showSupport(isAnimated: false)

要在 SwiftUI 应用程序中显示支持聊天屏幕，您可以使用以下视图

DevRev.supportView

您可以从您的应用程序中创建一个新的对话。 该方法将显示支持聊天屏幕并同时创建一个新的对话。

DevRev.createSupportConversation()

当创建新对话时，您可以通过设置以下闭包来接收回调

DevRev.conversationCreatedCompletion

这允许您的应用程序访问新创建的对话的 ID。

DevRev.conversationCreatedCompletion = { conversationID in
	print("A new conversation has been created: \(conversationID).")
}

DevRev SDK 提供了一种机制来处理从 DevRev SDK 的任何屏幕中打开的链接。

您可以通过设置专门的应用内链接处理程序来完全自定义链接处理行为。 这样您就可以决定从应用程序中打开链接时应该发生什么。

DevRev.inAppLinkHandler: ((URL) -> Void)?

您可以通过设置 shouldDismissModalsOnOpenLink 布尔标志来进一步自定义行为。 此标志控制当打开链接时，DevRev SDK 是否应关闭最顶层的模态屏幕。

DevRev.shouldDismissModalsOnOpenLink: Bool

DevRev SDK 允许您使用名称和字符串字典发送自定义分析事件。 您可以使用以下函数跟踪这些事件

DevRev.trackEvent(name:properties:)

await DevRev.trackEvent(name: "open-message-screen", properties: ["id": "foo-bar-1337"])

DevRev SDK 提供可观察性功能，以帮助您了解用户如何与您的应用程序交互。

会话分析功能默认选择加入，从一开始就启用它们。 但是，您可以使用以下方法选择退出

DevRev.stopAllMonitoring()

要重新选择加入，请使用以下方法

DevRev.resumeAllMonitoring()

您可以使用此属性检查是否已启用会话监视

DevRev.isMonitoringEnabled

您可以启用会话录制来捕获用户与您的应用程序的交互。

会话录制功能包括以下控制录制的方法

使用此属性将返回会话录制的状态

DevRev.isRecording

要检查是否启用了按需会话，请使用

DevRev.areOnDemandSessionsEnabled

您可以将自定义属性添加到会话录制中，以帮助您了解会话的上下文。 这些属性被定义为字符串值的字典。

DevRev.addSessionProperties(_:)

要在用户注销或会话结束等情况下清除会话属性，请使用以下方法

DevRev.clearSessionProperties()

为了保护敏感数据，DevRev SDK 提供了一个自动屏蔽功能，该功能在发送到服务器之前屏蔽数据。 输入视图（例如文本字段、文本视图和 Web 视图）会自动屏蔽。

虽然自动屏蔽功能可能足以应付大多数情况，但您可以使用以下方法手动将其他视图标记为敏感视图

DevRev.markSensitiveViews(_:)

如果需要取消屏蔽任何先前屏蔽的视图，您可以使用以下方法

DevRev.unmarkSensitiveViews(_:)

DevRev SDK 提供了一种计时器机制来测量在特定任务上花费的时间，使您可以跟踪事件，例如响应时间、加载时间或任何其他基于持续时间的指标。

该机制使用平衡的启动和停止方法，两者都接受计时器名称和可选的属性字典。

要启动计时器，请使用以下方法

DevRev.startTimer(_:properties:)

要停止计时器，请使用以下方法

DevRev.stopTimer(_:properties:)

DevRev.startTimer("response-time", properties: ["id": "foo-bar-1337"])

// Perform the task that you want to measure.

DevRev.stopTimer("response-time", properties: ["id": "foo-bar-1337"])

DevRev SDK 提供自动屏幕跟踪，以帮助您了解用户如何在您的应用程序中导航。 虽然会自动跟踪视图控制器，但您可以使用以下方法手动跟踪屏幕

DevRev.trackScreenName(_:)

DevRev.trackScreenName("profile-screen")

您可以配置您的应用程序以接收来自 DevRev SDK 的推送通知。 SDK 旨在处理推送通知并根据通知的内容执行操作。

DevRev 后端将推送通知发送到您的应用程序，以通知用户有关 PLuG 支持聊天中的新消息。

要接收推送通知，您需要按照 推送通知 部分中的说明配置您的 DevRev 组织。

您需要确保您的 iOS 应用程序已配置为接收推送通知。 您可以按照 Apple 文档 获取有关使用 Apple Push Notification Service (APNs) 注册您的应用程序的指南。

DevRev SDK 提供了一种注册您的设备以接收推送通知的方法。 您可以使用以下方法注册推送通知

DevRev.registerDeviceToken(_:deviceID:)

该方法需要一个设备标识符，该标识符可以是您的系统独有的标识符，也可以是 Apple 提供的供应商标识符 (IDFV)。 通常，令牌注册是从 AppDelegate.application(_:didRegisterForRemoteNotificationsWithDeviceToken:) 方法中调用的。

func application(
	_ application: UIApplication,
	didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
	guard
		let deviceID = UIDevice.current.identifierForVendor?.uuidString
	else {
		return
	}

	Task {
		await DevRev.registerDeviceToken(
			deviceToken,
			deviceID: deviceID
		)
	}
}

如果您的应用程序不再需要接收推送通知，您可以取消注册该设备。

使用以下方法取消注册该设备

DevRev.unregisterDevice(_:)

此方法需要设备标识符，该标识符应与注册期间使用的标识符相同。 建议在您的应用程序中调用 UIApplication.unregisterForRemoteNotifications() 之后放置此方法。

UIApplication.shared.unregisterForRemoteNotifications()

Task {
	guard
		let deviceID = UIDevice.current.identifierForVendor?.uuidString
	else {
		return
	}

	await DevRev.unregisterDevice(deviceID)
}

为了正确处理推送通知，请实现以下方法，通常在 UNUserNotificationCenterDelegate.userNotificationCenter(_:didReceive:) 或 UIApplicationDelegate.application(_:didReceiveRemoteNotification:fetchCompletionHandler:) 中实现。

DevRev.processPushNotification(_:)

func userNotificationCenter(
	_ center: UNUserNotificationCenter,
	didReceive response: UNNotificationResponse
) async {
	await DevRev.processPushNotification(response.notification.request.content.userInfo)
}

本仓库提供了一个示例应用程序，其中包含 UIKit 和 SwiftUI 的用例。

在使用示例应用程序之前，您需要配置它以与您的 Apple 开发者团队和您的 DevRev 凭据一起使用。 为了方便起见，代码中已使用编译器错误指令 (#error) 标记了需要注意的地方。

1. 将您的凭据添加到 ContentView.swift (SwiftUI) 或 AppDelegate.swift (UIKit) 中。
   • 添加凭据后，删除或注释掉相应文件中的编译器错误行。
2. 配置示例目标的证书签名
   • 打开项目设置 (1),
   • 选择适当的目标 (2),
   • 转到“Signing & Capabilities”（签名与功能）部分 (3), 并且
   • 在“Team”（团队）下选择您的开发团队 (4)。
   

• 问题：无法将 SDK 导入我的应用程序。解决方案：仔细检查设置过程，并确保 DevRevSDK 已正确链接到您的应用程序。

• 问题：DevRev SDK 如何处理错误？解决方案：DevRev SDK 使用 Apple 的统一日志记录系统在控制台中报告所有错误。 在子系统 ai.devrev.sdk 中查找错误消息。

• 问题：支持聊天不显示。解决方案：确保您已正确调用了其中一种身份验证方法：DevRev.identifyUnverifiedUser(...)、DevRev.identifyVerifiedUser(...) 或 DevRev.identifyAnonymousUser(...)。

• 问题：未收到推送通知。解决方案：确保您的应用程序已配置为接收推送通知，并且您的设备已在 DevRev SDK 中注册。