Skip to main content

Configuration Guide

This guide covers VEE-side configuration of the BILDIT Web Visual Experience Engine — admin access, webhooks, and caching. Configuration for rendering scheduled content on your production site (your API key and BILDIT base URL — the root URL of your CMS instance) lives with the SDK, not here.

API keys & production-site URLs​

Your production site's API key and BILDIT base URL (the root URL of your CMS instance — the host you log into BILDIT at) are set as environment variables in your Next.js app, not in this VEE configuration. See the Integration Guide → environment variables for BILDIT_API_KEY and BILDIT_API_URL.

Admin Access​

Edit Admin Settings​

  • Access the admin settings panel in the Visual Experience Engine
  • Configure user roles and permissions

Secure Access​

Implement authentication mechanisms such as OAuth or JWT:

  • Ensure secure access to admin functionalities
  • Set up proper user authentication flow

Advanced Configuration​

Webhooks Configuration​

Configure webhooks to enable real-time asset synchronization and notifications.

Asset Webhooks​

Set up webhooks to be notified when asset is created, updated, or deleted:

{
  "url": "https://webhook.example.com/content",
  "events": ["content.created", "content.updated", "content.deleted"],
  "description": "Asset webhook for real-time updates"
}

Scheduled Content Webhooks​

Configure webhooks for scheduled content lifecycle events:

{
  "url": "https://webhook.example.com/banners", 
  "events": ["banner.created", "banner.published", "banner.archived"],
  "description": "Scheduled content webhook for campaign management"
}

Specification Webhooks​

Set up webhooks for specification and layout changes:

{
  "url": "https://webhook.example.com/screens",
  "events": ["screen.updated", "layout.changed"],
  "description": "Specification webhook for layout synchronization"  
}

Replication Webhooks​

Configure webhooks for content replication across environments:

{
  "url": "https://webhook.example.com/replicate",
  "events": ["content.replicated", "sync.completed"],
  "description": "Replication webhook for multi-environment sync"
}

Cache & Optimizer Configuration​

Configure your CDN/load-balancer cache and image optimizer. Replace the placeholder values below with your own.

Cache Domain: the primary caching domain

https://your-cache-domain.example.com

Cache API Key: authentication for cache services (store securely; never commit)

<your-cache-api-key>

Cache Targets: cache invalidation targets

HOMEPAGE, CMS

Image Configuration​

Configure your image/content optimizer for media processing:

{
  "cacheSettings": {
    "protocol": "https",
    "hostname": "your-image-cdn.example.com", 
    "pathname": "*/ss"
  },
  "optimization": {
    "protocol": "https",
    "hostname": "your-optimizer-host.example.com",
    "pathname": "*/ss"  
  }
}

Configuration Options​

Location: the target environment URL

https://your-site.example.com/

Slot ID: the slot identifier for content placement

home-bottom-center-slot

Alternative Text: accessibility text for content

e.g. Spring Sale

Testing Configuration​

Verification Steps​

  1. Verify all configurations are correctly set by running tests
  2. Check for any errors or misconfigurations in the console
  3. Test webhook endpoints to ensure proper connectivity
  4. Validate cache configuration with sample content

Configuration Validation​

Use the built-in configuration validator:

# Test public configuration
curl -X GET "https://your-cms-domain.example.com/api/config/validate"

# Test webhook configuration  
curl -X POST "https://your-webhook-endpoint.example.com/test" \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

Troubleshooting Configuration​

Common Issues​

CORS Errors​

  • Issue: Cross-origin requests are blocked
  • Solution: Ensure your server allows cross-origin requests from the Visual Experience Engine domain

Missing Dependencies​

  • Issue: Required packages are not installed
  • Solution: Check for any missing packages and install them

Configuration Errors​

  • Issue: Invalid configuration values
  • Solution: Double-check your configuration files for typos or incorrect values

Webhook Failures​

  • Issue: Webhooks not receiving events
  • Solution: Verify endpoint URLs are accessible and properly configured

Configuration Checklist​

  • Admin authentication configured
  • Webhook endpoints created and tested
  • Cache settings configured
  • Image optimization settings applied
  • Configuration validated with test requests
  • Error handling and logging enabled
  • Security settings reviewed and applied

Next Steps​

After completing configuration:

  1. Render scheduled content on your production site with the Next.js Integration Guide
  2. Test your setup with the Getting Started guide
  3. Create your first content with Creating Scheduled Content

Support​

  • For configuration assistance:
  • Review the Troubleshooting Guide
  • Check webhook delivery logs in the Visual Experience Engine admin panel
  • Contact support with your configuration details