Asset Caching

The Asset Caching endpoint allows publishers to retrieve all compatible assets for their screens before they're needed. This enables pre-caching strategies that reduce latency and improve the user experience when displaying advertisements.

Asset compatibility

Assets must match your screen's specifications to be displayable. The compatibility system considers both dimensional requirements and playback capabilities.

Compatibility matrix

Different screen types support different asset formats based on their playback capabilities:

Name
static
Type
screen type
Description
Can only display static image assets
Name
slow
Type
screen type
Description
Can display static images and slow-motion videos
Name
moving
Type
screen type
Description
Can display all asset types including full-motion video

Screen Type	Static Assets	Slow Assets	Moving Assets
static
slow
moving

Dimensional requirements

Assets must exactly match your screen's resolution. For example, a 1920x1080 screen can only display assets with those exact dimensions.

Screen identification

You can identify screens in API requests using either UUIDs (recommended) or external IDs (fallback only).

UUID (recommended)

Use UUIDs for optimal performance. This is the recommended method for all integrations:

GET /screens/a1b2c3d4-e5f6-7890-abcd-ef1234567890/cacheable-assets

External ID (fallback only)

Performance Impact: External IDs significantly reduce API performance. Only use if your CMS/playout system cannot support UUIDs:

GET /screens/external-id/SCREEN-001/cacheable-assets

Learn more: See the External Screen IDs documentation for requirements, setup instructions, and important performance considerations.

Retrieve cacheable assets

This endpoint supports both UUID (recommended for best performance) and External ID (fallback only for legacy systems) identification methods.

Using UUID

Demo/Test Functionality

Use screen ID test-display-test for testing and development.

• Returns 3 demo assets with placeholder images
• 24-hour cache expiration time
• No database modifications
• Requires valid Publisher API key

This endpoint returns all assets that are compatible with the specified screen and available for caching. The response includes asset metadata, campaign information, and screen compatibility details.

Path parameters

Name
screenId
Type
string
Description
The unique identifier for the screen.

Request

GET

/functions/v1/api/screens/[screenId]/cacheable-assets

curl -X GET https://api.adlocaite.com/functions/v1/api/screens/[screenId]/cacheable-assets?min_bid_cents=123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "screen_id": "11111111-2222-3333-4444-555555555555",
  "total_assets": 1,
  "assets": [
    {
      "asset_url": "https://hipleh.com/wp-content/uploads/2022/04/Best_Burger_Cover.jpg",
      "cache_expires_at": "2025-08-20 18:05:55.758768+00"
    }
  ]
}

Demo Response

{
  "screen_id": "test-display-test",
  "total_assets": 3,
  "assets": [
    {
      "asset_url": "https://via.placeholder.com/1920x1080/FF0000/FFFFFF?text=Demo+Asset+1",
      "cache_expires_at": "2025-08-28 12:00:00.000000+00"
    },
    {
      "asset_url": "https://via.placeholder.com/1920x1080/00FF00/FFFFFF?text=Demo+Asset+2",
      "cache_expires_at": "2025-08-28 12:00:00.000000+00"
    },
    {
      "asset_url": "https://via.placeholder.com/1920x1080/0000FF/FFFFFF?text=Demo+Asset+3",
      "cache_expires_at": "2025-08-28 12:00:00.000000+00"
    }
  ]
}

Empty Response

{
  "screen_id": "11111111-2222-3333-4444-555555555555",
  "total_assets": 0,
  "assets": []
}

Error Response (401)

{
  "error": "Missing or invalid authorization header. Use: Bearer <publisher_api_key>"
}

Error Response (404)

{
  "error": "Screen not found or access denied"
}

Error Response (500)

{
  "error": "Internal server error",
  "details": "Specific error message"
}

Using External ID

Performance Warning

External IDs significantly reduce API performance. Only use this endpoint if your CMS or playout system cannot work with UUIDs. Your account must be activated for external IDs - contact support@adlocaite.com.

This endpoint returns the same cacheable assets as the UUID version, but allows you to identify screens using your own external identifiers. Use only if UUIDs are not technically feasible in your system.

Path parameters

Name
externalId
Type
string
Description
Your custom identifier for the screen (e.g., "SCREEN-001", "berlin-hauptbahnhof").

Query parameters

Name
min_bid_cents
Type
integer
Description
Optional minimum bid amount in cents to filter assets.

Request

GET

/functions/v1/api/screens/external-id/[externalId]/cacheable-assets

curl -X GET "https://uamoseamohhsxwybytqx.supabase.co/functions/v1/api/screens/external-id/SCREEN-001/cacheable-assets?min_bid_cents=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "screen_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "SCREEN-001",
  "total_assets": 2,
  "assets": [
    {
      "asset_url": "https://storage.example.com/ad-12345.jpg",
      "cache_expires_at": "2025-10-07T16:30:00Z"
    },
    {
      "asset_url": "https://storage.example.com/ad-67890.mp4",
      "cache_expires_at": "2025-10-07T16:30:00Z"
    }
  ]
}

Error Response (404)

{
  "error": "Screen not found with external_id: SCREEN-001"
}

Error Response (401)

{
  "error": "Missing or invalid authorization header. Use: Bearer <publisher_api_key>"
}

Integration guidelines

Asset pre-caching strategy

Asset pre-caching implementation

async function cacheAssetsForScreen(screenId, apiKey) {
  try {
    const response = await fetch(`https://api.adlocaite.com/functions/v1/api/screens/[screenId]/cacheable-assets?min_bid_cents=123`, {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    });
    
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
    
    const data = await response.json();
    
    // Preload all compatible assets
    data.assets.forEach(asset => {
      const link = document.createElement('link');
      link.rel = 'prefetch';
      link.href = asset.asset_url;
      document.head.appendChild(link);
    });
    
    return data.assets;
  } catch (error) {
    console.error('Asset caching failed:', error);
    return []; // Fallback to empty array
  }
}

Error handling best practices

Always implement proper error handling to ensure your application remains stable:

try {
  const assets = await fetch('https://api.adlocaite.com/functions/v1/api/screens/[screenId]/cacheable-assets?min_bid_cents=123', {
    headers: { 'Authorization': 'Bearer ' + API_KEY }
  });
  
  if (assets.status === 401) {
    // Handle authentication error
    await refreshApiKey();
    return;
  }
  
  if (assets.status === 404) {
    // Screen not found or no access
    console.warn('Screen not accessible');
    return [];
  }
  
  const data = await assets.json();
  return data.assets;
} catch (error) {
  console.error('Network error:', error);
  return []; // Always return fallback
}

Performance optimization

Caching recommendations

Name
Cache-Control
Type
HTTP header
Description
Use public, max-age=300, stale-while-revalidate=600 for optimal caching
Name
Polling frequency
Type
recommendation
Description
Check for new assets every hour - more frequent calls than every 15 minutes are not recommended
Name
Bandwidth management
Type
strategy
Description
Download assets during off-peak hours to reduce impact on live traffic

Response characteristics

Typical response size: 1-50 assets (< 10KB JSON)
Large networks: Up to 200 assets (< 50KB JSON)
Average response time: 20-80ms
Empty responses: Minimal overhead (< 1KB)

Asset properties

Each asset in the response contains the following information:

Name
asset_url
Type
string
Description
Direct URL to the asset file for download/caching.
Name
cache_expires_at
Type
timestamp
Description
When this cached asset URL expires and should be refreshed.