1. Raven Channel Support
  2. Onboarding / Education
  3. Developer Guides

Articles in this section

Enhanced Video Access (EVA)

Brayden Hermann
  • Updated

Raven Connected offers Enhanced Video Access (EVA) Web Component and API integration calls to integration partners. While automated events capture the majority of driving incidents, business-impacting situations often require additional visual context. EVA bridges this gap by allowing fleet managers to remotely request targeted, high-definition video segments directly from a vehicle's continuously recorded SD card footage.

By embedding the EVA Web Component into your platform, you can empower your users with complete visibility, unlocking three key operational benefits:

  • Complete Context: Beyond standard telematics-triggered event videos, partners can easily provide customers with downloadable footage from any point in time, enriched with additional context. Using preview images along a timeline, users can visually identify key moments and download custom clips (up to 60 seconds).
  • On-Demand Retrieval: Leverage Raven’s LTE connection to pull historical footage to the cloud on-demand, ensuring data usage is optimized while keeping critical evidence accessible.
  • Powerful UI Integration: Deliver a polished user experience, complete with an interactive trip timeline, event indicators, and preview images, without having to build complex video-scrubbing UIs from scratch.

 

Overview

The <rc-enhanced-video-access> component presents a timeline showing events and preview images from the associated Raven device between provided timestamps. Users can also request new preview images and videos through this interface.

rc-web-components-eva.gif

 

  • Initialization: The component makes GET requests to load events, existing preview images, and videos for the specified timeframe. Events and images populate the timeline immediately as they arrive.
  • Automated Previews: If existing previews don't cover the entire timeline, the component will automatically request up to 20 new preview images at calculated intervals to fill the gaps.
  • User-Requested Previews: Users can request a new preview by dragging the slider over a specific point on the timeline for 3 seconds. A spinner indicates processing.
  • Error Handling: If a preview request fails (e.g., timeout, device offline, or vehicle parked), an error message appears at the bottom of the component.

Sizing Recommendation: The component will occupy the max available width of its parent container. The recommended height for the parent container is 150px. Due to content density, heights under 100px are not recommended.

 

Technical Implementation: The EVA Web Component

You can implement Enhanced Video Access in two ways: by using our drop-in Web Component for immediate, out-of-the-box functionality, or by building a custom integration using the underlying RC-API for complete control over the user interface.

Method 1: The EVA Web Component (Recommended)

Instead of building a video request pipeline from the ground up, this functionality is exposed as a drop-in Web Component (<rc-enhanced-video-access>). This automatically handles complex timeline rendering, event fetching, and video request commands.

 

Installation

Embed the component directly into your web application by including the Raven library script:

<head>
  <script defer src='https://cdn.ravenconnected.com/rc-web-components/0.13.9.min.js'></script>
</head>
<body>
  <rc-enhanced-video-access
      apidomain="api.yourdomain.ravenconnected.com"
      sessiontoken="YOUR_SECURE_TOKEN"
      ravenid="RAVEN_UUID_OR_SERIAL" 
      starttimestamp="1234567890"
      endtimestamp="9876543210" />
</body>

 

Configuration Attributes

To authenticate and target the correct device, the component relies on the following attributes:

Attribute Type Requirement Description
sessiontoken String Required A valid session token provided from the Raven API.
apidomain String Required The target API environment (e.g., api.dev.<id>.ravenconnected.com for dev, or api.<id>.ravenconnected.com for prod).
ravenid String Required The identifier for the vehicle's device (UUID or Serial Number).
starttimestamp String Required A Unix timestamp specifying the start time of the trip/window.
endtimestamp String Required A Unix timestamp specifying the end time of the trip/window.
requesttimestamp String Optional A Unix timestamp specifying the initial position of the dragger on mount.
hidepreviewpopup Boolean Optional Hides the default preview popup above the timeline. Allows you to handle showing previews in your own UI by subscribing to evaNotifications.
hidevideoslist Boolean Optional Hides the "HD Clips To Download" panel and icon. Allows you to handle the list in your own UI via evaNotifications.
forcereporting Boolean Optional Forces internal error reporting. Useful for sharing error reports from your development environment.
lang String Optional Sets the language. Supported values: "en" and "fr".

 

Method 2: Custom API Integration (For Greater Customization)

If you require greater customization and wish to develop your own user interface rather than using the Web Component, you can replicate the EVA functionality using existing RC-API media endpoints.

The strategy relies on a three-step process to load images as efficiently as possible, minimizing load times and LTE data consumption:

 

Step 1: Getting Existing Images from the Raven Cloud

The fastest way to present previews is to query for images that have already been captured to the cloud (from Raven events, partner events, or previously requested previews).

Make a GET request to /ravens/{ravenId}/media with the following parameters:

  • start_timestamp: start of the trip
  • end_timestamp: end of the trip
  • type: preview
  • signed_urls: true

Example Request:

GET /ravens/{ravenId}/media?type=preview&signed_urls=true&start_timestamp=1727796899&end_timestamp=1727796950

Note: This call returns ROAD and CABIN media as separate items in the results array. Once received, pair them in your UI by matching their timestamps. The preview for the last event of the trip may not be included; if missing, include it in Step 2.

 

Step 2: Filling the Empty Slots

Identify gaps in your timeline. If a significant time span lacks pre-existing images (e.g., no image within 30 seconds of a target interval), request new previews from the Raven device. This requires a POST request to trigger the generation, followed by a GET request to retrieve the files.

The POST Request (Generate Previews) Make a POST request to /ravens/{ravenId}/media to tell the device to generate the preview. Because the POST call does not currently support an array of timestamps, you must make two POST calls per timestamp (one for the ROAD camera, one for the CABIN camera).

POST Payload Example:

{
  "timestamp": 1727796899,
  "cameraType": "ROAD", 
  "mediaType": "PREVIEW"
}

 

The GET Request (Retrieve Previews) After your POST requests, make a GET request to /ravens/{ravenId}/media to retrieve the generated previews. Add a slight delay between the POST and GET requests to allow the device to create and upload the images.

GET Request Example:

GET /ravens/{ravenId}/media?type=preview&signed_urls=true&ts=1727796899,1727796901,1727796903

 

Best Practice (LTE Usage): Images consume LTE data (~150kB per image). Limit your automated requests to no more than 20 images at a time to preserve bandwidth and optimize upload times, which vary based on the vehicle's cellular signal strength.

Note: The response of this specific GET call (using the ts parameter) conveniently groups the CABIN and ROAD previews for a timestamp into a single object, so manual pairing is not required.

 

Step 3: Get Additional Previews by User Request

If a user hovers or clicks on a point in the timeline that lacks a preview, you can request an image specifically for that timestamp (and optionally, a slight offset before and after).

The process is identical to Step 2:

  • Make the required POST requests to trigger the image generation for that specific timestamp.
  • Follow up with a GET request to retrieve the new media.

Important: Requests for historical preview images will only succeed if the continuous raw video is still available and hasn't been overwritten on the Raven device's SD card. All newly requested images are cached in the Raven cloud, meaning subsequent loads of the same trip will be much faster.

 

Component Events

The component emits events to help your application react to user interactions, system statuses, and authentication lifecycles. These are categorized into EVA-Specific Events and Common Events (shared across all Raven web components).

Note: All emitted events are configured to bubble (bubbles: true) and are cancelable (cancelable: true) by default.

 

EVA-Specific Events

You can listen for two main event types specific to the Enhanced Video Access integration: evaNotifications and evaError.

1. evaNotifications (Interactions & Statuses)

  • mediaSyncCompleted: All existing videos are loaded (includes URLs).
  • videoAlreadyExists: A video already exists for the requested timestamp/camera (includes the video).
  • videoUrlRefreshed: Signed URLs for existing videos have been refreshed (URLs expire after 1 hour).
  • newVideoRequested: A request for a new video has been sent (includes request details).
  • requestedVideoReady: The requested video is ready to view/download (includes video details).
  • draggerUpdated: The user is moving the timeline dragger (includes current timestamp, duration, and associated previews).
  • popupBlur: The mouse was clicked outside the timeline (hides the built-in popup).
  • draggerMouseEnter / draggerMouseLeave: The pointer has entered or left the timeline dragger.
  • draggerTouchStart / draggerTouchEnd: The mobile touch event has started or ended for the timeline dragger.

 

2. evaError (Failures & Exceptions)

  • networkError: Caused by invalid attributes (e.g., bad ravenId or apiDomain) or CORS policy issues.
  • resourceNotReady: The requested preview or video is currently processing.
  • resourceNotAvailable: The request cannot be fulfilled (e.g., timestamp is during a parking period).
  • ravenNotAvailable: The Raven device is not responding (e.g., offline).
  • serverError: General backend failure.
  • invalidRaven: The provided Raven ID does not exist or lacks permissions.
  • ravenResponseTimeout: The device took too long to respond.

 

Common Events

The EVA component also inherits standard events utilized by all Raven web components.

Authentication Events (Crucial for Session Management)

  • sessionExpired: Emitted when the component requests a new token (currently triggered on reconnect attempts).

    Important Integration Requirement: You must listen for the sessionExpired event and update the component's sessiontoken attribute to complete the reconnection process. If a new session token is not provided, the component will lose its connection to the cloud and will stop functioning (e.g., displaying a perpetual loading spinner).
     
  • authError: Indicates an authentication failure, such as invalid permissions or other errors during the authentication request. Error events provide additional context through the event.detail property, which includes a subtype, data (often containing the Error object), and origin. Currently, authError will include the forbidden subtype.

 

Lifecycle Events

These events may be particularly helpful when embedding the Web Component within JavaScript frameworks (like React, Vue, or Angular):

  • willMount: Fired just before the component mounts.
  • mount: Fired when the component has successfully mounted.

 

Customization (CSS Properties)

You can seamlessly blend the component into your platform's existing theme using the following CSS custom properties.

Media Controls Properties:

--media-control-exit-full-screen-icon-url
--media-control-fullscreen-icon-url
--media-control-camera-toggle-icon-url
--media-controls-visibility
--media-control-background-color
--media-controls-align
--media-controls-vertical-position
--media-control-active-background-color

 

EVA Timeline & UI Properties:

/* Layout */
--eva-previews-popup-align: /* "left", "right" or "center". Default follows dragger. */
--eva-previews-thumbnail-width: /* Height auto-calculates to maintain 16:9 ratio */

/* Colors (Defaults are based on --primary-color where applicable) */
--eva-timeline-background-color
--eva-timeline-video-interval-background-color
--eva-timeline-border-color
--eva-timeline-dragger-background-color
--eva-timeline-dragger-line-color
--eva-timeline-bookend-shadow-color
--eva-buttons-background-color
--eva-buttons-active-background-color
--eva-buttons-disabled-background-color
--eva-buttons-color
--eva-buttons-disabled-color
--eva-error-message-color
--eva-success-message-color
--eva-warning-message-color
--eva-retry-button-color
--eva-pending-color
--eva-preview-tick-color
--eva-overlay-panels-background-color
--eva-overlay-panels-font-color
--eva-videos-list-item-highlighted-background-color

/* Custom Icons (URLs) */
--eva-timeline-scroll-left-icon-url
--eva-timeline-scroll-right-icon-url    
--eva-timeline-prev-interval-icon-url
--eva-timeline-next-interval-icon-url
--eva-request-duration-icon-url
--eva-request-new-video-icon-url
--eva-overlay-panels-close-icon-url
--eva-videos-list-empty-icon-url
--eva-videos-list-active-icon-url
--eva-videos-list-video-pending-icon-url
--eva-videos-list-video-ready-icon-url

 

Security Requirements: Content Security Policy (CSP)

To mitigate Cross-Site Scripting (XSS) and ensure the secure loading of the component, you must configure specific CSP directives on your server if your website enforces strict security policies:

Directive Rule Notes
Required child-src https://cdn.ravenconnected.com Allows the component's embedded app to load securely.
Alternative frame-src https://cdn.ravenconnected.com Use this instead of child-src if your server requires higher precision.
Conditional script-src https://cdn.ravenconnected.com May be required depending on your existing headers and how you inject the library script.

 

Implementation Examples

1. Headless UI (Disable Default Popups & Lists) If you want the component to handle the complex timeline and video fetching, but you want to build your own list and preview UI using the evaNotifications events:

<html>
<head>
  <script defer src='https://cdn.ravenconnected.com/rc-web-components/0.13.9.min.js'></script>
</head>
<body>
  <rc-enhanced-video-access
      apidomain="api.dev.yourdomain.com"
      sessiontoken="eyJ0eXA...kPXLs"
      ravenid="1...23" 
      starttimestamp="1234567890"
      endtimestamp="9876543210"
      hidepreviewpopup
      hidevideoslist />
</body>
</html>

Related articles

Comments

0 comments

Article is closed for comments.

Powered by Zendesk