Why app tracking breaks at release time
On a website, a broken tag can be corrected in the tag manager the same day. An app is different, because its events are written into the code. The measurement plan for app installs spells out what that means: tracking goes through code review, the release train and store review, a parameter left out stays out until a later version, and even a corrected build reaches people only as quickly as they update. A fault that slips through one release can sit in the data for months.
Many of those faults can come from releases nobody thought of as tracking work. A developer rebuilding the checkout gives the purchase event a tidier name; a refactor moves the activation event to the button before the completed action; an updated SDKCode a vendor supplies for building into an app, such as an analytics, ad network or measurement partner kit, that records installs and in-app events. changes how consent is handled at start-up. Each change looks harmless in the release notes, and each silently changes a number the business is managed on.
The cost lands in three places. Reports show a step in activation, retention or revenue that is really a change in counting. Campaigns that optimise to an in-app eventAn action recorded inside an app, such as a sign-up, trial or purchase, reported through the measurement partner or SDK and used to optimise campaigns. lose the signal they learn from, because, as the attribution guide for apps explains, the optimisation event has to mean the same thing in the app, at the partner and inside each network, or the campaign learns from a behaviour the business does not measure. And the reconciliation between store, partner and analytics counts moves for reasons nobody can find, which is why the tutorial on reconciling app install numbers checks SDK releases first whenever a gap leaves its range.
Several pages already require a check at release time without walking through it. The tracking plan guide asks for a release checklist item that confirms the plan was updated and its version bumped. The app marketing operations playbook makes the release owner confirm, before campaigns use a build, that its tracking and links passed. The measurement governance playbook lets the measurement owner hold a release that touches a key eventA GA4 event marked as important to the business, the property's measure of success. until a person other than its author has checked it. The neighbouring checks each cover a different moment:
| Check | When it runs | What it proves | Where it lives |
|---|---|---|---|
| Release event check | Every release build, before submission | The build sends the events, parameters and postbacks the plan specifies | This tutorial |
| Deep link test | Before a campaign sends new links, and after releases that change routing | Every link opens the promised screen in every context | Testing app deep links |
| Campaign launch gate | Before spend starts on a network | The partner records a test install and events from a test device, and the network is linked | App install campaign launch checklist |
| Web tracking verification | After a site or container change | Tags, analytics, ad platforms and consent work on the website | Tracking verification checklist |
| Monthly reconciliation | Each month | Store, partner, analytics and network counts sit in their usual ranges | Reconciling app install numbers |
Before you start
- The tracking plan, current and versioned. Every event the app sends, its trigger, its parametersA named value sent with an analytics event that describes it, such as a page location, form name or item price. with types and allowed values, the user properties, the destinations and the status of each row, as the tracking plan guide lays out. The app's taxonomy, built as the guide to deep links and app events describes, is the app's part of that plan.
- The release's change list. The tickets or merge requests in the build, with a developer who can say which screens, flows and SDKs each one touched.
- The activation event, on one definition. The activation event tutorial records it in the plan with a named owner, precisely so a later build cannot quietly rename it or move its trigger. The release check is where that promise is kept.
- A release candidate build for each platform, installable on test devices through the team's usual internal distribution.
- Clean test devices or test accounts for iOS and Android, reset or with the app removed, so that a first open is really a first open. The guide to testing marketing changes with test data sets out how test records are marked and kept out of reports and platforms; agree the marker before the check.
- Access to the debug views: the analytics debug view for the app's data streams, and the measurement partner's test or debug view, which the launch checklist names among its prerequisites.
- A tagged test link from the deep link route table, for the campaign parameter check.
- The measurement change log and a named owner for the check, with the release owner who signs it off.
The steps
List the events, properties and postbacks the release touches
Go through the release's change list with the developers and, for each change, write down every event, parameter and user property on the affected screens, plus any SDK that was added, removed or updated. Ask directly whether anything was renamed, moved to a different screen or trigger, or removed, because those are rarely written in a ticket. Then follow each affected event outwards: is it the activation event, a key event in analytics, an event sent to the measurement partnerAn independent service that attributes app installs and in-app events across ad networks., an event a network campaign optimises to, an input to the iOS conversion value, a trigger for an onboarding or re-engagement message? The list that results is the scope of the deep check; the rest of the plan gets a shorter pass. A release that touches none of these still gets the short pass.
Compare the build's events with the tracking plan
Before touching a device, compare the code with the plan. Where the plan lives beside the code, the change to the plan should arrive in the same merge request as the change to the event, which is the review the tracking plan guide describes; where it lives in a spreadsheet, check each affected row by hand. Look for names that differ from the plan, parameters added or missing, types changed, and events the plan marks as deprecated that are still being sent. Google Analytics Help's article on events and the guide to Google Analytics events and parameters explain how events and parameters work, and the deep links guide prefers a recommended name, as documented by Google Analytics and the Firebase documentation, wherever one exists, so a rename away from a recommended name is a fault even when the new name looks tidier. A deliberate rename is fine if the plan records the old name, the new one and the cut-over version.
Install the release build on clean test devices for each platform
Install the release candidate, not a developer build, on a clean device for each platform. A developer build can carry different settings, keys or logging, and the point is to test what users will receive. Use test accounts marked as the test environments guide describes, so that test sessions, purchases and installs can be excluded from reports and do not reach ad platforms as real conversions. Note the device, operating system, app version and build for each run.
Walk the activation path and watch each event arrive in the debug view
Open the analytics debug view, then take the path a new user takes from first open to the activation event, and on through the core actions the release touched. Watch each event appear as you trigger it. The automatically collected events, such as the first open and screen views, should arrive without anything rebuilt, as the deep links guide notes; the custom and recommended events should arrive once, at the moment the plan's trigger column describes. Then run the negative tests the tracking plan guide asks for: go back, cancel, repeat a step, close and reopen the app, and confirm that nothing fires that should not. An activation event that fires on a button press rather than on the completed action, or fires twice when a screen reloads, is caught here and nowhere else before release.
Check names, parameters, user properties and the user identifier
For each event in scope, read the payload in the debug view against the plan: the exact name, every parameter with the expected type and a sensible value, nothing empty, and no parameter the plan does not list. The events and parameters guide explains that the debug view shows every parameter an event carries, while reports show only the parameters registered as custom definitions, so register any new parameter the release adds. Check the user properties the release touched and the user identifier that joins app behaviour to messaging, the website and the CRM. Then look for personal data. The deep links guide records that Google Analytics forbids sending information that identifies a person in any event or property value, so an email address in a parameter or a name in a user property fails the check outright.
Repeat the paths with tracking allowed and declined and with each consent choice the app offers
Run the activation path again for each state a real user can be in. On iOS, answer the App Tracking Transparency prompt both ways on separate clean installs; the attribution guide explains that a refusal removes the advertising identifier and with it any device-level match to another company's ad, so the point of the test is that the app and its SDKs behave as intended in both states, not that they report the same. Then go through each choice in the app's own consent flow. The mobile measurement hub points out that the partner's SDK, the analytics SDK and each network's SDK all gather data about users, so all of them belong in what the app discloses about privacy and in its consent flow; the check confirms that what each tool receives matches the choice the tester made. What that choice should allow is a question for whoever owns privacy, not for this tutorial. The reconciliation tutorial notes that a release that alters how an SDK treats consent can lose first opens on a single platform, which is why this step runs on both.
Confirm installs and events reach the measurement partner and each network
Open the measurement partner's test view and confirm that the test install arrived and that every event the partner forwards, above all the activation event, arrived under its planned name with its parameters. The launch checklist treats an install that appears without its events as a sign of a fault in the SDK integration. Then confirm that each network linked to the partner would receive the event its campaigns optimise to, under the name the campaign expects; a renamed event in the app reaches the partner as a new event and the network as nothing. On iOS, check that the conversion value the app updates still maps to the behaviour the schema encodes. Apple's SKAdNetwork documentation describes postbacks that arrive after a delay and in aggregate, as the attribution guide explains, so a test device cannot show a finished postback; what can be checked before release is that the app still sets the value at the planned moments.
Confirm campaign parameters arrive with the first open from a deep link
On a clean device, tap a tagged test link from the route table, install through the store if the path is deferred, and open the app. In the debug view, check that source, medium and campaign are attached as parameters to the session or to the first event, which is how the deep links guide says behaviour can be split by source, and that the partner attributes the test install to the test link. This is a smoke test, not the full matrix: the tutorial on testing app deep links owns route-by-route testing across both platforms, every app state and each place a link gets tapped, and it should be rerun in full whenever the release renames screens or changes routing. Any change the release makes to the route tableThe app's map from each deep link path to the screen it opens, including what happens for logged-out users, missing items and renamed screens. belongs in the measurement change log beside the release.
Record the build, the results and any known gap in the change log
Write the result into the measurement change log: the app version and build, the platforms and devices tested, the events and states checked, what failed and how it was fixed, the plan version the build implements, and who verified it. Update each tracking plan row the release changed to verified with the date. If a known gap ships anyway, such as a parameter that will only arrive in the next version, record it as a change logA dated record of changes made to tracking, accounts, reports, lists or rules, with who made each and why, so later movements in the figures can be traced. entry with the versions affected, so whoever reads activation next month finds the reason before they find the dip. Then the release owner signs off, as the operations playbook's gate requires, and nothing that failed is used by a campaign until it passes. Then clean up the test records.
Watch version adoption and the first cohorts on the new version
After release, the check moves from the build to the data. The measurement plan for app installs lists, among its health measures, how many active users are running a build with the current event specification; read it from the app's own version reports as the update spreads. Read the key events by app version, not as one blended series, so a step on the new version stands out. Read the first install cohortsA group of customers who share a starting event and period, tracked together over time. on the new version beside the previous ones, once their window has closed, and expect noise in early cohorts; the guide to reading small numbers explains why small ones swing. If an event is missing or wrong in live data, treat it as a tracking outageA period when conversion or analytics tracking stops recording, or records wrongly, while sales carry on; its start and end are marked as the outage window. and follow the tracking outage procedure: confirm against a source outside the app, protect the campaigns that bid on the signal, fix, verify and annotate. If activation itself falls on the new version and the events check out, the diagnosis of installs that do not activate takes over.
What every release checks, and what only some releases check
Running the whole routine on every build is rarely needed, and skipping it on builds that look harmless is how faults ship. The split below is general practice built from the measurement plan for app installs and the tracking plan guide: a short pass that every build gets, and a deep check whose scope comes from the first step.
| Check | Every release | Releases that touch the area |
|---|---|---|
| Build compared with the tracking plan | Changed rows only | Every row on the affected screens and flows |
| Activation path in the debug view | Once per platform, with tracking allowed and declined | Both tracking states and each consent choice |
| Payload of events, properties and the user identifier | The activation event and key events | Every event in scope, with negative tests |
| Measurement partner and networks | Test install and the activation event | Every forwarded event and the conversion value mapping |
| Campaign parameters through a deep link | One tagged link | The full deep link matrix after routing changes |
| Change log and plan status | Always | Always, with known gaps and versions affected |
| Version adoption and first cohorts | Always | Always, with the affected events read by version |
Any change to the activation path, payment, onboarding, sign-in, consent, an SDK, deep link routing or the events that feed messaging triggers the deep check. The tutorial on onboarding messages for new app users triggers and stops its messages on step events, so a renamed step event breaks the messages as well as the reports. The measurement plan framework ties each event to the objective it serves, which settles scope quickly: an event that feeds a key performance indicator, a campaign or a message gets the deep check.
A parking app catches a renamed event before release (illustrative)
Qindrapo Parking checks the build that redesigned its payment screens
Qindrapo Parking, an invented pay-by-phone parking app, defines activation as a first paid parking session, logged as
parking_session_paid with a zone_id parameter. Its install campaigns on two networks optimise to that event, and
its onboarding messages stop when it fires. Version 6.4 redesigns the payment screens. The developer who rebuilt them
renamed the event session_payment_complete and, because the new screen reads the zone from a different place, the
zone_id parameter is no longer sent.
The release check lists 9 events and 2 user properties on the affected screens. Comparing the build with the tracking
plan flags the new name before anyone opens a device, and the debug view on 4 clean test devices, 2 per platform,
confirms it: the new event arrives without zone_id, and the measurement partner's test view shows the test install
with no activation event at all, because the partner and both networks still expect the old name.
| Check on version 6.4 | iOS, tracking allowed | iOS, tracking declined | Android | Result |
|---|---|---|---|---|
| Activation event name matches the plan | No | No | No | Fixed before submission |
zone_id present | No | No | No | Fixed before submission |
| Partner receives the activation event | No | No | No | Passed after the fix |
| Campaign parameters on first open from a tagged link | Yes | Yes | Yes | Passed |
| No personal data in parameters | Yes | Yes | Yes | Passed |
The team restores the planned name and the parameter, reruns the deep check in half a day, records the build, the devices and the fix in the change log, and the release owner signs off. After release, version 6.4 reaches 46% of active users in the first week and 81% by the fourth, and activation for the first 3 weekly cohorts on the new version sits within a point of the 3 before it.
The check exists because of version 5.9, eight months earlier. That release renamed the same event during a smaller redesign and shipped without a check. For 3 weeks the campaigns optimised to an event that no longer arrived, cost per activated user rose by about a third, and reported activation fell by 22% before anyone traced it to the build rather than to the product.
Common mistakes
- Checking only releases labelled as tracking work. The renames that cost the most come from redesigns and refactors. Give every build the short pass and scope the deep check from the change list.
- Testing on a device that already had the app. The first open, the deferred link and the attribution of the install only behave as they will for new users on a clean install.
- Watching the event arrive and stopping there. An event with the right name and an empty or mistyped parameter still breaks reports and campaigns. Read the payload against the plan.
- Testing only with tracking allowed. Users can decline, and a change to how an SDK treats consent can lose data on one platform. Run the path in each state the app offers.
- Forgetting the partner and the networks. A rename that the analytics tool absorbs reaches the measurement partner as a new event and the networks as nothing. Check where campaigns learn, not only where reports read.
- Leaving no record. A check that is not in the change log cannot explain a step in a metric next month. Log the build, the result and every known gap.
- Reading the new version as one blended series. A fault on the new version is diluted by users still on the old one. Read key events by version until adoption is high.
