adzerk-ios-sdk

需求

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

安装

可以使用手动构建并将框架复制到项目中，或者使用 Swift 包管理器（推荐）、Carthage 或 CocoaPods 自动安装框架。

注意，对于手动和 Carthage 框架导入，您可能需要指定“包含 Swift 代码的嵌入内容”，以避免在构建过程中出现链接器错误。另一种强制 Xcode 载入 Swift 库的方法是向您的项目添加单个 Swift 源文件。

Swift 包管理器

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

Carthage

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

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

如果您想处于最新主分支

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

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

CocoaPods

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

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

再次，如果您想处于最新主分支

use_frameworks!

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

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

示例

API 凭证 & 所需 ID

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

获取广告决策

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的请求，您可以在单个位置请求中指定此信息。

如果您需要，您可以预先设置一个自定义主机，如下所示

  DecisionSDK.host = "your custom host"

请注意，主机只是请求的域部分。不要在自定义主机中包括方案，如https://。

请求位置

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

有内置两种位置类型

标准位置
自定义位置

标准位置

为了简洁，您可以使用Placements类型创建位置。

let placement = Placements.standard(...)

自定义位置

如果您需要向服务器发送额外的JSON数据，请使用CustomPlacement。

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

此功能适用于测试版功能或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 传输安全

Adzerk 的 API 服务器符合 App 传输安全规范。

构建 / 运行测试

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

swift test

生成文档

文档使用 jazzy 生成并托管在 GitHub Pages 上。要安装 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.2.0: 支持 Swift 5.6
2.1.1: 在触发像素事件时添加对毛利总额的支持
2.1.0: 添加一般像素触发支持
2.0.2: 为 CustomPlacement 和 PlacementRequest 添加 additionalOptions 支持
2.0.1: 更新某些成员的可视性，以提高灵活性。
2.0: 使用 Swift 和 Swift 包管理器重写。这是一个重大变化，因为许多类型已经演变为更贴近 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：首次发布

adzerk-ios-sdk 2.2.0

adzerk-ios-sdk 2.2.0

adzerk-ios-sdk 2.2.0

adzerk-ios-sdk

需求

安装

Swift 包管理器

Carthage

CocoaPods

示例

API 凭证 & 所需 ID

获取广告决策

距离定位

记录曝光和点击

记录曝光

记录点击

UserDB: 读取用户记录

UserDB: 设置自定义属性

使用说明

请求位置

标准位置

自定义位置

发送请求

处理响应

GDPR同意

日志记录

App 传输安全

构建 / 运行测试

生成文档

许可证

变更日志