UbuduSDK 1.25.0

UbuduSDK 1.25.0

许可证 BSD-2-Clause
发布最新发布2019年8月

Jean-Baptiste QuesneyJean Felix TRANTomasz ZiolkowskiFrancois Kruta 维护。



UbuduSDK 1.25.0

Ubudu iOS SDK

Ubudu iOS SDK 是一款用于 iOS 的上下文交互 SDK。有关定价、功能、示例以及我们兼容 iBeacon 的强大信标的信息,请访问我们的网站 http://www.ubudu.com。使用 Ubudu SDK 进行开发完全是免费的,我们仅对超过一定阈值的活动用户收费。

系统及硬件要求

对于与 iBeacon 相关的功能

  • iOS 7.0 或更高版本(推荐使用 iOS 7.1.2 或 iOS 8.0+)
  • iPhone 4S / iPad 第 3 代 / iPad mini / iPod touch 第 5 代或更新设备

对于地理围栏

  • iOS 7.0 或更高版本
  • iPhone 4 或更新版本

I. 将 Ubudu SDK 添加到项目中

在 iOS 原生应用中开始使用 Ubudu SDK 应该是一个 5 至 10 分钟的过程。请参阅目录中的示例应用以获得完整示例。

使用 CocoaPods

这是开始使用(推荐且最简单)的方式。只需在您的 Podfile 文件中添加以下行。

pod 'UbuduSDK'

然后执行 pod install 命令。

如果您还没有在项目中使用 CocoaPods,可以通过阅读 CocoaPods 文档 来开始。

手动方式

如果您不想使用 CocoaPods,可以按照以下说明手动安装 SDK。

  1. UbuduSDK.framework 文件夹拖放到 XCode 项目的 Frameworks 文件夹中。勾选 "Copy items into destination group's folder (if needed)" 选项。

  2. 如果项目中还没有,请添加以下框架和库:

    • CoreLocation.framework
    • CoreBluetooth.framework
    • CoreData.framework
    • PassKit.framework
    • SystemConfiguration.framework
    • MobileCoreServices.framework
    • UIKit.framework
    • CoreGraphics.framework
    • Foundation.framework
    • AdSupport.framework
    • libz.dylib

如果您不知道如何将 Apple 框架添加到项目中,请按照这些说明操作

您的框架文件夹应如下所示:

Framework list
3. 在项目设置中,转到 "General" -> "Your Target" -> "Build Settings" -> "Other Linker Flags",并添加以下标志:-ObjC -all_load

Linker flag

II. 项目配置

位置权限

从 iOS 8.0 开始,需要在 Info.plist 文件中添加一个条目,指明您的应用程序需要哪种位置权限。

  • 要使用主要由SDK设计用于工作的"始终"模式,请添加NSLocationAlwaysUsageDescription键。此模式允许您的应用在接近信标时(通过信标区域监控)唤醒,而且在应用处于后台时接收详细的信标数据更新(通过信标测距)几分钟。当应用处于前台时没有任何限制。

  • 如果决定使用"使用中"模式,请添加NSLocationWhenInUseUsageDescription键。使用此模式,您的应用在接近信标时无法唤醒,在后台也无法接收详细的信标数据更新。您的应用只有在应用处于前台时才能获取详细的信标数据更新(信标测距)。

Framework list

支持两种模式(可选)

您可以通过提供这两个键来支持两种模式。在这种情况下,Ubudu SDK将默认尝试获取"始终"位置授权,但您的用户将从设备设置中有机会将应用位置授权"降级"为"使用中"

如果您更希望SDK首先请求"使用中"授权(并允许您的用户稍后升级授权为"始终"),请在SDK上设置以下选项为YES /!\ 在调用start之前 /!\

[UbuduSDK sharedInstance].requestWhenInUseAuthorization = YES;
仅支持"使用中"模式(可选)

如果您决定仅支持"使用中"模式,则只需在您的Info.plist文件中添加NSLocationWhenInUseUsageDescription键,并将上述相同的选项设置为YES,这样SDK将请求正确的授权。

[UbuduSDK sharedInstance].requestWhenInUseAuthorization = YES;
备注
The value(s) for the key(s) can be left empty, but if provided will be displayed in the alert
asking the user if he'd like to grant access to his physical location to the app.
You should provide a description of one or two line(s) of why you need to access your user's location so he will be more enclined to accept.
Warning: if you fail to properly provide the required key then the location access alert 
won't be displayed and your app will never get access to the location of the user.

其他功能

如果您计划在您的应用中使用SDK的Passbook功能,请在XCode的"功能"选项卡中启用相应的功能。

Framework list

III. 配置并启动SDK - Objective-C

  1. 在您的 AppDelegate.m 文件中添加以下语句:#import <UbuduSDK/UbuduSDK.h>

  2. 将其添加到 didFinishLaunchingWithOptions: 方法中。您需要用您在 Ubudu管理平台 上创建的应用命名空间替换。

[UbuduSDK sharedInstance].appNamespace = @"634b207ee2f313c109c58675b44324ac2d41e61e"; [UbuduSDK sharedInstance].delegate = self; NSError *error = nil; BOOL started = [[UbuduSDK sharedInstance] start:&error]; if (!started) { NSLog(@"UbuduSDK start error: %@", error); }

The delegate is the object which will be receiving all the notifications via callbacks defined in the **UbuduSDKDelegate** protocol. This might be your AppDelegate for example.  

3. To allow to the SDK to work as expected (automatic execution of the actions other than "notifications", i.e. open a web page) you need to implement the UIKit callback `application:didReceiveLocalNotification:` like this:

    ```objective-c
- (void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification
{
    [[UbuduSDK sharedInstance] executeLocalNotificationActions:notification];
}

停止SDK

如果您想停止SDK运行,请调用

[[UbuduSDK sharedInstance] stop];

停止SDK将停止更新位置和跟踪地理围栏和信标。它还将阻止系统唤醒您的应用程序(在那之后,您将没有后台支持)。

完整代码示例

以下是一个初始化和启动SDK的完整示例

// AppDelegate.m

#import <UbuduSDK/UbuduSDK.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [UbuduSDK sharedInstance].appNamespace = @"634b207ee2f313c109c58675b44324ac2d41e61e";
    [UbuduSDK sharedInstance].delegate = self;
    /* Optionally, provide the ID of your user so we can link the Ubudu user with the IDs of your information system. */
    //[UbuduSDK sharedInstance].user = [[UbuduUser alloc] initWithID:@"Your client ID" withProperties:@{@"foo_property":@"bar_value"}];
    NSError *error = nil;
    BOOL started = [[UbuduSDK sharedInstance] start:&error];
    if (!started) {
        NSLog(@"UbuduSDK start error: %@", error);
    }
}

- (void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification
{
    [[UbuduSDK sharedInstance] executeLocalNotificationActions:notification];
}

III Bis. 配置并启动SDK - Swift

一旦安装了框架或pod,您需要添加一个桥接头,这是当您想将第一个Objective-C文件添加到Swift项目时XCode自动创建的。因此,在空项目中,我们只需添加一个名为“dummy”的文件。该文件以后可以删除。

BridgingFile_add

然后Xcode会提问

dialog_x_code

此自动生成还将此头文件对应的路径添加到您的构建设置中

dialog_x_code

在名为 cocoapods-test-Bridging-Header.h 的header文件中,您可以然后导入所需的头文件 #import <UbuduSDK/UbuduSDK.h>

然后,在AppDelegate.swift中添加协议 UbuduSDKDelegate,UbuduSDK的初始化和最小回调函数。例如

import AdSupport // add AdSupport for optional profiling step

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate, UbuduSDKDelegate {

    var window: UIWindow?

    func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
        var ubuduSDK = UbuduSDK.sharedInstance() as UbuduSDK
        let namespace : NSString = "634b207ee2f313c109c58675b44324ac2d41e61e"
        ubuduSDK.appNamespace = namespace
        
        // BEGIN Optional profiling step
        // If user as enabled advertising, we add the idfa as the external id of the user
        // in order to  allow cross-application advertsing targeting. The id used by the hosting application could be used as well
        // We could also add tags which could be used to target interactions
        var idfa_mgr = ASIdentifierManager.sharedManager() as ASIdentifierManager
        var idfa_s : NSString?
        if idfa_mgr.advertisingTrackingEnabled {
            var idfa = idfa_mgr.advertisingIdentifier as NSUUID
            idfa_s = idfa.UUIDString
        }
        ubuduSDK.user = UbuduUser(ID: idfa_s, withProperties: nil, tags: nil)
        // END Optional profiling step
        
        ubuduSDK.delegate = self
        var error: NSError?
        ubuduSDK.start(&error)
        if error != nil {
            println("Error while starting Ubudu SDK")
        }
        return true
    }
    
    func application(application: UIApplication!, didReceiveLocalNotification notification: UILocalNotification!) {
        // Let the Ubudu SDK handle the notification
        UbuduSDK.sharedInstance().executeLocalNotificationActions(notification)
    }
}

命名空间值(例如上述示例中的 634b207ee2f313c109c58675b44324ac2d41e61e)是你应用在 后台管理平台 中创建的应用的命名空间。当你访问创建的应用详情中的后台网络界面时,你将找到一个与正确命名空间集成应用的示例。

SDK 默认行为 & 自定义

SDK 在进入或退出区域时可以执行 5 种类型的操作

  • 向服务器 URL 发送 HTTP 回调:服务器可以“决定”SDK 执行的下一步操作,或执行服务器端的自定义操作(例如,将条目添加到 CRM 或向客户端发送推送通知)。请注意,SDK 将自动利用一些通配符,您可以使用这些通配符识别回调中的操作。URL 示例: https://yourserver.com/push_event_to_app.json?event=exit&udid={udid}
  • 在设备上发布本地通知:本地通知可以包含消息和自定义负载,请参阅Apple 文档后台配置本地通知
  • 在网页视图中打开网页:请注意,页面可以是在线的(http:// 或 https://)或应用包中的(在这种情况下,请使用 URL 中的 file:// 协议)。 后台配置打开网页视图通知
  • 打开钱包票证:请注意,票证可以是在线的(http:// 或 https://)或应用包中的(在这种情况下,请使用 URL 中的 file:// 协议)。
  • 打开跳转链接 URL。链接可以被您的应用本身处理(在这种情况下,您需要注册 URL Scheme 并处理传入的 URL),或者打开第三方应用,例如 Twitter。

Ubudu SDK 代理

Ubudu SDK 提供回调方法,可用于控制和覆盖 SDK 的行为。

以下方法在要执行的规则的操作即将执行时调用(如果已实现)。你可以通过从您的代理实现中返回 NO 来防止执行此操作。

请在管理平台上检查您想实现以控制规则触发的功能是否已内置,这将为您节省更多工作量并更好地集成。

- (BOOL)ubudu:(UbuduSDK *)ubuduSDK shouldExecuteServerNotificationRequest:(NSURL *)url triggeredBy:(UbuduTriggerSource)trigger;

- (BOOL)ubudu:(UbuduSDK *)ubuduSDK shouldExecuteLocalNotificationRequest:(UILocalNotification *)localNotification triggeredBy:(UbuduTriggerSource)trigger;

- (void)ubudu:(UbuduSDK *)ubuduSDK shouldExecuteLocalNotificationRequest:(UILocalNotification *)localNotification triggeredBy:(UbuduTriggerSource)trigger completionBlock:(void(^)(BOOL shouldExecuteLocalNotificationRequest))completionBlock;

- (BOOL)ubudu:(UbuduSDK *)ubuduSDK shouldExecuteOpenWebPageRequest:(NSURL *)url triggeredBy:(UbuduTriggerSource)trigger;

- (BOOL)ubudu:(UbuduSDK *)ubuduSDK shouldExecuteOpenPassbookRequest:(NSURL *)passUrl triggeredBy:(UbuduTriggerSource)trigger;

- (BOOL)ubudu:(UbuduSDK *)ubuduSDK shouldExecuteOpenDeepLinkRequest:(NSURL *)url triggeredBy:(UbuduTriggerSource)trigger;

取消注释并实现以下任何方法以自定义任何类型的操作。如果您为任何动作类型使用空实现,则这些操作将不会发生,因此请仔细选择您想自定义的内容以及如何操作。

- (void)ubudu:(UbuduSDK *)ubuduSDK executeServerNotificationRequest:(NSURL *)url triggeredBy:(UbuduTriggerSource)trigger
     success:(void (^)())successHandler failure:(void (^)(NSError* error))failureHandler {
     // By default the SDK sends an HTTP request to url
}

- (void)ubudu:(UbuduSDK *)ubuduSDK executeLocalNotificationRequest:(UILocalNotification *)localNotification triggeredBy:(UbuduTriggerSource)triggeredBy {
   // That is what the SDK does by default (post the prepared local notification)
   [[UIApplication sharedApplication] presentLocalNotificationNow:localNotification];
}

- (void)ubudu:(UbuduSDK *)ubuduSDK executeOpenWebPageRequest:(NSURL *)url triggeredBy:(UbuduTriggerSource)trigger {
    // By default the SDK modally presents a view controller with a web view loading the content at url on the currently top most view controller
}

- (void)ubudu:(UbuduSDK *)ubuduSDK executeOpenPassbookRequest:(NSURL *)passbookUrl triggeredBy:(UbuduTriggerSource)trigger {
    // By default the SDK modally presents a PKAddPassesViewController loading the pass at url
}

- (void)ubudu:(UbuduSDK *)ubuduSDK executeOpenDeepLinkRequest:(NSURL *)url triggeredBy:(UbuduTriggerSource)trigger {
    // By default the SDK opens the url like this
    [[UIApplication sharedApplication] openURL:url];
}

Ubudu SDK 代理方法的实现示例

// AppDelegate.m

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    NSError *error = nil;
    [UbuduSDK sharedInstance].appNamespace = @"634b207ee2f313c109c58675b44324ac2d41e61e";
    [UbuduSDK sharedInstance].delegate = self;
    BOOL started = [[UbuduSDK sharedInstance] start:&error];
    if (!started) {
        NSLog(@"UbuduSDK start error: %@", error);
    }
    return YES;
}

#pragma mark - UbuduSDKDelegate

- (void)ubudu:(UbuduSDK *)ubuduSDK executeLocalNotificationRequest:(UILocalNotification *)localNotification triggeredBy:(UbuduTriggerSource)triggeredBy
{
    // Dumb example: this is what the SDK does by default!
    [[UIApplication sharedApplication] presentLocalNotificationNow:localNotification];
}

- (void)ubudu:(UbuduSDK *)ubuduSDK didReceiveErrorNotification:(NSError *)error;
{
    NSLog(@"Ubudu SDK Error: %@", error);
}

#pragma mark - Local Notifications

- (void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification
{
    NSString *notifType = [notification.userInfo valueForKeyPath:@"payload.type"];
    
    // If the notification contains a custom payload that we want to handle
    // In this case we display a custom alert view
    if ([notifType isEqualToString:@"order"]) {
        [self displayOrderAwaitingAlert:@"Do you want to send your order to preparation now?"];
    } else {
        UIAlertView *alert = [[UIAlertView alloc] initWithTitle:@"Notification" message:notification.alertBody delegate:nil cancelButtonTitle:@"OK" otherButtonTitles:nil];
        [alert show];
    }
    
    // Send back to the SDK the notification (that may have been received in background)
    // So it can trigger the right actions linked to the notification (open a web view or passboon pass for example)
    [[UbuduSDK sharedInstance] executeLocalNotificationActions:notification];

    // Clear the received notification
    [application cancelLocalNotification:notification];
    application.applicationIconBadgeNumber--;
}

#pragma mark - Alert

- (void)displayOrderAwaitingAlert:(NSString *)message
{
    UIAlertView *alert = [[UIAlertView alloc] init];
    [alert setTitle:@"Your order"];
    [alert setMessage:message];
    [alert setDelegate:self];
    [alert addButtonWithTitle:@"No, I'll do it later"];
    [alert addButtonWithTitle:@"Yes"];
    [alert show];
}

- (void)alertView:(UIAlertView *)alertView clickedButtonAtIndex:(NSInteger)buttonIndex
{
    if (buttonIndex == 0) {
        // No. Do nothing.
    } else if (buttonIndex == 1) {
        // Yes. Open order summary page.
        UIViewController *orderSummaryVC = [self.window.rootViewController.storyboard instantiateViewControllerWithIdentifier:@"UDOrderSummaryViewController"];
        [self.window.rootViewController presentViewController:orderSummaryVC animated:YES completion:nil];
    }
}

用户分段 - 标签

如果要针对您的用户群体中的子集进行定位,可以将任意标签(由您的业务需求定义)与用户相关联。

然后,您需要定义触发规则的条件,这一步骤可以从管理平台上的信标和地理围栏编辑页面完成。

Capabilities

在管理平台的条件下定义好之后,您需要使用Ubudu iOS SDK为您的移动用户分配标签。具体操作如下

[UbuduSDK sharedInstance].appNamespace = @"634b207ee2f313c109c58675b44324ac2d41e61e";
[UbuduSDK sharedInstance].delegate = self;

[UbuduSDK sharedInstance].user = [[UbuduUser alloc] initWithID:@"your_user_id" withProperties:@{@"foo_property": @"bar_value"} tags:@[@"female", @"under_40"]];

NSError *error = nil;
BOOL started = [[UbuduSDK sharedInstance] start:&error];
if (started == NO) {
  NSLog(@"UbuduSDK start error: %@", error);
}

如果在SDK启动后需要更新标签(或用户ID,或属性)信息,只需重新在用户对象上分配对应的属性,SDK会自动将更新后的数据发送到后台办公室。

// Could be called if the user changes his age in the settings for example
[UbuduSDK sharedInstance].user.tags = @[@"female", @"under_25"];