adzerk-ios-sdk

要求

使用 Adzerk iOS SDK 需要 iOS 10.0 或更高版本。

安装

可以通过手动构建并将框架复制到您的项目中，或通过 Swift Package Manager（首选）、Carthage 或 CocoaPods 自动安装框架。

请注意，对于手动和 Carthage 框架导入，您可能需要指定“Embedded Content Contains Swift Code”以避免在构建期间出现链接器错误。强制 Xcode 加载 Swift 库的另一种方法是将单个 Swift 源文件添加到您的项目中。

Swift Package Manager

使用 Xcode，在“项目设置”选项卡中添加一个 Swift Package。输入 URL https://github.com/adzerk/adzerk-ios-sdk.git 并单击“下一步”。选择您的版本，然后单击“继续”以集成它。

Carthage

如果您正在使用 Carthage，请将其添加到您的 Cartfile 中

github "adzerk/adzerk-ios-sdk" ~> 2.3.0

如果您想使用最新的前沿版本，可以指定 master 分支

github "adzerk/adzerk-ios-sdk" "master"

然后运行 carthage update 来获取和构建框架。您可以在 Carthage 文件夹中找到该框架，您可以手动将其添加到您的项目中。

CocoaPods

如果您正在使用 CocoaPods，请将其添加到您的 Podfile 中

pod 'adzerk-ios-sdk', '~> 2.3.0

同样，如果您想使用最新的 master 分支

use_frameworks!

pod 'adzerk-ios-sdk', github: 'adzerk/adzerk-ios-sdk', branch: 'master'

然后运行 pod install 下载代码并将其集成到您的项目中。然后，您将打开 pod 创建的工作区而不是您的项目来构建。

示例

API 凭据 & 必需的 ID

网络 ID：登录 Adzerk UI & 使用右上角的“circle-i”帮助菜单来查找网络 ID。所有 SDK 操作都需要。
站点 ID：转到管理站点页面以查找站点 ID。获取广告决策时需要。
广告类型 ID：转到广告尺寸页面以查找广告类型 ID。获取广告决策时需要。
用户密钥：UserDB ID 为每个用户指定或生成。

获取广告决策

import AdzerkSDK

// Demo network, site, & ad type IDs; find your own via the Adzerk UI!
DecisionSDK.defaultNetworkId = 23
DecisionSDK.defaultSiteId = 667480

let client = DecisionSDK()

var p = Placements.custom(divName: "div0", adTypes: [5])

var reqOpts = PlacementRequest<StandardPlacement>.Options()
reqOpts.userKey = "abc"
reqOpts.keywords = ["keyword1", "keyword2"]

client.request(placements: [p], options: reqOpts) {response in
  dump(response)
}

// or if using Swift 5.5

let response = await client.request(placements: [p], options: reqOpts)
dump(response)

距离定位

import AdzerkSDK

// Demo network, site, & ad type IDs; find your own via the Adzerk UI!
DecisionSDK.defaultNetworkId = 23
DecisionSDK.defaultSiteId = 667480

let client = DecisionSDK()

var p = Placements.custom(divName: "div0", adTypes: [5])

var reqOpts = PlacementRequest<StandardPlacement>.Options()
reqOpts.userKey = "abc"
reqOpts.additionalOptions = [
  "intendedLatitude": .float(35.91868),
  "intendedLongitude": .float(-78.96001),
  "radius": .float(50) // in km
]

client.request(placements: [p], options: reqOpts) { response in
  dump(response)
}

记录展示和点击

与上面的获取广告示例一起使用。

记录展示

// Impression pixel; fire when user sees the ad
client.request(placements: [p], options: reqOpts) {
    switch $0 {
    case .success(let response):
        for decision in response.decisions {
            print(decision.key)

            for selection in decision.value {
                dump(selection, maxDepth: 3)

                print("\nFiring impression pixel...")
                client.recordImpression(pixelURL: selection.impressionUrl!)
            }
        }

    case .failure(let error):
        print(error)
    }
}

记录点击

// Click pixel; fire when user clicks on the ad
client.request(placements: [p], options: reqOpts) {
    switch $0 {
    case .success(let response):
        for decision in response.decisions {
            print(decision.key)

            for selection in decision.value {
                dump(selection, maxDepth: 3)

                print("\nFiring click pixel...")
                client.firePixel(url: selection.clickUrl!) { response in
                    // status: HTTP status code
                    print(response.statusCode)
                    // location: click target URL
                    print(response.location)
                }

                // or if using Swift 5.5

                let response = await client.firePixel(url: selection.clickUrl!)
                print(response.statusCode)
                print(response.location)
            }
        }

    case .failure(let error):
        print(error)
    }
}

由于事件默认情况下没有收入，因此覆盖事件的收入会增加新的收入。例如

client.firePixel(url: clickUrl, override: 0.5) { ...

将事件的新值设置为 0.50 美元。

client.firePixel(url: clickUrl, additional: 1.0) { ...

将事件的值设置为 1.00 美元，或者如果事件已设置收入，则额外增加 1.00 美元。

client.firePixel(url: clickUrl, grossMerchandiseValue: 1.5) { ...

设置事件的总商品价值为 1.50 美元。

UserDB：读取用户记录

import AdzerkSDK

// Demo network ID; find your own via the Adzerk UI!
DecisionSDK.defaultNetworkId = 23

let keyStore = UserKeyStoreKeychain()
keyStore.save(userKey: "abc")

let client = DecisionSDK(keyStore: keyStore)

client.userDB().readUser() {response in
  dump(response)
}

// or with Swift 5.5

let response = await client.userDB().readUser()
dump(response)

UserDB：设置自定义属性

import AdzerkSDK

// Demo network ID; find your own via the Adzerk UI!
DecisionSDK.defaultNetworkId = 23

let keyStore = UserKeyStoreKeychain()
keyStore.save(userKey: "abc")

let client = DecisionSDK(keyStore: keyStore)

let props:[String: AnyCodable] = [
    "favoriteColor":  .string("blue"),
    "favoriteNumber": .int(42),
    "favoriteFoods":  .array([
        .string("strawberries"),
        .string("chocolate"),
    ])
]

client.userDB().postProperties(props) {response in
  dump(response)
}

用法

所有 API 操作都通过 DecisionSDK 的实例完成。

对于大多数用途，整个应用程序将使用单个网络 ID 和站点 ID。如果是这种情况，您可以在 AppDelegate 中配置一次

@import AdzerkSDK

func applicationDidFinishLaunching(...) {
  DecisionSDK.defaultNetworkId = YOUR_NETWORK_ID
  DecisionSDK.defaultSiteId = YOUR_SITE_ID
}

对于需要不同网络 ID 或站点 ID 的请求，您可以在单个展示位置请求中指定此 ID。

如果需要，您还可以提前设置自定义主机，如下所示

  DecisionSDK.host = "your custom host"

请注意，主机只是请求的域部分。请勿在您的自定义主机中包含类似 https:// 的方案。

请求展示位置

要请求展示位置，您可以构建一个符合 Placement 的类型并指定要发送的属性。

有两种内置的展示位置类型

StandardPlacement
CustomPlacement

标准展示位置

为了简洁起见，您可以使用 Placements 类型创建展示位置

let placement = Placements.standard(...)

自定义展示位置

如果您需要将其他 JSON 数据发送到服务器，可以使用 CustomPlacement

let placement = Placements.custom(...)
placement.additionalOptions = [
  "arbitraryKey": .string("value")
]

此功能对于 beta 功能或添加到 API 但尚未通过 SDK 正式支持的功能非常有用。

发送请求

// Assumes that the default network ID and site ID are already set on DecisionSDK

let sdk = DecisionSDK()
let placement = Placements.standard(divName: "div1", adTypes: [1])

sdk.request(placement: placement) { result in
    // gives you a Swift Result of type Result<PlacementResponse, AdzerkError>
}

与单个展示位置一样，您可以在请求级别发送 additionalOptions

let sdk = DecisionSDK()
let placement = Placements.standard(divName: "div1", adTypes: [1])
let opts = PlacementRequest<StandardPlacement>.Options()
opts.additionalOptions = [
  "arbitraryKey": .string("value")
]

sdk.request(placement: placement, options: opts) { result in
    // gives you a Swift Result of type Result<PlacementResponse, AdzerkError>
}

注意：完成块在主队列上调用。如果您希望在不同的队列上被回调，您可以将此队列传递给 DecisionSDK 初始化器。

处理响应

展示位置请求将接受一个完成块，该块被传递给 Result<PlacementResponse, AdzerkError> 的一个实例。

根据您的应用程序适当处理每种情况。在 .success 的情况下，您将获得一个 PlacementResponse，其中包含每个请求的展示位置的决策。

GDPR 同意

构建请求时可以指定同意偏好。例如，设置欧盟跟踪的 GDPR 同意（默认为 false）

var options = PlacementRequest<StandardPlacement>.Options()
options.consent = Consent(gdpr: false)

日志记录

默认情况下，警告和错误将定向到 os_log。您可以配置所需的日志级别

DecisionSDK.logger.level = .debug

App Transport Security

Adzerk 的 API 服务器符合 App Transport Security。

构建/运行测试

您可以使用命令行运行测试

swift test

生成文档

文档是使用 jazzy 生成的，并托管在 github 页面上。要安装 jazzy

$ gem install jazzy

如果您使用的是系统 ruby，您可能需要在上面加上 sudo 前缀.

所有文档生成都在不同的分离分支上进行。确保您的工作副本是干净的，关闭 Xcode，然后切换到 gh-pages 分支

$ git checkout gh-pages

到达那里后，工作目录的内容将成为静态 HTML 站点。运行 generate_docs.sh 脚本从 master 分支复制项目的最新版本，并在其上运行 jazzy 以生成文档 HTML

$ ./generate_docs.sh

完成后，提交更改并推送到 github

$ git add .
$ git commit -m "Update docs"
$ git push

几秒钟后，您的更改将发布在 https://adzerk.github.io/adzerk-ios-sdk 上。

许可证

此 SDK 根据 Apache 2.0 许可证发布。有关更多信息，请参阅 LICENSE。

更新日志

2.3.0：支持 JSON 响应中的空值
2.2.0：支持 Swift 5.6
2.1.1：添加在触发像素事件时对总商品价值的支持
2.1.0：添加常规像素触发支持
2.0.2：支持 CustomPlacement 和 PlacementRequest 的 additionalOptions
2.0.1：更新某些成员的可见性以允许添加灵活性。
2.0：为 Swift、Swift Package Manager 重写。这是一个重大更改，因为许多类型都已演变为更接近 Swift 风格。
1.2：添加对可配置主机名覆盖的支持
1.1：读取/更新 GDPR 同意
1.0.4：展示位置和决策的 Objective-C 兼容性修复。
1.0.3：默认情况下关闭日志记录，添加对何时/如何记录到控制台的控制。
1.0.2：可以指定 sdk 回调您的队列。默认为 DispatchQueue.main
1.0：Swift 3 支持

重大更改：Objective-C 状态代码已从 NSNumber * 更改为 NSInteger，因为 Swift 3 不再自动将 Int? 映射到 NSNumber *。

0.4：初始版本