Sojourn

Sojourn 是一种灵活的位置收集服务。它包括 Android 或 iOS 的移动 SDK 和基于 Web 的仪表板以管理您的部署。Sojourn 的核心功能是其高效的位置数据收集算法。只有在设备移动较大之后才会使用位置服务。

Web 仪表板提供了一个管理部署的门户。您可以在这些位置创建和管理地理围栏，并测量用户在这些位置的停留时间。提供基本的报告功能。

我们认识到，每个需要从移动设备获取位置的使用案例都是不同的。因此，该系统高度可定制，使开发者能够触发数据更新时的操作，并轻松地将数据持久化到云端。

功能

• iOS 和 Android 原生 SDK
• 快速轻松的集成。
• 收集位置数据的高效算法。
• 高度可定制。
• 支持离线存储和转发算法。
• 提供 JavaScript SDK。
• 支持 iBeacon。
• 支持圆形地理围栏。

其他功能

• 灵活的云规则引擎。
• 收件箱
• 社交动态
• 深层链接。
• 系统支持用户注册和匿名用户。
• 电子邮件和短信多因素认证。
• Web 仪表板
• 创建和管理地理围栏
• 创建和管理 iBeacon
• 基本报告活跃用户、访问量
• 导出位置数据
• 服务器支持保存前和保存后的触发。
• 可以实现自定义规则逻辑。
• 推送通知。
• 高度可扩展的系统。

入门指南

SDK 通过 CocoaPods 分发。CocoaPods 是一个用于 Swift 和 Objective-C 的 Cocoa 项目的开源依赖管理器。CocoaPods 使您在使用 Xcode 时轻松安装或更新新的 SDK。

您可以通过在终端中运行以下命令来在 macOS 上安装 CocoaPods 工具。

$ sudo gem install cocoapods

有关详细信息，请参阅入门指南。

将 Sojourn SDK 添加到您的 iOS 应用中

CocoaPods 用于在现有的 Xcode 项目中安装和管理依赖项。

• 创建一个 Xcode 项目，并将它保存在您的本地计算机上。
• 在项目的根目录中创建一个名为 Podfile 的文件。该文件定义了您项目的依赖项，通常称为 Podspec。
• 打开 Podfile，添加您的依赖项。这里显示了一个简单的 Podspec 示例。根据需要替换。

platform :ios, '8.0'

target '<xcode-target-name>' do
   pod 'sojourn', '~> 0.0.49'
end

• 保存文件。
• 打开终端并进入包含 Podfile 的目录

$ cd <path-to-project>

• 运行 pod install 命令。这将安装 Podspec 中指定的 SDK 及其可能依赖的所有依赖项。'pod repo update' 将首先确保您在本地缓存中有所需的版本。

$ pod repo update

$ pod install

• 打开您的应用 .xcworkspace 文件以启动 Xcode。使用此文件进行您应用的所有开发。在此之后请不要打开 xcodeproj（项目）本身。

启用项目背景位置

• 在 Xcode 中显示项目导航器（?+1）
• 确保标准编辑器可见（?+↵）
• 在项目导航器中选择项目
• 在右侧的标准编辑器中选择功能
• 打开“后台模式”选项
• 选中“位置更新”复选框
• 为应用程序的 plist 文件中以下键添加描述：NSLocationAlwaysAndWhenInUseUsageDescription，NSLocationWhenInUseUsageDescription 和/或 NSLocationAlwaysUsageDescription。通过在 XCode 的 Info 面板中添加自定义 iOS 目标属性来实现这一点。

添加SDK初始化

为了开始工作，SDK需要被初始化。为此，您需要联系支持以获取您的应用ID和服务器URL。

• 将init函数添加到您的appDelegate中的didFinishLaunchingWithOptions函数。

 
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [[Sojourn sharedService] initWithConfiguration:@"ENTER_YOUR_APPLICATION_ID" serverUrl:@"ENTER_YOUR_SERVER_URL"];
    return YES;
}

启用位置

为了启用Sojourn开始收集位置数据，您必须使用以下命令明确启用。这必须在初始化之后调用。

[Sojourn sharedService].enableLocation = YES;

自定义属性

您可以将自定义属性应用到设备记录中。现有值将被覆盖。这允许例如根据性别或团队偏好等发送更复杂的规则。

支持的数据类型：NSString、NSDate、NSNumber。

- (void)applyCustomAttributes:(NSDictionary* _Nullable)attributes

处理推送

Sojourn需要启用推送以在应用处于后台时通知用户新消息。还有许多其他系统通知是静默的。也就是说，在收到这些消息时不会显示UI。

存储推送令牌

推送令牌需要持久化，以便Sojourn能够向设备发送推送。调用以下API来存储推送。这应在每次从操作系统收到推送令牌时调用。因为它可能会改变。

- (void)storeRemoteNotificationsWithDeviceToken:(NSData *_Nullable)deviceToken

处理接收到的推送

推送通知应传递给Sojourn进行处理。无论目标接收者是谁，都可以安全地传递每个通知。

- (void)handlePush: (NSDictionary * _Nullable)userInfo fetchCompletionHandler:(PushResultBlock _Nullable) completionHandler

收件箱

收件箱包含平台上发送的0..*条消息。这些消息可能是由用户进入或离开地理围栏或信标生成的。

获取收件箱消息

获取特定设备的消息。

[[Sojourn sharedService] getInbox:0 limit:30 block:^(NSArray * _Nullable objects, NSError * _Nullable error) {
    if (!error) {
        //do something with the messages.
    }
}];

获取收件箱总数

获取收件箱中的消息总数和未读消息总数。

[[Sojourn sharedService] getInboxCount:^(int total, int unread) {
    NSLog(@"Inbox Total:%d, Unread:%d", total, unread);
}];

如果发生错误，则将-1的值传递给块处理器。

标记所有消息为已读

将收件箱中的所有消息标记为已读。

[[Sojourn sharedService] markInboxAsRead:^(BOOL succeeded, NSError * _Nullable error) {
    NSLog(@"Marked all messages as read result:%d", succeeded);
}];

标记消息为已读

将特定消息（通过其objectId标识）标记为已读。

[[Sojourn sharedService] markAsRead:message.objectId block:^(BOOL succeeded, NSError * _Nullable error) {
    NSLog(@"Marked message %@ as read result:%d", message.objectId, succeeded);
}];

删除一条信息

根据其objectId删除特定的信息。

[[Sojourn sharedService] deleteInboxMessage:message.objectId block:^(BOOL succeeded, NSError * _Nullable error) {
    NSLog(@"Delete message %@ result:%d", message.objectId, succeeded);
}];

删除所有信息

删除所有信息。

[[Sojourn sharedService] deleteAllInboxMessages:^(BOOL succeeded, NSError * _Nullable error) {
    NSLog(@"Deleted all messages result:%d", succeeded);
}];

通用数据保护条例（GDPR）

与个人相关的位置数据很可能能够识别他们的身份。因此，它构成个人数据，除非有例外适用，否则《1988年数据保护法》和《2003年数据保护法》（以下简称为“数据保护法”）适用。它也可能构成敏感数据，因此应谨慎处理。数据控制者有责任最小化收集、处理和保存的数据量，因为这些风险是由链接的位置数据引起的。

更多详情请查看：[《数据控制者关于位置数据的指引》](https://www.dataprotection.ie/docs/Guidance-Note-for-Data-Controllers-on-Location-Data/1587.htm)

在大多数情况下，获得知情同意是处理个人位置数据的最适当的基础。这强调了应用开发者向用户告知他们为何收集位置数据、他们将如何使用这些数据以及它将如何使用户受益的责任。

为确保Sojourn符合欧盟通用数据保护条例（GDPR）“被遗忘权”，我们提供API以允许用户标记其账户为已删除。这将记录用户想要被遗忘的要求，并触发一个异步过程以删除位置数据。

- (void)deleteMe:^(BOOL succeeded, NSError * _Nullable error) {
    NSLog(@"User account data marked for deletion result:%d", succeeded);
}];

故障排除

如果您的高级项目无法编译或链接，请检查您是否已经打开了xcode workspace而不是xcode project。由前面的pod步骤创建的工作区确保管理了所有依赖项。