The two kinds of change

Here’s the single most useful idea to keep in mind once your app is live: not all changes travel the same way. An update can reach the phone in your user’s hand by one of two completely different paths:

1. A content change — something you edit in WordPress that the app fetches the next time it asks the server for data. These reach users almost immediately, with no app-store involvement.
2. A binary change — something baked into the compiled app itself. These require a brand-new build to be submitted to Apple and Google, reviewed, and installed by the user as an app update.

Most of the day-to-day work you do in Mobile App Manager is the first kind. Knowing where the line falls between the two saves you from two opposite mistakes: waiting on a store review for a change that already went live, or assuming a change is live when it actually needs a new build.

This article walks through where that line falls, why it falls there, and what the version and build numbers on the Publish Your App screen are actually tracking.

Why content changes are instant: the phone-data payload

A MAM app is, at its core, a thin native shell that asks your WordPress site, “What should I show right now?” — and renders whatever comes back.

That question is a single network call. The app hits the local_app_get_phone_data endpoint on your site, and your site assembles the entire screen-graph for the current user — buttons, tabs, layouts, content sections, forms, notifications, theme and branding settings — and returns it as one JSON payload. The app then draws the screens from that payload. (For the full picture, see How content flows into the app: the phone-data payload and Data model: the mobile client consumes one JSON payload.)

The consequence is the part that matters here:

Anything that is described in the payload rather than compiled into the app can change without a new build.

The app re-fetches this payload on launch and on many in-app refreshes. So when you edit content in WordPress, the very next fetch returns the new version and the app just renders it — no resubmission, no review, no update for the user to install.

Things that travel this instant, no-build path include:

• Adding, removing, or reordering buttons, tabs, and screens
• Content behind those buttons (posts, pages, products, listings)
• Most theme and branding settings — colors, layout choices, on-screen text
• Form configuration and form fields
• Notification content and push messages
• Role-based visibility — what each role sees in the app

If you change one of these and a tester says “I don’t see it yet,” the answer is almost never a new build. It’s usually a cache or a stale fetch. MAM uses a cursor mechanism so the app can skip re-downloading sections that haven’t changed; a forced refresh or a fresh launch will pull the new content. See How the cursor cache works and Caching model: the cursor keeps the app fast and fresh.

Why some changes still need a build: what’s compiled in

A native app is still a native app. Some things genuinely live inside the compiled binary that Apple and Google distribute, and those cannot be changed by editing WordPress. To change them, you build a new version of the app and ship it through the store.

These binary-level concerns are handled on the Publish Your App screen, where MAM collects everything the build pipeline needs and submits it to the WPMAM publishing service. Things that require a new build include:

• The app icon and launch screen (the splash image the OS shows before your content loads)
• The app’s name as it appears under the icon on the home screen
• Bundle identifiers and signing identity (the iOS bundle ID, Android package name, and team ID that tie the app to your developer accounts)
• OS permission strings — the messages iOS shows when the app asks for camera, location, or contacts access
• Native capabilities and SDKs compiled into the shell — anything the native code itself must contain to function

Rule of thumb: if the change is content or configuration, it’s instant. If the change is part of the app the OS installed, it needs a new build.

When you submit on the Publish screen, MAM assembles the build settings and hands them to the build pipeline, which produces signed iOS and Android binaries via Fastlane-driven CI. That build is what you (or TSL on your behalf) submit to the App Store and Play Store, where it goes through each store’s review before users can install it. You don’t have to sit and wait once you submit, either — the build runs in the background, and its status comes back to you separately instead of holding up the page.

What version and build numbers actually track

On the Publish screen you’ll see a read-only App Identifiers & Versions panel showing four version-related values: an iOS Version Number and Build Number, and an Android Version Number and Build Number. These are shown for reference and are managed by WP Mobile App Manager — you don’t normally type them in by hand.

It’s worth getting precise about what each one means, since the two are easy to mix up:

• Version number (the marketing version, e.g. 2.4.0) is the human-facing version users see on the app’s store listing — in the version history, the “What’s New” notes, and the app’s own About screen. It signals “this is a new release of the app,” and it climbs when a meaningful new build ships to users.
• Build number is an internal counter whose only job is to make every upload unique. It must increase with every binary sent to a store, even two builds that share the same marketing version. Apple and Google reject a build whose number isn’t higher than the last one they accepted, so this value has to keep climbing. It exists so the stores can tell two uploads apart; users never see it — a customer sees 2.4.0, never 2.4.0 (7).

The two platforms count the build number differently, and it’s worth knowing that when you read the panel. Apple treats it as a value within a marketing version: several builds can share 2.4.0 and just tick the build number up (1), (2), (3) — exactly what happens as TestFlight builds get iterated before one is submitted for review. Google treats it (the version code) as a single integer that must be strictly higher than any version code ever uploaded to that app, across all releases, forever. WP Mobile App Manager handles both rules for you — that’s the whole reason the panel is read-only.

That split is also why there are two numbers instead of one. Say a build gets fixed and re-uploaded during review, before anything has reached the public — bumping the marketing version at that point would be misleading, since there’s no released version for the new one to actually improve on. What really happened is a new build of the same version, so the marketing version holds steady and only the build number advances. That keeps users’ version history clean; they only ever see the one release that eventually ships.

The important takeaway for an admin: these numbers only move when a new binary is built. A content change you made through the phone-data path does not — and should not — change them, because no new app was produced. If you ever find yourself wondering “do I need to bump the version for this?”, that question is itself the test: if the change goes out through the payload, the answer is no.

Note for context: this is distinct from the internal TSL code version that identifies which release of the MAM platform code your app was built from. That’s a platform-engineering concern tracked separately from your public store version, and it isn’t something an admin sets.

How this connects to the rest of MAM

These two paths aren’t competing — they’re complementary, and a healthy app uses both constantly:

• The build sets up the native shell — the icon on the home screen, the name, the permissions, the signing identity. You configure this once and come back to it only when one of those native concerns changes. See Publishing pipeline: from app settings to a store build and the Publish your app (iOS & Android) recipe.
• The payload carries everything else, every day, instantly. This is the surface where you’ll spend most of your time — buttons, screens, content, notifications, branding. See How a MAM app is structured: tabs, screens, and buttons and How content flows into the app: the phone-data payload.

Holding the distinction lets you set expectations correctly. When a customer asks “how fast can we get this change live?”, the honest answer depends entirely on which path it takes. A new promotion, a reordered menu, a fresh push — minutes. A new icon or a renamed app — a new build and a store review, on the stores’ timeline, not yours.

Related

• How content flows into the app: the phone-data payload
• Data model: the mobile client consumes one JSON payload
• Caching model: the cursor keeps the app fast and fresh
• Publishing pipeline: from app settings to a store build
• The MAM app lifecycle: enroll, build, brand, preview, publish
• Recipe: Publish your app (iOS & Android)

What’s next

If you’re preparing an actual store submission, move on to the Publish your app recipe, which walks through the Publish screen field by field. If instead you’re trying to get a content change in front of testers and it isn’t showing up, start with the cursor cache article — that’s almost always where the answer is, not a new build.