FireworkSdk API Reference

The FireworkSdk object is the main entry point for the Firework Android SDK. It provides methods for SDK initialization, player management, shopping, livestream, and advanced configurations.

SDK Initialization

init()

Initialize the Firework SDK with configuration.

Signature:

fun init(
    fireworkSdkConfig: FireworkSdkConfig,
    onSuccess: (() -> Unit)? = null,
    onError: ((FireworkInitError) -> Unit)? = null
)

Parameters:

fireworkSdkConfig - SDK configuration built with FireworkSdkConfig.Builder
onSuccess - Optional callback invoked on successful initialization
onError - Optional callback invoked on initialization failure

Example:

val config = FireworkSdkConfig.Builder(context = this)
    .clientId("YOUR_CLIENT_ID")
    .imageLoader(GlideImageLoaderFactory.createInstance(context = this))
    .build()

FireworkSdk.init(
    fireworkSdkConfig = config,
    onSuccess = {
        // SDK initialized successfully
    },
    onError = { error ->
        when (error) {
            is FireworkInitError.InitializationError -> {
                // Handle initialization error
            }
            is FireworkInitError.AlreadyInitializedError -> {
                // SDK already initialized
            }
        }
    }
)

See Also: Getting Started Guide

Video Player

startPlayer()

Launch the fullscreen video player.

Variant 1: With URL

Launch a specific video directly using its URL.

Signature:

fun startPlayer(
    viewOptions: ViewOptions,
    url: String
): PlayerLaunchResult

Parameters:

viewOptions - Player configuration options
url - Video URL to play

Returns: PlayerLaunchResult indicating success or failure

Example:

val viewOptions = viewOptions {
    playerOptions {
        showShareButton(true)
        enablePipMode(true)
    }
}

when (val result = FireworkSdk.startPlayer(viewOptions, "https://video-url")) {
    is PlayerLaunchResult.Success -> {
        // Player launched successfully
    }
    is PlayerLaunchResult.Failure -> {
        // Handle failure: result.message
    }
}

Variant 2: With Feed Configuration

Launch the player with a feed configuration.

Signature:

fun startPlayer(
    viewOptions: ViewOptions
): PlayerLaunchResult

Parameters:

viewOptions - Player and feed configuration options

Returns: PlayerLaunchResult indicating success or failure

Example:

val viewOptions = viewOptions {
    baseOptions {
        feedResource(FeedResource.Discovery)
    }
    playerOptions {
        showShareButton(true)
        enablePipMode(true)
    }
}

when (val result = FireworkSdk.startPlayer(viewOptions)) {
    is PlayerLaunchResult.Success -> {
        // Player launched successfully
    }
    is PlayerLaunchResult.Failure -> {
        // Handle failure: result.message
    }
}

See Also: Open Fullscreen Player Guide

Shopping Features

shopping

Access shopping-related functionality and callbacks.

Type: Shopping object

Available Methods:

setOnCtaButtonClickListener() - Handle CTA button clicks
setOnCartClickListener() - Handle shopping cart clicks
setOnProductHydrationListener() - Hydrate product data
setOnProductLinkClickListener() - Handle product link clicks
setOnProductCardClickListener() - Handle product card clicks
setOnShoppingErrorListener() - Handle shopping errors
setCartBehaviour() - Configure cart behavior
setShoppingViewOptions() - Customize shopping UI
trackPurchase() - Track purchase events

Example:

// Handle CTA button clicks
FireworkSdk.shopping.setOnCtaButtonClickListener { url, videoInfo ->
    // Open product page
    openUrl(url)
}

// Configure cart behavior
FireworkSdk.shopping.setCartBehaviour(CartBehaviour.Embedded)

// Track purchase
FireworkSdk.shopping.trackPurchase(
    productId = "product123",
    price = 29.99,
    currency = "USD"
)

See Also: Shopping Integration Guide

Livestream Features

livestream

Access livestream-related functionality and callbacks.

Type: Livestream object

Available Methods:

setOnLinkClickListener() - Handle link clicks in livestream
setOnInteractionListener() - Handle polls, questions, and giveaways
setOnGiveawayTermsAndConditionsClickListener() - Handle T&C clicks
setOnUpdateUsernameListener() - Handle username updates
updateUsername() - Update user's display name
getUsername() - Get current username
updateUsernameConfiguration() - Configure username settings

Example:

// Handle link clicks
FireworkSdk.livestream.setOnLinkClickListener { link ->
    openUrl(link)
    true // Return true if handled
}

// Handle interactions
FireworkSdk.livestream.setOnInteractionListener { interaction ->
    when (interaction) {
        is QuestionInteraction -> {
            // Handle question
        }
        is PollInteraction -> {
            // Handle poll
        }
        is GiveawayInteraction -> {
            // Handle giveaway
        }
    }
}

// Update username
FireworkSdk.livestream.updateUsername(
    username = "JohnDoe",
    onSuccess = {
        // Username updated successfully
    },
    onError = { error ->
        // Handle error
    }
)

See Also: Livestream Integration

Picture-in-Picture (PIP)

isInPip

Check if the player is currently in PIP mode.

Type: Boolean property

Example:

if (FireworkSdk.isInPip) {
    // Player is in PIP mode
}

enterPip()

Enter Picture-in-Picture mode programmatically.

Signature:

fun enterPip(
    onSuccess: ((alreadyInPipMode: Boolean) -> Unit)? = null,
    onError: ((PipEnterError) -> Unit)? = null
)

Parameters:

onSuccess - Optional callback with boolean indicating if already in PIP
onError - Optional callback invoked on PIP entry failure

Example:

FireworkSdk.enterPip(
    onSuccess = { alreadyInPip ->
        if (alreadyInPip) {
            // Already in PIP mode
        } else {
            // Successfully entered PIP mode
        }
    },
    onError = { error ->
        // Handle PIP entry error
    }
)

closePip()

Close Picture-in-Picture mode and dismiss the player.

Signature:

fun closePip()

Example:

override fun onDestroy() {
    FireworkSdk.closePip()
    super.onDestroy()
}

Player Versions

setVideoPlayerVersion()

Set the version of the video player to use.

Signature:

fun setVideoPlayerVersion(playerVersion: FwVideoPlayerVersion)

Parameters:

playerVersion - The video player version

Available Values:

FwVideoPlayerVersion.V1 - Video Player version 1
FwVideoPlayerVersion.V2 - Video Player version 2 (recommended)

Example:

// Use V2 player (recommended)
FireworkSdk.setVideoPlayerVersion(FwVideoPlayerVersion.V2)

// Call before SDK initialization
FireworkSdk.init(config)

setLivestreamPlayerVersion()

Set the version of the livestream player to use.

Signature:

fun setLivestreamPlayerVersion(playerVersion: FwLivestreamPlayerVersion)

Parameters:

playerVersion - The livestream player version

Available Values:

FwLivestreamPlayerVersion.V1 - Livestream Player version 1
FwLivestreamPlayerVersion.V2 - Livestream Player version 2 (recommended)

Example:

// Use V2 player (recommended)
FireworkSdk.setLivestreamPlayerVersion(FwLivestreamPlayerVersion.V2)

// Call before SDK initialization
FireworkSdk.init(config)

Important: Call player version setters before FireworkSdk.init().

Player Launch Mode

setPlayerLaunchMode()

Configure the Android launch mode for the player activity.

Signature:

fun setPlayerLaunchMode(playerActivityLaunchMode: FwPlayerActivityLaunchMode)

Parameters:

playerActivityLaunchMode - The launch mode to set

Available Values:

FwPlayerActivityLaunchMode.SINGLE_TASK - Standard single task launch mode
FwPlayerActivityLaunchMode.SINGLE_INSTANCE - Single instance for complete isolation
FwPlayerActivityLaunchMode.SINGLE_TASK_WITH_OWN_AFFINITY - Single task with custom affinity

Example:

// Set single instance mode
FireworkSdk.setPlayerLaunchMode(FwPlayerActivityLaunchMode.SINGLE_INSTANCE)

// Then launch player
FireworkSdk.startPlayer(viewOptions)

API Summary Table

API