asc-analytics-reports

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

asc analytics reports

asc 分析报告

Collect a complete set of analytics report segments and verify the compressed files before handing them to a separate analysis workflow. Do not interpret, aggregate, or present the report contents as part of this skill.

收集完整的分析报告分段集，并在将压缩文件移交至独立分析工作流前进行验证。本skill不负责解读、汇总或展示报告内容。

Guardrails

约束规则

Treat report inventories, signed URLs, downloaded segments, and identifiers as confidential business data.
Prefer an existing request. Creating a request changes App Store Connect state and requires an Admin-authorized profile; obtain explicit user approval before running
```
asc analytics request
```
.
Never delete or replace a request as part of collection.
Use
```
asc analytics download
```
; do not fetch or persist signed segment URLs separately.
Store private files outside the source repository with owner-only permissions.
Do not claim the collection is complete if any expected segment is missing or fails verification.

将报告清单、签名URL、已下载分段及标识符视为机密业务数据。
优先使用现有请求。创建请求会更改App Store Connect状态，且需要管理员授权的配置文件；在运行
```
asc analytics request
```
前需获得用户明确批准。
收集过程中不得删除或替换请求。
使用
```
asc analytics download
```
；不得单独获取或存储分段签名URL。
将私有文件存储在源仓库之外，并设置仅所有者可访问的权限。
若任何预期分段缺失或验证失败，不得声称收集已完成。

1. Verify the CLI contract

1. 验证CLI契约

Inspect the installed command before authentication or collection:

bash

asc analytics view --help

Continue only when help lists

--processing-date

--granularity

--paginate

, and

--include-segments

. These filters require asc 3.5.0 or newer. If either filter is absent, ask the user to upgrade. Do not substitute the deprecated

--date

flag because it uses legacy local matching rather than Apple's server-side processing-date filter.

在认证或收集前检查已安装的命令：

bash

asc analytics view --help

仅当帮助信息中列出

--processing-date

、

--granularity

、

--paginate

和

--include-segments

时才可继续。这些过滤器需要asc 3.5.0或更高版本。若缺少任一过滤器，请要求用户升级。不要使用已弃用的

--date

标志替代，因为它使用的是旧版本地匹配而非Apple的服务器端处理日期过滤器。

2. Prepare private storage

2. 准备私有存储

Create a private temporary directory outside the repository before capturing JSON or downloading segments:

bash

umask 077
ASC_ANALYTICS_DIR="$(mktemp -d "${TMPDIR:-/tmp}/asc-analytics.XXXXXX")"
mkdir -m 700 "$ASC_ANALYTICS_DIR/segments"

Redirect command output and errors into this directory. Do not paste raw inventory JSON or error output into chat, commits, issues, or pull requests.

在捕获JSON或下载分段前，在仓库外创建一个私有临时目录：

bash

umask 077
ASC_ANALYTICS_DIR="$(mktemp -d "${TMPDIR:-/tmp}/asc-analytics.XXXXXX")"
mkdir -m 700 "$ASC_ANALYTICS_DIR/segments"

将命令输出和错误重定向到该目录。不要将原始清单JSON或错误输出粘贴到聊天记录、提交记录、问题或拉取请求中。

3. Find an existing request

3. 查找现有请求

Resolve the app ID and selected asc profile, then list every request:

bash

asc --profile "$PROFILE" analytics requests \
  --app "$APP_ID" \
  --paginate \
  --output json \
  > "$ASC_ANALYTICS_DIR/requests.json" \
  2> "$ASC_ANALYTICS_DIR/requests.stderr"

Inspect the JSON structurally and select an existing usable request. Do not rely on

--state

when discovery works without it. If no usable request exists, stop and ask whether the user wants to create

ONGOING

ONE_TIME_SNAPSHOT

access. State the target app and profile before requesting approval. After approval, prefer

--reuse-existing

to avoid duplicates:

bash

asc --profile "$APPROVED_PROFILE" analytics request \
  --app "$APP_ID" \
  --access-type "$ACCESS_TYPE" \
  --reuse-existing \
  --output json \
  > "$ASC_ANALYTICS_DIR/request.json" \
  2> "$ASC_ANALYTICS_DIR/request.stderr"

Do not run that command without explicit approval. Read the returned request ID from the private JSON response before continuing:

bash

REQUEST_ID="$(jq -er '.requestId' "$ASC_ANALYTICS_DIR/request.json")"

When a request was created or reused with the approved profile, set

ANALYTICS_PROFILE="$APPROVED_PROFILE"

. For an existing request discovered with the read-only profile, set

ANALYTICS_PROFILE="$PROFILE"

. Use that same profile for every subsequent

analytics view

and

analytics download

call.

解析应用ID和选定的asc配置文件，然后列出所有请求：

bash

asc --profile "$PROFILE" analytics requests \
  --app "$APP_ID" \
  --paginate \
  --output json \
  > "$ASC_ANALYTICS_DIR/requests.json" \
  2> "$ASC_ANALYTICS_DIR/requests.stderr"

从结构上检查JSON并选择一个可用的现有请求。当无需使用

--state

即可完成发现时，不要依赖该参数。若没有可用请求，请停止操作并询问用户是否要创建

ONGOING

或

ONE_TIME_SNAPSHOT

访问权限。在请求批准前说明目标应用和配置文件。获得批准后，优先使用

--reuse-existing

以避免重复：

bash

asc --profile "$APPROVED_PROFILE" analytics request \
  --app "$APP_ID" \
  --access-type "$ACCESS_TYPE" \
  --reuse-existing \
  --output json \
  > "$ASC_ANALYTICS_DIR/request.json" \
  2> "$ASC_ANALYTICS_DIR/request.stderr"

未经明确批准不得运行该命令。从私有JSON响应中读取返回的请求ID后再继续：

bash

REQUEST_ID="$(jq -er '.requestId' "$ASC_ANALYTICS_DIR/request.json")"

当使用已批准的配置文件创建或复用请求时，设置

ANALYTICS_PROFILE="$APPROVED_PROFILE"

。若使用只读配置文件发现了现有请求，则设置

ANALYTICS_PROFILE="$PROFILE"

。后续所有

analytics view

和

analytics download

调用都使用同一个配置文件。

4. Discover and select report instances

4. 发现并选择报告实例

First retrieve report and instance metadata without segment URLs:

bash

asc --profile "$ANALYTICS_PROFILE" analytics view \
  --request-id "$REQUEST_ID" \
  --paginate \
  --output json \
  > "$ASC_ANALYTICS_DIR/discovery.json" \
  2> "$ASC_ANALYTICS_DIR/discovery.stderr"

Select an available

processingDate

and the granularity requested by the user. Accept

DAILY

WEEKLY

, and

MONTHLY

, individually or as a comma-separated list. Split the input on commas, trim each token, and normalize it to uppercase. Validate every token against that allowlist, including empty tokens. Report the invalid input and stop before running

analytics view

; never silently discard unsupported values or continue with an empty filter. After validation, remove duplicates and join the remaining values with commas. Treat

processingDate

as the date Apple processed the report, not necessarily the period represented by its rows.

Retrieve the filtered inventory, including all segment metadata:

bash

asc --profile "$ANALYTICS_PROFILE" analytics view \
  --request-id "$REQUEST_ID" \
  --processing-date "$PROCESSING_DATE" \
  --granularity "$GRANULARITY" \
  --paginate \
  --include-segments \
  --output json \
  > "$ASC_ANALYTICS_DIR/inventory.json" \
  2> "$ASC_ANALYTICS_DIR/inventory.stderr"

Always use

--paginate

; asc follows Apple-provided report and instance next links. Do not reconstruct, alter, or follow pagination URLs manually.

首先获取不含分段URL的报告和实例元数据：

bash

asc --profile "$ANALYTICS_PROFILE" analytics view \
  --request-id "$REQUEST_ID" \
  --paginate \
  --output json \
  > "$ASC_ANALYTICS_DIR/discovery.json" \
  2> "$ASC_ANALYTICS_DIR/discovery.stderr"

选择一个可用的

processingDate

和用户要求的粒度。接受

DAILY

、

WEEKLY

和

MONTHLY

，可单独选择或用逗号分隔的列表形式。按逗号拆分输入，修剪每个标记并将其标准化为大写。对照该允许列表验证每个标记，包括空标记。若输入无效则报告并停止运行

analytics view

；不得静默丢弃不支持的值或使用空过滤器继续。验证完成后，移除重复项并将剩余值用逗号连接。注意

processingDate

是Apple处理报告的日期，不一定是报告行所代表的时间段。

获取包含所有分段元数据的过滤后清单：

bash

asc --profile "$ANALYTICS_PROFILE" analytics view \
  --request-id "$REQUEST_ID" \
  --processing-date "$PROCESSING_DATE" \
  --granularity "$GRANULARITY" \
  --paginate \
  --include-segments \
  --output json \
  > "$ASC_ANALYTICS_DIR/inventory.json" \
  2> "$ASC_ANALYTICS_DIR/inventory.stderr"

始终使用

--paginate

；asc会遵循Apple提供的报告和实例下一页链接。不得手动重建、修改或跟随分页URL。

5. Download every segment

5. 下载所有分段

Parse

inventory.json

structurally. For every selected instance, enumerate all segments and retain each segment's exact ID,

sizeInBytes

, and

checksum

for verification. Do not print

downloadUrl

Download each segment by its request, instance, and segment IDs. Use a filename derived only from the segment ID and keep the compressed bytes intact. Analytics reports are tab-delimited text, so use

.txt.gz

rather than implying CSV:

bash

SEGMENT_FILE="$ASC_ANALYTICS_DIR/segments/$SEGMENT_ID.txt.gz"
asc --profile "$ANALYTICS_PROFILE" analytics download \
  --request-id "$REQUEST_ID" \
  --instance-id "$INSTANCE_ID" \
  --segment-id "$SEGMENT_ID" \
  --output "$SEGMENT_FILE" \
  > /dev/null \
  2>> "$ASC_ANALYTICS_DIR/download.stderr"

Do not use

--decompress

before verification. If an instance has multiple segments, download every one; never treat the first segment as the whole report.

从结构上解析

inventory.json

。对于每个选定的实例，枚举所有分段并保留每个分段的准确ID、

sizeInBytes

和

checksum

用于验证。不得打印

downloadUrl

。

通过请求ID、实例ID和分段ID下载每个分段。仅使用分段ID生成文件名，并保持压缩字节完整。分析报告是制表符分隔的文本，因此使用

.txt.gz

而非暗示CSV格式：

bash

SEGMENT_FILE="$ASC_ANALYTICS_DIR/segments/$SEGMENT_ID.txt.gz"
asc --profile "$ANALYTICS_PROFILE" analytics download \
  --request-id "$REQUEST_ID" \
  --instance-id "$INSTANCE_ID" \
  --segment-id "$SEGMENT_ID" \
  --output "$SEGMENT_FILE" \
  > /dev/null \
  2>> "$ASC_ANALYTICS_DIR/download.stderr"

验证前不得使用

--decompress

。若一个实例有多个分段，则需下载所有分段；不得将第一个分段视为完整报告。

6. Verify the downloaded files

6. 验证已下载文件

For each file, compare the compressed byte count with

sizeInBytes

and the lowercase MD5 digest with

checksum

. Use local system tools such as:

bash

actual_size="$(wc -c < "$SEGMENT_FILE" | tr -d ' ')"
actual_md5="$(openssl dgst -md5 -r "$SEGMENT_FILE" | awk '{print tolower($1)}')"
expected_md5="$(printf '%s' "$CHECKSUM" | tr '[:upper:]' '[:lower:]')"

Require

actual_size

to equal

sizeInBytes

and

actual_md5

to equal

expected_md5

. On a mismatch, mark that segment failed, keep the raw error private, and do not claim a complete collection.

asc analytics download

refuses to overwrite an existing output, so retry the failed segment once to a new path such as

$ASC_ANALYTICS_DIR/segments/$SEGMENT_ID.retry-1.txt.gz

. Verify the retry independently and use it only if both checks pass. Keep the original failed file unless the user approves its deletion. Do not parse or analyze a file until verification succeeds.

对于每个文件，将压缩字节数与

sizeInBytes

对比，将小写MD5摘要与

checksum

对比。使用本地系统工具，例如：

bash

actual_size="$(wc -c < "$SEGMENT_FILE" | tr -d ' ')"
actual_md5="$(openssl dgst -md5 -r "$SEGMENT_FILE" | awk '{print tolower($1)}')"
expected_md5="$(printf '%s' "$CHECKSUM" | tr '[:upper:]' '[:lower:]')"

要求

actual_size

等于

sizeInBytes

且

actual_md5

等于

expected_md5

。若不匹配，标记该分段验证失败，保留原始错误信息不公开，且不得声称收集已完成。

asc analytics download

会拒绝覆盖现有输出，因此可将失败的分段重新下载到新路径，例如

$ASC_ANALYTICS_DIR/segments/$SEGMENT_ID.retry-1.txt.gz

。独立验证重新下载的文件，仅当两项检查都通过时才可使用。除非用户批准删除，否则保留原始失败文件。验证成功前不得解析或分析文件。

7. Report the result

7. 报告结果

Return a concise summary containing:

the selected processing date and granularity values;
counts of reports, instances, expected segments, downloaded segments, and verified segments;
whether the collection is complete;
failed or missing segment IDs, if any, without signed URLs or report rows;
the private output directory when appropriate for the current user session.

Do not include analytics values, signed URLs, profile names, credentials, or raw rows in a public artifact. Keep the verified files for the user's next workflow. Ask before deleting the temporary directory or any downloaded evidence.

返回简洁的摘要，包含：

选定的处理日期和粒度值；
报告、实例、预期分段、已下载分段和已验证分段的数量；
收集是否完成；
若有失败或缺失的分段ID，仅列出ID，不包含签名URL或报告行；
适用于当前用户会话的私有输出目录路径。

不得在公开工件中包含分析数值、签名URL、配置文件名称、凭证或原始行。保留已验证的文件供用户进行下一个工作流操作。删除临时目录或任何已下载的证据前需征得用户同意。