@npaw/forge-web
v10.8.0
Published
Forge Web JavaScript and WASM binding facade.
Readme
@npaw/forge-web
NPAW Forge analytics for Web and TV browsers: application sessions, video and ad analytics, network capture, autocapture, and Web Vitals, powered by the shared Forge analytics core (WASM).
Use of this package requires an active NPAW commercial agreement. See LICENSE.
Install
npm install @npaw/forge-webimport { NPAWForge, HlsjsAdapter } from "@npaw/forge-web";
const forge = await NPAWForge.create({
accountCode: "<account-code>",
appName: "Player App",
appReleaseVersion: "1.0.0",
startSessionOnInitialize: true,
});
const video = await forge.videoBuilder()
.setIdentifier("main")
.setMetadata({ title: "Episode 1", contentType: "vod" })
.setPlayerAdapter(new HlsjsAdapter(hls))
.build();A script-tag IIFE build with data-* bootstrap configuration is also
distributed for TV/browser targets without a bundler.
Smart TVs: choosing the entry
Use the explicit legacy entry on TV engines without WebAssembly or older than
Chromium 85: LG webOS 3.x to 6.x and Samsung Tizen 2.4 to 6.0. Before
Chromium 85 the V8 engine compiles WebAssembly on the ARM processors of TVs
with its optimizing compiler only, so the WebAssembly entry's create() waits
seconds for its kernel (about 11 s on a 2020 LG webOS 5 TV, against 43-70 ms
for the legacy entry on the same TV). The legacy entry uses handwritten
JavaScript and the same player/ad adapters for online video, ads and manual
application sessions:
import { create, HTML5Adapter } from "@npaw/forge-web/legacy";
const forge = await create({ accountCode: "<account-code>" });
const video = await forge.videoBuilder()
.setMetadata({ title: "Episode 1", contentType: "vod" })
.setPlayerAdapter(new HTML5Adapter(document.querySelector("video")))
.build();The standalone script is npaw-forge-web.legacy.iife.min.js, exposing
NPAWForgeLegacy. It targets Chromium 53; compile application code for that
browser too. Physical TV qualification is still pending. Automatic capture,
network capture, experiments, Web Vitals and offline replay are outside this
smaller profile.
From Chromium 85 (Samsung Tizen 6.5, LG webOS 22 and newer) and in desktop and
mobile browsers, use the standard WebAssembly entry; the legacy entry also runs
there, but the WebAssembly entry is the supported choice. Hisense VIDAA TVs
are not yet a declared target; the same Chromium 85 rule applies to them.
Call preloadKernel() as early as the app starts so the kernel downloads and
compiles during the app's own bootstrap, and serve forge_kernel_wasm_bg.wasm
with Content-Type: application/wasm so it compiles while it downloads.
Node.js and set-top-box UI engines
Node.js 18 and later run the same manual video, ad and session API, for
example in the UI engine of a set-top box. @npaw/forge-web/node supplies the
host defaults (no browser capture, a node:http transport, a file storage when
you give a directory and an in-memory one otherwise, a clock that ignores
wall-clock jumps):
import { NPAWForge } from "@npaw/forge-web";
import { nodeCreateOptions } from "@npaw/forge-web/node";
const forge = await NPAWForge.create(nodeCreateOptions({
accountCode: "<account-code>",
// The box's own stable identifier, read from the hardware: no storage directory needed.
deviceUuid: await readBoxId(),
deviceInfo: { type: "STB", brand: "<brand>", model: "<model>", osName: "<os>", osVersion: "<version>" },
}));
const video = await forge.videoBuilder()
.setMetadata({ title: "Channel 4", contentType: "live", channel: "4" })
.build();
await video.fireStart();The storage directory is optional when the box passes its own deviceUuid;
Forge then writes nothing to disk. A box without a stable identifier passes
storageDirectory, where Forge keeps the identifier it generates. A directory
also keeps the last good configuration from NPAW, which the next start applies
at once instead of running on the defaults until NPAW answers.
A good identifier is stable for the life of the box, unique per box, the same
in every process that reports for it, and never blank: a blank deviceUuid
counts as not given. Prefer a pseudonymous value, such as a vendor device ID or
a salted hash of the serial number, to a raw serial number or MAC address.
Without deviceUuid, storageDirectory or storage, every restart reports a
new device, and Node prints one NPAWForgeWarning (NPAW_FORGE_NO_STORAGE).
Where Node runs without WebAssembly (--jitless), use
@npaw/forge-web/legacy and pass it createNodeHttpTransport(),
createNodeFileStorage({ directory }) and createNodeClock() from
@npaw/forge-web/node.
Documentation
Integration guides, the full adapter catalog (HTML5, Shaka, Hls.js, dash.js, Video.js, Bitmovin, THEOplayer, IMA, and more), migration notes, and troubleshooting are available from NPAW. Contact your NPAW representative or visit https://npaw.com for access and support.
