@hexdn/react

Ready-made, customizable playback and upload UI. Import only the entry point you need. Styles are included; use labels, CSS variables and custom content to fit your application. Keep HexDN environment API keys on your server.

Player

import { Player } from "@hexdn/react/player";

<Player source="https://cdn.example/video/master.m3u8" title="My video" />;

For restricted video, expose a tenant endpoint that authorizes the viewer and returns hexdn.playback.createSource(...) for protected playback or hexdn.playback.createSignedSource(...) for signed playback, using @hexdn/sdk:

<Player sourceEndpoint="/api/videos/42/playback" title="My video" />

The player acquires and renews the source through that endpoint. getSource supports custom acquisition. Labels, themes and slots customize the controls; integration callbacks connect application navigation, preferences and progress persistence. Ready public sources need no credential request. The HLS engine loads only when required.

Playback-origin restrictions are optional. If your HexDN environment has playback origins configured, include your application's origin; an empty playback-origin list does not restrict origins.

Enable analytics by supplying a public collection key. A ready HexDN source already supplies its playbackId, so no separate video identity is needed:

<Player source={source} analytics={{ collectionKey: "ack_..." }} />

For external videos, or when the source must first be fetched, supply your stable video ID once. This allows analytics to measure authorization/startup failures before the source arrives:

<Player
  sourceEndpoint="/api/videos/42/playback"
  analytics={{ collectionKey: "ack_...", video: { id: "42" } }}
/>

Provision the collection key once on your trusted server using @hexdn/sdk:

const key = await hexdn.analytics.collectionKeys.create({
  origins: ["https://app.example"],
});
const publicAnalytics = hexdn.analytics.collectionConfig(key.id);

Publish publicAnalytics through your application's configuration and pass it as analytics (adding video when needed). This helper also carries the environment choice from your server client. Production collection needs only the key. Use exact website origins (scheme, host and port); provision once, not per view. Keep the environment API key on the server. Collection origins are independent of playback and upload permissions.

Custom transport callbacks remain available for advanced reporting workflows; normal collection needs no transport construction or extra analytics import.

An existing beginPlaybackAttempt() handle can be supplied as analytics.pendingAttempt when play intent precedes mounting the player. Its video identity is reused automatically. Credential changes retain the attempt. Changing the collection key or HexDN environment starts a new attempt without reloading the media; prior reports stay with their original destination. Product view rules and resume persistence remain application responsibilities.

A source descriptor's playbackId supplies the default content identity. Credential URL changes with the same ID preserve position, playback speed and play/pause intent. Use playbackIdentity to override it; external sources without an ID use their URL for playback only. Analytics defaults to an explicit playbackIdentity or a ready source's playbackId; analytics.video overrides that default for your own grouping. Credential URLs are never used as analytics IDs. Invalid analytics configuration is surfaced through analytics.onError without stopping playback.

Uploader

Have your HexDN operator register your website for uploads once. Registration also applies and verifies the source-storage CORS policy; tenants do not maintain a separate storage-origin list. Origin provisioning is currently an operator task, not a method on the public server SDK.

import { Uploader } from "@hexdn/react/upload";

<Uploader
  uploadEndpoint="/api/video-uploads"
  onComplete={() => refreshApplicationVideo()}
/>;

The uploader POSTs { filename, byteLength, mimeType } to your endpoint using same-origin credentials, an abort signal and a retry-stable Idempotency-Key. Your endpoint authenticates the uploader, chooses outputs, forwards that key to asset creation, and returns { upload: { url, token } }. Media bytes go directly to storage. An existing capability can be passed as upload={capability}; getUpload(file, { signal, idempotencyKey }) supports custom authorization flows.

The default UI supports file selection, dropping a file, progress, pause and resume/retry. Media bytes go directly to storage through @hexdn/upload. Resume uses the same capability and original file, including authoritative part reconciliation and completion recovery. Upload completion confirms receipt of source bytes; processing/readiness comes from the application's normal API reads or webhooks.

Pause and default unmount cleanup stop local transfer only. Remote cancellation is a separate explicit application action. Set abortOnUnmount={false} only when the application owns a continuing background workflow. The accept prop is a file-picker hint; enforce product and content rules on your server.

Customize labels and --hexdn-upload-color, --hexdn-upload-background, --hexdn-upload-border, --hexdn-upload-radius, and --hexdn-upload-accent. For an existing application, use the same controller with your own presentation:

import { Uploader, useUploader } from "@hexdn/react/upload";

const uploader = useUploader({ upload: capability });

<Uploader controller={uploader} dropEnabled={false}>
  <button disabled={uploader.isBusy} onClick={uploader.openPicker}>
    Choose video
  </button>
  <progress max={100} value={uploader.state.progress?.percent ?? 0} />
</Uploader>;

children can also be a render function receiving the controller. Advanced applications can supply transfer(file, { signal, onProgress, idempotencyKey }) to wrap their existing authorization and product workflow around the upload core. That callback owns retry/resume semantics and must distinguish local abort from any destructive product action. Errors remain available as controller.state.error; raw provider errors are not displayed by the default UI.

Neither uploader entry point nor upload core imports the player, HLS, or analytics.