Players

This guide shows how to use and customize JOIN Stories players in your Android application.

Player View

You can customize the player that opens when the trigger is clicked.

val playerConfiguration: PlayerConfiguration = PlayerConfiguration()

cardTrigger.playerConfiguration = playerConfiguration
bubbleTrigger.playerConfiguration = playerConfiguration

Player view type

You can force the player to use horizontal mode for stories or vertical mode for short videos if you don't want to rely on the JOIN Studio settings.

val configuration = PlayerConfiguration(playerType = PlayerType.STORY)
//or
val configuration = PlayerConfiguration(playerType = PlayerType.VERTICAL)

Player Start Opening Animation (only standalone mode)

The start opening animation can be changed when the player is used in standalone mode. By default, the animation start from the bottom of the screen.

// enum class PlayerStandaloneAnimationOrigin {
//     TOP_LEFT, BOTTOM_LEFT, BOTTOM, BOTTOM_RIGHT, TOP, TOP_RIGHT
// }

JOINStories.startPlayer(
  ...
  configuration = PlayerConfiguration(playerStandaloneAnimationOrigin: PlayerStandaloneAnimationOrigin)
)

Player Vertical Anchor

The attribute changes the player anchor when the player's height is smaller than screen height. The default anchor is TOP

// enum class PlayerVerticalAnchor {
//     TOP, BOTTOM, CENTER
// }

trigger.playerConfiguration = PlayerConfiguration(playerVerticalAnchor: PlayerVerticalAnchor)

Player Background Color

The attribute changes the background color of player. The background color is Color.BLACK by default

trigger.playerConfiguration = PlayerConfiguration(playerBackgroundColor: Int)

Player Horizontal Margins

The attribute changes the player's left and right margins. By default, the player has no margin.

trigger.playerConfiguration = PlayerConfiguration(playerBackgroundColor: Int)

Player Corner Radius

The attribute changes the corner radius of player. By default, the corner radius is 0.

trigger.playerConfiguration = PlayerConfiguration(playerCornerRadius: Int)

Player Progress Bar

These attributes change the style of the progress bar at the top of the player

trigger.playerConfiguration = PlayerConfiguration(playerProgressBarDefaultColor: Int)
trigger.playerConfiguration = PlayerConfiguration(playerProgressBarFillColor: Int)
trigger.playerConfiguration = PlayerConfiguration(playerProgressBarThickness: Int)
trigger.playerConfiguration = PlayerConfiguration(playerProgressBarRadius: Int)

📘

Tip

Default Color : The default color is WHITE with 50% of alpha

Fill Color : The default color is WHITE

Thickness : By default, the thickness is 2dp

Radius : By default, the radius is6dp

Vertical Player configuration

📘

Feature available from SDK v3.9.0+

The Vertical Player is a new full-screen playback mode, as an alternative to the classic "story" player (horizontal navigation, chapters). It follows the conventions of vertical video feeds seen on social networks: vertical swipe navigation between stories, a vertical progress bar, and adapted controls.

Video sizing

videoSizing simply controls how the video fills the player's screen:

VerticalPlayerVideoSizing.FIT : (default value): respect the 16:9 video format and keeps its original aspect ratio, with black bars if needed (letterboxed).
VerticalPlayerVideoSizing.FILL: the video fills the entire screen edge-to-edge, cropping the image slightly if needed.

Widget player configuration

Player video sizing can be configure in player configuration at widget init.

For example in Bubble widget , videoSizing can be setup in PlayerConfigurations, with playerType: PlayerType.VERTICAL.

val bubbleView = BubbleTriggerView(context).apply {
    playerConfiguration = PlayerConfiguration(
        playerType = PlayerType.VERTICAL,
        videoSizing = VerticalPlayerVideoSizing.FIT
    )

    init = JOINStoriesInit(alias = "<your_join_alias>")
}
@Composable
fun StoriesBubbles() {
    AndroidView(
        modifier = Modifier.fillMaxWidth(),
        factory = { context ->
            BubbleTriggerView(context).apply {
                playerConfiguration = PlayerConfiguration(
                    playerType = PlayerType.VERTICAL,
                    videoSizing = VerticalPlayerVideoSizing.FIT
                )
                init = JOINStoriesInit(alias = "<your_join_alias>")
            }
        }
    )
}

Player Standalone

JOINStories.showVerticalPlayer(
    context = this,
    alias = "<your_join_alias>",
    videoSizing = VerticalPlayerVideoSizing.FIT
)

Player Embedded

// XML
<com.joinstoriessdk.androidsdk.ui.JOINVerticalPlayerView
    android:id="@+id/vertical_player_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
/>

// Kotlin
import com.joinstoriessdk.androidsdk.VerticalPlayerVideoSizing
import com.joinstoriessdk.androidsdk.ui.JOINVerticalPlayerView

findViewById<JOINVerticalPlayerView>(R.id.vertical_player_view).bind(
    alias = "your_join_alias",
    videoSizing = VerticalPlayerVideoSizing.FIT
)
@Composable
fun EmbeddedPlayer(alias: String, videoSizing: VerticalPlayerVideoSizing) {
    AndroidView(
        factory = { context ->
            JOINVerticalPlayerView(context).apply {
                bind(alias = alias, videoSizing = videoSizing)
            }
        },
        modifier = Modifier.fillMaxSize(),
        onRelease = { player -> player.release() }
    )
}

Action buttons

What is it?

The Vertical Player exposes a space where your app can add its own action button (for example, an "Add to my list", "Like" or "Share", button). Just provides your View or Button. JOIN just gives it a place to live and tells it which story is currently on screen.

How it works?

  • You provide an array of view. All button's UI customization and logic is in your hands.
  • SDK renders it in a fixed spot on the right side of the Vertical Player.
  • SDK passes the current story to your component whenever the user swipes to a new one.
  • Everything else, state, styling, click handling, network calls : is entirely up to you.
  • SDK does not store or manage the button's state. If a user taps it, that's your app's logic to handle.
  • Your component gets the current story object as input, with public fields only (id, title, cover, etc.). No private or internal data is passed.
  • Your action buttons must be conform to JOINCustomButtonDelegate and provide an id and title

What's inside storyData ?

  • storyId: String (Id of the current story)
  • title: String (Title of the current story)
  • lastPublishDate: Long (Last published date from studio of the current story)

Properties to provide in getButtonMetadata :

PropertyTypeDescription
idStringYour button identifier (without space).
titleStringYour button title.

class MyFirstButton(
    context: Context,
    action: () -> Unit
) : ImageButton(context), JOINCustomButtonDelegate {

    init {
        // Config button here.
    }

    override fun getButtonMetadata() = JOINCustomButtonMetadata(
        id = "<your_button_id>",
        title = "<your_button_title>"
    )
}

// Example for single action button (e.g. Screen 1)  
JOINStories.showVerticalPlayer(
    context = this,
    alias = "<your_join_alias>",
    configuration = PlayerConfiguration(
        customActionButtons = { storyData ->
            if (storyData.isEmpty) emptyList()
            else listOf(MyFirstButton(context).apply {
                          setOnClickListener { action(storyData.id) }
                 }
            )
        }
    )
)

// Example for few action buttons (e.g. Screen 2)  
JOINStories.showVerticalPlayer(
    context = this,
    alias = "<your_join_alias>",
    configuration = PlayerConfiguration(
        customActionButtons = { storyData ->
            if (storyData.isEmpty) emptyList()
            else listOf(MyFirstButton(this), MySecondButton(this))
        }
    )
)

// Your cusom button must be conformed to JOINCustomButtonDelegate.
class MyFirstButton(
    context: Context,
    private val action: () -> Unit
) : AbstractComposeView(context), JOINCustomButtonDelegate {

    override fun getButtonMetadata() = JOINCustomButtonMetadata(
        id = "<your_button_id>",
        title = "<your_button_title>"
    )

    @Composable
    override fun Content() {
        // Your button code here.
    }
}

// Example for single action button (e.g. Screen 1)
JOINStories.showVerticalPlayer(
    context = context,
    alias = "<your_join_alias>",
    configuration = PlayerConfiguration(
        customActionButtons = { storyData ->
            if (storyData.isEmpty) emptyList()
            else listOf(MyFirstButton(context))
        }
    )
)

// Example for few action buttons (e.g. Screen 2)
JOINStories.showVerticalPlayer(
    context = context,
    alias = "<your_join_alias>",
    configuration = PlayerConfiguration(
        customActionButtons = { storyData ->
            if (storyData.isEmpty) emptyList()
            else listOf(MyFirstButton(context), MySecondButton(context))
        }
    )
)
Screen 1

Screen 1

Screen 2

Screen 2

💡

Tips for placement

Action buttons are added from bottom to top of the space available and have a max height and width of 40.


Did this page help you?