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

isSdkInitialized()

Checks whether the Firework SDK has been successfully initialized.

This method returns true if the SDK's initialization process has completed successfully, including dependency injection setup and all core modules registration. It is essential to verify initialization status before calling any other SDK methods to avoid runtime errors.

Signature:

fun isSdkInitialized()

Initialization Requirements

The SDK is considered initialized when both of the following conditions are met:

• The dependency injection (DI) system has been set up

• The init method has completed successfully with all modules registered

Use Cases

• Conditional Feature Access: Check initialization before accessing SDK features

• Error Prevention: Avoid crashes by verifying SDK readiness before operations

• State Management: Track SDK lifecycle in your application

• Debugging: Verify initialization status when troubleshooting integration issues

Important Notes

• This method is thread-safe and can be called from any thread

• Calling SDK methods before initialization will typically result in failures or exceptions

• The SDK can only be initialized once per application lifecycle

• If initialization fails, this method will return false

---

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

closeFullScreenPlayer()

Closes the currently running full-screen player.

This method programmatically closes the full-screen player Activity launched by the Firework SDK. When invoked, it triggers a close event that all running player Activities listen to and respond by executing a graceful shutdown process.

Signature:

fun closeFullScreenPlayer()

Example:

// Close the player when user logs out
 fun onUserLogout() {
     FireworkSdk.closeFullScreenPlayer()
     // Perform other logout logic
 }

 // Close the player when app goes to background
 override fun onPause() {
     super.onPause()
     if (shouldClosePlayerOnBackground) {
         FireworkSdk.closeFullScreenPlayer()
     }
 }

---

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)

---

Tracking and Metrix

setTrackingLevel()

Sets the level of data tracking.

Signature:

fun setTrackingLevel(trackingLevel: FwTrackingLevel)

Parameters:

• FwTrackingLevel - the level of data tracking to be set.

Available Values:

• FwTrackingLevel.ALL - Sends all analytic events

• FwTrackingLevel.ESSENTIAL_ONLY - Sends only the essential tracking events.

• FwTrackingLevel.NONE - Sends no tracking events

Notes:

Please note that if you set the FwTrackingLevel to FwTrackingLevel.NONE, data regarding users watching videos and livestreams will not be reported. This may negatively impact the data reports related to each video or livestream displayed in the Business Portal.

---

API Summary Table

API	Category	Description
init()	Initialization	Initialize the SDK
isSdkInitialized()	Initialization	Check SDK Initialization status
startPlayer()	Player	Launch fullscreen video player
closeFullScreenPlayer()	Player	Close fullscreen video player
shopping	Shopping	Access shopping features
livestream	Livestream	Access livestream features
analytics	Analytics	Access analytics event bus
isInPip	PIP	Check if in PIP mode
enterPip()	PIP	Enter PIP mode
closePip()	PIP	Close PIP mode
setTrackingLevel()	Analytics	Configure tracking level
setVideoPlayerVersion()	Player	Set video player version
setLivestreamPlayerVersion()	Player	Set livestream player version
setPlayerLaunchMode()	Player	Set player launch mode

See Also

• Getting Started - SDK initialization and setup

• Video Player Configuration - Player customization options

• Shopping Integration - Shopping features and callbacks

• Livestream Integration - Livestream features and callbacks

• Configuration Guide - ViewOptions and customization

• Analytics - About listen to analytics event from Firework SDK