Widget - Player Deck -Beta

FwPlayerDeckView is a horizontal video feed component in the Firework Android SDK. It displays a scrollable row of video thumbnails with built-in autoplay support and product panel

This page covers how to integrate FwPlayerDeckView into your Android app and documents every public method and property.

---

Table of Contents

1. Adding the View in XML

2. Recommended Height Configuration

3. Programmatic Initialization (Fragment)

4. Compose Integration

5. Public API Reference

---

1. Adding the View in XML

Add FwPlayerDeckView to your layout file. The recommended way to configure FwPlayerDeckView is programmatically via ViewOptions, so the XML tag only needs android:id, layout_width, and layout_height:

<com.firework.videofeed.FwPlayerDeckView
    android:id="@+id/playerDeck"
    android:layout_width="match_parent"
    android:layout_height="500dp" />

Note: Do not set custom XML attributes on FwPlayerDeckView. Use the ViewOptions.Builder API (described below) for all configuration. See the next section for how to choose the correct layout_height.

---

2. Recommended Height Configuration

Choosing the right height for FwPlayerDeckView is important for a good user experience. We recommend a height that shows approximately 1.5 deck items on screen, so the user can see the current item fully and get a visual hint that more content is available by scrolling horizontally.

How Item Width Is Derived from View Height

Each deck item fills the full height of the FwPlayerDeckView. The item consists of a 9:16 video area on top and a 72dp product panel at the bottom. The SDK calculates item width from the available height:

videoHeight = viewHeight - 72dp
itemWidth   = videoHeight × 9 / 16

The number of items visible on screen is determined by: screenWidth / itemWidth.

The Formula

To display 1.5 items horizontally, set the view height to:

recommendedHeight = screenWidth × (32 / 27) + 72dp
                  ≈ screenWidth × 1.185 + 72dp

This is derived from solving itemWidth = screenWidth / 1.5:

screenWidth / 1.5 = (H - 72dp) × 9 / 16
H = screenWidth × 16 / (9 × 1.5) + 72dp
H = screenWidth × 32 / 27 + 72dp

Reference Values for Common Screen Widths

Screen Width (dp)	Recommended Height (dp)	Example Devices
360	~499	Budget / mid-range phones
390	~534	Pixel 7, iPhone-class widths
412	~560	Pixel 7 Pro, Samsung Galaxy S series

Tip: For most portrait-mode phones, a height of 500dp is a reasonable default that works well across common screen sizes. For a more precise fit, compute the height dynamically at runtime.

Dynamic Calculation at Runtime

To compute the optimal height programmatically based on the device's actual screen width:

In traditional Views (Kotlin):

import android.content.res.Resources

fun calculateRecommendedHeight(): Int {
    val screenWidthDp = Resources.getSystem().configuration.screenWidthDp
    val bottomPanelDp = 72
    val recommendedHeightDp = (screenWidthDp * 32.0 / 27.0 + bottomPanelDp).toInt()
    // Convert dp to pixels for use in LayoutParams
    val density = Resources.getSystem().displayMetrics.density
    return (recommendedHeightDp * density).toInt()
}

// Usage:
playerDeckView.layoutParams.height = calculateRecommendedHeight()
playerDeckView.requestLayout()

In Jetpack Compose:

import androidx.compose.runtime.Composable
import androidx.compose.ui.platform.LocalConfiguration
import androidx.compose.ui.unit.Dp
import androidx.compose.ui.unit.dp

@Composable
fun rememberRecommendedHeight(): Dp {
    val screenWidthDp = LocalConfiguration.current.screenWidthDp
    val bottomPanelDp = 72
    return (screenWidthDp * 32.0 / 27.0 + bottomPanelDp).dp
}

// Usage:
val deckHeight = rememberRecommendedHeight()
AndroidView(
    modifier = Modifier
        .fillMaxWidth()
        .height(deckHeight),
    // ...
)

Note: If you configure feedPadding or itemSpacing in LayoutOption, the effective visible area changes slightly. The formula above ignores these values for simplicity; in practice the difference is negligible.

---

3. Programmatic Initialization (Fragment)

The typical lifecycle for FwPlayerDeckView in a Fragment is:

1. Build a ViewOptions instance via ViewOptions.Builder.

2. Call init(viewOptions, fragmentManager) to start loading content.

3. Call destroy() in onDestroyView() to release resources.

Full Example

import android.os.Bundle
import android.view.LayoutInflater
import android.view.View
import android.view.ViewGroup
import androidx.fragment.app.Fragment
import com.firework.common.feed.FeedResource
import com.firework.videofeed.FwPlayerDeckView
import com.firework.viewoptions.BaseOption
import com.firework.viewoptions.LayoutOption
import com.firework.viewoptions.PlayerOption
import com.firework.viewoptions.ViewOptions

class MyPlayerDeckFragment : Fragment() {

    private var playerDeckView: FwPlayerDeckView? = null

    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?,
    ): View {
        // Inflate a layout that contains <FwPlayerDeckView android:id="@+id/playerDeck" android:layout_height="500dp" ... />
        return inflater.inflate(R.layout.fragment_my_player_deck, container, false)
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        playerDeckView = view.findViewById(R.id.playerDeck)

        // 1. Build ViewOptions
        val viewOptions = ViewOptions.Builder()
            .baseOption(
                BaseOption.Builder()
                    .feedResource(FeedResource.Channel("your_channel_id"))
                    .build()
            )
            .playerOption(
                PlayerOption.Builder()
                    .autoplay(true)
                    .build()
            )
            .layoutOption(
                LayoutOption.Builder()
                    .backgroundColor(0xFFFFFFFF.toInt())
                    .itemSpacing(8)
                    .build()
            )
            .build()

        // 2. Set up listeners (optional, but recommended)
        playerDeckView?.setOnErrorListener { error ->
            // Handle SDK errors (SdkNotInitialized, VideoFeedError, PlayerError, etc.)
            android.util.Log.e("PlayerDeck", "Error: $error")
        }

        playerDeckView?.setOnFeedItemClickListener { item ->
            // Called when a user taps a video thumbnail
            android.util.Log.i("PlayerDeck", "Clicked: ${item.id} - ${item.title}")
        }

        playerDeckView?.setOnFeedViewStateListener { state ->
            // Observe feed loading state changes
            android.util.Log.d("PlayerDeck", "State: $state")
        }

        // 3. Initialize with options and FragmentManager
        playerDeckView?.init(viewOptions, childFragmentManager)
    }

    override fun onDestroyView() {
        // 4. Release all resources
        playerDeckView?.destroy()
        playerDeckView = null
        super.onDestroyView()
    }
}

Key Points

• feedResource determines the content source. Common options include:

  • FeedResource.Discovery — curated discovery feed

  • FeedResource.Channel("channelId") — all videos from a channel

  • FeedResource.Playlist("channelId", "playlistId") — a specific playlist

• autoplay in PlayerOption controls whether the first visible video plays automatically.

• init() can be called multiple times to reinitialize with new options (e.g., switching channels). Each call generates a new feedId.

• destroy() must always be called when the view is no longer needed to prevent memory leaks.

---

4. Compose Integration

Embed FwPlayerDeckView inside Jetpack Compose using AndroidView. Use the factory block for creation and initialization, and onRelease for cleanup.

import android.view.ViewGroup
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.compose.ui.viewinterop.AndroidView
import androidx.fragment.app.FragmentActivity
import com.firework.common.feed.FeedResource
import com.firework.videofeed.FwPlayerDeckView
import com.firework.viewoptions.BaseOption
import com.firework.viewoptions.PlayerOption
import com.firework.viewoptions.ViewOptions

@Composable
fun PlayerDeckViewComposable(
    modifier: Modifier = Modifier,
) {
    val context = LocalContext.current

    // Build ViewOptions once and remember across recompositions
    val viewOptions = remember {
        ViewOptions.Builder()
            .baseOption(
                BaseOption.Builder()
                    .feedResource(FeedResource.Channel("your_channel_id"))
                    .build()
            )
            .playerOption(
                PlayerOption.Builder()
                    .autoplay(true)
                    .build()
            )
            .build()
    }

    AndroidView(
        modifier = modifier
            .fillMaxWidth()
            .height(500.dp), // See "Recommended Height Configuration" for how to choose this value
        factory = { androidContext ->
            FwPlayerDeckView(androidContext).apply {
                layoutParams = ViewGroup.LayoutParams(
                    ViewGroup.LayoutParams.MATCH_PARENT,
                    ViewGroup.LayoutParams.MATCH_PARENT,
                )

                // Set up error listener
                setOnErrorListener { error ->
                    android.util.Log.e("PlayerDeck", "Error: $error")
                }

                // Set up feed item click listener
                setOnFeedItemClickListener { item ->
                    android.util.Log.i("PlayerDeck", "Clicked: ${item.id} - ${item.title}")
                }

                // Set up feed view state listener
                setOnFeedViewStateListener { state ->
                    android.util.Log.d("PlayerDeck", "State: $state")
                }

                // Initialize — obtain FragmentManager from the hosting FragmentActivity
                val fragmentManager = (context as FragmentActivity).supportFragmentManager
                init(viewOptions, fragmentManager)
            }
        },
        onRelease = { view ->
            // Clean up when the composable leaves the composition tree
            view.destroy()
        },
    )
}

Key Points

• The hosting Activity must extend FragmentActivity (or AppCompatActivity) so that supportFragmentManager is available.

• onRelease is called when the AndroidView is removed from the composition. This is the correct place to call destroy().

• Wrap ViewOptions in remember { } to avoid rebuilding on every recomposition.

---

5. Public API Reference

init(options: ViewOptions?, fragmentManager: FragmentManager)

Initializes the view with configuration options and starts loading content.

Parameter	Description
options	A ViewOptions instance built via ViewOptions.Builder. Pass null to use XML-declared attributes or defaults.
fragmentManager	The FragmentManager from the hosting Fragment (childFragmentManager) or Activity (supportFragmentManager).

Usage notes:

• Must be called before any content is displayed.

• Can be called multiple times to reinitialize with new options. Each call generates a new embed instance ID (feedId).

• If the Firework SDK has not been initialized, the error listener will receive SdkNotInitialized.

---

destroy()

Releases all resources held by the view: cancels coroutines, unbinds dependency injection, destroys impression trackers, and stops visibility tracking.

override fun onDestroyView() {
    playerDeckView.destroy()
    super.onDestroyView()
}

Usage notes:

• Must be called when the view is no longer needed (e.g., in onDestroyView() for Fragments, or onRelease for Compose AndroidView).

• If a fullscreen player or PiP session is active for this view, the DI scope is preserved until the player closes.

---

refresh()

Clears the current feed and reloads content from the data source.

playerDeckView.refresh()

Usage notes:

• Useful for pull-to-refresh implementations.

• If the SDK is not initialized, the error listener receives SdkNotInitialized.

---

setOnErrorListener(listener: FwErrorListener)

Registers a callback to receive SDK errors.

playerDeckView.setOnErrorListener { error ->
    when (error) {
        is SdkLevelError.SdkNotInitialized -> { /* SDK not initialized */ }
        is VideoFeedError -> { /* Feed loading error, check error.cause */ }
        is PlayerError -> { /* Playback error */ }
        else -> { /* Other errors */ }
    }
}

Parameter	Type	Description
listener	FwErrorListener	A functional interface: fun onFwError(error: FwError)

Usage notes:

• Set this before calling init() so that initialization errors (e.g., SdkNotInitialized) are captured.

• Only one listener can be active at a time. Setting a new listener replaces the previous one.

---

setOnFeedItemClickListener(listener: FeedItemClickListener)

Registers a callback triggered when a user taps a video thumbnail.

playerDeckView.setOnFeedItemClickListener { item ->
    Log.i("PlayerDeck", "Video: ${item.id}, title: ${item.title}, " +
        "duration: ${item.duration}s, index: ${item.indexInTheList}")
}

The FeedItem data class contains:

Field	Type	Description
id	String	The video ID
title	String	The video caption/title
duration	Long	Video duration in seconds (0 for livestreams)
indexInTheList	Int	Position in the feed list
videoInfo	VideoInfo	Detailed video metadata for analytics

---

setOnFeedViewStateListener(listener: FeedViewStateListener)

Registers a callback for feed loading state changes.

playerDeckView.setOnFeedViewStateListener { state ->
    when (state) {
        is FeedViewState.Loading  -> { /* Feed is loading */ }
        is FeedViewState.LoadData -> { /* Data loaded successfully */ }
        is FeedViewState.EmptyFeed -> { /* No content available */ }
        is FeedViewState.EndOfFeed -> { /* All content has been loaded */ }
        is FeedViewState.Error    -> { /* Error: ${state.message} */ }
    }
}

State	Description
Loading	The feed is currently fetching data.
LoadData	Data has been successfully loaded and displayed.
EmptyFeed	The data source returned no content.
EndOfFeed	All available content has been loaded (no more pages).
Error(message)	An error occurred during loading.

---

setVisibilityTrackingEnabled(enabled: Boolean)

Enables or disables automatic visibility-based autoplay control.

// Enable before or after init()
playerDeckView.setVisibilityTrackingEnabled(true)

When enabled, the view uses a ViewTreeObserver-based tracker (OnScrollChangedListener + OnGlobalLayoutListener + getGlobalVisibleRect) to automatically detect when the view scrolls in or out of the visible area. Playback is paused when less than 50% of the view is visible and resumed when at least 50% is visible again.

Usage notes:

• Can be called before or after init().

• See Page 2: Handling Autoplay in Scrollable Containers for details and known Compose limitations.

---

onViewPortEntered()

Manually notifies the view that it has become visible in the viewport. Resumes autoplay if applicable.

playerDeckView.onViewPortEntered()

Usage notes:

• Use this when you are manually tracking visibility (Approach 1 in Page 2).

• Has no effect if init() has not been called.

---

onViewPortLeft()

Manually notifies the view that it has left the viewport. Pauses autoplay.

playerDeckView.onViewPortLeft()

Usage notes:

• Use this when you are manually tracking visibility (Approach 1 in Page 2).

• Has no effect if init() has not been called.

---

feedId: String (read-only property)

Returns the current embed instance ID. This value is unique per initialization cycle and changes each time init() is called.

val currentFeedId = playerDeckView.feedId

Usage notes:

• Useful for analytics or debugging to correlate events with a specific initialization cycle.