Skip to main content
ShortKit feeds are polymorphic. Each position in the feed can be a video, a live stream, an image carousel, a video carousel, a survey, or an ad slot. The SDK represents this with the FeedItem enum, and each case wraps a typed model with all the data you need to render it.

Feed item types at a glance


Video

Videos are the primary content type. Each video is an HLS stream with optional caption tracks and arbitrary custom metadata.

ContentItem fields

Caption tracks

Each video can include multiple caption tracks. The SDK loads and renders captions automatically when the user enables them.

Custom metadata

customMetadata is a [String: JSONValue] dictionary that accepts strings, numbers, booleans, nested objects, and null. Values are set when you upload content through the API or portal and delivered to the SDK as-is. Custom metadata can also be used as a filter dimension. Set FeedFilter(metadata: ["country": "Japan"]) on your FeedConfig to show only content with matching metadata values.

Custom feed input (FeedInput.video)

In custom feed mode, you build FeedInput items yourself instead of letting the SDK fetch them. For individual videos:
Video carousels wrap per-slide inputs of the same shape:
The per-slide origin works the same way as on FeedInput.video.
The origin field is available on the iOS, React Native, and Flutter SDKs. Android SDK support for origin ships in an upcoming release — on Android, FeedInput.Video(playbackId, fallbackUrl) works unchanged and defaults to the standard thumbnail path.

Fallback URLs

fallbackUrl is an optional static MP4 URL that the SDK uses when the primary HLS stream fails. This is useful when migrating a video library to ShortKit — you can provide your existing hosted URLs as fallbacks while transitioning to ShortKit’s streaming infrastructure. The SDK activates the fallback automatically in three scenarios:
  1. Player error — The HLS stream fails during playback. The SDK switches to the fallback MP4 and resumes from the same position.
  2. Proactive next-slot detection — The SDK pre-watches the next video in the feed. If its HLS stream fails before the user swipes, the SDK swaps in the fallback so the transition is seamless.
  3. Missing primary URL — If the primary streamingUrl is empty or invalid, the SDK uses the fallback immediately.
Fallback activation is tracked as a playbackFallback engagement event with a reason field (player_failed, proactive_next_slot, or no_primary_url).
Fallback URLs are only used in custom feed mode with FeedInput.video. Pass the fallback URL when constructing your feed items.

Image carousels display a horizontally paged set of images with optional auto-scrolling. They share the same vertical feed slot as videos and surveys.

ImageCarouselItem fields


Video carousels display a horizontally paged set of videos within a single feed slot. The SDK handles the horizontal pager, video playback, and player handoff between pages natively. Your overlay provides the chrome (titles, buttons, page indicators) on top.

VideoCarouselItem fields

Each video in the videos array is a standard ContentItem — the same type used by standalone video feed items. This means your overlay can display per-video metadata (title, duration, captions) alongside carousel-level metadata (section, author, articleUrl).

How video carousels differ from image carousels


Survey

Surveys display a single-question poll. After the user selects an option, the SDK reports their response and auto-advances to the next feed item.

SurveyItem fields

Receiving survey responses

Survey responses are delivered through the SurveyOverlay protocol’s onSurveyResponse callback. When using a custom survey overlay, the SDK sets this callback on your overlay instance. Call it when the user selects an option. See Overlays — Survey overlay for the full protocol reference.

Ad slot

Ad slots are server-positioned placeholders in the feed that get filled by your ad provider at runtime. The position and targeting configuration are set in the Admin Portal or via the API. The SDK loads and displays ads automatically when an adProvider is configured.

The FeedItem enum

The SDK wraps all five content types in a single discriminated union. The API response includes a "type" field ("content", "image_carousel", "video_carousel", "survey", "ad_slot") that the SDK uses for deserialization. Missing "type" defaults to "content" for backward compatibility.

Handling each type in a custom UI

When you set videoOverlay: .none, carouselOverlay: .none, videoCarouselOverlay: .none, and surveyOverlay: .none, the SDK renders raw content without any overlay UI. You build your own by switching on FeedItem and using the data available on each model.
For non-video types, switch on the FeedItem enum directly:

Data available per type