feat(apps): track the app store tags apple assigns to tracked apps
Maintainers usually reply within 1 day
@MrAdex77 is already working on this.
Since Oct 22, 2026.
Assessment
This issue has not been assessed yet.
Description
Problem
Since iOS 26 the App Store attaches tags to every app: short labels Apple generates with a model from the listing's metadata, shown on product pages and as tappable groups in search results, rolled out in the United States first. A tag is a new indexed surface that the developer did not write and cannot write; the only control is opting out of a tag through App Store Connect. AsoBeast, which exists to watch every surface a listing is judged on, does not see them.
- A listing change can gain or lose a tag without any field AsoBeast diffs having changed in a way that explains it, so the changes timeline cannot say why search exposure moved.
- A developer learns which tags Apple assigned only by opening App Store Connect, and never learns which tags competitors carry, so there is no way to notice that every competitor is grouped under a tag the own listing's words do not support.
- Coverage judges a keyword against the title, subtitle, description, keyword field and screenshot captions. A tag is a phrase Apple itself derived from those fields; if the own app is missing a tag the competitors share, that is the most direct evidence available that the listing does not say what the category expects.
- No ASO tool tracks tags yet, so this is a distinctive feature at a point where the data is new.
What is verified: the App Store Connect API lists an app's tags at GET /v1/apps/{id}/appTags and PATCH /v1/appTags/{id} opts out of one (both since API 4.1.0; 4.5 deprecated the per territory relationship). The public web product page at apps.apple.com does not carry the tags: two United States listings fetched on 2026-10-15 contain no tag data in their server rendered page data. So the owner's own tags are readable with the key that #269 and #368 already plan to store, while competitor tags have no public source today and need one before anything is built on them.
This affects every owner of a primary App Store app in a storefront where tags are shown, and competitor tags would affect everyone who tracks competitors.
Proposed solution
Two pull requests, the second conditional on a finding.
Phase 1: the own app's tags (branch feat/app-store-tags, depends on the App Store Connect connection from #269 or #368)
- Every daily run reads the tags of each connected primary App Store app through
GET /v1/apps/{id}/appTags, through thestore-connectqueue and never through the store request budget, and stores them in a tenant ownedAppTagtable (RLS,@@unique([appId, tagId])) with the tag's name, whether it is opted out, and the dates it was first and last seen. A tag that disappears from the answer keeps its row with aremovedAt. - A new
ChangeFieldmembertagsis recorded inChangeEventwhen the set changes, with the added and removed names indetail, so the changes timeline, the change impact report and thechange_impactMCP tool see a tag change like any other field, and ametadata.changedalert carries it. Adding a member toCHANGE_FIELDSis additive. - The metadata page shows the tags beside the listing fields with the opt out state, and the keyword coverage matrix gains a
tagssurface: a tracked keyword whose normalized text appears in a tag is covered there. A tag is reported, never written, and coverage from a tag is listed separately from the indexed fields the way screenshot captions are, because Apple has not said that tag text is searchable. - A guide section explains where tags come from, that they cannot be added, and that opting out is done in App Store Connect; AsoBeast never calls the
PATCH.
Phase 2: competitor tags (branch feat/competitor-app-store-tags, only if a public source exists)
- Step one is research, not code: find whether the tags are served by any public endpoint the provider may read under the existing request budget, for example the storefront's search response or the product page in another rendering. The finding is written up in
plan/with the request cost per app. If no public source exists the phase is closed as not possible and the issue says so. - If one exists:
AppSnapshotgains the tag list read alongside the listing it already captures, for the own app and every competitor in every captured market, at no extra request when the source is the page or search response already fetched. Competitor tag changes are recorded inChangeEventlike every competitor change. - The competitors page shows a tag matrix: every tag any app in the set carries, which apps carry it, and the ones the own app lacks. A new Action Center rule
listing.add_tag_wordsopens when at least a named share of competitors share a tag whose words are absent from the own listing's indexed fields, naming the words; it is a pure function with boundary tests and its fingerprint carries the rule, the app, the country and the tag name.
Everything is additive: a new table, a new ChangeField member, a new coverage surface, a new rule. No existing field changes and no MCP tool is narrowed.
Out of scope
- Opting out of a tag from AsoBeast. It is a one click action in App Store Connect and a write to the store, which stays with #269.
- Treating a tag as an indexed field in
uncovered, the keyword field suggestion or the regression rules until Apple documents that tag text is searchable. - Google Play, which has no equivalent surface.
- Localized tag names per storefront beyond what the API answers.
Acceptance criteria
- Without a connection no tag is read, the metadata page shows no tag section and nothing is recorded.
- A daily run stores every tag the API answers, marks a vanished tag removed rather than deleting it, and never records a change when the set is unchanged.
- A changed set records one
tagschange event with the added and removed names, visible in the timeline, the change impact report and the alert payload, and the existing change fields are untouched. - A tracked keyword whose text appears in a tag is shown as covered by a tag, listed apart from the indexed fields, and does not alter
uncovered, the keyword field suggestion or any Action Center rule. - Phase 2 starts with a written finding on the public source and its request cost; without a source, nothing in phase 2 is built.
- If built, competitor tags cost no request beyond the listing capture that already runs, the rule opens and closes on its named thresholds and its fingerprint excludes every magnitude.
- The new table carries a
tenant_isolationpolicy and the isolation suite covers it; no test calls Apple. - The guide, the OpenAPI document and the MCP tool reference describe the new surface.
Alternatives considered
- Read competitor tags from the public page now. Checked and not possible: the server rendered product page carries no tag data as of 2026-10-15. Building on an assumption would ship a feature that records nothing.
- Skip the own tags and wait for a competitor source. The own tags are available today with a credential already planned, and seeing a tag appear or vanish after a change is useful on its own.
- Count tags as indexed text in coverage. Apple has described tags as derived from metadata and shown for browsing, not as a search index, so a tag is reported like a screenshot caption until that changes.
Compatibility acknowledgement
- I understand that the HTTP contract, the shared contract types and the MCP tool surface stay compatible throughout 1.x, so a proposal that removes, renames or narrows any of them cannot ship before 2.0.0.
- Dominant language
- TypeScript
- Stars
- 124
- Forks
- 18
- Avg merge
- 12h 19m
- Merged PRs (30d)
- 196
Getting set up
- Ships a Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from AsoBeast/asobeast
-
bug: dashboard By app list hides the store, so one app on two stores shows as identical rowsPossibly taken @MrAdex77 claimed this today. Openbug
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
bug: visibility values and change badges mix whole numbers with one decimalPossibly taken @MrAdex77 claimed this today. Openbug
Difficulty 3/5 1-2 days Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
bug: App Store keywords show Not in listing when every word is indexed but not as one phrasePossibly taken @MrAdex77 claimed this today. Openbug
Difficulty 4/5 3-5 days Newbie friendliness 52/100
Maintainers usually reply within 1 day
-
bug: Action Center and audit recommend adding competitor brand keywords to the listingPossibly taken @MrAdex77 claimed this today. Openbug
Difficulty 4/5 3-5 days Newbie friendliness 55/100
Maintainers usually reply within 1 day
-
bug: rating chart repeats a Y axis label when the rating moves less than 0.4Possibly taken @MrAdex77 claimed this today. Openbug
Difficulty 3/5 1-2 days Newbie friendliness 78/100
Maintainers usually reply within 1 day
All issues in AsoBeast/asobeast
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
twilio/twilio-node#1241 ·
Maintainers usually reply within 1 day
-
documentation
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
hugomrdias/playwright-test#786 · 1 comment ·
Maintainers usually reply within 1 day
-
area:stdlib effort:S impact:med platform:linux type:bug
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
WenyuChiou/agent-board#1745 ·
Maintainers usually reply within 1 day
-
Difficulty 1/5 1-3 hours Newbie friendliness 88/100
Maintainers usually reply within 1 day