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
- Swift
- Kotlin
- React Native
- Web
Caption tracks
Each video can include multiple caption tracks. The SDK loads and renders captions automatically when the user enables them.- Swift
- Kotlin
- React Native
- Web
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.
- Swift
- Kotlin
- React Native
- Web
Custom feed input (FeedInput.video)
In custom feed mode, you build FeedInput items yourself instead of letting the SDK fetch them. For individual videos:
- Swift
- Kotlin
- React Native
Video carousels wrap per-slide inputs of the same shape:
- Swift
- Kotlin
- React Native
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:
- Player error — The HLS stream fails during playback. The SDK switches to the fallback MP4 and resumes from the same position.
- 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.
- Missing primary URL — If the primary
streamingUrlis empty or invalid, the SDK uses the fallback immediately.
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 carousel
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
- Swift
- Kotlin
- React Native
- Web
Video carousel
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
- Swift
- Kotlin
- React Native
- Web
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
- Swift
- Kotlin
- React Native
- Web
Receiving survey responses
Survey responses are delivered through theSurveyOverlay 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 anadProvider 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.
- Swift
- Kotlin
- React Native
- Web
Handling each type in a custom UI
When you setvideoOverlay: .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.
- Swift
- Kotlin
- React Native
- Web
FeedItem enum directly: