Dynamic Mode (Device-Aware Optimization)

About dynamic mode

What is it? Dynamic mode automatically adapts image quality, dimensions, and format based on the visitor's device type. Instead of serving the same image to every user, each device category (mobile, tablet, desktop, etc.) receives an optimized version defined by a preset.

Example: A 4K product image is served at 1920 px wide / quality 90 on desktop, but 800 px wide / quality 75 on mobile — automatically, without any URL changes.

Enable dynamic mode

Dynamic mode is included in the Image Optimizer service. Configure via environment variables:

DYNAMIC_MODE=true
PRESET_LIST='[&#123;"device":"mobile","quality":75,"width":800&#125;,&#123;"device":"tablet","quality":80,"width":1200&#125;,&#123;"device":"pc","quality":90,"width":1920&#125;,&#123;"device":"default","quality":80&#125;]'

Variable	Type	Default	Description
`DYNAMIC_MODE`	boolean	`false`	Enable device-aware preset matching
`PRESET_LIST`	string	(none)	JSON array of device presets (required when enabled)

When DYNAMIC_MODE is false (default), the system uses static defaults from QUALITY_PRESET, CONVERT_TO_WEBP, and other environment variables as before.

Device categories

The device type is detected automatically from the User-Agent header:

Category	Matches
`mobile`	Smartphones
`tablet`	Tablets
`pc`	Desktop / laptop browsers
`appliance`	Smart TVs, game consoles
`default`	Unrecognized or missing UA

Preset configuration

Each preset in PRESET_LIST is a JSON object with the following fields:

Field	Type	Required	Description
`device`	string	Yes	Device category to match (see table above)
`quality`	number (1-100)	No	Image quality for this device
`width`	number	No	Target image width in pixels
`height`	number	No	Target image height in pixels
`webp`	boolean	No	Override WebP conversion for this device

Fallback preset

If no preset matches the detected device, the system looks for a preset with device set to "default" or "default/fallback". If no fallback exists either, the static defaults from other environment variables are used.

Example preset list

[
  &#123; "device": "mobile",  "quality": 75, "width": 800, "webp": true &#125;,
  &#123; "device": "tablet",  "quality": 80, "width": 1200 &#125;,
  &#123; "device": "pc",      "quality": 90, "width": 1920 &#125;,
  &#123; "device": "appliance", "quality": 70, "width": 1280 &#125;,
  &#123; "device": "default", "quality": 80 &#125;
]

Query parameter overrides

Query parameters (?width=, ?height=, ?quality=, ?fmt=, ?crop=) always take priority over preset values. This allows per-image fine-tuning on top of device-aware defaults.

# Preset sets width=800 for mobile, but this URL forces 400
https://cdn.example.com/photo.jpg?width=400

Usage examples

# Automatic: mobile gets 800px/q75, desktop gets 1920px/q90
https://cdn.example.com/photo.jpg

# Override quality regardless of device preset
https://cdn.example.com/photo.jpg?quality=60

# Override width + add crop regardless of device preset
https://cdn.example.com/photo.jpg?width=600&crop=1:1