THE MANUAL
How to build your own Apptonomy
The complete instructions, free of charge. Every step is real — including the last one.
ASO is constant. So is Apptonomy.
- Core team
- 3–4, plus security and on-call
- Time to first audit
- 12–18 months
- Difficulty
- Expert
- Ongoing
- Permanent
A strong team can build this. Some should.
This page is the field manual for the road we took, with the failure points marked: the engines, the data, the repeated runs, the history that accumulates behind them, and the parts nobody sees. An internal build can skip sign-in, billing and the rest of the SaaS shell. If your version of do-it-yourself is a chat window rather than a build team, we wrote a page for that too.
The whole manual, on one screen
| Step | Primary dependency |
|---|---|
| 01Hire the expertise you can't download | A senior ASO practitioner |
| 02Wire up the stores | Platform engineer, patient |
| 03Gather the intel | Distributed-systems engineer |
| 04Build the engines | Four model providers, a schema for everything |
| 05Measure the surface that has no rankings | Five AI surfaces, one of which you scrape |
| 06Turn ten reports into one plan | Someone whose judgment you'd defend |
| 07Translate everything | One locale catalog you trust |
| 08Now do it every day | Dozens of scheduled jobs, time-series storage |
| 09Now remember all of it | A schema you can still query in three years |
| 10Build the parts nobody will ever see | A security engineer, kept after the demo |
| 11Watch it while it runs. Then keep it alive | Someone who answers at 3 a.m. |
Who should actually build this
Some teams should. That includes teams running a portfolio large enough that per-app pricing stops making sense, teams with data-residency rules a vendor cannot satisfy, and teams whose ASO problem is specialized enough that a general tool would fight them the whole way. Build it. We'd rather you built it well than bought something that does not fit.
For everyone else, the manual shows exactly what sits beneath the score, even when somebody else maintains it.
Before you start
People
One senior ASO practitioner with years of judgment. Two or three platform engineers who enjoy distributed systems and do not mind undocumented APIs. A security engineer, part-time at first and full-time by Step 10. Someone who answers the monitoring stack at 3 a.m.
Access
Accounts with four AI model providers. Apple and Google developer accounts. App Store Connect and Play Console API access. A .p8 signing key that downloads exactly once. A residential proxy contract with per-country exits and rotation.
Infrastructure
A database sized for mountains of repeated data. Somewhere to run dozens of scheduled jobs. A monitoring stack. Automated tests, applied liberally.
Operating supplies
Patience, and a budget line that was not there last quarter.
Hire the expertise you can’t download.
What you’ll need: a senior ASO practitioner, several years of pattern recognition, and a willingness to write all of it down.
Every analysis your platform runs is only as good as the expert reading behind it. Ours took shape as dozens of hand-authored prompts, tens of thousands of words, each one encoding how a practitioner reads one specific slice of a listing: what makes a screenshot set tell a story, when a subtitle is wasting its thirty characters, which review themes should change your copy. Behind the prompts sit hand-set scoring bands for dozens of app categories and a keyword-volume model fitted against Apple's own popularity curve.
Budget for the writing. Then budget for the rewriting. Apple, Google and the model landscape all move, and calibration is never finished.
Wire up the stores.
What you’ll need: an Apple developer account, a .p8 key that downloads exactly once, a headless browser willing to log into Apple on your behalf, and patience.
The documented half comes first. App Store Connect's analytics API is a six-step asynchronous dance that ends in gzipped TSV files. Google Play's analytics “API” is a set of UTF-16LE CSV files that appear in a cloud storage bucket once a month. Both work, eventually.
The undocumented half is where builds quietly die, so take your time here. Storefronts are selected by a numeric header code you will maintain in a table by hand. Product pages carry their data in embedded JSON blobs whose shape changes without notice. Some of the best signal lives behind endpoints with no documentation. One of ours authenticates with a cookie renewed through a headless Apple login. When a store ships a change and your parser goes quiet mid-run, treat it as an operational event: trace the shape change, patch the path, add the fixture, carry on.
Budget for the dependencies underneath, too. In August a headless-browser major version turned one path lookup async, renamed a click option, and dropped the bundled zip reader its own installer had been relying on. The audit image stopped building until its base image learned to unzip.
Gather the intel.
What you’ll need: a residential proxy contract, a distributed-systems engineer, and a spend alert you’ll be glad you set.
Now the raw material: search results, category charts, ratings histograms, reviews by the thousand, version histories, privacy labels and similar-apps carousels. Gather them for your app and every competitor, in every market you care about, every day. Pulling the data reliably is the job: geo-targeted proxies with per-country exit IPs and forced rotation the moment a request is blocked, a concurrency gate that holds your whole fleet exactly at your proxy plan's limit, adaptive rate limits that back off before the ban, and negative caching so a blocked request does not get retried into a blacklist.
Instrument the failures while you are in there. Ours spent a week of logs unable to tell a throttled request from a genuinely empty results page, because the error we raised carried no status code, no response envelope and no body.
Add a budget breaker for the month the scraping bill surprises you. It will.
Build the engines.
What you’ll need: accounts with four model providers, a schema for every response, and a second model that doesn’t trust the first.
This is the part everyone pictures when they picture the build, and it is the fun one. Take your time with it. It is also about a sixth of the work. ten parallel analysis engines, each with its own published methodology: keywords and semantic clusters, store text, screenshots, icon, user sentiment, competitors, user intent, localization analysis, policy checker, AI discoverability. A single audit fires a hundred-plus model calls across four providers, validates every response against an enforced schema, then has a second model at temperature zero grade each engine's output for plausibility before anyone sees it.
Make that grader survivable. One afternoon in August our AI gateway started rejecting its own credential, and because a failed grade counted as a failed audit, a single judge error threw away finished reports after every engine had already run and been paid for.
The keyword problem
The tidy 0–100 volume and difficulty scales sit on top of imperfect source data. Apple publishes a popularity index with no units, underlying volumes or documented derivation. Google publishes absolute monthly counts for web search, not Google Play search. Neither store publishes monthly store-search volume. Every ASO platform bridges that gap with a model, including Apptonomy.
Treat demand and difficulty as different outputs. Our demand score is a calibrated estimate built from named source classes and versioned parameters that are re-derived against collected data. Our difficulty score comes from the apps actually holding the top ten for that term today. We keep the coefficients proprietary and make the provenance clear: what kind of number it is, what feeds it, how it is calibrated and when the model changes. The tidy scale is useful. Write down how yours got there.
The tenth engine measures a different surface. It gets its own step.
Measure the surface that has no rankings.
What you’ll need: accounts with four model providers, a scraper for the fifth, and a way to tell a real change from a model having a different day.
When someone asks an assistant for the best app in your category, there is no chart, rank, impressions report or store console to open. The measurement target is what the model said this time. That calls for a different discipline. Ours is the AI Discoverability engine.
The pipeline
- 1Questions
- 2Surfaces
- 3Extraction
- 4Citations
- 5Community
- 6Cross-channel
- 7Change control
Start with the questions. Ours are generated per audit across seven shapes: straight category asks, problem-first asks, audience-specific asks, head-to-head comparisons, feature-led asks, switching asks and asks that name you outright. Each prompt is wrapped for the market's own language, because the best budgeting app in Portuguese produces a different list. Keep a template corpus behind it for the days generation fails. And keep the wrapper off the search path — ours spent a stretch sending the locale instruction to Google as the search query.
Then query five surfaces: ChatGPT, Claude, Gemini, Perplexity and Google's AI Overviews. The fifth has no API, so you scrape it from the search page using the proxy fleet from Step 3. When no AI Overview renders, read the organic results so the run still tells you something.
Every question goes to every surface. The run size is your question set multiplied by your panel, so a single category's worth of questions becomes dozens of separate answers to read before anything can be scored.
Reading the answers creates the next pipeline. Every response goes through an extraction model that records whether you were named, where in the answer, in what words, with what sentiment, how strongly recommended, which competitors appeared and in what order, and which intents the answer served. At panel scale you will want a heuristic pre-filter for obvious misses, batching, bounded concurrency and a circuit breaker that drops to heuristics when the extraction model rate-limits you mid-run.
Next, find out why the answer said what it said. Harvest every cited URL, resolve it to its registrable domain, and classify it as community, editorial, owned or store listing. That breakdown shows which rooms the answer was assembled from. Ours goes further into the community layer with a Reddit pipeline: generate queries, discover the subreddits that matter, search under rate limits, pull comment threads, classify mentions and surface the threads worth showing up in. A cross-channel pass finds the app's website through the store description, a domain crawl and a search model, stopping once three candidates validate. It extracts the messaging from the site and listing and compares them across five dimensions, because assistants read both and notice when they disagree.
Model answers are non-deterministic. Ask twice and you can get two answers with your listing untouched. Change control fingerprints the inputs, caches at the gateway for a day, and records the vendor, model and published version stamp beside every result. When the score moves, you can separate a listing change from a provider change.
One answer becomes
prompt · locale · provider · model version · mention position · evidence quote · cited domain · competitors · input fingerprint
That last stage is most of the engineering.
Turn ten reports into one plan.
What you’ll need: a scoring model you’re prepared to defend, and taste.
Ten engines produce ten piles of findings, and nobody ships a pile. Synthesis applies invariant checks, cross-engine consistency assertions and a weighted scoring model that rolls everything into one readiness score. It then ranks every recommendation by estimated lift and puts the single best effort-to-impact move on top. The output is one publishable plan per app: rows you approve, edit or decline.
This step is the product. It has no API to call: pure judgment, encoded as software.
Translate everything.
What you’ll need: one locale catalog you trust, because the vendors’ four disagree.
87 languages, and the vendors do not agree on what to call them. The same language carries different codes on different surfaces, so reconcile them into one catalog and test that it never drifts. German ignores a 30-character title ceiling, so translations get a second AI pass to shorten what the first one wrote. Keyword fields get compiled per locale to fit a 100-character box. Right-to-left scripts need their own handling. Screenshots get regenerated with the translated text in place.
And your coverage checker has to probe each language through its home storefront, because stores silently serve your default listing in markets you never localized. It looks localized right up until you check.
Now do it every day.
What you’ll need: dozens of scheduled jobs, time-series storage, and a calendar with no gaps in it.
A one-time audit gives you the snapshot. Repeated runs create the film. Schedule audits on the cadence your plan sets, up to every night. Ingest reviews from both stores. Snapshot and diff every competitor listing, down to perceptual fingerprints of their screenshots, so a swapped image set shows up with a date on it. Run rank tracking as an allocation problem with rotation cursors and a hard daily request ceiling, so every tracked term gets covered without melting the budget. Store all of it as time series. Day-over-day, week-over-week and month-over-month movement becomes something you can chart and prove. Draw the score history with a reference line at every shipped change, tied to the install and conversion movement that followed in your own console numbers.
Then multiply by your portfolio: every app, every market, every competitor, both storefronts.
Now remember all of it.
What you’ll need: a schema you can still query in three years, a retention budget, and a front end that makes the history worth having.
Every run from Step 8 produces data. A year of uninterrupted runs becomes the asset.
Design for that on day one, because history cannot be retrofitted. Your row count grows on six axes at once: every app, competitor, market, locale, engine and day. A schema that felt roomy in month two starts timing out in month nine. Decide early what you keep at full fidelity and what you roll up, because the storage bill compounds at exactly the rate the data does.
Then build the half nobody budgets for. A database nobody can interrogate is a cost line. Trend views measured in months rather than days. Competitor listing diffs shown side by side with a date on each. Rank movement plotted against the day you shipped the change. Anomaly surfacing, so something that moved gets noticed without a person going to look for it. And the score-history timeline with a reference line at every published revision, which is the artifact that turns “we changed the subtitle” into “and here is what happened next.”
Now the part that sets your timeline. Reviews, version histories and ratings totals are public, so you can arrive late and pull them retroactively. Competitor listing snapshots, rank history, score history and AI panel answers are forward-only. What a competitor's screenshot set looked like in March, where you ranked the week before you rewrote your subtitle, and what the AI panel said about your category on a given Tuesday exist only if something was recording on the day.
The first audit gives you a baseline. A year of uninterrupted recording gives you history.
Build the parts nobody will ever see.
What you’ll need: a security engineer, a performance budget, and the discipline to keep both after the demo goes well.
Nothing in this step shows up in a demo. A good share of our engineering time has gone here, so the manual has to include it. An internal tool can skip most of it. Here is what the time buys.
Security
Your platform now holds credentials that can publish to your apps and read your sales data, so treat the place it keeps them accordingly. Ours wraps each connected key in double envelope encryption under separate cloud KMS keys, per user, with a keyless mode for Google Play that stores no private key at all. Every internal handoff runs on short-lived, single-use signed tokens. Every log line passes through a redaction layer before it reaches any sink. Every push is secret-scanned. Every deploy is preflighted so a secret that is not bound to the runtime stops the release. Every environment gets its own isolated mutable caches and object stores. Every public door gets rate limits and a bot check. The dependency list carries a reviewed vulnerability baseline that fails the build when it drifts. None of it is visible to the person using the tool. All of it is visible to the person attacking it.
Speed
An audit that takes an hour gets run once. Ours runs in minutes because of a cache economy an in-house build rarely gets around to: dozens of cache layers with per-signal expiry, compressed payloads, edge key-value stores, images cached behind a CDN, AI responses cached at the gateway, and batched prefetches that cut upstream calls by an order of magnitude. Without that layer each audit costs many times more and takes hours, and a daily cadence quietly stops being affordable. So it stops.
Robustness
Every upstream in this manual fails, and the failure has to land somewhere sensible. That means hard timeouts on every fetch — our shared request layer had no default timeout, so a review pull once froze with no log line and no error, and the run sat in “running” until the platform's own thirty-minute ceiling killed the container. Then heartbeats so a long run cannot be mistaken for a dead one, sweepers that catch anything spinning forever, engines that can fail without taking the audit down, a failed rank check that is never allowed to show up as “dropped out of the top 50”, and retry policies tuned against real outages. Then the tests: thousands of them, plus health checks that exercise production every half hour, and a deploy pipeline that promotes an immutable candidate through staging and can roll it back.
The demo stays the same. Week six does not.
Watch it while it runs. Then keep it alive.
What you’ll need: cost accounting per audit, an alert channel you actually read, and someone on call.
Everything above now runs unattended, which means everything above now fails unattended. Ours once recorded a clean run while AI Discoverability had quietly timed out and the keyword engine, handed no competitors at all, had scored the listing against its own title words.
Add per-audit cost accounting calibrated against months of production runs. Put spend breakers on every vendor. Run a nightly AI judge that re-reads finished audits the way a skeptical consultant would and files what it finds. Add sweepers for anything spinning forever, health checks on the health checks, and a human rotation for the 3 a.m. failures. The stores do not reserve breaking changes for your business hours.
When it is stable, return to Step 1. The stores moved while you were building Steps 2 through 10, and the expertise you wrote down has already started to age. The last step of this manual points back at the first.
What went around the loop last quarter
June to August 2026.
Step 11 sends you back to Step 1, which sounds like a figure of speech. Here is one quarter of it, taken from our own change log.
Google Ads started missing its own deadline.
The keyword-ideas endpoint enforces a server-side deadline of about twenty seconds and answers 503 when a request outlives it. On one measured day, 60 of 663 calls landed in a 19.5–20.2 second band against a median of 784 milliseconds. Our client had no retry for 5xx, a timeout three times longer than Google’s own, and — the expensive part — it wrote the empty result into a seven-day cache, so a failure read back as a successful hit.
A model gateway rejected its own credential.
Every call to one provider failed from 18:34 one afternoon. Because a failed plausibility grade counted as a failed audit, one transient error discarded finished reports after every engine had already run and been paid for.
Apple’s analytics API needed three accommodations at once.
Sales backfill clamped to Apple’s 365-day retention window, a null cursor that had been defaulting to 2008, and 410 GONE handled as a real response rather than an error.
Apple’s rate limiting outgrew our backoff.
App Store Connect 429s needed budget-aware retry, routing through the same adaptive concurrency gate as everything else, and enough log visibility to stop being invisible.
The SERP scraper began returning nothing, silently.
A week of logs could not separate throttling from a genuinely empty results page, because the error carried no status code, no envelope and no body.
A headless-browser major version moved underneath us.
One path lookup became async, one click option was renamed, and the installer dropped a bundled zip reader — so the audit image stopped building until its base image learned to unzip.
That list will be different next quarter. That's the whole point of it.
Known failure mode
The build that stalls.
Picture a platform that reaches Step 4, ships something genuinely useful, and then stops being maintained without anyone deciding to stop. From the inside, it does not look like failure.
Month fourteen: the engines still run. The benchmark tables have not been recalibrated since launch, so the scores drift a little further from the market each quarter and nobody can name the day it started. One competitor's listing has been returning nulls since a Play change in the spring. The audit still renders; it quietly stopped covering them. The person who wrote the prompts moved to another team. The daily run became a weekly run the month the scraping bill got reviewed, and nobody has argued for changing it back.
All of that is recoverable, and none of it announces itself. Budget Step 11 before you budget Steps 1 through 10.
The last page of the manual
A strong team can build every step above. We know because we did, then built a company around keeping all eleven running.
If you take only part of the manual, take Steps 1, 4 and 6. Expert judgment written down, engines that apply it, and synthesis that turns the output into something shippable will get you an internal tool worth having, at a fraction of the whole build. A lot of in-house builds should stop exactly there.
Build the rest and your platform can audit the portfolio on the cadence you set, remember every run, publish the plan to iOS and Google Play from the same workspace, and connect each shipped change to the score history that followed.
We do not hold years of history on an app that connects this afternoon. Nobody does. Apptonomy holds the machine that starts recording that afternoon: the schema, retention policy, repeated snapshots and front end that makes them useful. An in-house build starts recording when it is ready.
This manual is also a sales pitch. The instructions remain the instructions.
See how the finished build works on the Methodology page, or compare plans on Pricing.
Revision 1. This manual changes when the stores do.
One of these costs a team and a year.
Seven of the ten engines run free on one app in one market. No credit card. Paste your URL and read your first audit before your first hiring loop would have closed.
Get a free quick audit for your app.