Blesh iOS SDK-Lite 5 开发者指南

版本： 5.0.0

本文档描述了 Blesh iOS SDK-Lite 与您的 iOS 应用程序的集成。

简介

Blesh iOS SDK-Lite 会从安装了 iOS 应用的设备中收集位置信息。Blesh 广告平台使用这些数据创建和增强受众，投放目标广告和生成洞察。

注意： Blesh iOS SDK 的轻量级版本不显示广告。其主要用途是增强受众和帮助生成洞察。

更新日志

5.0.0 (发布于 2019 年 11 月 26 日)
- 添加了初始化支持
- 添加了处理位置权限变更的回调处理器
- 支持服务器端 HTTP 压缩
- 编译成 Mac-O 宇宙二进制文件

要求

为了集成 Blesh iOS SDK-Lite，请确保以下条件

目标 iOS 版本为 9 或更高
使用 Swift 4.2.1 编译器
使用支持蓝牙 4.0 的 iOS 设备（可选。若要支持 Blesh Beacon 侦测，则必需）
在 Blesh Publisher Portal 注册
- 您可能需要在 iOS 平台上创建一个 Blesh Ads Platform Access Key

注意：请确保在 App Store Connect 上声明“您的应用使用 IDFA”。否则，您的应用可能会在审核时被拒绝。Blesh iOS SDK-Lite 从设备收集 IDFA，完全符合苹果的要求。

集成

1. 添加 Blesh iOS SDK-Lite

Blesh iOS SDK-Lite 可以通过 CocoaPods 或手动方式添加。

1.1. 使用 CocoaPods 添加 Blesh iOS SDK-Lite

在 Podfile 中参考 BleshSDKLite 版本 5.0.0，就足以将 Blesh iOS SDK 添加到项目中。

添加步骤

如果您的项目没有 Podfile，可以在终端运行以下命令来创建一个

pod init

在 Podfile 中引用 BleshSDKLite

target 'YOUR_APPLICATION_NAME' do

  # ... beginning of your Podfile ...

  pod 'BleshSDKLite', :git => 'https://github.com/bleshcom/Blesh-iOS-SDK-Lite.git', :tag => '5.0.0' # this will reference the Blesh iOS SDK-Lite 5

  # ... remaining of your Podfile ...

end

注意：请将 YOUR_APPLICATION_NAME 替换为 target 部分中的应用程序名称

在终端运行以下命令来安装 pods

pod install

1.2. 手动添加 Blesh iOS SDK-Lite

下载 SDK

您可以从以下仓库下载 SDK

https://github.com/bleshcom/Blesh-iOS-SDK-Lite.git

要集成 SDK 的特定版本，应该检出带有所需版本标签的 Git 修订版本。

将 BleshSDKLite.framework 添加到您的 Xcode 项目中

2. 添加框架

Blesh iOS SDK-Lite采用了以下框架。请确保您的项目引用了所有这些框架

Foundation.framework
UIKit.framework
AdSupport.framework
CoreBluetooth.framework
CoreLocation.framework
CoreTelephony.framework
SystemConfiguration.framework

3. 权限审查

为了提供适当的推送通知和正确的信标跟踪，您需要在应用程序安装后从应用程序用户处获取一些权限。根据iOS用户指南，应用程序可以使用自己的语句请求必需的权限。可以在Info.plist文件中配置权限。

Blesh iOS SDK使用iBeacon协议，默认情况下需要位置权限。Blesh iOS SDK需要检测信标和地理围栏，即使在应用程序处于后台或已杀死时也是如此。因此，您必须向用户请求"始终使用位置"。

在iOS 11之前，当用户授予位置使用权限时，被认为是"始终"，应用程序可以在它们被杀死或处于后台时使用位置。

从iOS 11开始，规则发生了变化，用户只在应用程序在使用时才能授予位置使用权限。因此，对于iOS v11及更高版本，应用程序必须请求两种不同类型的位置权限：WhenInUse或AlwaysAndWhenInUse。

为了保持向后兼容，您应在位置权限中包括以下三个描述符

NSLocationAlwaysAndWhenInUseUsageDescription
NSLocationWhenInUseUsageDescription
NSLocationAlwaysUsageDescription

在位置权限条目的描述字段中，我们建议您鼓励用户允许"始终使用我的位置"，以获得更好的系统性能。在下面的子部分中，我们提供了一些示例描述文本。请检查并考虑它们。

请注意，iOS版本11及更高版本，为向后兼容，您必须在Info.plist文件中包含以下3个描述符。

始终并且在使用时

此描述符用于iOS 11及更高版本。为使用和不使用时都提供权限。

示例文本："此应用使用您的位置以通知附近有趣的优惠。我们建议您选择始终选项，以便在不使用应用时也能收到优惠!"

您可以使用以下语法将其插入Info.plist文件。

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string><# insert always and when in use usage description text #></string>

始终

此描述符用于iOS 10及之前版本。为使用和不使用时都提供权限。

示例文本："此应用使用您的位置以通知附近有趣的优惠。我们建议您选择始终选项，以便在不使用应用时也能收到优惠!"

您可以使用以下语法将其插入Info.plist文件。

<key>NSLocationAlwaysUsageDescription</key>
<string><# insert always usage description text #></string>

在使用时

此描述符用于所有iOS版本。只为使用时提供权限。我们建议您警告您的用户，在收到附近优惠时性能可能非常低。

示例文本：“本应用使用您的位置信息向附近提供有趣的优惠。仅在使用时允许位置可能导致寻找附近优惠的性能不佳！”

您可以使用以下语法将其插入Info.plist文件。

<key>NSLocationWhenInUseUsageDescription</key>
<string><# insert when in use usage description text #></string>

使用

为了使用Blesh iOS SDK-Lite的功能，需要在其应用程序生命周期中的某个点启动它。

您可以选择创建并管理一个新的BleshSDK实例，或者可以通过BleshSDK.SharedInstance访问BleshSDK的单例实例。

1. 启动Blesh iOS SDK-Lite

为了在应用程序被“杀死/后台运行”时继续接收通知，调用start方法不需要应用程序处于前台。请注意，最佳实践是在应用程序代理的applicationDidFinishLaunchingWithOptions中进行Blesh的启动。

Swift

BleshSDK 包含以下对 start 方法的重写

Void start(withSecretKey: string)

Void start(withSecretKey: string, completion: ((Bool) -> Void))

Void start(withSecretKey: string, withConfiguration: BleshSdkConfiguration)

Void start(withSecretKey: string, withConfiguration: BleshSdkConfiguration, completion: ((Bool) -> Void))

Void start(withSecretKey: string, withApplicationUser: BleshSdkApplicationUser)

Void start(withSecretKey: string, withApplicationUser: BleshSdkApplicationUser, completion: ((Bool) -> Void))

Void start(withSecretKey: string, withApplicationUser: BleshSdkApplicationUser, withConfiguration: BleshSdkConfiguration)

Void start(withSecretKey: string, withApplicationUser: BleshSdkApplicationUser, withConfiguration: BleshSdkConfiguration, completion: ((Bool) -> Void))

start 方法的第一个参数始终是 Blesh 广告平台访问密钥。您可能需要在 Blesh 发布者门户 中为iOS平台创建一个，如果您在 Blesh 发布者门户 中没有账户，请联系我们 [email protected]。
completion 参数允许您在 Blesh iOS SDK-Lite 初始化成功或失败后执行您的业务逻辑。
withConfiguration 参数允许您配置 Blesh iOS SDK-Lite 的行为。BleshSdkConfiguration 类包含以下内容：

属性	类型	描述	示例
TestMode	Bool	使用测试模式（true）或使用生产模式（false）的SDK	false

注意： 默认不启用 TestMode。您可以在集成测试期间启用此模式。当此标志设置为 true 时，生产环境不会受到影响。

withApplicationUser 参数允许您通过提供有关应用程序的主要用户（订阅者）的信息来增强受众数据。您可以提供任何使订阅者在您应用程序中独一无二的信息。BleshSdkApplicationUser 类包含以下内容

属性	类型	描述	示例
UserId	String?	用户唯一的标识符（可选）	42
Gender	NSNumber?	用户性别（可选）（0表示女性或1表示男性）	0
YearOfBirth	Int?	用户出生年份（可选）	1999
Email	String?	Optional email address of the user	[email protected]
PhoneNumber	String?	Optional mobile phone number of the user	+905550000000
Other	Dictionary<String, String>?	Optional extra information for the user	nil

注意: Email 和 PhoneNumber 详细信息永远不会以纯文本形式发送到 Blesh Ads Platform。这些值始终不可逆地散列，以确保不会存储任何个人可识别信息。

示例：简单初始化（单例）

您可以通过提供 Blesh Ads Platform Access Key 来启动 Blesh iOS SDK-Lite。

BleshSDK.SharedInstance.start(withSecretKey: "YOUR-SECRET-KEY-HERE")

示例：简单初始化

您可以通过提供 Blesh Ads Platform Access Key 来启动 Blesh iOS SDK-Lite。

let bleshSdk = BleshSDK()

bleshSdk.start(withSecretKey: "YOUR-SECRET-KEY-HERE")

示例：完整初始化

let bleshSdkConfiguration = BleshSdkConfiguration(
	TestMode: false
)

let bleshSdkApplicationUser = BleshSdkApplicationUser(
	UserId: "42",
	Gender: 0,
	YearOfBirth: 1999,
	Email: "[email protected]",
	PhoneNumber: "+905550000000",
	Other: nil
)

BleshSDK.SharedInstance.start(
	withSecretKey: "YOUR-SECRET-KEY-HERE",
	withApplicationUser: bleshSdkApplicationUser,
	withConfiguration: bleshSdkConfiguration) {
		(isSuccessful: Bool) -> () in
		// ... INSERT BUSINESS LOGIC HERE ...
		NSLog(String(isSuccessful))
	}

2. 通知 Blesh iOS SDK-Lite 关于权限变化

从 Blesh iOS SDK 4.0.7 开始，该 SDK 不再要求用户进行权限请求。您的应用程序需要请求位置权限。请参阅 "审查权限" 部分了解更多信息。

Swift

当位置权限发生变化时，您的应用应该使用新状态调用 BleshSDK 的 didChangeLocationAuthorization 方法。

示例

import UIKit
import WebKit
import BleshSDKLite
import CoreLocation

class WebViewController: UIViewController, CLLocationManagerDelegate {
    var locationManager : CLLocationManager

    required init?(coder aDecoder: NSCoder) {
        self.locationManager = CLLocationManager()
        super.init(coder: aDecoder)
    }

    override func viewDidLoad() {
        super.viewDidLoad()

        self.locationManager.delegate = self
        self.locationManager.desiredAccuracy = kCLLocationAccuracyBest
        self.locationManager.distanceFilter = 10
        self.locationManager.requestWhenInUseAuthorization()
        self.locationManager.requestLocation()

        // ... rest of the method ...
    }

    public func locationManager(_ manager: CLLocationManager, didChangeAuthorization status: CLAuthorizationStatus) {
        // Notify the Blesh iOS SDK about the change here
        BleshSDK.SharedInstance.didChangeLocationAuthorization(status)
    }

    // ... rest of the controller ...
}

BleshSDK-Lite 5.0.0

BleshSDK-Lite 5.0.0

BleshSDK-Lite 5.0.0

Blesh iOS SDK-Lite 5 开发者指南

简介

更新日志

要求

集成

1. 添加 Blesh iOS SDK-Lite

1.1. 使用 CocoaPods 添加 Blesh iOS SDK-Lite

1.2. 手动添加 Blesh iOS SDK-Lite

2. 添加框架

3. 权限审查

使用

1. 启动Blesh iOS SDK-Lite

Swift

示例：简单初始化（单例）

示例：简单初始化

示例：完整初始化

2. 通知 Blesh iOS SDK-Lite 关于权限变化

Swift