AppleSearchAds

AppleSearchAds 是一个框架，使您能够使用来自 Apple 的 Apple Search Ads API。

CI

安装

您可以通过将 swift-apple-search-ads-api 作为软件包添加到您的 Xcode 项目中。

https://github.com/mihai8804858/swift-apple-search-ads-api

如果您想在 SwiftPM 项目中使用 swift-apple-search-ads-api，只需将其添加到您的 Package.swift 中即可

dependencies: [
    .package(url: "https://github.com/mihai8804858/swift-apple-search-ads-api", branch: "main")
]

然后将产品添加到任何需要访问该库的目标中

.product(name: "AppleSearchAds", package: "swift-apple-search-ads-api")

入门

请参阅 为 Apple Search Ads API 实施 OAuth，了解身份验证过程的工作原理。

邀请用户

API 的访问通过 API 用户完成。帐户管理员使用以下流程邀请具有 API 权限的用户

生成私钥

API 用户需要创建私钥。如果您使用的是 MacOS 或类似 UNIX 的操作系统，OpenSSL 可以原生工作。如果您在 Windows 平台上，则需要下载 OpenSSL。

openssl ecparam -genkey -name prime256v1 -noout -out private-key.pem

生成的 private-key.pem 文件类似于以下示例

-----BEGIN EC PRIVATE KEY-----
MHcCAQEEIKtnxllRY8nbndBQwT9we4pEULtjpW605iwvzLlKcBq4oAoGCCqGSM49
AwEHoUQDQgAEY58v74eQFyLtu5rtCpeU4NggVSUQSOcHhN744t0gWGc/xXkCSusz
LaZriCQnnqq4Vx+IscLFcrjBj+ulZzKlUQ==
-----END EC PRIVATE KEY-----

重要提示

始终确保您的私钥安全，切勿共享。如果您的私钥泄露，您需要重新创建私钥和客户端密钥，并将其重新上传到您的 Apple Search Ads 帐户。

提取公钥

使用以下命令从您持久化的私钥中提取公钥

openssl ec -in private-key.pem -pubout -out public-key.pem

在文本编辑器中打开 public-key.pem 文件，并复制公钥，包括起始行和结束行。

上传公钥

按照以下步骤上传您的公钥

clientId SEARCHADS.aeb3ef5f-0c5a-4f2a-99c8-fca83f25a9
teamId SEARCHADS.hgw3ef3p-0w7a-8a2n-77c8-scv83f25a7
keyId a273d0d3-4d9e-458c-a173-0db8619ca7d7

用法

导入 SDK

import AppleSearchAds

创建 API 配置

您将需要客户端 ID、团队 ID、密钥 ID 和私钥来创建 API 配置。

在文本编辑器中打开私钥，并复制 -----BEGIN EC PRIVATE KEY----- 和 -----END EC PRIVATE KEY----- 之间的内容，同时删除内容中的任何换行符。

使用私钥创建配置

let configuration = try APIConfiguration(
  clientIdentifier: "<CLIENT-ID>",
  teamIdentifier: "<TEAM-ID>",
  keyIdentifier: "<KEY-ID>",
  privateKey: "PRIVATE-KEY"
)

也可以使用私钥的文件 URL 创建 API 配置

let configuration = try APIConfiguration(
  clientIdentifier: "<CLIENT-ID>",
  teamIdentifier: "<TEAM-ID>",
  keyIdentifier: "<KEY-ID>",
  privateKeyURL: URL(string: "<PRIVATE-KEY-URL>")!
)

初始化器还接受一个可选的 jwtExpirationDuration 参数，用于定义 JWT 过期时长，默认为 1 天。最大允许值为 180 天。

let configuration = try APIConfiguration(
  clientIdentifier: "<CLIENT-ID>",
  teamIdentifier: "<TEAM-ID>",
  keyIdentifier: "<KEY-ID>",
  privateKey: "PRIVATE-KEY",
  jwtExpirationDuration: 86400 * 7 // 7 days
)

创建 API 提供程序

let provider = APIProvider(configuration: configuration)

执行请求

let campaigns = try await provider.listCampaigns()

部分获取

部分获取指示在获取数据时要在响应中返回哪些属性。当 Selector 可用时，通过使用可选的字段参数来限制每个返回记录中的字段，从而使用部分获取。例如，您可以选择仅返回每个广告系列的 id 和 name。

重要提示

由于部分获取限制了返回的字段，因此您应该根据您正在筛选的字段创建自己的可解码类型，并将这些类型与 Selector 一起使用。

struct MyCampaignModel: Decodable, Sendable {
  let id: Int
  let name: String
}

let campaigns = try await provider.findCampaigns(
  selector: Selector(fields: [.id, .name]),
  decoding: MyCampaignModel.self
)

这将执行以下 GET 请求

GET https://api.searchads.apple.com/api/v5/campaigns?fields=id,name

这将导致以下响应

{
    "data": [
        {
            "id": 542370539,
            "name": "Campaign example 1"
        },
        {
            "id": 542370549,
            "name": "Campaign example 2"
        }
    ],
    "pagination": {
        "totalResults": 2,
        "startIndex": 0,
        "itemsPerPage": 20
    },
    "error": null
}

分页响应

如果 API 请求的响应可以分多页交付，您可以使用 AsyncSequence 迭代所有页面，或者单独请求当前页面的下一页。

for try await page in provider.pages(size: 20, request: { provider, pagination in
  try await provider.listCampaigns(pagination: pagination)
}) {
  print(page)
}

速率限制

Apple Search Ads Campaign Management API 中存在速率限制，以避免在有限时间内 API 调用过多而导致的延迟和其他系统问题。对于在其环境中使用自动重试逻辑的 API 用户，Apple 的解决方案是要求重试逻辑以秒为单位呈指数级增加重试尝试次数。例如，如果您的默认最小重试等待时间为 2 秒，则下一次重试等待时间为 4 秒，依此类推。

此 SDK 自动处理达到速率限制错误 (429) 并实现指数退避（最多 16 秒）

许可证

此库在 MIT 许可证下发布。有关详细信息，请参阅 LICENSE。