AdCP — preview_creative (Advanced)

Advanced patterns for creative preview integration including workflows, caching strategies, and implementation notes. For basic usage, see preview_creative.

Common Workflows

Format Showcase Pages

Build a browsable catalog of available formats:

// 1. List all formats from creative agent
const formats = await creative_agent.list_creative_formats();

// 2. Generate format card previews (batch + HTML)
const formatPreviews = await creative_agent.preview_creative({
  request_type: "batch",
  output_format: "html",
  requests: formats.formats.map(format => ({
    format_id: format.format_id,
    creative_manifest: format.format_card.manifest
  }))
});

// 3. Render in a grid
function FormatCatalog({ formatPreviews }) {
  return (
    <div className="format-grid">
      {formatPreviews.results.map((result, idx) => (
        result.success && (
          <div
            key={idx}
            className="format-card"
            dangerouslySetInnerHTML={{
              __html: result.response.previews[0].renders[0].preview_html
            }}
          />
        )
      ))}
    </div>
  );
}

Campaign Review Grid

Review all creatives before launch:

const campaignCreatives = await getCreativesForCampaign(campaignId);

const previews = await creative_agent.preview_creative({
  request_type: "batch",
  output_format: "html",
  requests: campaignCreatives.map(c => ({
    format_id: c.format_id,
    creative_manifest: c.manifest
  }))
});

function CampaignReview({ previews }) {
  return (
    <div className="review-grid">
      {previews.results.map((result, idx) => (
        <div className="creative-card">
          <div dangerouslySetInnerHTML={{
            __html: result.response.previews[0].renders[0].preview_html
          }}/>
          <button onClick={() => approve(idx)}>Approve</button>
          <button onClick={() => reject(idx)}>Reject</button>
        </div>
      ))}
    </div>
  );
}

Web Component Integration

For production applications with lazy loading:

<script src="https://creative.adcontextprotocol.org/static/rendered-creative.js"></script>

<div class="grid">
  <rendered-creative
    src="https://creative-agent.example.com/preview/abc123"
    width="300"
    height="400"
    lazy="true">
  </rendered-creative>
</div>

Benefits:

Shadow DOM for CSS isolation
Lazy loading (only loads when visible)
Framework agnostic

Choosing Output Format

Use output_format: "url" (default) when:

Security is paramount (third-party creatives)
Building interactive preview tools
Need iframe isolation

Use output_format: "html" when:

Building format catalogs (10+ formats)
Creating campaign review grids (20+ creatives)
Server-side rendering
Working with trusted creative agents only

Caching Strategy

Cache individual preview results by format_id + manifest hash:

function cachePreviewResults(results, formatIds, manifests) {
  results.forEach((result, idx) => {
    if (result.success) {
      const cacheKey = `${formatIds[idx]}:${hashManifest(manifests[idx])}`;
      cache.set(cacheKey, result.response, result.response.expires_at);
    }
  });
}

async function getPreviewsWithCache(formatIds, manifests) {
  const cached = [];
  const toFetch = [];

  formatIds.forEach((id, idx) => {
    const cacheKey = `${id}:${hashManifest(manifests[idx])}`;
    const cachedResult = cache.get(cacheKey);

    if (cachedResult && !isExpired(cachedResult.expires_at)) {
      cached[idx] = cachedResult;
    } else {
      toFetch.push({ idx, id, manifest: manifests[idx] });
    }
  });

  // Batch fetch only missing previews
  if (toFetch.length > 0) {
    const fetched = await client.preview_creative({
      request_type: "batch",
      output_format: "html",
      requests: toFetch.map(f => ({
        format_id: f.id,
        creative_manifest: f.manifest
      }))
    });

    fetched.results.forEach((result, i) => {
      cached[toFetch[i].idx] = result.response;
    });
  }

  return cached;
}

Key points:

Cache by format_id + manifest hash (not entire batch)
Request [A,B,C] → cache each separately
Later request [B,C,D] → only fetch D
Always check expires_at before using cached previews

Preview URL Storage

Preview URLs are review resources, not just transport conveniences. A buyer, browser, or MCPUI host may fetch a preview_url after the original preview_creative call returns, after a pod restart, or from a different pod than the one that created the render. For production agents, persist enough preview state to resolve every preview_url through its advertised lifetime:

If expires_at is present, keep the render available until that timestamp.
If expires_at is omitted, treat the URL as non-expiring at the protocol layer and keep it available until explicit out-of-band revocation or purge.
Use shared storage for multi-process or multi-pod deployments: database metadata plus object storage, a shared cache tier, or an authenticated preview route that can recover the render from durable session state.
Limit process-local Map or LRU storage to single-process demos, local development, or URLs whose advertised lifetime is shorter than the process lifetime you can actually guarantee.

Error Handling

const response = await client.preview_creative({
  request_type: "batch",
  requests: formatRequests
});

const succeeded = response.results.filter(r => r.success);
const failed = response.results.filter(r => !r.success);

if (failed.length > 0) {
  console.log(`${failed.length} previews failed`);
  failed.forEach((result) => {
    console.error(`  - ${result.error.code}: ${result.error.message}`);
  });
}

// Display successful previews, show error states for failures
function displayPreviews(results) {
  return results.map((result, idx) => {
    if (result.success) {
      return <Preview html={result.response.previews[0].renders[0].preview_html} />;
    } else {
      return <PreviewError
        code={result.error.code}
        message={result.error.message}
        onRetry={() => retryPreview(idx)}
      />;
    }
  });
}

Migration from Single to Batch

Before (Sequential):

previews = []
for format in formats:
    preview = await client.preview_creative(
        request_type="single",
        creative_manifest=format.format_card.manifest
    )
    previews.append(preview)
# Total time: N × 250ms = 5000ms for 20 formats

After (Batch):

response = await client.preview_creative(
    request_type="batch",
    output_format="html",
    requests=[
        {"creative_manifest": fmt.format_card.manifest}
        for fmt in formats
    ]
)
# Total time: ~500ms for 20 formats

Use Case Patterns

Device Variants

{
  "inputs": [
    { "name": "Desktop", "macros": { "DEVICE_TYPE": "desktop" } },
    { "name": "Mobile", "macros": { "DEVICE_TYPE": "mobile" } },
    { "name": "CTV", "macros": { "DEVICE_TYPE": "ctv" } }
  ]
}

Geographic Variants

{
  "inputs": [
    { "name": "NYC", "macros": { "CITY": "New York", "DMA": "501" } },
    { "name": "LA", "macros": { "CITY": "Los Angeles", "DMA": "803" } }
  ]
}

Privacy Compliance Testing

{
  "inputs": [
    { "name": "Full consent", "macros": { "GDPR": "1", "GDPR_CONSENT": "CPc7TgP..." } },
    { "name": "No consent", "macros": { "GDPR": "1", "GDPR_CONSENT": "" } },
    { "name": "LAT enabled", "macros": { "LIMIT_AD_TRACKING": "1" } }
  ]
}

AI Content Variants

{
  "inputs": [
    { "name": "Morning commute", "context_description": "User commuting to work" },
    { "name": "Evening relaxation", "context_description": "User relaxing at home" }
  ]
}

Implementation Notes

For Creative Agents

Required:

Return complete HTML pages from preview_url
Handle all media types (images, video, audio, interactive)
Echo input parameters in response
Validate manifest before rendering
Apply macro values (or use defaults)
Back preview URLs with storage that survives load balancing and restarts for the URL’s advertised lifetime
Implement security sandboxing
Set reasonable expiration (24-48 hours) for previews that should not be retained indefinitely

Optional enhancements:

Provide hints object (media type, dimensions, duration)
Provide embedding metadata (sandbox policy, CSP)
Support responsive design
Include accessibility features

For Buyers

Just iframe the preview_url - no special rendering needed
Use inputs array for specific scenarios
Check input field to confirm macros applied
Share preview URLs with clients for approval
Use interactive_url for advanced testing

For Publishers

Return consistent HTML from preview URLs
Implement responsive preview pages
Document supported macros via supported_macros in formats
Clarify preview vs production differences
Consider providing interactive_url for testing

preview_creative - Basic usage and parameters
Creative Manifests - Manifest structure
Universal Macros - Available macro values

​Common Workflows

​Format Showcase Pages

​Campaign Review Grid

​Web Component Integration

​Choosing Output Format

​Caching Strategy

​Preview URL Storage

​Error Handling

​Migration from Single to Batch

​Use Case Patterns

​Device Variants

​Geographic Variants

​Privacy Compliance Testing

​AI Content Variants

​Implementation Notes

​For Creative Agents

​For Buyers

​For Publishers

​Related Documentation