Module: VistarClient::API::CreativeCaching

Includes:
Base
Included in:
Client
Defined in:
lib/vistar_client/api/creative_caching.rb

Overview

Creative Caching API methods for pre-fetching and caching creative assets.

This module implements the Vistar Media Creative Caching API which allows media owners to request and cache creatives in advance. This is beneficial for poor internet connectivity scenarios and bandwidth optimization.

Returns all creatives that qualify to run on a venue over the next 30 hours.

See Also:

Instance Method Summary collapse

Instance Method Details

#get_asset(device_id:, venue_id:, display_time:, display_area:, **options) ⇒ Hash

Request creative assets for caching in advance.

Returns all creatives that qualify to run on the specified venue over the next 30 hours based on campaign targeting. Recommended to call once daily combined with downloading assets on first sight for dynamic creatives.

Examples:

Basic usage

assets = client.get_asset(
  device_id: 'device-123',
  venue_id: 'venue-456',
  display_time: Time.now.to_i,
  display_area: {
    id: 'display-0',
    width: 1920,
    height: 1080,
    supported_media: ['image/jpeg', 'video/mp4'],
    allow_audio: false
  }
)

With optional parameters

assets = client.get_asset(
  device_id: 'device-123',
  venue_id: 'venue-456',
  display_time: Time.now.to_i + 3600,
  display_area: {
    id: 'display-0',
    width: 1920,
    height: 1080,
    supported_media: ['image/jpeg', 'video/mp4']
  },
  device_attribute: [
    { name: 'location', value: 'lobby' }
  ],
  latitude: 37.7749,
  longitude: -122.4194
)

Parameters:

  • device_id (String) —

    unique identifier for the device (required)

  • venue_id (String) —

    venue identifier making the request (required)

  • display_time (Integer) —

    time to match relevant assets in UTC epoch seconds (required)

  • display_area (Hash) —

    display configuration (required, keys: :id, :width, :height, :supported_media)

  • options (Hash) —

    optional parameters

Options Hash (**options):

  • :device_attribute (Array<Hash>) —

    custom targeting attributes

  • :latitude (Float) —

    degrees north (optional)

  • :longitude (Float) —

    degrees east (optional)

Returns:

  • (Hash) —

    response containing array of assets with metadata

Raises:

  • (ArgumentError) —

    if required parameters are missing or invalid

  • (AuthenticationError) —

    if API key is invalid (401)

  • (APIError) —

    for other API errors (4xx/5xx)

  • (ConnectionError) —

    for network failures



72
73
74
75
76
77
78
79
 
# File 'lib/vistar_client/api/creative_caching.rb', line 72

def get_asset(device_id:, venue_id:, display_time:, display_area:, **options)
  validate_get_asset_params!(device_id, venue_id, display_time, display_area)

  payload = build_get_asset_payload(device_id, venue_id, display_time, display_area, options)

  response = connection.post('/api/v1/get_asset/json', payload)
  response.body
end