Customize click behaviors (iOS)

The SDK provides behavior delegate methods to customize click behaviors, including those for the video CTA button, product cards, and shopping CTA button.

Customize video overlay CTA button click behavior

1. Set FireworkVideoCTADelegate delegate:

FireworkVideoSDK.ctaDelegate = <FireworkVideoCTADelegate delegate>

2. Implement handleCustomCTAClick(_:url:for:):

func handleCustomCTAClick(
    _ viewController: PlayerViewController,
    url: URL,
    for video: VideoDetails
) -> Bool {
    // Here, you could write codes to navigate to the host app page.
    // For best practices on navigating to the host page,
    // please consult "Navigate to the host app page" below.

    // Return true to customize video overlay CTA button click behavior
    return true
}

You could write codes to navigate to the host app page within the delegate method. For best practices on navigating to the host page, please consult Navigate to the host app page below.

Customize click behaviors for shopping

To customize click behaviors for shopping, you need to set FireworkVideoShoppingDelegate delegate first:

FireworkVideoSDK.shopping.delegate = <FireworkVideoShoppingDelegate delegate>

Customize product card click behavior

Implement fireworkShopping(_:didTapProductVariant:forVideo:):

func fireworkShopping(
    _ fireworkShopping: FireworkVideoShopping,
    didTapProductVariant item: SelectedProductVariant,
    forVideo video: VideoDetails
) -> Bool {
    // Here, you could write codes to navigate to the host app page.
    // For best practices on navigating to the host page,
    // please consult "Navigate to the host app page" below.

    // Return true to customize product card click behavior
    return true
}

You could write codes to navigate to the host app page within the delegate method. For best practices on navigating to the host page, please consult Navigate to the host app page below.

Customize shopping CTA click behavior

Implement fireworkShopping(_:productVariantCTASelected:fromVideo:ctaCompletionHandler:):

func fireworkShopping(
    _ fireworkShopping: FireworkVideoShopping,
    productVariantCTASelected item: SelectedProductVariant,
    fromVideo video: VideoDetails,
    ctaCompletionHandler: @escaping ShoppingCTAHandler
) {
    // Here, you could write codes to navigate to the host app page.
    // For best practices on navigating to the host page,
    // please consult "Navigate to the host app page" below.

    // Calling completion closure with none refer to
    // host app will customize the click behavior
    ctaCompletionHandler(.none)
}

You could write codes to navigate to the host app page within the delegate method. For best practices on navigating to the host page, please consult Navigate to the host app page below.

Customize product link button click behavior

Implement fireworkShopping(_:didTapLinkButtonAt:fromVideo:withURL:):

func fireworkShopping(
        _ fireworkShopping: FireworkVideoShopping,
        didTapLinkButtonAt item: SelectedProductVariant,
        fromVideo video: VideoDetails,
        withURL itemURL: String
    ) -> Bool {
        // Here, you could write codes to navigate to the host app page.
        // For best practices on navigating to the host page,
        // please consult "Navigate to the host app page" below.

        // Return true to customize product link button click behavior
        return true
}

You could write codes to navigate to the host app page within the delegate method. For best practices on navigating to the host page, please consult Navigate to the host app page below.

Customize cart icon click behavior

The SDK does not provide a cart page of its own. The page the user sees after tapping the cart icon is always supplied by the host app, through one of the two options below. The cart icon is also hidden by default — to show it, see Shopping configurations (iOS).

FireworkVideoSDK.shopping.cartAction determines what happens when the user taps the cart icon. There are two options.

Option 1: Show the host app cart view inside the SDK player (.showEmbeddedCart)

This is the default value of cartAction. The SDK requests a cart view controller from the host app and shows it inside the player, so the host app must supply one.

1. Implement CartViewControllerProviding to return your own cart view controller. CartViewController is a typealias for UIViewController & CartViewRepresentable:

class HostAppCartViewProvider: CartViewControllerProviding {
    func cartViewController(for video: VideoDetails) -> CartViewController {
        // Return the host app cart view controller.
        return HostAppCartViewController()
    }
}

1. Set cartAction to showEmbeddedCart and assign the provider:

// `.showEmbeddedCart` is the default value of `cartAction`
FireworkVideoSDK.shopping.cartAction = .showEmbeddedCart
FireworkVideoSDK.shopping.cartViewControllerProvider = HostAppCartViewProvider()

1. The cart view controller can close the drawer that contains it through drawerController:

class HostAppCartViewController: UIViewController, CartViewRepresentable {
    private func handleContinueShopping() {
        drawerController?.closeDrawer(animated: true)
    }
}

cartViewControllerProvider must be set for this option. If it is nil, tapping the cart icon does nothing at all.

The same provider is used when the host app calls ctaCompletionHandler(.showEmbeddedCart) from fireworkShopping(_:productVariantCTASelected:fromVideo:ctaCompletionHandler:), which shows the cart after the user taps the shopping CTA button.

Option 2: Handle the cart icon click in the host app (.custom)

With this option the SDK presents nothing and only notifies the host app, so the host app is free to navigate to its own page.

1. Set cartAction to custom:

FireworkVideoSDK.shopping.cartAction = .custom

1. Implement fireworkShopping(_:didTapCartIconForVideo:):

func fireworkShopping(
    _ fireworkShopping: FireworkVideoShopping,
    didTapCartIconForVideo videoDetails: VideoDetails
) {
    // Here, you could write codes to navigate to the host app page.
    // For best practices on navigating to the host page,
    // please consult "Navigate to the host app page" below.
}

You could write codes to navigate to the host app page within the delegate method. For best practices on navigating to the host page, please consult Navigate to the host app page below.

If this delegate method is not implemented, tapping the cart icon does nothing at all.

Custom livestream link interaction click behavior

1. Set FireworkLiveStreamBehaviorDelegate delegate:

FireworkVideoSDK.liveStreamBehaviorDelegate = <FireworkLiveStreamBehaviorDelegate delegate>

1. Implement fireworkLiveStream(_:didTapLinkInteraction:):

func fireworkLiveStream(
    _ liveStream: LiveStreamEventDetails,
    didTapLinkInteraction interaction: LiveStreamLinkInteraction
) -> Bool {
    // Here, you could write codes to navigate to the host app page.
    // For best practices on navigating to the host page,
    // please consult "Navigate to the host app page" below.

    // Return true to customize livestream link interaction click behavior
    return true
}

You could write codes to navigate to the host app page within the delegate method. For best practices on navigating to the host page, please consult Navigate to the host app page below.

Customize social attribution click behavior

1. Set FireworkVideoSocialDelegate delegate:

FireworkVideoSDK.socialDelegate = <FireworkVideoSocialDelegate delegate>

1. Implement handleSocialAttributionClick(_:fromVideo:):

func handleSocialAttributionClick(
    _ source: VideoSocialAttributionSource,
    fromVideo video: VideoDetails,
) -> Bool {
    // This delegate method allows the host app to customize the behavior when users tap on
    // social media attribution displayed in videos. If the host app returns `false` or if
    // this delegate is not set, the SDK will open the URL using `UIApplication.shared.open`.
    return false
}

Customize video feed item click behavior

1. Set VideoFeedViewControllerDelegate delegate:

videoFeedVC.delegate = <VideoFeedViewControllerDelegate delegate>

1. Implement videoFeed(_:didTapFeedItem:):

func videoFeed(
    _ viewController: VideoFeedViewController,
    didTapFeedItem feedItemDetails: FeedEventDetails
) -> Bool {
    /// Called when the user taps a feed item.
    ///
    /// Return `true` to indicate that the tap has been handled externally,
    /// preventing the SDK from opening the full-screen player.
    /// Return `false` to let the SDK proceed with the default behavior.
    return false
}

Navigate to the Host App Page

We have three ways to navigate to the host app page when customizing click behaviors.

1. Present the host app page over the SDK player.

2. Push the host app page inside the SDK player.

3. Use the host app navigation controller to push the host app page.

Present the Host App Page Over the SDK Player

Use present to display the host app PDP page over the SDK player:

func fireworkShopping(
    _ fireworkShopping: FireworkVideoShopping,
    didTapProductVariant item: SelectedProductVariant,
    forVideo video: VideoDetails
) -> Bool {
    // The following PDP view controller is a sample.
    // Please create your own PDP view controller.
    let pdpVC = UIViewController()
    // As we may have other flows in PDP(such as the checkout page),
    // we could embed the PDP controller with navigation controller.
    let nav = UINavigationController(rootViewController: pdpVC)
    nav.modalPresentationStyle = .fullScreen
    UIViewController.topPresentedVC()?.present(nav, animated: true)
    
    // Return true to customize product card click behavior
    return true
}

Push the Host App Page Inside the SDK Player

UIViewController.topNavigationController() resolves to different navigation controllers depending on the current context:

• Inside the fullscreen player: returns the player's own navigation controller, so the page is pushed within the player context.

• Inside a story block: falls back to the host app's navigation controller.

Because the fullscreen player hides the navigation bar, the pushed view controller must explicitly show and configure it in viewWillAppear. Using viewWillAppear (rather than viewDidLoad) is important — when the user navigates back, UIKit calls viewWillAppear on the player, allowing it to hide the bar again and restore its original state.

func fireworkShopping(
    _ fireworkShopping: FireworkVideoShopping,
    didTapProductVariant item: SelectedProductVariant,
    forVideo video: VideoDetails
) -> Bool {
    // `topNav` resolves to the fullscreen player's navigation controller when inside
    // the fullscreen player, or to the host app's navigation controller inside a story block.
    if let topNav = UIViewController.topNavigationController() {
        let vc = HostAppProductDetailsController()
        vc.hidesBottomBarWhenPushed = true
        topNav.pushViewController(vc, animated: true)
    }
    
    // Return true to customize product card click behavior
    return true
}

class HostAppProductDetailsController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
        view.backgroundColor = .red
    }

    override func viewWillAppear(_ animated: Bool) {
        super.viewWillAppear(animated)
        // Show and configure the navigation bar here to match your design.
        // Since the navigation bar is shared with the fullscreen player, configuring it in
        // `viewWillAppear` ensures the player's original bar state (hidden, style, etc.)
        // is restored when navigating back.
        navigationController?.setNavigationBarHidden(false, animated: true)
        configNavigationBar()
    }

    private func configNavigationBar() {
        self.title = "PDP"
        guard let navBar = navigationController?.navigationBar else { return }
        let bgColor = UIColor.white
        if #available(iOS 15, *) {
            let navigationBarAppearance = UINavigationBarAppearance()
            navigationBarAppearance.backgroundColor = bgColor

            navBar.scrollEdgeAppearance = navigationBarAppearance
            navBar.standardAppearance = navigationBarAppearance
        } else {
            navBar.barTintColor = bgColor
        }
    }
}

Use the Host App Navigation Controller to Push the Host App Page

When the fullscreen player is visible, the host app's navigation controller sits beneath it, so any page pushed directly would be obscured by the player.

FireworkVideoSDK.startPiPOrDismissFullScreenPlayer handles this by transitioning the player to a floating window (if PiP is enabled) or dismissing it (if PiP is disabled), ensuring the new page is fully visible. To always dismiss the player regardless of PiP, use FireworkVideoSDK.dismissFullScreenPlayer instead.

func fireworkShopping(
    _ fireworkShopping: FireworkVideoShopping,
    didTapProductVariant item: SelectedProductVariant,
    forVideo video: VideoDetails
) -> Bool {
    /*
     When a Firework full-screen player is present, startPiPOrDismissFullScreenPlayer will either
     transition it to a floating player (if PiP is enabled), or dismiss it (if PiP is disabled).
     If you wish to consistently dismiss the full-screen player, regardless of whether PiP is
     enabled or not, you can use the dismissFullScreenPlayer API.
     */
    FireworkVideoSDK.startPiPOrDismissFullScreenPlayer { _ in
        // Use host app navigation controller to push the host app page.
        // But you can also use your own method to push the host app page.
        if let nav = FireworkVideoSDK.getHostAppNavigationController() {
            // The following PDP view controller is a sample.
            // Please create your own PDP view controller.
            let pdpVC = UIViewController()
            nav.pushViewController(pdpVC, animated: true)
        }
    }
    return true
}

The above code snippets are based on fireworkShopping(_:didTapProductVariant:forVideo:). But they are also applicable to other behavior delegate methods.