使用 App Store Connect API 生成和读取分析报告

前言

Apple 最近推出了50多个新的分析报告，其中包含数百个新的数据点和指标，以帮助开发者了解他们的应用程序的表现情况。

这些报告包括应用商店参与度、应用商店商业、应用使用情况、框架使用情况和性能等数据。

尽管这些新数据提供了许多见解，并且可能非常有价值，但它仅通过 App Store Connect API 提供，并且检索数据的方式并不直观。

在本文中，我将向你展示如何使用 Antoine Van Der Lee 的 App Store Connect Swift SDK 访问这些新的指标。

安装 API Swift SDK

安装 App Store Connect API Swift SDK

在最新版本的 App Store Connect API 中宣布新指标后，我决定发起一个拉取请求，重新生成 App Store Connect Swift SDK 中的 Swift 接口，以包含使用最新的 App Store Connect 3.4 开放 API 规范的新端点。

这些更改已合并并发布到 SDK 的 3.2.0 版本中，这也是我们在本文中使用的版本。

要安装 App Store Connect Swift SDK，你只需将其添加为包清单文件的依赖项即可，Package.swift 配置如下：

// swift-tools-version: 5.10

import PackageDescription

let package = Package(
    name: "ASCAnalytics",
    platforms: [.macOS(.v13)],
    dependencies: [
        .package(
            url: "https://github.com/AvdLee/appstoreconnect-swift-sdk.git", 
            exact: "3.2.0"
        )
    ],
    targets: [
        .executableTarget(
            name: "ASCAnalytics", 
            dependencies: [
                .product(
                    name: "AppStoreConnect-Swift-SDK", 
                    package: "appstoreconnect-swift-sdk"
                )
            ]
        ),
    ]
)

配置 API Swift SDK

配置 App Store Connect API Swift SDK

现在 SDK 已安装，我们只需要使用 App Store Connect API 密钥对其进行配置，ASCAnalytics.swift 文件配置如下：

import AppStoreConnect_Swift_SDK
import Foundation

let configuration = try! APIConfiguration(
    issuerID: "🙈",
    privateKeyID: "🙈",
    privateKey: "🙈"
)

let provider = APIProvider(configuration: configuration)

生成分析报告

要访问新指标，你需要首先为特定应用程序生成报告请求。这可以通过获取你要为其生成报告的应用程序的 ID，然后向 /v1/analyticsReportRequests 端点发出 POST 请求来完成。

ASCAnalytics.swift 代码如下：

// MARK: - Get the ID of the app
// https://api.appstoreconnect.apple.com/v1/apps?sort=bundleId&fields%5Bapps%5D=name
let request = APIEndpoint
    .v1
    .apps
    .get(parameters: .init(sort: [.bundleID], fieldsApps: [.name]))

let appsResponse = try await provider.request(request)
let qreateAppId = appsResponse.data.first { $0.attributes?.name == "QReate - QR code generator" }.map { $0.id }

guard let qreateAppId else { exit(1) }

// MARK: - Create a new Report Request
let relationships = AnalyticsReportRequestCreateRequest.Data.Relationships(
    app: .init(data: .init(type: .apps, id: qreateAppId))
)
let attributes = AnalyticsReportRequestCreateRequest.Data.Attributes(accessType: .ongoing)
let data = AnalyticsReportRequestCreateRequest.Data(
    type: .analyticsReportRequests,
    attributes: attributes,
    relationships: relationships
)
let createRequest = AnalyticsReportRequestCreateRequest(data: data)
// https://api.appstoreconnect.apple.com/v1/analyticsReportRequests
let requestReport = APIEndpoint.v1.analyticsReportRequests
    .post(createRequest)

_ = try await provider.request(requestReport)

尽管看起来似乎很复杂，但 POST 请求的有效负载非常简单。我们只需将要为其生成报告的应用程序的 ID 指定为关系（在这种情况下是我的应用程序 QReate），以及报告的访问类型。

访问类型参数可以是以下两个值之一：

• .ongoing：最常见的报告请求类型，为所有频率的报告生成每日数据。
• .oneTimeSnapshot：一次性报告请求，用于获取历史数据。

获取所有可用的报告

进行 POST 请求后，我们可以定期检查报告请求并检索其所有可用的报告。如果我们只对特定类型的数据感兴趣，可以通过类别（在这种情况下是应用使用情况）过滤到报告端点的请求。

ASCAnalytics.swift 代码如下：

// MARK: - Read all available report requests for an app
// https://api.appstoreconnect.apple.com/v1/apps/6446048195/analyticsReportRequests?filter%5BaccessType%5D=ONE_TIME_SNAPSHOT,ONGOING&fields%5BanalyticsReportRequests%5D=accessType,reports,stoppedDueToInactivity&fields%5BanalyticsReports%5D=category,instances,name&include=reports
let readReportsRequest = APIEndpoint
    .v1
    .apps
    .id(qreateAppId)
    .analyticsReportRequests
    .get(parameters: .init(filterAccessType: [.oneTimeSnapshot, .ongoing], fieldsAnalyticsReportRequests: [.accessType, .reports, .stoppedDueToInactivity], fieldsAnalyticsReports: [.category, .instances, .name], include: [.reports]))

let allReports = try await provider.request(readReportsRequest).data

// MARK: - Get all reports for a report request
guard let reportRequestId = allReports.first?.id else { exit(1) }
// https://api.appstoreconnect.apple.com/v1/analyticsReportRequests/105262f5-0cc0-4c4f-8eed-ff56509ee135/reports?filter%5Bcategory%5D=APP_USAGE
let reportInformation = APIEndpoint
    .v1
    .analyticsReportRequests
    .id(reportRequestId)
    .reports
    .get(parameters: .init(filterCategory: [.appUsage]))

let appUsageReports = try await provider.request(reportInformation)

这将返回该应用程序的所有可用的 APP USAGE 报告列表，然后我们可以按名称检索报告，以查看我们感兴趣的数据。例如，让我们获取 App Crashes 报告的 ID，以便稍后使用它来检索其数据。

ASCAnalytics.swift 代码如下：

guard let crashesReportId = appUsageReports.data
    .filter({ $0.attributes?.name == "App Crashes" })
    .first?.id else {
    exit(1)
}

获取报告的分段

不幸的是，App Store Connect API 不会直接返回报告的数据。相反，它将数据分割成实例，这些实例是根据可用的粒度（每日、每周或每月）生成的。

而每个实例又包含多个分段，每个分段都包含一系列用于下载报告数据的 URL。

现在，让我们获取报告实例的所有分段。

ASCAnalytics.swift 代码如下：

// MARK: - Get the information for a report
// https://api.appstoreconnect.apple.com/v1/analyticsReports/r2-105262f5-0cc0-4c4f-8eed-ff56509ee135/instances
let instances = APIEndpoint
    .v1
    .analyticsReports
    .id(crashesReportId)
    .instances
    .get()
let instancesResponse = try await provider.request(instances)
guard let instanceId = instancesResponse.data.first?.id else { exit(1) }

// MARK: - Get segments
// https://api.appstoreconnect.apple.com/v1/analyticsReportInstances/3472b36d-b349-41e5-8ff2-25967428947b/segments?fields%5BanalyticsReportSegments%5D=url,checksum,sizeInBytes
let segments = APIEndpoint
    .v1
    .analyticsReportInstances
    .id(instanceId)
    .segments
    .get(fieldsAnalyticsReportSegments: [.url, .checksum, .sizeInBytes])
let segmentsResponse = try await provider.request(segments)

下载分段的数据

最后，让我们使用分段实体的 url 属性下载报告数据，并将其写入我们稍后可以读取的文件中。

ASCAnalytics.swift 代码如下：

// MARK: - Download segment file
guard let segmentURL = segmentsResponse.data.first?.attributes?.url else { exit(1) }

let (location, downloadFileResponse) = try await URLSession.shared.download(from: segmentURL)
guard let httpResponse = downloadFileResponse as? HTTPURLResponse,
      httpResponse.statusCode == 200 else {
    exit(1)
}

try FileManager.default
    .moveItem(
        at: location,
        to: URL.desktopDirectory.appending(component: "crashes.zip")
    )

完成上述所有步骤后，我们的桌面上应该会有一个名为 crashes.zip 的文件，解压后其中将包含应用崩溃报告的数据文件：

crashes 文件内容如下：

Date    App Name    App Apple Identifier    App Version    Device    Platform Version    Crashes    Unique Devices
2024-01-15    QReate - QR-code generator    6446048195    1.0.4    Desktop    macOS 13.6    1    1
2024-01-15    QReate - QR-code generator    6446048195    1.0.4    Desktop    macOS 14.2    4    4

总结

本文介绍了苹果最新推出的多个新的分析报告，其中包含数百个新的数据点和指标，帮助开发者了解其应用程序的表现情况。这些报告涵盖了诸如应用商店参与度、商业情况、应用使用情况、框架使用情况和性能等方面的数据。然而，这些数据仅通过 App Store Connect API提供，并且检索数据的方式并不直观。展示了如何使用 Antoine Van Der Lee 的 App Store Connect Swift SDK 访问这些新指标，包括安装 API Swift SDK、配置 API Swift SDK、生成分析报告、获取所有可用报告以及下载报告数据。