SmartCallingSDK 1.6.4

SmartCallingSDK 1.6.4

×

由 Deniz Adalar、Cornelis van der Bent、Ian Kevan 维护。

SmartCallingSDK 1.6.4

  • 由
  • SmartCom

SmartCalling iOS 库

SmartCalling 库允许您将公司联系信息添加到 iOS 地址簿。这样，当用户接到来自您公司的电话时，会看到个性化的屏幕。

如果您计划使用 SmartCalling 示例应用程序进行参考，请记住，在下载代码后，在示例应用程序项目目录下使用命令行应用程序运行 pod install

请将任何错误/问题/建议报告给 [email protected]

先决条件

首先您必须在门户中设置一个帐户、一个应用程序和一个活动。UAT 门户地址是：https://portal-uat.smartcom.net/

下一步是将应用程序添加到门户中。如果您还没有应用程序，您需要创建自己的测试应用程序。一旦您有了应用程序，您需要登录到门户并使用“添加应用程序”按钮。请确保您提供了所有必要的详细信息，特别是包名。对于 iOS 包名，如果没有 iOS 应用程序，请输入任何值。此库可以更好地工作，如果您能包括 Firebase 推送消息的详细资料，因此您可能需要为测试应用程序创建一个 Firebase 帐户。要找到您的 FCM 密钥和发送者 ID，请登录到您的 Firebase 帐户，选择您的应用程序，然后点击项目概述标签旁边的设置按钮。然后选择云消息，您将在那里看到服务器密钥和发送者 ID。如果您没有服务器密钥，则需要添加一个。

一旦在门户中创建了应用程序，您可以去门户中的“帐户”部分（菜单 - 帐户）查看和复制您的 API 密钥。您将需要在将库集成到应用程序时使用此密钥。

现在您已准备好按照以下说明进行操作。只需按照说明操作即可在您的应用中引用库，并为库提供它所需的所有细节。一个重要的部分是Client Id，您的应用必须在每个设备/用户的应用中提供唯一的Client Id，并且在创建活动时必须使用这些client Id。

仿真器

虽然您可以在仿真器中测试SmartCalling库，但我们注意到在测试活动和反诈骗时偶尔会出现一些意外的结果。因此，我们强烈建议您为了获得最佳结果，在物理设备上测试SmartCalling库。

权限

该iOS库需要两个权限

  • 联系人权限
    SmartCalling主要需要联系人权限才能正常运行，因为SDK会向用户的通讯录添加条目，并从中删除。

  • 推送通知权限
    推送活动功能还需要推送通知权限，而联系人管理则由客户端在静默推送通知触发下完成。

安装

此库最低需要iOS版本12。

CocoaPods

SmartCallingSDK可通过CocoaPods获得。要安装，只需将以下行添加到您的Podfile中

pod 'SmartCallingSDK'

请确保您从命令行运行pod install。请注意，此技术需要CocoaPods 1.9以上版本。

手动安装

SmartCalling.xcframework 已包含在此存储库中。你可以将文件直接拖放到你的 Xcode 项目中。请确保在项目设置中可见，作为“嵌入并签名”。

项目设置

要将联系人添加到用户设备，应用需要访问“通讯录”的权限。您需要在 Info.plist 文件中为键 NSContactsUsageDescription 添加拥有文本值的用法描述。

库将最初请求用户的权限。如果用户拒绝，则库无法添加配置文件并返回错误。为了更好的用户体验，应用可以检查用户是否拒绝了联系人权限，并在这种情况下显示提示框。此逻辑应由应用开发者引入。

使用方法

  1. 要使用框架，首先需要导入它。在 Swift 中这很简单
import SmartCalling
  1. 如果尚未如此，您需要将您的应用添加到 SmartCom 门户中（见上文）。完成此操作后，您将获得一个 API 密钥。在使用库的任何其他功能之前，需要设置 API 密钥。
    SDK 将为创建的联系人设置一个电子邮件地址，该地址应与您的应用程序唯一。SDK 将运行针对该电子邮件的查询，因此您在初始化 SmartCallingManager 时设置一个独特的公司电子邮件地址非常重要。
    库默认使用 SmartCalling 服务器。如果您不打算使用自己的服务器，则必须在测试期间使用我们的 UAT 服务器（https://portal-uat.smartcom.net/）。准备好上线后，您需要联系 SmartCom 启用您的组织在实时服务器上的功能，您将获得我们的实时服务器地址。
    如果您使用自己的服务器，只需覆盖以下值即可
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
  SmartCallingManager.shared.apiKey = "XXXX-XXXX-XXXX-XXXX"
  SmartCallingManager.shared.corporateEmail = "[email protected]"
  SmartCallingManager.shared.url = URL(string: "https://YOUR_SERVER_ADDRESS")!

  return true
}
  1. 每次调用库的 updateProfiles 函数时，如果您的远程配置有变化，所有联系人都会被更新。例如，'applicationDidBecomeActive' 可能是更新配置文件的好地方。如果使用 Scene Delegate，则需要将此代码添加到您的 'sceneDidBecomeActive' 函数中。
func applicationDidBecomeActive(_ application: UIApplication) {
  // Check for profile updates everytime app becomes active
  SmartCallingManager.shared.updateProfiles { error in
    if let error = error {
      print("SmartCalling Update Profiles Failed: \(error)")
    } else {
      print("SmartCalling Update Profiles Succeeded")
    }
  }
}
  1. 假设您的应用程序将有一个登录过程，该过程导致应用程序接收用户信息。为了让库完全正常工作，您的登录过程必须返回登录用户的唯一ID。此唯一ID必须使用以下代码传递给库（其中XXX是唯一的用户ID）
func loginSucessful(_ userInfo: UserInfo) { // Hypothetical function defined in the app which is called after a successful login.  
  SmartCallingManager.shared.setClienId("XXX") { error in
    if let error = error {
      print("SmartCalling setClientId Failed: \(error)")
    } else {
      print("SmartCalling setClientId Succeeded")
    }
  }
}

库将自动更新特定客户端ID的配置文件，所以不需要单独调用updateProfiles。

  1. 如果您的应用程序有注销过程，请为库中调用logOut函数添加代码
func logOut() { // Hypothetical function defined in the app which is called when user logs out of your app.  
  SmartCallingManager.shared.logOut();
}

SSL Pinning

默认情况下，库包括所有SmartCalling证书的SSL固定，但是如果您在自己的环境中托管SmartCalling API，您必须提供有关库可以下载您的证书的信息。为此，您首先需要将证书.der文件放置在库可以通过URL访问的位置。要下载您的证书，您可以在命令行中运行此函数

openssl s_client -connect <yourURL>:443 -showcerts < /dev/null | openssl x509 -outform DER > <yourFileName>.der

请将<yourURL>替换为您的API实例的HTTPS位置的URL，将<yourFileName>替换为您想要给证书文件命名的名称。下载后，将证书文件放在可以通过URL访问的位置。

完成此操作后，您必须在调用库的任何其他调用之前向库提供证书信息。要设置证书位置和文件名，您需要调用' الاحتمال الخاصة بالشهادة'函数

SmartCallingManager.shared.setCertificateLocation(url: "https://www.myurl.com/", fileName: "myCertificate.der") { (success: Bool) in
  if (success) {
    ...
  }
};

将URL和FileName参数替换为您的证书URL和文件名。请注意，URL不包含.der文件，只是文件的位置。只有当此函数在完成处理程序中返回true结果时，您才应仅调用SmartCalling库的后续调用。

启用远程更新

远程配置文件更新与静默推送通知配合工作。SmartCalling Demo使用Firebase Cloud Messaging进行推送通知的注册。虽然演示解决方案使用FCM作为其推送解决方案，但您的推送通知管理并不局限于Google Firebase。如果您正在使用或计划使用不同的系统，请让我们知道，我们将确保您的解决方案得到支持。请遵循Firebase网站上的iOS设置说明。当您收到FCM令牌时，请订阅Smartcalling主题并注册该令牌，然后直接将didReceiveRemoteNotification调用到SmartCallingManager的processRemoteNotification函数，如下所示

func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
  // Update profiles when silent push arrives
  let isSmartCallingNotification = SmartCallingManager.shared.processRemoteNotification(userInfo: userInfo) { error in
    let result: UIBackgroundFetchResult = error == nil ? .newData : .failed
    completionHandler(result)
  }

  if !isSmartCallingNotification { // Not a SmartCalling notification, check for potential other types.
    completionHandler(.failed)
  }
}

// Firebase MessagingDelegate    
func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String) {
  // Register to push notification
  messaging.subscribe(toTopic: "smartcallingcampaign")
  messaging.subscribe(toTopic: "smblacklistupdate")
  SmartCallingManager.shared.setFCMToken(fcmToken) { error in
    // Some additional logic for error case
  }
}

您可以在SmartCalling iOS库GitHub页面上托管示例应用程序代码中找到参考。

后台应用刷新

请注意，后台刷新仅在您使用我们的门户创建和管理您的活动时相关。如果您通过您的联系人管理系统创建活动，则后台更新将不起作用。
这一原生iOS功能可以在应用处于后台时触发SmartCalling联系人同步。请首先按照这篇Apple文档页面设置您的应用程序的后台刷新。之后，您只需开始如下所示的SmartCalling更新过程。

func application(_ application: UIApplication, performFetchWithCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
  SmartCallingManager.shared.updateProfiles { error in
    let result: UIBackgroundFetchResult = error == nil ? .newData : .failed
    completionHandler(result)
  }
}

请注意，后台进程可能会影响用户设备上的电池和数据处理。

反钓鱼（使用CallKit扩展）

以下部分仅适用于您使用SmartCalling反钓鱼功能。
为了激活SmartCalling反钓鱼功能，您首先需要创建一个电话目录扩展。

如果您使用Cocoapods安装库，请确保将SmartCallingSDK标记为新的扩展目标。如果您是手动安装框架，请确保它已显示在您的项目设置中，作为“不嵌套（非嵌套并签名）”。

打开CallDirectoryHandler.swift文件，导入SmartCalling。将该类标记为SmartCallingCallDirectoryHandler的子类以继承所有必需的行为。您需要重写apiKey（如果您使用的是自定义的SmartCalling后端，还需重写url）。最终文件应如下所示

import Foundation
import SmartCalling

class CallDirectoryHandler: SmartCallingCallDirectoryHandler {
//  // Uncomment this line if you are using a custom SmartCalling server
//  override var url: URL {
//    get { URL(string: "https://portal.smartcom.net")! }
//    set {}
//  }

  override var apiKey: String? {
    get { "XXXXXX-XXXX-XXXX-XXXX-XXXXXX" }
    set {}
  }
}

调试

您可以通过SmartCallingManager.shared.setDebugLoggingEnabled(true)启用调试日志，然后SDK将打印额外的日志到控制台进行诊断。

支持 & 常见问题解答

如果您需要SmartCom集成支持，请首先通过电子邮件[email protected]申请支持帐户。收到电子邮件后，您将收到一封激活电子邮件。请按照电子邮件中的说明设置您的帐户和密码。完成后，您将能够登录我们的支持系统以创建工单。请注意，我们只为每个组织提供单个支持帐户。


Q1. 我的推广活动的图片应该是什么大小和格式？
对于iOS，我们建议正方形图像（1:1），理想大小为200 * 200像素。对于Android，我们建议比例为4:3，建议大小为480 * 360像素。

Q2. 在推送活动取消后，Client Ready或Are Clients Ready API调用是否返回True？
如果所涉及的设备已关闭或无法接收推送通知，则可能会返回true的响应。
考虑以下情况：手机A和手机B都处于开启状态。向两部手机发送推送活动，每部手机都收到推送并设置设备以接收电话。对每个设备的“Is Client Ready”调用返回true。然后手机B关闭或移动到一个没有信号的区域。客户向每个设备发送“取消推送活动”。因为只有手机A能够接收推送，所以只有手机A移除了活动。手机B没有信号或已关闭，因此没有接收推送，仍然设置好以接收活动呼叫。现在为每个手机施加“Is Client Ready”调用时，手机A返回false，但手机B仍返回true，因为没有收到取消推送。