Getting Started (iOS)

Introduction

FireworkVideo is a library to integrate video feeds from Firework - a short form video platform - into your iOS app.

To integrate FireworkVideo into your application, you have to register your application with Firework platform and get unique FireworkVideo app ID. To get the app ID:

• Provide your application's bundle identifier or package name to the business team / engineering team you are co-ordinating with.

• You will receive via email the app ID and then follow the setup steps below under Firework IDs to include both in your app.

The app ID is used to authenticate your application with the server. Authentication will fail if you use wrong app ID.

Requirements

FireworkVideo is compatible with:

• iOS 13+

• Xcode 14+

• Swift 5.5+

Installation

FireworkVideo can be added as a Swift binary package using Swift Package Manager or it can be imported manually as framework. Instructions for both installation methods are below.

Importing Using Swift Package Manager

In your Xcode project, select File > Swift Packages > Add Package Dependency and enter the following URL: https://github.com/loopsocial/firework_ios_sdk.git

If you are new to Xcode's Swift Pacakage Manager integration, please refer to Apple's documentation on Adding a Package Dependency to Your App

Select Version > Up to Next Major > {Latest Version from CHANGELOG.md}

Latest version release notes can be found here

Importing Using Cocoapods

In your Podfile add FireworkVideo: pod FireworkVideo and then run pod install.

Importing FireworkVideo Framework Manually

• Clone the SDK repo located at https://www.github.com/loopsocial/firework_ios_sdk/

• Download the SDK binary and unzip if needed.

• Drag the unzipped FireworkVideo.xcframework into the Xcode project navigator and drop it at root of your project. Make sure Copy items if needed checkbox is selected in the confirmation dialog. Check to make sure your project directory now has FireworkVideo.xcframework in it and it is visible and linked in your Xcode project navigator.

• In your apps Project pane select your app Target > Build Phases, click the + button, and add a Copy Files step. Select Frameworks as the destination and click the + within the Copy Files step and select FireworkVideo.xcframework. Your Copy Files step should look like below.

Copy Files Step

Initialization

Start by importing the SDK into your App Delegate. Then initialize the Firework Video SDK in the App Delegate method application(:, didFinishLaunchingWithOptions:) -> Bool.

import UIKit

// Add the dependency SDK
import FireworkVideo

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        // Initialize the SDK with app ID
        FireworkVideoSDK.initializeSDK(appID: "Firework App ID")

        // SDK has privacy manifest configuration to ensure compliance with privacy guidelines and regulations. Please use the `AppTrackingTransparency` framework to present an app-tracking authorization request to the user and provide the tracking authorization status.

        return true
    }

    // ... //
}

Requirement

FireworkVideoSDK.initializeSDK() must be called before using any SDK components. Using the SDK without initialization will trigger a fatal error, causing your app to crash immediately.

Why Fatal Errors?

The SDK intentionally crashes on uninitialized usage because:

1. Invalid Internal State: Without initialization, the SDK's dependency injection container, networking layer, and analytics system are uninitialized. Allowing execution would cause unpredictable behavior, data corruption, or crashes at unexpected points in your app.

2. Early Detection: Fatal errors force you to discover and fix integration issues during development and testing, preventing these problems from reaching your production users.

3. Clear Diagnostics: An immediate crash with an explicit error message makes the problem obvious and easy to fix, rather than causing subtle bugs that are hard to trace.

This approach follows industry standards set by Firebase, Stripe, and AWS Amplify.

Proper Integration

✅ Correct: Initialize unconditionally

func application(_ application: UIApplication, 
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Always initialize - no UI side effects, minimal overhead
    FireworkVideoSDK.initializeSDK()
    return true
}

❌ Incorrect: Conditional initialization with feature flags

func application(_ application: UIApplication, 
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // DON'T: This can cause crashes
    if featureFlags.isFireworkEnabled {
        FireworkVideoSDK.initializeSDK()  // ⚠️ Dangerous!
    }
    return true
}

Why Not Use Feature Flags for Initialization?

Problem: SwiftUI views and view controllers may be instantiated before your feature flag is evaluated, causing the SDK components to be used before initialization.

Solution: Always initialize the SDK unconditionally in application(_:didFinishLaunchingWithOptions:). The initialization:

• Has no UI side effects (doesn't display anything)

• Has minimal overhead

• Makes the SDK ready whenever needed

Use feature flags to control visibility, not initialization:

// ✅ Good: Feature flag controls UI visibility
var body: some View {
    if featureFlags.isFireworkEnabled {
        FWSVideoFeedSwiftUIView(...)  // Show when enabled
    }
}

This ensures the SDK is always properly initialized, while your feature flags still control when and where Firework components appear in your app.

Configure App ID

You can configure Firework app ID via Info.plist or Initialization method.

Configure via Info.plist

Include the app ID in your app Info.plist file using the key FireworkVideoAppID see image below. If the app ID is not included or is included under a differently spelled key, the SDK will return an error. See Troubleshooting for more details.

App Setup Info Plist

Configure via Initialization method

We also support passing the app ID via the SDK initialization method. The app ID provided through this method takes precedence over the value specified in the Info.plist file.

FireworkVideoSDK.initializeSDK(appID: "Firework App ID")

Check SDK Initialization Status

You can use FireworkVideoSDK.isInitialized to determine whether the SDK has been successfully initialized.

Next

ATT compliance

To ensure compliance with Apple privacy guidelines and regulations, we don't track data if users don't allow it. Please refer to ATT compliance (iOS) for more details.

Video Feed

If you want to integrate the video feed, please follow the instruction here.

Story Block

If you want to integrate the story block, please follow the instruction here.

Customization

If you want to customize SDK, please refer to Customization.

Live stream support

If you want to integrate the live stream, please follow the instruction here.

Shopping

If you want to integrate video shopping, please follow the instruction here.

Analytics

If you want to integrate video shopping, please follow the instruction here.