Product page experiments: treatments, assets, review proposal

flightline experiments manages selected App Store product page experiment workflows directly. These v2 experiments, their treatments, and treatment media have no L2 state YAML contract. The examples use the synthetic bundle ID com.example.app and placeholder IDs returned by your own account. Verify the commands in your installed build with flightline experiments --help and each subcommand's --help. This source workflow has local test coverage; live Apple qualification is pending.

Select the version and inspect

Shell

flightline experiments list com.example.app \
  --version 1.0 --platform IOS --output json

flightline experiments get com.example.app \
  --version 1.0 --platform IOS --experiment EXPERIMENT_ID --output json

All selected experiment, treatment, locale, and asset commands resolve the bundle ID and the unique App Store version identified by --version and --platform (IOS defaults). They verify experiment membership in that version's v2 collection and app/platform identity. Use IDs returned by reads; names are for humans and can collide.

Creation is different: Apple's create endpoint binds the experiment to the app, not to the caller-selected version. Flightline resolves the requested version as a guard, but its create response explicitly says version association is not established by the create API. Inspect experiments list for the selected version after creation. Until it appears there, selected treatment, lifecycle, and proposal commands cannot treat it as a member of that version. Do not infer membership from a successful create response.

Create and author a treatment

Shell

flightline experiments create com.example.app \
  --version 1.0 --platform IOS \
  --name 'Example icon test' --traffic 50 --confirm --output json

flightline experiments list com.example.app \
  --version 1.0 --platform IOS --output json

--traffic is an integer from 1 to 100. A create call with an existing app experiment of the same name and platform returns that experiment only if traffic matches; conflicting traffic or duplicate matches require inspection. If creation has an uncertain outcome, inspect the app/version before retrying. Authoring proceeds only after the version-scoped list confirms the experiment ID.

Shell

flightline experiments treatments list com.example.app \
  --version 1.0 --platform IOS --experiment EXPERIMENT_ID --output json

flightline experiments treatments create com.example.app \
  --version 1.0 --platform IOS --experiment EXPERIMENT_ID \
  --name 'Alternate artwork' --confirm --output json

flightline experiments treatments localizations create com.example.app \
  --version 1.0 --platform IOS --experiment EXPERIMENT_ID \
  --treatment TREATMENT_ID --locale en-US --confirm --output json

flightline experiments treatments localizations list com.example.app \
  --version 1.0 --platform IOS --experiment EXPERIMENT_ID \
  --treatment TREATMENT_ID --output json

There can be at most three treatments. Treatment creation also accepts --app-icon-name for an icon in the current app binary. Reusing the same treatment name with a different icon is a conflict. Creating a locale that already exists returns the existing localization. Keep treatment and locale IDs from the read responses for diagnosis, even though asset commands select the locale by --locale.

Experiment name/traffic updates, treatment edits, localization changes, media uploads/deletes, and experiment deletion require an editable draft: state PREPARE_FOR_SUBMISSION, no start date, and no end date. Mutations require --confirm. experiments update accepts --name and/or --traffic; treatments update accepts --name and/or --app-icon-name. Changes to started, stopped, completed, or other noneditable states fail the local guard.

Upload and inspect treatment media

Asset commands select the experiment, treatment, locale, kind, and display type. --kind screenshot uses a screenshot display type, such as APP_IPHONE_67; --kind preview uses a preview type, such as IPHONE_67. The type vocabularies differ. Use the values supported by the installed build for the relevant kind before choosing a device slot.

Shell

flightline experiments treatments localizations assets list com.example.app \
  --version 1.0 --platform IOS --experiment EXPERIMENT_ID \
  --treatment TREATMENT_ID --locale en-US --output json

flightline experiments treatments localizations assets upload \
  com.example.app ./alternate-iphone.png \
  --version 1.0 --platform IOS --experiment EXPERIMENT_ID \
  --treatment TREATMENT_ID --locale en-US \
  --kind screenshot --display-type APP_IPHONE_67 \
  --confirm --output json

Upload finds or creates the selected media set, uploads the file, then waits for processing. Screenshot and preview media use the same command with different --kind and --display-type. Local files must exist, be regular, and be nonempty. --max-polls defaults to 20 and --poll-interval to 3 seconds; increase the bound when processing takes longer. A returned asset ID identifies the reservation to inspect after a timeout.

Shell

flightline experiments treatments localizations assets wait com.example.app \
  --version 1.0 --platform IOS --experiment EXPERIMENT_ID \
  --treatment TREATMENT_ID --locale en-US \
  --kind screenshot --display-type APP_IPHONE_67 --asset ASSET_ID \
  --output json

wait first confirms that the asset belongs to the selected set, then polls processing without uploading again. Unlike event media, treatment screenshots and previews expose source checksums. Upload computes a local MD5 and compares filename/checksum against assets in the selected set. A matching processed asset can be reused; a conflicting or ambiguous filename/checksum requires inspection. An AWAITING_UPLOAD asset requires --resume with the exact matching local checkpoint and file. Do not create a second reservation merely because processing is still pending.

To upload a preview, use --kind preview --display-type IPHONE_67 with a suitable video file. The same assets list and assets wait paths apply. Deleting an asset is explicit: assets delete takes the same selector flags, --asset ASSET_ID, and --confirm; it is allowed only while the experiment remains an editable draft.

Shell

flightline experiments treatments localizations assets upload \
  com.example.app ./alternate-preview.mp4 \
  --version 1.0 --platform IOS --experiment EXPERIMENT_ID \
  --treatment TREATMENT_ID --locale en-US \
  --kind preview --display-type IPHONE_67 \
  --confirm --output json

List assets again to inspect the selected set, filenames, checksums, and processing states. A committed upload is not complete until its processing state is ready; use assets wait with the returned asset ID when the upload's bounded wait expires.

Lifecycle and review readiness

Shell

flightline experiments get com.example.app \
  --version 1.0 --platform IOS --experiment EXPERIMENT_ID --output json

flightline experiments proposal com.example.app \
  --version 1.0 --platform IOS --experiment EXPERIMENT_ID --output json

The read-only proposal checks unique membership in the selected version and requires READY_FOR_REVIEW with no start or end date. It returns an appStoreVersionExperimentV2 item proposal. A proposal does not attach an item or submit a review. Recheck it immediately before a separate submission assembly action. Flightline does not use this command to force the experiment into READY_FOR_REVIEW; that state must be observed from Apple.

experiments start requires an APPROVED experiment with reviewRequired false and no prior start/end date. experiments stop requires a started experiment. Both require the selected version, --experiment, and --confirm. A STOPPED or COMPLETED experiment, or one with an end date, cannot restart. Treat stop as a terminal decision; inspect the fresh state before issuing it.