GoSquared Live Chat for iOS

如果您发现有任何功能不正常，或希望留下改进意见，请提出问题。您也可以直接联系： [email protected]。

本指南用于将 People CRM 跟踪和 Live Chat 添加到您的原生 iOS 应用程序中。

如果您想看到我们的 Live Chat SDK 的实际效果，我们已在自己的应用程序中使用了它。下载 GoSquared 的Inbox iOS 应用并与我们开始一次支持对话！

安装

您需要使用具有 Write Tracking 权限的 API 密钥。您可以从设置 > 您的帐户 > API 中生成此密钥。

使用 CocoaPods 安装（推荐）

您应该熟悉通过 CocoaPods 安装。您的 Podfile 应该包含以下两行，用于安装 Chat

将GoSquared添加到Podfile有两种选择

如果您想要自动跟踪视图，请在Podfile中添加pod 'GoSquared/Autoload'
如果您不希望这样做，请将pod 'GoSquared'添加到您的Podfile中。

要使用GoSquared实时聊天，请将pod GoSquared/Chat添加到您的Podfile

pod 'GoSquared'
pod 'GoSquared/Chat'

# optional if you want to automatically track view controllers
# if not added, you must manually call `trackScreen:` yourself
pod 'GoSquared/Autoload'

然后只需运行pod install

使用Carthage安装

支持使用Carthage安装，但是不会提供自动视图跟踪功能。因此，您需要在每个ViewControllers上调用来实现跟踪。trackScreen:

有关使用Carthage的说明，请参阅他们的文档。

配置

在调用任何跟踪/人方法之前，请确保使用您的项目令牌（GoSquared项目的唯一标识符 - 您可以在项目设置中找到）初始化库，否则库会抛出异常。建议将以下行添加到您的UIApplication的didFinishLaunchingWithOptions方法中。

注意：从iOS 10（Xcode 8）开始，当访问相册时，Apple要求在info.plist中包含NSPhotoLibraryUsageDescription键。如果您希望用户能够通过聊天发送图像，则必须为此键添加简短的描述，当聊天访问相册时显示。如果省略iOS 10之前的这一项，则上传按钮将被简单隐藏。

Objective-C

#import <GoSquared/GoSquared.h>
#import <GoSquared/GoSquared+Chat.h> //Remove if you are not using chat

// ...

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [GoSquared sharedTracker].token = @"your-project-token";
    [GoSquared sharedTracker].key   = @"your-api-key";

    // this enables Secure Mode and is required for Live Chat. 
    // generate a Secure Mode Secret from your Project Settings here:
    // https://www.gosquared.com/setup/general
    // [NOTE] If you are using the same project token on a website, you will also need to implement Secure Mode on your site too.
    [GoSquared sharedTracker].secret = @"your-secure-secret";


    // ===========================================================
    // this is where we will configure the Live Chat view controller...
    // ===========================================================

    // this opens the connection for Live chat, showing the user as online, and
    // loading messages they missed while the app was closed
    [[GoSquared sharedChatViewController] openConnection];

    // [OPTIONAL] override the title at the top of the view controller (by default
    // it will use the name set at https://www.gosquared.com/setup/chat)
    // [GoSquared sharedChatViewController].title = @"Chatting with Support";


    // ===========================================================
    // Other options...
    // ===========================================================

    // [OPTIONAL] set logging level: Debug, Quiet (Default), Silent
    // [GoSquared sharedTracker].logLevel = GSLogLevelDebug;

    // if your app primarily runs in the background and you want visitors to show in
    // your Now dashboard, you should set the following to `YES` (default: NO)
    // [GoSquared sharedTracker].shouldTrackInBackground = YES;

    return YES;
}

Swift

import GoSquared

// ...

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {

    GoSquared.sharedTracker().token = "your-project-token"
    GoSquared.sharedTracker().key   = "your-api-key"

    // this enables Secure Mode and is required for Live Chat. 
    // generate a Secure Mode Secret from your Project Settings here:
    // https://www.gosquared.com/setup/general
    // [NOTE] If you are using the same project token on a website, you will also need to implement Secure Mode on your site too.
    GoSquared.sharedTracker().secret = "your-secure-secret"

    // ===========================================================
    // this is where we will configure the Chat view controller...
    // ===========================================================

    // this opens the connection for chat, showing the user as online, and
    // loading messages they missed while the app was closed
    GoSquared.sharedChatViewController().openConnection();

    // [OPTIONAL] override the title at the top of the view controller (by default
    // it will use the name set at https://www.gosquared.com/setup/chat)
    // GoSquared.sharedChatViewController().title = "Chatting with Support";


    // [OPTIONAL] set logging level: Debug, Quiet (Default), Silent
    // GoSquared.sharedTracker().logLevel = .Debug

    // [OPTIONAL] if your app primarily runs in the background and you want
    // visitors to show in your Now dashboard, you should set the following to
    // `true` (default: false)
    // GoSquared.sharedTracker().shouldTrackInBackground = true

    return true
}

打开实时聊天

我们知道每个应用的界面设计都不同，所以我们没有提供自己的应用内聊天按钮，而是让您选择如何/何时/在哪里提供聊天选项。实时聊天可以是帮助菜单的一部分，也可以在UI中有自己的专用图标。您所需做的就是使用我们的SDK中可用的方法来触发在所需的UI元素上点击时打开实时聊天。

在我们自己的应用中，我们使用问号图标来触发聊天打开。

Objective-C

#import <GoSquared/GoSquared.h>
#import <GoSquared/GoSquared+Chat.h>
#import <GoSquared/UIViewController+Chat.h>

// from within a UIViewController

// open from storyboard action
- (IBAction)buttonWasTapped:(id)sender
{
    [self gs_presentChatViewController];
}

Swift

import GoSquared

// from within a UIViewController

// open from storyboard action
@IBAction func buttonWasTapped(sender: AnyObject) {
    self.gs_presentChatViewController();
}

显示未读消息数量

通常，您可能想要在某个实时聊天界面中显示未读消息的数量（通常在打开聊天的按钮上是一个明智的选择）。

Objective-C

#import <GoSquared/GoSquared.h>
#import <GoSquared/GoSquared+Chat.h>

// add a notification observer for `GSUnreadMessageNotification`
- (void)someSetupMethod
{
    [[NSNotificationCenter defaultCenter] addObserver:self
                                             selector:@selector(unreadNotificationHandler:)
                                                 name:GSUnreadMessageNotification
                                               object:nil];
}

// method for handling notification
- (void)unreadNotificationHandler:(NSNotification *)notification
{
    NSUInteger count = ((NSNumber *)notification.userInfo[GSUnreadMessageNotificationCount]).unsignedIntegerValue;
    // update ui with count
}

Swift

import GoSquared

// add a notification obsever for `GSUnreadMessageNotification`
func someSetupFunction() {
    let notifCenter = NSNotificationCenter.defaultCenter()
    let notifHandler = #selector(CustomUIButton.unreadNotificationHandler(_:))

    notifCenter.addObserver(self, selector: notifHandler, name: GSUnreadMessageNotification, object:nil)
}

// function for handling notification
func unreadNotificationHandler(notification: NSNotification) {
    let count = notification.userInfo![GSUnreadMessageNotificationCount]
    // update ui with count
}

显示应用内新消息的通知

目前我们未提供显示应用内新消息通知的UI，但是允许您创建并显示自己的通知。

Objective-C

#import <GoSquared/GoSquared.h>
#import <GoSquared/GoSquared+Chat.h>

// add a notification observer for `GSMessageNotification`
- (void)someSetupMethod
{
    [[NSNotificationCenter defaultCenter] addObserver:self
                                             selector:@selector(newMessageHandler:)
                                                 name:GSMessageNotification
                                               object:nil];
}

// method for handling notification
- (void)newMessageHandler:(NSNotification *)notification
{
    NSDictionary *messageInfo = notification.userInfo;

    NSString *senderName = messageInfo[GSMessageNotificationAuthor];
    NSString *senderAvatar = messageInfo[GSMessageNotificationAvatar];
    NSString *messageBody = messageInfo[GSMessageNotificationBody];

    // build and display ui for message notification
}

Swift

import GoSquared

// add a notification obsever for `GSMessageNotification`
func someSetupFunction() {
    let notifCenter = NSNotificationCenter.defaultCenter()
    let notifHandler = #selector(CustomUIButton.newMessageHandler(_:))

    notifCenter.addObserver(self, selector: notifHandler, name: GSMessageNotification, object:nil)
}

// function for handling notification
func newMessageHandler(notification: NSNotification) {
    let messageInfo = notification.userInfo!

    let senderName = messageInfo[GSMessageNotificationAuthor]
    let senderAvatar = messageInfo[GSMessageNotificationAvatar]
    let messageBody = messageInfo[GSMessageNotificationBody]

    // build and display ui for message notification
}

创建和更新People CRM资料

如果您的应用程序需要用户登录，可以将他们的详细信息（id，电子邮件地址等）返回给GoSquared。这将在People CRM中为用户创建一个资料，任何在该会话中跟踪的行为都会归功于他们。这也在当用户开始实时聊天时识别您正在与谁交谈时非常有用。

注意：要跟踪用户设备信息（iOS版本、IP地址/位置、屏幕尺寸等），需要实现页面/屏幕视图跟踪，因为目前这是更新该信息的唯一方式。

会话期间跟踪的任何事件或自定义属性都将归因于这位用户。

识别您的用户

要识别用户，您需要提供id或email属性。这将在GoSquared People中创建一个新的资料，其中将跟踪所有用户的会话数据、事件和自定义属性。

如果您没有用于该人员的id，将从一个电子邮件地址创建一个。

注意：库将缓存您的识别id并将在下一次启动时再次使用它。如果您不希望这种行为，请在每次启动后设置token后调用unidentify。

Objective-C

NSDictionary *properties = @{
                             @"id": @"user-id", // Required if no email address
                             @"email": @"[email protected]", // Required if no id

                             // Reserved property names
                             @"name": @"Test User",
                             @"username": @"testuser",
                             @"phone": @"+447901229693",
                             @"created_at": @"2016-06-07T15:44:20Z", // ISO 8601 formatted NSString
                             @"company_name": @"GoSquared",
                             @"company_industry": @"Customer Analytics",
                             @"company_size": @150000,

                             // Custom properties
                             @"custom": @{
                                      // @"custom_property_name": @"custom property value"
                                         }
                             };

[[GoSquared sharedTracker] identifyWithProperties:properties];

Swift

let properties = [
    "id": "user-id", // Required if no email address
    "email": "[email protected]", // Required if no id

    // Reserved property names
    "name": "Test User",
    "username": "testuser",
    "phone": "+447901229693",
    "created_at": "2016-06-07T15:44:20Z", // ISO 8601 formatted String
    "company_name": "GoSquared",
    "company_industry": "Customer Analytics",
    "company_size": 150000,

    // Custom properties
    "custom": [
    // "custom_property_name": "custom property value"
    ]
]

GoSquared.sharedTracker().identify(properties: properties)

取消识别（例如，在登出时）

默认情况下，我们将缓存用户详情，以便他们下次打开应用时知道他们是谁。如果您不希望这种行为，则可以使用'unidentify'方法。

Objective-C

[[GoSquared sharedTracker] unidentify];

Swift

GoSquared.sharedTracker().unidentify();

页面浏览（屏幕）跟踪

GoSquared的网站跟踪历史意味着用户的大量信息将通过页面浏览进行跟踪。然而，页面浏览并不能完美地应用于移动应用跟踪，但是，当UIViewController发生变化时，模拟页面浏览是最好的方法，用于在People CRM和Live Chat中更新用户设备/会话信息。

注意：跟踪页面浏览将自动跟踪用户的iOS版本、IP地址/位置、屏幕大小、最后在线时间和People CRM和Live Chat中的总访问量。

页面浏览还将构成People CRM中用户会话历史的一部分。

自动页面浏览跟踪

此方法将自动跟踪UIViewController的变化作为新页面浏览。这是安装最容易的方法，但可能会比用户期望的更多使用移动数据和电池电量。为了更精细的控制，请使用手动页面浏览方法。

注意：此功能仅在您使用CocoaPods安装时可用。

请确保您在Podfile中使用GoSquared/Autoload子规范。按照上述说明配置您的项目令牌和API密钥，然后就可以使用了！

如果需要，您可以在单个ViewControllers上禁用跟踪，或设置自定义标题

Objective-C

#import <GoSquared/GoSquared.h>

// ...

- (void)viewDidLoad {
    [super viewDidLoad];

    // use this to override the title property on a ViewController class
    self.trackingTitle = @"My Custom Title";
    // set this to YES to disable tracking for a particular ViewController
    self.doNotTrack = YES;
}

Swift

import GoSquared

// ...

override func viewDidLoad() {
    super.viewDidLoad()

    // use this to override the title property on a ViewController class
    self.trackingTitle = "My Custom Title";
    // set this to true to disable tracking for a particular ViewController
    self.doNotTrack = true;
}

手动页面浏览跟踪

如果您不想跟踪每个新的屏幕，但需要跟踪用户设备信息，此方法推荐。手动跟踪页面浏览将自动更新用户在Live Chat和People CRM中的设备信息和位置。

Objective-C

#import <GoSquared/GoSquared.h>

// ...

- (void)viewDidAppear
{
    [[GoSquared sharedTracker] trackScreenWithTitle:self.title];
    [[GoSquared sharedTracker] trackScreenWithTitle:self.title path:@"/custom-url-path"];
}

Swift

import GoSquared

// ...

override func viewDidAppear(animated: Bool) {
    super.viewDidAppear(animated)

    GoSquared.sharedTracker().trackScreen(title: self.title)
    GoSquared.sharedTracker().trackScreen(title: self.title, path:"/custom-url-path")
}

事件跟踪

事件将在趋势仪表板的“事件”小部件中聚合。如果您正在识别用户，事件将被归因于该用户，并在People仪表板的个人资料中显示。然后您可以根据他们跟踪的事件搜索和筛选用户。

跟踪事件

Objective-C

[[GoSquared sharedTracker] trackEventWithName:"event name"];

Swift

GoSquared.sharedTracker().trackEvent(name: "event name")

跟踪带属性的事件

您可以选择在事件正文中以键值对的形式提供其他信息。这些信息将可以在个人的事件流中查看。但您目前还不能根据事件正文属性进行搜索/过滤。

Objective-C

[[GoSquared sharedTracker] trackEventWithName:@"event name" properties:@{ @"properties": @"are cool" }];

Swift

GoSquared.sharedTracker().trackEvent(name: "event name", properties: ["properties": "are cool"])

交易跟踪（电商）

交易将在电商仪表板和人群CRM中显示（如果您正在识别用户）。

跟踪交易

Objective-C

GSTransactionItem *coke = [GSTransactionItem transactionItemWithName:@"Coca Cola"
                                                               price:@0.99
                                                            quantity:@6];

[[GoSquared sharedTracker] trackTransactionWithId:@"unique-id" items: @[ coke ]];

Swift

let coke = GSTransactionItem(name: "Coca Cola", price: 0.99, quantity: 6)

GoSquared.sharedTracker().trackTransaction(id: "unique-id", items: [coke])

行为规范

请注意，本项目发布时具有贡献者行为规范。通过参与本项目，您同意遵守其条款。

请参阅CODE_OF_CONDUCT.md以获取完整条款。

许可协议

MIT许可协议（MIT）

致谢

感谢Urban Massage的Giles Williams设计了图书馆的初始版本，并允许我们接管。

GoSquared 1.0.2

GoSquared 1.0.2

GoSquared 1.0.2

GoSquared Live Chat for iOS

安装

使用 CocoaPods 安装（推荐）

使用Carthage安装

配置

打开实时聊天

Objective-C

Swift

显示未读消息数量

Objective-C

Swift

显示应用内新消息的通知

Objective-C

Swift

创建和更新People CRM资料

识别您的用户

取消识别（例如，在登出时）

页面浏览（屏幕）跟踪

自动页面浏览跟踪

手动页面浏览跟踪

事件跟踪

跟踪事件

跟踪带属性的事件

交易跟踪（电商）

跟踪交易

行为规范

许可协议

致谢