@phenixrts/sdk 2025.2.4-beta.630 → 2025.2.4-beta.656

package/README.md

@@ -100,3 +100,83 @@ Setting different levels for the console log appender and other appenders:
         consoleLoggingLevel: 'Error'
     });
 ```
+
+## Providing hls.js
+
+The SDK does not bundle hls.js, and it never fetches it for you. Chunked live playback needs it, so your application supplies the constructor through the `hlsJsLoader` option of `phenix.SDK.init`.
+
+The SDK is built and tested against hls.js 1.7.2. Later 1.x releases have changed the APIs the SDK calls, so test playback before you move the version.
+
+### Preferred: bundle hls.js with your application
+
+Install hls.js yourself, then hand the constructor to the SDK. Your lockfile pins the version, your bundler ships the code, and no third party is involved:
+```
+    import Hls from 'hls.js';
+
+    phenix.SDK.init({
+        hlsJsLoader: function(callback) {
+            callback(Hls);
+        }
+    });
+```
+
+### Loading hls.js from a CDN
+
+If you load the SDK from a script tag and do not bundle, inject hls.js yourself. Pin the exact version and add a Subresource Integrity hash:
+```
+    phenix.SDK.init({
+        hlsJsLoader: function(callback) {
+            var script = document.createElement('script');
+
+            script.async = true;
+            script.integrity = 'sha384-xZKOEqJSfUEI1E4N6MG1+KjnKYM1R1v2WKpyaS0c+ksIxRi5PB8MAkyEdX48MX2/';
+            script.crossOrigin = 'anonymous';
+
+            script.onload = function() {
+                callback(window.Hls);
+            };
+
+            script.onerror = function() {
+                callback(undefined);
+            };
+
+            // Set the source last, so the handlers and the hash are in place first.
+            script.src = 'https://cdn.jsdelivr.net/npm/hls.js@1.7.2/dist/hls.min.js';
+
+            document.head.appendChild(script);
+        }
+    });
+```
+The hash above matches hls.js 1.7.2 on jsDelivr. Regenerate it whenever you move the version:
+```
+    curl -fsSL https://cdn.jsdelivr.net/npm/hls.js@<version>/dist/hls.min.js |
+        openssl dgst -sha384 -binary | openssl base64 -A
+```
+
+Four details matter in a loader of your own:
+
+- **Pin the version.** A floating range such as `hls.js@1` changes the executed bytes without a release on your side, and no integrity hash can cover a moving file.
+- **Keep `crossOrigin`.** Subresource Integrity needs it for a cross-origin script, and the load fails without it.
+- **Inject once.** Call back immediately when `window.Hls` is already set, so repeated sessions reuse the script the page already carries.
+- **Report failure.** Call back with nothing on `onerror`, as the example above does. The SDK checks for a constructor, and treats anything else as a failed load.
+
+The SDK bounds the wait for your loader, so a loader that never calls back fails the request rather than hanging it. If your loader carries its own timeout, keep it below the SDK's bound so your own diagnostic reports first.
+
+`examples/src/channel-viewer-hls-dash-player-loading-example.js` carries a working version of this loader.
+
+### Content Security Policy
+
+Grant the origin you fetch from. For the URL above:
+```
+    Content-Security-Policy: script-src https://cdn.jsdelivr.net
+```
+Some policies pin script hashes or set `require-sri-for`. Add the integrity hash above if yours does.
+
+### Before you load from a CDN
+
+Weigh these points, because the choice is yours to make and the SDK will not make it for you:
+
+- The fetch runs third-party code inside your origin. A compromise of the file or the CDN would run in your page, with your DOM and your tokens in reach. The pinned version and the integrity hash exist to close that gap, so keep both.
+- The fetch sends every viewer's IP address, User-Agent and Referer to the CDN. Under GDPR you are the controller, so name the recipient in your privacy notice before you ship this.
+- The CDN becomes an availability dependency of playback. If it is unreachable, chunked playback fails.
+- A strict `script-src` policy, an offline deployment or an on-premise deployment will block the fetch. Bundle hls.js or mirror it on your own origin instead.