跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
营销与销售

asc-apple-ads

Use when managing Apple Ads with asc, including OAuth profiles, ad-account discovery, Platform API v1 campaigns and targeting, reports, assets, recommendations, guarded mutations, raw requests, and Campaign Management API v5 migration.

rorkai · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add rorkai/app-store-connect-cli-skills --skill asc-apple-ads

技能说明


name: asc-apple-ads description: Use when managing Apple Ads with asc, including OAuth profiles, ad-account discovery, Platform API v1 campaigns and targeting, reports, assets, recommendations, guarded mutations, raw requests, and Campaign Management API v5 migration.

asc Apple Ads

Run Apple Ads work through asc ads. Apple Ads credentials are separate from App Store Connect credentials; asc auth login does not configure Ads.

Pick the API first

  • Direct asc ads <resource> ... commands use Apple Ads Platform API v1 and an ad account ID.
  • Deprecated Campaign Management API v5 commands live under asc ads v5 ... and use an organization ID. Apple retires v5 on January 26, 2027.
  • Never substitute an org ID for an ad account ID. The CLI keeps them separate.
  • Run the exact leaf command with --help before building a request file. Platform v1 payloads and response envelopes differ from v5; the CLI does not translate them.
  • For non-interactive pipelines, pass --file - to read a JSON request body from stdin; the CLI rejects it when stdin is a terminal.
  • Resource, report, upload, and raw commands emit lossless JSON. Use jq for projections instead of asking for table or markdown output.

Authenticate and pin the account

Store both contexts when a profile must support v1 and legacy v5:

asc ads auth login \
  --name "Marketing" \
  --client-id "$ASC_ADS_CLIENT_ID" \
  --team-id "$ASC_ADS_TEAM_ID" \
  --key-id "$ASC_ADS_KEY_ID" \
  --private-key "$ASC_ADS_PRIVATE_KEY_PATH" \
  --ad-account "987654" \
  --org "123456" \
  --network

For CI, set Ads-specific variables and bypass the host keychain:

export ASC_ADS_CLIENT_ID="SEARCHADS_CLIENT_ID"
export ASC_ADS_TEAM_ID="SEARCHADS_TEAM_ID"
export ASC_ADS_KEY_ID="KEY_ID"
export ASC_ADS_PRIVATE_KEY_PATH="$HOME/.asc/apple-ads-private-key.pem"
export ASC_ADS_AD_ACCOUNT_ID="987654"
export ASC_ADS_BYPASS_KEYCHAIN=1

ASC_ADS_PRIVATE_KEY and ASC_ADS_PRIVATE_KEY_B64 also work. If another trusted process minted a short-lived token, set ASC_ADS_ACCESS_TOKEN; scoped v1 calls still need an ad account ID.

Check auth without printing a token:

asc ads auth status --validate --output json
asc ads auth discover --ads-profile "Marketing" --output json
asc ads auth doctor --output json

Discovery calls Platform v1 GET /v1/me and GET /v1/acls. Compare each ACL's ad-account ID, name, organization ID, and roles; never select the first result automatically. Print the chosen account before any mutation, then pass both --ads-profile "Marketing" and --ad-account "987654" when more than one profile or account is available.

For named profiles, the profile's ad_account_id and org_id stand alone; they do not inherit context from another profile or root config. V1 context precedence is --ad-account, ASC_ADS_AD_ACCOUNT_ID, the selected profile, then profile-less root config. Legacy v5 uses the matching --org and ASC_ADS_ORG_ID chain.

Start read-only

Identity and ACL calls need no ad account context:

asc ads me view --ads-profile "Marketing" --output json
asc ads acls list --ads-profile "Marketing" --output json
asc ads orgs view --ads-profile "Marketing" --org-id "123456" --output json

Then prove the selected account with a small app search:

asc ads apps search \
  --ads-profile "Marketing" \
  --ad-account "987654" \
  --query "Example" \
  --limit 1 \
  --output json

App search requires at least one of --query, --cpids, or --return-owned-apps. Storefronts use comma-separated ISO alpha-2 codes. Add --paginate only when every search result is needed.

Use each resource's find command for inventory. Most v1 queries put filters, sorting, and pagination in a JSON object. A subordinate-resource filter looks like this:

{
  "filters": [
    {"field": "campaignId", "operator": "EQUALS", "value": ["campaign-id"]}
  ],
  "pagination": {"offset": 0, "pageSize": 100, "fetchTotalCount": true}
}
asc ads campaigns find --ads-profile "Marketing" --ad-account "987654" --output json
asc ads ad-groups find --ads-profile "Marketing" --ad-account "987654" --file query.json --output json
asc ads ads find --ads-profile "Marketing" --ad-account "987654" --file query.json --output json

Omitting --file from campaigns find requests the default first page. To control or exhaust the result set, use pagination.offset, pageSize, and fetchTotalCount in a query file, read the response pagination, and advance the offset until complete. This command has no --paginate flag. Platform filters use the singular value; do not copy v5 Selector fields such as conditions or plural values, which current asc rejects before auth.

The direct v1 tree also covers ad accounts and advertiser resources; app eligibility, locales, product pages, and rejection reasons; brands, business categories, locations, location groups, creatives, and assets; geographic targeting and shared budgets; reports for apps and brands; insights, suggestions, recommendations, and change history. Discover the exact leaf instead of falling back to raw HTTP:

asc ads change-history --help
asc ads suggestions --help
asc ads rejection-reasons --help
asc ads reports brands --help

Keyword queries need a selector file. Targeting keywords require an id, adGroupId, or campaignId filter. Negative keywords require id or adGroupId; campaign-level negative keywords combine campaignId with an adGroupId filter whose operator is IS_NULL.

asc ads targeting-keywords find --ads-profile "Marketing" --ad-account "987654" --file keyword-query.json --output json
asc ads negative-keywords find --ads-profile "Marketing" --ad-account "987654" --file negative-keyword-query.json --output json

Reports and optimization

V1 reports require an endpoint-specific body. Dates live under timeRange, page controls use offset and pageSize, and campaign or ad-g

阅读完整来源 ↗