Developer Guide: Target CDN Asset Delivery

This guide explains how to use test.tgtcdn.com for private GCS-backed image retrieval, Cloudflare-native image transformations, Scene7-style compatibility URLs, cache behavior, and purge by GCS object key.

Platform Summary

Native Image Retrieval

Use raw object URLs when the page or application needs the original GCS object without resizing, format conversion, or quality changes.

https://test.tgtcdn.com/<object-key>

Known working example:

https://test.tgtcdn.com/007/ORIGINAL

Retrieval behavior:

Native Image Transformations

Use native Cloudflare Image Transformations URLs when Target controls application or page markup. This is the preferred long-term path because the browser requests Cloudflare's image pipeline directly without a compatibility redirect.

https://test.tgtcdn.com/cdn-cgi/image/<options>/<object-key>

Example product detail image:

https://test.tgtcdn.com/cdn-cgi/image/width=1200,height=1200,quality=85,format=auto,fit=scale-down,metadata=none/007/ORIGINAL

Example product tile:

https://test.tgtcdn.com/cdn-cgi/image/width=400,height=400,quality=80,format=auto,fit=crop,metadata=none/007/ORIGINAL

Example responsive gallery markup:

<img
  src="https://test.tgtcdn.com/cdn-cgi/image/width=800,height=800,quality=80,format=auto,fit=scale-down,metadata=none/007/ORIGINAL"
  srcset="
    https://test.tgtcdn.com/cdn-cgi/image/width=300,height=300,quality=80,format=auto,fit=scale-down,metadata=none/007/ORIGINAL 300w,
    https://test.tgtcdn.com/cdn-cgi/image/width=400,height=400,quality=80,format=auto,fit=scale-down,metadata=none/007/ORIGINAL 400w,
    https://test.tgtcdn.com/cdn-cgi/image/width=600,height=600,quality=80,format=auto,fit=scale-down,metadata=none/007/ORIGINAL 600w,
    https://test.tgtcdn.com/cdn-cgi/image/width=800,height=800,quality=80,format=auto,fit=scale-down,metadata=none/007/ORIGINAL 800w,
    https://test.tgtcdn.com/cdn-cgi/image/width=1200,height=1200,quality=80,format=auto,fit=scale-down,metadata=none/007/ORIGINAL 1200w
  "
  sizes="(min-width: 992px) 60vw, 50vw"
  alt="Product image"
>

Transformation Defaults

Each unique option set creates a separate cacheable image variant. Keep widths, quality levels, and fit modes intentional to avoid unnecessary variant growth.

Compatibility URL Translation

Use compatibility URLs when testing existing Scene7-style URLs or when URL generation cannot change yet.

https://test.tgtcdn.com/is/image/Target/<object-key>?wid=<width>&hei=<height>&qlt=<quality>&fmt=<format>&fit=<fit>

Example compatibility request:

https://test.tgtcdn.com/is/image/Target/007/ORIGINAL?wid=800&hei=800&qlt=80&fmt=pjpeg

Current flow:

/is/image/Target/... -> image-url-translator Worker -> 302 -> /cdn-cgi/image/...

Compatibility parameter mapping:

Examples of compatibility normalization:

Compatibility URLs are useful for migration testing and noisy legacy URL handling. They are not the preferred final markup because the current implementation adds a browser redirect before the transformed image is fetched.

Cache And Purge Logic

Raw source assets and transformed variants are cached at Cloudflare. The same source image requested with different transform options creates distinct transformed variants.

Purge is based on the GCS object key. The Worker attaches the object key directly as the Cloudflare cache tag, prefixed with gcs-key:.

gcs-key:007/ORIGINAL

Purge behavior:

API example:

ZONE_ID="aacac726952b470209b3c31c95ea0b17"

curl -X POST "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/purge_cache" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"tags":["gcs-key:007/ORIGINAL"]}'

Do not exact-purge /cdn-cgi/image/... transformed URLs. Cloudflare rejects exact purges for resized image URLs; purge the gcs-key:<object-key> tag instead.

When To Use Each Structure

Observability And Tooling

Observability backend split:

For Log Explorer or Logpush, enable the http_requests dataset for test.tgtcdn.com. The POC uses header-based enrichment as the recommended default: Workers emit approved X-* response headers and Log Explorer captures them as custom response fields. Current fields are X-Asset-Key, X-Cache-Tag, X-CDN-Origin, X-Origin-Mode, X-Transform-Method, X-Resolved-Width, and X-Resolved-Format.

Customer decision point:

Native /cdn-cgi/image/... responses are generated by Cloudflare Image Transformations and may not carry Worker headers, so investigate those by request path, status, cache status, Ray ID, and the object key derived from /cdn-cgi/image/<options>/<object-key>.

Validation Commands

Validate raw native retrieval:

curl -I "https://test.tgtcdn.com/007/ORIGINAL"

Validate native transform delivery:

curl -I -H "Accept: image/webp" \
  "https://test.tgtcdn.com/cdn-cgi/image/width=640,quality=85,format=webp,fit=scale-down/007/ORIGINAL"

Validate compatibility behavior:

curl -IL "https://test.tgtcdn.com/is/image/Target/007/ORIGINAL?wid=1200&hei=1200&qlt=80"

Run the full guide-derived image suite:

node scripts/test-developer-image-guide.mjs

Expected signals: