Social Link

This guide explains how to handle social media link click events in the Firework SDK.

---

Overview

When a video contains external media sources from TikTok, Instagram, or YouTube, the SDK displays corresponding social media icons and usernames on the video. When users click these links, you can:

1. Custom Handling: Open native apps, log analytics data, or execute other business logic

2. Default Handling: Let the SDK open the link in the browser

---

Quick Start

Setting Up the Listener

Set up the listener after SDK initialization (typically in Application or MainActivity):

import com.firework.sdk.FireworkSdk
import com.firework.player.common.social.SocialLinkInfo
import com.firework.player.common.social.SocialPlatform

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Set up social link click listener
        setupSocialLinkClickListener()
    }

    private fun setupSocialLinkClickListener() {
        FireworkSdk.social.setOnVideoSocialLinkClickListener { info ->
            // info contains all click-related information
            Log.d("Firework", "Social link clicked: ${info.platform}")

            when (info.platform) {
                SocialPlatform.TIKTOK -> {
                    // Custom handling for TikTok links
                    openTikTokApp(info.username, info.url)
                    true // Return true to indicate you've handled it
                }
                SocialPlatform.INSTAGRAM -> {
                    // Custom handling for Instagram links
                    openInstagramApp(info.username, info.url)
                    true
                }
                SocialPlatform.YOUTUBE -> {
                    // Custom handling for YouTube links
                    openYouTubeApp(info.url)
                    true
                }
                SocialPlatform.UNKNOWN -> {
                    // Return false to let SDK open in default browser
                    false
                }
            }
        }
    }

    override fun onDestroy() {
        // Clean up the listener
        FireworkSdk.social.setOnVideoSocialLinkClickListener(null)
        super.onDestroy()
    }
}

---

Callback Parameters

SocialLinkInfo

Property	Type	Description
videoId	String	Unique identifier of the current video
url	String	Target URL of the social media link
username	String?	Social media username (may be null)
platform	SocialPlatform	Social platform type
videoInfo	VideoInfo	Detailed video information for analytics

SocialPlatform

Value	Description
TIKTOK	TikTok platform
INSTAGRAM	Instagram platform
YOUTUBE	YouTube platform
UNKNOWN	Unknown platform

VideoInfo

Provides complete video context for analytics and tracking:

Property	Type	Description
id	String	Video ID
caption	String	Video title
duration	Double	Video duration in seconds
badge	String?	Video badge label (e.g., "ad")
playerHeight	Int?	Player height in pixels
playerWidth	Int?	Player width in pixels
hasCta	Boolean	Whether the video has a call-to-action
isAd	Boolean	Whether the video is an ad (deprecated, use videoType == VideoType.Ad)
hashtags	List<String>	Hashtags associated with the video
feedType	String	Feed type identifier
channelId	String?	Channel ID
playlistId	String?	Playlist ID
feedId	String	Feed ID
videoType	VideoType	Video type (see below)
autoPlay	Boolean?	Whether the video was auto-played
ctaLabel	String?	Video CTA label, when available.
ctaActionUrl	String?	Video CTA target URL, when available.
ctaActionType	String?	Video CTA action type, when available.

VideoType

A sealed interface representing the type of video content:

Value	Description
VideoType.ShortVideo	Short-form video
VideoType.Ad	Advertisement video
VideoType.Livestream.Idle	Livestream that hasn't started yet
VideoType.Livestream.Live	Livestream currently live
VideoType.Livestream.Replay	Livestream replay
VideoType.Livestream.Completed	Livestream that has ended

---

Return Value

The callback function must return a Boolean value:

Return Value	Behavior
true	You've handled the click event; SDK will not take any action
false	SDK will open the URL in the system's default browser

---

Customize Social Link Text Style

Social link click handling is configured through FireworkSdk.social. Social link visual styling is configured through ViewOptions.

Use PlayerOption.socialLinkStyle to customize social/sponsor link text in the fullscreen player:

import com.firework.common.social.SocialLinkStyle

val viewOptions = viewOptions {
    playerOptions {
        socialLinkStyle(SocialLinkStyle(fontSizeSp = 14f, fontWeight = 600))
    }
}

Use PlayerDeckOption.socialLinkStyle to customize social/sponsor link text in the inline FwPlayerDeckView player:

import com.firework.common.social.SocialLinkStyle

val viewOptions = viewOptions {
    playerDeckOptions {
        socialLinkStyle(SocialLinkStyle(fontSizeSp = 14f, fontWeight = 600))
    }
}

fontSizeSp and fontWeight are optional. fontWeight uses Android numeric font weight values from 1 to 1000; common values include 400 for regular, 600 for semibold, and 700 for bold.

If socialLinkStyle is null, or if a SocialLinkStyle field is null, the SDK keeps the default style for that field. The effective SDK defaults are 12sp text size and 400 font weight. The social link start icon scales with the text height.

For the full option references, see PlayerOption and PlayerDeckOption.

---

Best Practices

1. Clean Up Listeners

Remove the listener when Activity or Fragment is destroyed to avoid memory leaks:

override fun onDestroy() {
    FireworkSdk.social.setOnVideoSocialLinkClickListener(null)
    super.onDestroy()
}

2. Handle App Not Installed

Always handle ActivityNotFoundException when trying to open native apps:

try {
    startActivity(appIntent)
    true
} catch (e: ActivityNotFoundException) {
    // App not installed, fall back to browser
    false
}

---

FAQ

Q: What happens if I don't set a listener?

The SDK will use the default behavior and open the link in the system browser.

Q: Can I set listeners in multiple places?

No. Each call to setOnVideoSocialLinkClickListener replaces the previous listener.

Q: Which thread does the callback run on?

The callback runs on the main thread (UI thread), so you can directly update the UI.

Q: How can I get more video information?

info.videoInfo contains complete video context including title, duration, channel, and more.

---

API Reference

// Social interface
interface Social {
    fun setOnVideoSocialLinkClickListener(listener: OnVideoSocialLinkClickListener?)

    fun interface OnVideoSocialLinkClickListener {
        fun onVideoSocialLinkClick(info: SocialLinkInfo): Boolean
    }
}

// Set listener (using Kotlin SAM conversion)
FireworkSdk.social.setOnVideoSocialLinkClickListener { info ->
    // handle click
    true // or false
}

// Remove listener
FireworkSdk.social.setOnVideoSocialLinkClickListener(null)

---

Support

If you have any questions, please contact the Firework technical support team.