使用 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、生成剖析陈述、获取一切可用陈述以及下载陈述数据。