Module: VistarClient::API::AdServing

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

Overview

Ad Serving API methods for requesting ads and submitting proof of play.

This module implements the core Vistar Media Ad Serving API:

  • GetAd endpoint: Request programmatic ads

  • Proof of Play endpoint: Confirm ad display

See Also:

Instance Method Summary collapse

Instance Method Details

#request_ad(device_id:, display_area:, latitude:, longitude:, **options) ⇒ Hash

Request an ad from the Vistar Media API.

Examples:

response = client.request_ad(
  device_id: 'device-123',
  display_area: { width: 1920, height: 1080 },
  latitude: 37.7749,
  longitude: -122.4194,
  duration_ms: 15_000
)

Parameters:

  • device_id (String) —

    unique identifier for the device (required)

  • display_area (Hash) —

    display dimensions (required, keys: :width, :height in pixels)

  • latitude (Float) —

    device latitude (required)

  • longitude (Float) —

    device longitude (required)

  • options (Hash) —

    optional parameters

Options Hash (**options):

  • :duration_ms (Integer) —

    ad duration in milliseconds

  • :device_type (String) —

    type of device (e.g., ‘billboard’, ‘kiosk’)

  • :allowed_media_types (Array<String>) —

    supported media types (e.g., [‘image/jpeg’, ‘video/mp4’])

Returns:

  • (Hash) —

    ad response data from the API

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



43
44
45
46
47
48
49
50
 
# File 'lib/vistar_client/api/ad_serving.rb', line 43

def request_ad(device_id:, display_area:, latitude:, longitude:, **options)
  validate_request_ad_params!(device_id, display_area, latitude, longitude)

  payload = build_ad_request_payload(device_id, display_area, latitude, longitude, options)

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

#submit_proof_of_play(advertisement_id:, display_time:, duration_ms:, **options) ⇒ Hash

Submit proof of play for a displayed ad.

Examples:

response = client.submit_proof_of_play(
  advertisement_id: 'ad-789',
  display_time: Time.now,
  duration_ms: 15_000,
  device_id: 'device-123'
)

Parameters:

  • advertisement_id (String) —

    ID of the advertisement that was displayed (required)

  • display_time (Time, String) —

    when the ad was displayed (required)

  • duration_ms (Integer) —

    how long the ad was displayed in milliseconds (required)

  • options (Hash) —

    optional parameters

Options Hash (**options):

  • :device_id (String) —

    device that displayed the ad

  • :venue_metadata (Hash) —

    additional venue information

Returns:

  • (Hash) —

    proof of play confirmation from the API

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



75
76
77
78
79
80
81
82
 
# File 'lib/vistar_client/api/ad_serving.rb', line 75

def submit_proof_of_play(advertisement_id:, display_time:, duration_ms:, **options)
  validate_proof_of_play_params!(advertisement_id, display_time, duration_ms)

  payload = build_proof_of_play_payload(advertisement_id, display_time, duration_ms, options)

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