Video Player (iOS)

Video Player Customizations

Video player behavior such as the sharing functionality can also be customized using VideoPlayerContentConfiguration.

let feedVC = VideoFeedViewController(source: .discover)
var config = VideoFeedContentConfiguration()

// Hide the share button
config.playerView.shareButton.isHidden = true

// Show or hide the mute button
config.playerView.muteButton.isHidden = true

// Show or hide the playback button
config.playerView.playbackButton.isHidden = true

//Set the action after a video playback is complete. Options are .loop and .advanceToNext. When loop is used the current video will keep looping until the user hits next or swipes. When advanceToNext is used the video moves to the next video after completion. Default is advanceToNext
config.playerView.videoCompleteAction = .loop

// Set the delay of the CTA button. Using 0 will result in no delay.
config.playerView.ctaButton.behavior.delay = .constant(0)

// Set the highlight delay of the CTA button. Using 0 will result in no delay and the button will be highlighted immediately.
config.playerView.ctaButton.behavior.highlightDelay = .constant(0)

// Adjusts the width of the CTA button by using one of the three available cases in the VideoPlayerCTAWidth enumeration
config.playerView.ctaButton.width = .fullWidth

// Show or hide the countdown timer. Default is hidden
config.playerView.countdownTimerConfiguration.isHidden = false

// Defines the option to be used for displaying the logo instead of the ellipsis. Default is .disabled
config.playerView.logoConfiguration.option = .channelAggregator("{ChannelId}")

// Disables or enables the open details page functionality. Default is true, meaning touching on the logo will open the details page
config.playerView.logoConfiguration.isEnabled = false

// Set the player to fit the screen or fullbleed. Options are .fit and .fullbleed.  Default is fullbleed. When fit is used, the player would have black patches on top and bottom. Fullbleed would crop the video on edges to fill the screen
config.playerView.playerStyle = .fit

// Add UIActivity instances specific to your app
config.playerView.shareButton.behavior.applicationActivities = customApplicationActivities()

// Exclude certain UIActivity Types
config.playerView.shareButton.behavior.excludedActivityTypes = [UIActivity.ActivityType.markupAsPDF]

// Player launch behaviors
// Using muteOnFirstLaunch will mute all videos when the player is launched for the first time
// After the user unmutes the video the behavior will be retained across video launches.
// Note: If the mute button is hidden this option is ignored
config.playerView.onFirstLaunch = .muteOnFirstLaunch

// Customize the play icon
config.playerView.playbackButton.playDisplay.displayMode = .image(someImage)
// Customize the pause icon
config.playerView.playbackButton.pauseDisplay.displayMode = .image(someImage)
// Customize the more option icon
config.playerView.videoDetailButtonDisplayConfiguration.displayMode = .image(someImage)
// Customize the mute icon
config.playerView.muteButton.muteDisplay.displayMode = .image(someImage)
// Customize the unmute icon
config.playerView.muteButton.unmuteDisplay.displayMode = .image(someImage)
// Customize the close icon
config.playerView.closeButtonConfiguration.closeDisplay.displayMode = .image(someImage)
// Customize the pip icon
config.playerView.pipButtonConfiguration.pipDisplay.displayMode = .image(someImage)

// Hide ad badge for embedded mode
config.playerView.sponsored.isHidden = true

// Hide player caption for embedded mode
config.playerView.playerCaption.isHidden = true

// Hide player video detail button(ellipsis button)
config.playerView.videoDetailButton.isHidden = true

// Change item shadow properties.
// - Default opacity is 0.6
// - Default color is black
// - Default offset is CGSize(width: 0, height: 2)
config.itemView.shadow = ViewContentConfiguration.ShadowConfiguration(
    opacity: 0.6,
    color: .black,
    offset: CGSize(width: 0, height: 2)
)

// Must set the viewConfiguration property to apply the changes
feedVC.viewConfiguration = config

Picture in Picture (PiP)

This feature allows the user to watch media while the application is in a backgrounded state. While in background mode a video will display in a floating, resizable window.

To enable PiP functionality, you’ll need to add Background Modes capability via Signing & Capabilities in your project settings. More information about this can be found here: Apple Documentation

To use Picture in Picture, we configure the app to support background audio playback. See Configuring the Audio Playback of iOS and tvOS Apps for more details.

Once the background mode is enabled, moving from an active state to a background state will immediately trigger the Picture In Picture functionality. PictureInPictureController is responsible for handling all of this functionality. PictureInPictureController retains a strong reference of AVPictureInPictureController. AVPictureInPictureController is a controller that responds to user-initiated Picture in Picture playback of video in a floating, resizable window.

     let feedVC = VideoFeedViewController(
     layout: VideoFeedHorizontalLayout(),
     source: source,
     adConfiguration: adConfiguration)
     pipViewControlelr = PictureInPictureController(videoFeed: feedVC)

Programmatically Invoking PIP Player

When a user clicks the CTA button on a video or Product card, before the app is navigated to the target page, the PIP player needs to be programmatically invoked if the video playback experience needs to continue on top of the navigated pages. This can be done as follows

extension ViewController: FireworkVideoCTADelegate {
    func handleCustomCTAClick(_ viewController: PlayerViewController, url: URL, for video: VideoDetails) -> Bool {
        // Use `url` for app navigation
        try? viewController.startPictureInPicture()
        return true
    }
}

Enhanced APIs

The PictureInPictureController offers serveral enhanced APIs that remove the burden of managing the PictureInPictureController instance.

Enabling PiP

A new property, isPictureInPictureEnabled, was added to VideoFeedViewController and StoryBlockViewController. Set this property to true and FireworkVideoSDK will manage the resources on your behalf.

Programmatically starting and stopping

The PictureInPictureController has new static methods which allows to easily start and stop picture in picture mode. There are 2 sets of methods for both start and stop operations.

The first set allows for starting and stopping of picture in picture with a feedID; start(with feedID: String) throws and stop(with feedID: String) throws. This set of APIs allows for you to start or stop specific feeds.

These APIs will throw when trying to start or stop a feed which does not have picture in picture enabled first. The second set allows for starting and stopping of picture in picture of any "eligible" feed; start() throws and stop() throws. This set of APIs allows for you to quickly start any feed that is eligible to enter picture in picture. Or stop any currently active picture in picture.

Eligibility is determined by many factors and is subject to change in future releases.

Video Player Playback Control

When a user clicks the CTA button on a video, you can pause or resume video player as your needed. This can be done as follows

extension ViewController: FireworkVideoCTADelegate {
    func handleCustomCTAClick(_ viewController: PlayerViewController, url: URL, for video: VideoDetails) -> Bool {
        // Pause video player example:
        viewController.pause()
        return true
    }
}