Ad Retrieval

Purpose

Ad Retrieval addresses the specific need to fetch video advertisements from an ad server, supplying the necessary contextual information to request targeted ads for playback. Within the broader scope of managing advertisements and cue points in media playback, this subtopic focuses exclusively on preparing, sending, and representing ad request data that enables the system to obtain relevant ads for preroll, midroll, and postroll insertion points.

While other subtopics handle cue point detection or playback monitoring, Ad Retrieval ensures that the system can dynamically acquire ad content by communicating with external servers, making it a critical link between playback logic and ad content availability.

Functionality

The core functionality of Ad Retrieval revolves around encapsulating and managing the data required to request ads from the ad server:

• Ad Request Data Model
  The AdRetriever class acts as a structured data container holding key identifiers and playback parameters needed for ad fetching. These include:

  • videoId: Identifies the video content for which ads are requested.

  • publisherId: Specifies the publisher or channel context for ad targeting.

  • cubPoint: Represents the cue point position (in milliseconds) within the video timeline where the ad should be inserted.

• Data Access and Mutation
  Getters and setters allow the FSM and ad-fetching components to create and modify the ad request parameters dynamically based on playback state or cue points discovered.

• Integration with Ad Fetching Workflow
  When the FSM reaches states that require ad retrieval (e.g., preroll or midroll ad calls), an AdRetriever instance is created and populated with the current playback context. This instance is then passed to an ad interface or network layer that executes the actual server request.

Example snippet illustrating creation of an ad retrieval request:

AdRetriever adRequest = new AdRetriever(currentVideoId, currentPublisherId, cuePointPosition);
adInterface.fetchAds(adRequest);

This decouples the ad data representation from the networking logic, enabling modular handling of ad requests.

Integration with Parent Topic and Other Subtopics

Ad Retrieval integrates tightly with the parent topic—Ad and Cue Point Management—by supplying the necessary data inputs to trigger ad fetching processes. Its role complements:

• Cue Point Retrieval
  Cue Point Retrieval detects the timing points where ads should be inserted. Upon identifying a cue point, it signals the FSM to initiate an ad retrieval request using an AdRetriever object populated with the cue point data.

• Playback Monitoring
  Playback Monitoring listens to playback progress and triggers ad retrieval when an upcoming cue point is reached, again relying on AdRetriever instances to specify what ads to fetch.

Together, these subtopics form a pipeline: cue points identify when ads should play, ad retrieval requests the appropriate ads, and playback monitoring ensures timely triggering and transitioning to ad playback.

Unlike the parent topic and other subtopics that focus on state transitions, event monitoring, or UI updates, Ad Retrieval introduces the structured representation of ad request parameters critical for backend communication, which is not covered elsewhere.

Diagram

flowchart TD
    A[Playback Position] --> B{Cue Point Detected?}
    B -- Yes --> C[Create AdRetriever with videoId, publisherId, cuePoint]
    C --> D[Send AdRetriever to Ad Fetching Service]
    D --> E[Receive Ads Data]
    E --> F[FSM Transitions to Ad Playing State]
    B -- No --> G[Continue Content Playback]

This flowchart highlights how Ad Retrieval fits into the ad fetching process, starting from cue point detection and culminating in loading ads for playback.