asc-analytics-reports

Files (1)

• SKILL.md

SKILL.md (first lines)

# asc analytics reports

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.

## 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.

## 1. Verify the CLI contract

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.

## 2. Prepare private storage

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.

## 3. Find an existing request

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` or `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.

## 4. Discover and select report instances

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" \

From rorkai/app-store-connect-cli-skills, MIT.

More from rorkai/app-store-connect-cli-skills