# 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: > 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](https://developer.apple.com/documentation/xcode/adding_package_dependencies_to_your_app) Select Version > Up to Next Major > {Latest Version from [CHANGELOG.md](https://github.com/loopsocial/firework_ios_sdk/blob/main/CHANGELOG.md)} Latest version release notes can be found [here](https://help.firework.com/en/knowledge/sdk-ios-updates) #### 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](https://www.github.com/loopsocial/firework_ios_sdk/releases/download/v0.15.0/FireworkVideo-v0.15.0.xcframework.zip) 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](https://github.com/loopsocial/firework_ios_sdk/blob/main/Resources/manual_installation_copy_files_step.png?raw=true) ### **Initialization** Start by importing the SDK into your App Delegate. Then initialize the Firework Video SDK in the App Delegate method `application(:, didFinishLaunchingWithOptions:) -> Bool`. ```swift 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 ```swift 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 ```swift 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: ```worktree-swift // ✅ 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](https://github.com/loopsocial/firework_ios_sdk/blob/main/Resources/app_setup_info_plist.png?raw=true) #### **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. ```swift 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 Please refer to [ATT compliance (iOS)](https://docs.firework.com/firework-for-developers/ios-sdk/integration-guide-for-ios-sdk/att-compliance-ios) for more details. #### Video Feed If you want to integrate the video feed, please follow the instruction [here](https://docs.firework.com/firework-for-developers/ios-sdk/integration-guide-for-ios-sdk/video-feed). #### Story Block If you want to integrate the story block, please follow the instruction [here](https://docs.firework.com/firework-for-developers/ios-sdk/integration-guide-for-ios-sdk/storyblock). #### Customization If you want to customize SDK, please refer to [Customization](https://docs.firework.com/firework-for-developers/ios-sdk/integration-guide-for-ios-sdk/customization-ios). #### Live stream support If you want to integrate the live stream, please follow the instruction [here](https://docs.firework.com/firework-for-developers/ios-sdk/integration-guide-for-ios-sdk/live-stream-support). #### Shopping If you want to integrate video shopping, please follow the instruction [here](https://docs.firework.com/firework-for-developers/ios-sdk/integration-guide-for-ios-sdk/shopping-ios). #### Analytics If you want to integrate video shopping, please follow the instruction [here](https://docs.firework.com/firework-for-developers/ios-sdk/integration-guide-for-ios-sdk/analytics). ####