# Social Link

***

### 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`):

```kotlin
import com.firework.sdk.FireworkSdk
import com.firework.videofeed.social.SocialLinkInfo
import com.firework.videofeed.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                                        |

#### 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        |

***

### Best Practices

#### 1. Clean Up Listeners

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

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

#### 2. Handle App Not Installed

Always handle `ActivityNotFoundException` when trying to open native apps:

```kotlin
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

```kotlin
// 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.firework.com/firework-for-developers/android-sdk/integration-guide/social-link.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.