The big idea: two kinds of image, two different pipelines

Almost every “why does my image look wrong in the app” question traces back to one thing people miss: MAM treats app images as two separate kinds, and each one travels through the system its own way.

• Branding images — the app icon and the launch (splash) screen. Think of these as the artwork your phone shows before and around your app itself: the home-screen icon, the App Store / Play Store listing icon, and the screen you see while the app boots. MAM actively processes these — resizing, recoloring backgrounds, flattening transparency, and baking them into the app binary the moment you publish.
• Content images — the photos and graphics that live inside your screens: a post’s featured image, a logo on the login screen, the picture on a list-with-detail item. MAM leaves these alone: it hands the phone a URL, and the phone fetches the image straight from your WordPress media library whenever it needs it.

Branding images get uploaded once and baked in for good. Content images turn over every time you publish a post. That’s why the two need different machinery — and why “the right size” means something different depending on which one you’re dealing with.

Everything that follows is here to get you comfortable with both pipelines — comfortable enough that your art looks crisp, your publish sails past Apple’s review, and your app stays quick.

Where app images actually live

There’s no separate “image database” hiding behind the scenes. Every image you upload — branding or content — lands in the WordPress Media Library as a normal attachment, stored under wp-content/uploads/. MAM keeps track of it by its WordPress attachment ID, never by a duplicate file.

This matters to you in two ways:

1. Deleting media breaks apps. If you delete an attachment from the Media Library that a screen still points to, the phone requests a URL that no longer resolves, and the image shows up broken. Treat anything the app uses as load-bearing media.
2. The original file is the source of truth. When MAM needs a resized or recolored version of a branding image, it reads the original attachment, generates a new file from it, and registers that new file as an attachment of its own. Your original stays untouched.

For branding work, MAM also keeps a handful of plain WordPress options that remember your choices: which attachment is the icon (local-app-images-app-icon), which one is the launch screen (local-app-images-launch-screen-2), and which background colors to use (local-app-app-icon-bg for the icon, ios_app_launch_screen_bg for the launch screen). One more flag (mam_launch_screen_use_custom) simply remembers whether you’re letting MAM auto-generate the splash screen or supplying your own.

Pipeline 1: branding images (icon + launch screen)

This is the pipeline where MAM rolls up its sleeves. It’s implemented by the app image manager (mam_app_image_manager in app-settings/mam-image-manager.php) and driven from the publish / App Setup screens.

The app icon

You upload one square icon — the product asks for a 1024×1024 PNG — and the publish checklist will stop you cold if it’s any smaller than 1024×1024. From that single source, MAM works out what both app stores and every device size need — no uploading a dozen icon sizes by hand the way you would starting from a raw Xcode or Android project.

There’s one non-obvious step here, and it exists purely to keep Apple happy: Apple rejects App Store icons that contain transparency (the dreaded error 90717). A PNG with a transparent corner — common when a logo comes straight out of a design tool — will fail review. So MAM flattens the icon for you: whenever the icon image or its background color changes, it composites your PNG onto a solid background color and overwrites the file, so what ships is fully opaque. That’s why the icon has a background color setting sitting right next to it — if your logo has rounded or transparent edges, that color is what fills in behind them.

The practical takeaway: design your icon to look right sitting on its background color, not floating over a checkerboard of transparency. Whatever you see once it’s flattened is exactly what the store gets.

The launch (splash) screen

The launch screen is that brief screen you see while the app is starting up. MAM can either generate it for you or accept a fully custom image.

• Generated (default). Give MAM your icon plus a launch-screen background color, and it builds the splash art for you. Under the hood, it paints a solid-color canvas at fixed device resolutions and centers a scaled copy of your icon on top. The current generation produces two standard sizes — 640×1136 and 1125×2436 — so both older and newer phones get a sharp image. Change the icon or the background color, and MAM regenerates these automatically so the splash always matches what your icon looks like now.
• Custom. Flip the “use custom launch screen” switch, upload your own splash image, and MAM stores that attachment and uses it exactly as given instead of generating one. Reach for this option when you want full-bleed splash art rather than “icon centered on a color.”

How resizing works under the hood

For branding work, MAM does its resizing with PHP’s GD image library rather than WordPress’s built-in thumbnail sizes:

• It loads your source PNG, creates a fresh square canvas at the requested pixel size, fills in the background (a chosen solid color, or transparency if none is given), and resamples your image onto it. Resampling — rather than a crude pixel-drop resize — is what keeps your edges smooth even at small sizes.
• Each generated file then gets registered as its own Media Library attachment, so the resized icon or splash becomes a first-class image — one WordPress can serve and Fastlane can pick up at build time.
• There’s a safety ceiling here too: source images get validated and rejected if they exceed 4096×4096, which guards against a memory-blowout upload. Stay at or near the requested 1024×1024 for your icon and you’ll never come close to hitting it.

Because all of this happens at publish/save time on the server, none of it costs your end users a thing. The phone never resizes a branding image — it simply receives the finished art already baked into the build.

Pipeline 2: content images (served from WordPress at runtime)

Content images — featured images on posts, logos on the login screen, pictures on list/detail items — travel the opposite path. MAM doesn’t resize or recolor them at all. When it builds the phone’s data payload, it simply looks up the attachment and emits its URL — typically the full-size version of the image — and the phone downloads it directly.

You can see this pattern throughout the content classes: a post’s featured image, for example, gets resolved to its full attachment URL and dropped into the payload as a plain image URL for the app to fetch. There’s no MAM-side crop, no MAM-side compression, and no per-device variant.

That design choice has one clear consequence for you:

• Content image weight is your responsibility. Use a 6000×4000, 8 MB camera JPEG as a post’s featured image, and that’s exactly the size sent to the phone. It’ll still display, but it’ll load slowly on cellular and burn through the user’s data. WordPress does generate smaller thumbnail sizes for the Media Library, but the app payload generally points at the full image, so having “WordPress made a thumbnail” doesn’t save you here.
• Right-size before you upload. Export content images at sensible display dimensions with reasonable compression before they ever go into the Media Library. For most in-app photos, a longest edge somewhere in the low thousands of pixels, saved as a well-compressed JPEG, is plenty for a phone screen.

This is the single biggest, easiest performance win you control as an admin: keep your content images lean, and the app feels fast everywhere an image shows up.

Choosing the right size and format

A quick reference, following straight from the two pipelines above:

Two format rules worth committing to memory:

• Branding art is PNG, on purpose. The icon and launch pipeline runs PNG end to end, and PNG is what the stores expect for icons — don’t hand it a JPEG.
• Photos should be JPEG; flat graphics should be PNG. Save a photographic featured image as a PNG and you’re carrying needless bulk; a logo or screenshot with hard edges and text, on the other hand, comes out cleaner as PNG.

How this connects to the rest of MAM

• Publishing. The branding pipeline is part of publishing the app: change the icon or its background, and MAM flattens and regenerates the art, with the result being exactly what Fastlane uploads to the App Store and Play Store. See the app lifecycle and publishing concepts.
• The phone data payload. Content images ride along inside the one JSON payload the mobile client consumes. That payload carries image URLs, not image bytes, so the phone fetches each image only when it needs it. See the data-model and phone-data-pipeline concepts.
• Caching. Since content image URLs flow through the cached payload, changing an attachment referenced by a screen interacts with the cursor cache just like any other content change would. See the caching-model concept.
• Frozen contracts. The image-URL keys the app reads (a post’s image fields, for example) are part of the mobile contract — rename them, and you’d break every deployed app out there. See the frozen-public-contracts concept.

Quick mental model to keep

• Icon and splash → MAM resizes, recolors, flattens, and bakes them into the app at publish time. Just give it a 1024×1024 PNG and a background color.
• Everything inside a screen → MAM just sends a URL, and the phone downloads it live. Right-size and compress it before it ever enters the Media Library.
• Both kinds live in the WordPress Media Library. Don’t delete media that the app still points to.

Verification

This article was last verified against:

• mam-main/includes/app-settings/mam-image-manager.php (mam_app_image_manager: resize_image, generate_launch_screen, gd_resize, flatten_png_alpha, register_attachment)
• mam-main/includes/publish-app/app-submit.php (icon/launch-screen save + regen logic, publish checklist rendering)
• mam-main/includes/helper-classes/mam-publish-status.php (1024×1024 minimum enforced via the app-icon-too-small check)
• mam-main/includes/publish-app/mam-app-publishing.php (icon/launch-screen/background options)
• mam-main/includes/content-classes/* (featured-image / content-image URL emission into the phone payload)

Re-verify whenever the icon size requirement changes, the GD resize/flatten logic changes, the launch-screen sizes or generation behavior changes, or the way content images are emitted into the payload changes.

Related articles

• Concept: The MAM app lifecycle — enroll, build, brand, preview, publish
• Concept: The data model — the mobile client consumes one JSON payload
• Concept: How content flows into the app (the phone data payload)
• Concept: The caching model — how the cursor cache keeps the app fast and fresh
• Concept: Frozen public contracts — wrap, don’t rename