Understanding the App Asset Library
Upload an image or video once, then reuse it across your app’s App Store surfaces with per-surface placements.
Overview
The App Asset Library gives your app a single, shared collection of marketing and product media. Instead of uploading the same screenshot or app preview separately to every App Store version, custom product page, and in-app event, you upload each asset once into the library and then create placements that position it on specific surfaces. One asset can back many placements at the same time.
This article explains how the pieces fit together. For the step-by-step workflows, see Uploading and managing image assets, Uploading and managing video assets, and Placing assets on your App Store surfaces. For a comparison of the App Asset Library and the previous approach, see Migrating to the App Asset Library.
Understand the model
The asset library is built from a small set of resources:
- Asset library
The per-app container that holds every reusable asset. Each app has exactly one library, reachable through the app’s
assetLibraryrelationship. For more information, see App Asset Libraries.- Image and video assets
The reusable media you upload. You upload each AppAssetLibraryImage or AppAssetLibraryVideo once, and App Store Connect processes it once. The asset then lives in the library independently of where it appears. For more information, see App Asset Library images and App Asset Library videos.
- Placements
A placement (AppAssetLibraryPlacement) positions one asset on one App Store surface: an App Store version localization, a custom product page localization, an in-app event localization, or an App Store version experiment treatment localization. For more information, see App Asset Library placements.
- Ordering requests
A single request that sets the display order of placements within one localization and placement group, such as the order of screenshots. For more information, see App Asset Library placement ordering requests.
- Reference data
A machine-readable catalog of valid specifications: dimensions, aspect ratios, file formats, placement groups, and per-placement limits. Query it instead of hard-coding requirements. For more information, see App Asset Library reference data.
Learn the vocabulary of a placement
Three values describe where an asset appears. You supply the first two when you create a placement, and App Store Connect provides the third:
- Placement type (AppAssetLibraryPlacementType)
Names the kind of slot:
APP_SCREENSHOT,APP_PREVIEW,PRODUCT_PAGE_HEADER_ASSET,EVENT_CARD_ASSET, and so on.- Placement group
Narrows that slot to a family of devices. Group identifiers are strings such as
IPHONE_DYNAMIC_ISLAND_LARGE_PROFILEorMAC_PROFILE, and the full list comes from the reference data. Each group maps to a platform (AppAssetLibraryPlacementPlatform) and a display class (AppAssetLibraryDisplayClass).- Specification
Describes the file itself: exact pixel dimensions, aspect ratio, formats, and maximum size. You don’t choose a specification; App Store Connect matches your uploaded file to one during processing and reports it back as the asset’s
specId.
Placement group identifiers and their limits come from the reference data rather than an enumeration, so you need to read them at runtime. For more information, see Discovering asset specifications.
Follow the end-to-end workflow
A typical integration moves through these stages:
Find the library. Read the app’s asset library with
GET /v1/apps/{id}/assetLibrary(Read related asset library) and note itsid. You relate every asset you upload to this library.Check the specifications. Query the reference data with
GET /v1/appAssetLibraryRefData(List app asset library ref data) to learn the dimensions, formats, placement groups, and limits that apply to the surfaces you’re targeting.Upload your assets. Reserve, upload, and commit each image or video, then wait for processing. For more information, see Uploading and managing image assets and Uploading and managing video assets.
Place the assets. Create placements that link each asset to a target localization, then set their order within each placement group. For more information, see Placing assets on your App Store surfaces.
Submit for review. Placements travel through App Review as part of their parent surface. A placement’s state reflects the review state of that parent.
Track asset state
Every image and video reports a state (AppAssetLibraryAssetState). Reserving, uploading, and processing an asset moves it through:
AWAITING_UPLOAD → UPLOAD_COMPLETE → PREPARE_FOR_SUBMISSION
After the asset reaches PREPARE_FOR_SUBMISSION, it’s processed and you can place it. Submitting the parent surface for review advances the asset through READY_FOR_REVIEW, WAITING_FOR_REVIEW, IN_REVIEW, ACCEPTED, and APPROVED.
Three states sit outside that progression:
FAILEDProcessing didn’t succeed. Read
stateDetailsfor the reason.REJECTEDApp Review declined the asset.
ARCHIVEDYou retired an approved asset from active use.
Re-fetch an asset at any time to read its current state and stateDetails. Placements track their own state (AppAssetLibraryPlacementState), which mirrors the review state of the parent surface, from ASSET_PROCESSING through PARENT_APPROVED.
Choose an asset category
When you create an asset, you assign it a category (AppAssetLibraryAssetCategory):
APP_SCREENSHOTS_AND_PREVIEWSScreenshots and app previews for your product pages.
CREATIVE_ASSETSOther marketing media, such as in-app event artwork and product page header assets.
The category determines the placement types for which an asset is eligible. Each placement type in the reference data lists the categories it accepts in acceptsAssetCategories, and creating a placement with a category that doesn’t match that list returns an error.
Review roles and access
To manage the asset library with the App Store Connect API, you need one of the following user roles:
ACCOUNT_HOLDERADMINAPP_MANAGER
For the full list of App Store Connect user roles, see UserRole and Program Roles. If you’re new to the API, see Creating API Keys for App Store Connect API, Generating Tokens for API Requests, and Identifying Rate Limits.