Introduce Debug Logging

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [Unreleased]
+
+### Added
+
+- `isDebugLoggingEnabled` and `setDebugLogging(value: boolean)` to check and set whether debug logging is enabled. Debug logging helps diagnose problems and trace the flow of execution within the Player and **should not be enabled in production** as it may log sensitive or confidential information to the console.
+
 ## [0.32.0] - 2024-11-14
 
 ### Added

android/src/main/java/com/bitmovin/player/reactnative/DebugModule.kt

@@ -0,0 +1,23 @@
+package com.bitmovin.player.reactnative
+
+import com.bitmovin.player.api.DebugConfig
+import com.facebook.react.bridge.*
+import com.facebook.react.module.annotations.ReactModule
+
+private const val MODULE_NAME = "DebugModule"
+
+@ReactModule(name = MODULE_NAME)
+class DebugModule(context: ReactApplicationContext) : BitmovinBaseModule(context) {
+    override fun getName() = MODULE_NAME
+
+    /**
+     * Enable/disable verbose logging for the console logger.
+     * @param enabled Whether to set verbose logging as enabled or disabled.
+     */
+    @ReactMethod
+    fun setLoggingEnabled(enabled: Boolean, promise: Promise) {
+        promise.unit.resolveOnUiThread {
+            DebugConfig.isLoggingEnabled = enabled
+        }
+    }
+}

android/src/main/java/com/bitmovin/player/reactnative/RNPlayerViewPackage.kt

@@ -30,6 +30,7 @@ class RNPlayerViewPackage : ReactPackage {
             BitmovinCastManagerModule(reactContext),
             BufferModule(reactContext),
             NetworkModule(reactContext),
+            DebugModule(reactContext),
         )
     }
 

ios/DebugModule.m

@@ -0,0 +1,7 @@
+#import <React/RCTBridgeModule.h>
+
+@interface RCT_EXTERN_REMAP_MODULE(DebugModule, DebugModule, NSObject)
+
+RCT_EXTERN_METHOD(setLoggingEnabled:(nonnull BOOL)enabled)
+
+@end

ios/DebugModule.swift

@@ -0,0 +1,38 @@
+import BitmovinPlayer
+
+@objc(DebugModule)
+public class DebugModule: NSObject, RCTBridgeModule {
+    // swiftlint:disable:next implicitly_unwrapped_optional
+    @objc public var bridge: RCTBridge!
+
+    // swiftlint:disable:next implicitly_unwrapped_optional
+    public static func moduleName() -> String! {
+        "DebugModule"
+    }
+
+    /// Module requires main thread initialization.
+    public static func requiresMainQueueSetup() -> Bool {
+        true
+    }
+
+    // swiftlint:disable:next implicitly_unwrapped_optional
+    public var methodQueue: DispatchQueue! {
+        bridge.uiManager.methodQueue
+    }
+}
+
+extension DebugModule {
+    /// Enable/disable verbose logging for the console logger.
+    /// - Parameter enabled: Whether to set verbose logging as enabled or disabled.
+    @objc(setLoggingEnabled:)
+    func setLoggingEnabled(enabled: Bool) {
+        bridge.uiManager.addUIBlock { [weak self] _, _ in
+            let defaultMinimumLevel: LogLevel = .warning
+            if enabled {
+                DebugConfig.logging.logger?.level = .verbose
+            } else {
+                DebugConfig.logging.logger?.level = defaultMinimumLevel
+            }
+        }
+    }
+}

src/debug.ts

@@ -0,0 +1,56 @@
+import { NativeModules } from 'react-native';
+
+const DebugModule = NativeModules.DebugModule;
+
+/**
+ * Global debug configuration for all Bitmovin components.
+ */
+export class DebugConfig {
+  private static _isDebugEnabled = false;
+
+  /**
+   * Retrieves the current debug logging state.
+   *
+   * @returns `true` if debug logging is enabled, otherwise `false`.
+   */
+  static get isDebugLoggingEnabled(): boolean {
+    return DebugConfig._isDebugEnabled;
+  }
+
+  /**
+   * Enables or disables global debug logging for all Bitmovin components.
+   *
+   * Debug logging provides detailed information primarily for debugging purposes,
+   * helping to diagnose problems and trace the flow of execution within the Player.
+   *
+   * ### Warning:
+   * This option **should not be enabled in production** as it may log sensitive or confidential
+   * information to the console.
+   *
+   * ## Platform-Specific Logging Behavior
+   * ---
+   * - **iOS:** logs are printed using `NSLog` at the verbose log level.
+   * - **Android:** logs are printed using `android.util.Log` with the following tags:
+   *   - `BitmovinPlayer`
+   *   - `BitmovinPlayerView`
+   *   - `BitmovinOffline`
+   *   - `BitmovinSource`
+   *   - `BitmovinExoPlayer`
+   *
+   * ## Limitations
+   * ---
+   * **Android**
+   * - This flag **must** be set **before** creating any Bitmovin component to take effect.
+   *
+   * ## Usage Notes
+   * ---
+   * - We recommend setting this flag during your app's initialization phase, such as in the
+   *   application's entry point (e.g. `App.tsx`).
+   *
+   * @defaultValue `false`
+   */
+  static async setDebugLogging(value: boolean): Promise<void> {
+    DebugConfig._isDebugEnabled = value;
+    await DebugModule.setLoggingEnabled(value);
+  }
+}

src/index.ts

@@ -25,3 +25,4 @@ export * from './liveConfig';
 export * from './bufferApi';
 export * from './network';
 export * from './mediaControlConfig';
+export * from './debug';