设置

将依赖项添加到您的项目

CocoaPods

将以下行添加到您的 podfile

pod 'ForceCuBeSDK'

老式静态库

从我们的 仓库 下载二进制文件 libForceCuBe.a、资源包和头文件，并将它们添加到您的 XCode 项目中。

转到 Target -> Build Phases -> Link Binary With Libraries。将 libForceCuBe.a 添加到列表中。

将所有需要的框架添加到相同的列表中

• AdSupport
• CoreBluetooth
• CoreLocation

相应地更改头文件搜索路径以包含 ForceCuBe 头文件目录。

安装 libForceCuBe.a 依赖项

• Reachability
• CocoaLumberjack

转到 Target -> Build Phases -> Copy Bundle Resources。将 ForceCuBeResources.bundle 添加到列表中。

配置应用的模式和权限

开启后台模式

转到 Target -> Capabilities -> Background Modes。开启

• 位置更新
• 使用蓝牙 LE 设备

请求始终使用位置服务的权限

您的应用程序将使用用户的地理位置信息，即使在后台模式下也是如此。因此，您需要将 NSLocationAlwaysUsageDescription 键添加到应用程序的 .plist 中。

建议值

ru-RU

我们需要访问您的位置信息，以便向您提供最有价值和相关的折扣优惠

en

我们需要访问您位置，以便为您提供最相关和最有价值的折扣优惠

请求显示通知的权限

您的应用程序应请求用户的权限以显示带有徽章和声音的警报。

- (BOOL) application: (UIApplication *) application didFinishLaunchingWithOptions: (NSDictionary *) launchOptions
{
    ...
    if ([UIApplication instancesRespondToSelector: @selector (registerUserNotificationSettings:)])
    {
        [application registerUserNotificationSettings: [UIUserNotificationSettings settingsForTypes: UIUserNotificationTypeAlert | UIUserNotificationTypeBadge | UIUserNotificationTypeSound
                                                                                         categories: nil]];
    }

    ...
    return YES;
}

集成演示应用

我们构建了一个演示应用来展示SDK的集成和使用。

使用

初始化

从ForceCuBe获取APP_DEV_KEY和APP_DEV_SECRET。请联系我们[email protected]。

创建一个ForceCuBe类的实例，传递上述提到的APP_DEV_KEY和APP_DEV_SECRET。你还应传递一个externalId，这是一个用于在您的应用程序的分析/后台系统中识别设备的id。它将用于调试和数据匹配的目的。

[[ForceCuBe alloc] initWithAppDeveloperKey: @"YOUR APP DEV KEY"
                        appDeveloperSecret: @"YOUR APP DEV SECRET"
                                externalId: @"YOUT EXTERNAL ID HERE"];

现在您可以通过调用它的start方法来启动SDK初始化过程。当首次启动时，SDK需要注册新的应用实例并下载服务器数据，包括信标列表和其他信息。

处理SDK状态变化和错误

仔细监听SDK状态的变化。如果您收到FCBStatusStopped，请检查error码以了解问题的原因。如果您收到FCBStatusStartedWithGeofencing，则表示蓝牙已关闭，SDK将使用地理围栏来发送优惠。当状态为FCBStatusStarted时，SDK使用的是全功率模式。

- (void) forceCuBe: (ForceCuBe *) fcb didChangeStatus: (FCBStatus) status error: (NSError *) error
{
    if (status == FCBStatusStopped)
    {
        if (error.code == kFCBUserErrorBackgroundLocationTrackingIsOff)
        {
            [self showAlertWithTitle: @"Error" message: @"Access to user location in background is denied."];
        }
        else if (error.code == kFCBNoNetworkOnInitError)
        {
            [self showAlertWithTitle: @"Error" message: @"No network access while initializing"];
        }
        else if (error.domain == kFCBServerErrorDomain)
        {
            [self showAlertWithTitle: @"Error" message: @"Server error while initializing"];
        }
        else if (error.code == kFCBUnrecoverableErrorAuthFailure)
        {
            [self showAlertWithTitle: @"Error" message: @"Wrong dev key or/and dev secret"];
        }
        else if (error.domain == kFCBRegionMonitoringErrorDomain)
        {
            [self showAlertWithTitle: @"Error" message: @"Failed to start location manager, please restart."];
        }
        else if (error.code == kFCBUnrecoverableErrorBLEIsUnsupported)
        {
            [self showAlertWithTitle: @"Error" message: @"BLE is not supported on this device"];
        }
        else if (error.code == kFCBUnrecoverableErrorBLEAccessIsUnauthorized)
        {
           [self showAlertWithTitle: @"Error" message: @"App doesnt have permission to access BLE"];
        }
    }
    else if (status == FCBStatusStartedWithGeofencing)
    {
        [self showAlertWithTitle: @"Warning" message: @"Bluetooth is off."];
    }
}

详细说明SDK的错误域和错误，请参阅FCBErrors.h。

优惠传递

当手机位于正确位置时，SDK将触发一个回调manager:didDeliverCampaignOffer:。回调可以通过基于GPS的地理围栏或通过BLE广告数据包触发。

您的应用程序应为FCBCampaignManager对象设置一个适当的委托。

- (void) manager: (id<FCBCampaignManager>) campaignManager
didDeliverCampaignOffer: (id<FCBCampaignOffer>) campaignOffer
{
    UILocalNotification * ln = [UILocalNotification new];

    ln.alertBody = [campaignOffer.notificationText stringByReplacingOccurrencesOfString: @"%" withString: @"%%" options: 0  range: NSMakeRange(0, campaignOffer.notificationText.length)];
    ln.soundName = UILocalNotificationDefaultSoundName;
    ln.userInfo = @{ kNotificationCampaignIdKey: @(campaignOffer.campaignOfferId)};
    ln.applicationIconBadgeNumber = campaignManager.unopenedOffers.count;

    [[UIApplication sharedApplication] presentLocalNotificationNow: ln];
}

在优惠的通知Text中应转义'%'并将通知的userInfo设置为在之后正确处理它。

-(void) application: (UIApplication *) application didReceiveLocalNotification: (UILocalNotification *) notification
{
    if (notification.userInfo[kNotificationCampaignIdKey])
    {
        NSUInteger campaignId = [notification.userInfo[kNotificationCampaignIdKey] integerValue];

        // Show offer controller
    }    
}

您可以通过FCBCampaignManager实例的campaignOfferById:方法获取优惠详情。

在通知发送后，优惠活动状态设置为kFCBCampaignStatusPresented，并将其放入未开优惠列表中。

之后，用户可以保存优惠以备将来兑换，在这种情况下调用setCampaignOfferAsAccepted:或拒绝它（调用setCampaignOfferAsDeclined:）。

如果用户接受优惠，它将被添加到已接受优惠集合中。您应使用此集合向用户显示已接受的优惠列表。

获取用户接受的优惠列表

您应使用已接受优惠集合来显示用户接受的优惠列表。集合中的每个项目都支持FCBCampaignOffer协议。

显示优惠详情和管理兑换过程

首先，您应该从ForceCuBe获取FCBDataWriter实例。

当用户点击'兑换'按钮或以其他方式开始兑换过程时，应用程序应设置适当的数据写入上下文。

dataWriter.campaignOfferId = campaignOfferId;
dataWriter.delegate = self;

您还必须为FCBDataWriter实现一个委托。

- (void) dataWriterDidStartDataWriting: (id<FCBDataWriter>) dataWriter
{
    // Show activity indicator to the user
}

- (void) dataWriter: (id<FCBDataWriter>) dataWriter didFailToStartWritingWithError: (NSError *) error
{
    // Something bad happend, show error

    // Clear data writing context
    dataWriter.campaignOfferId = kFCBDataWriterCampaignOfferIdNotSet;
    dataWriter.delegate = nil;
}

- (void) dataWriter: (id<FCBDataWriter>) dataWriter didFinishWritingWithError: (NSError *) error
{
    if (error)
    {
        // Something bad happend, show error
    }
    else
    {
        // Everything went fine, yay!
    }

    // Clear data writing context
    dataWriter.campaignOfferId = kFCBDataWriterCampaignOfferIdNotSet;
    dataWriter.delegate = nil;
}

有关数据写入错误域和错误代码的详细说明，请参阅FCBDataWriterErrors.h。

如果用户兑换优惠券，它将从acceptedOffers列表中移除。

优惠券提醒

当用户进入可以使用的特定位置时，其中已接受优惠券，SDK将发送回调manager:hasAcceptedOffers:forCurrentLocation:advertisers。回调携带多个参数：可附近使用的优惠券列表，当前位置（含名称），接受该优惠券的广告商的列表。以下是一个典型的处理此回调的代码示例：

- (void) manager: (id<FCBCampaignManager>)campaignManager hasAcceptedOffers: (NSArray<id<FCBCampaignOffer>> *)campaignOffers forCurrentLocation:(id<FCBLocation>)location advertisers: (NSArray<id<FCBAdvertiser>> *) advertisers
{
    UILocalNotification * ln = [UILocalNotification new];

    NSString * names = [[advertisers valueForKey: @"name"] componentsJoinedByString: @","];

    ln.alertBody = [NSString stringWithFormat: @"You have saved offers in %@ from %@", location.name, names];
    ln.soundName = UILocalNotificationDefaultSoundName;

    [[UIApplication sharedApplication] presentLocalNotificationNow: ln];
}

运行时设置

运行时设置包括：

• 日志级别
• 服务器轮询模式
• 接受优惠券提醒政策

应用开发者可以修改这些设置以简化集成。服务器轮询模式确定SDK检索服务器数据（即能够多快从FCB服务器获取新优惠）的频率。提醒策略确定提醒的触发条件——自接受优惠以来经过的时间以及提醒的允许频率。