cliplister-viewer

React component wrapper for the Cliplister Viewer. It loads the Cliplister viewer script on demand and renders a player container configured with your customer and asset keys.

Installation

npm i cliplister-viewer

Basic Usage

import { CLViewer } from "cliplister-viewer";

export function App() {
  return (
    <CLViewer
      customerId="YOUR_CUSTOMER_ID"
    />
  );
}

This example will load a video player with default settings and attempt to auto-detect an EAN/GTIN in your page's metadata (Like a Schema.org Product object) as a video identifier.

Advanced Usage

import { CLViewer } from "cliplister-viewer";

export function App() {
  return (
    <CLViewer
      customerId="YOUR_CUSTOMER_ID"
      requestkey={["ASSET_REQUEST_KEY"]}
      keytype={0} // 0 is for EAN of a related Product, see the "Props" section for other supported keytypes
      type="video"
      aspectRatio="asset"
    />
  );
}
// see Props section, for other video Props

Next.js (client-only)

The viewer depends on browser APIs, so render it on the client side only. Use next/dynamic with ssr: false:

import dynamic from "next/dynamic";

const CLViewer = dynamic(
  () => import("cliplister-viewer").then((mod) => mod.CLViewer),
  { ssr: false }
);

export default function Page() {
  return (
    <CLViewer
      customerId="YOUR_CUSTOMER_ID"
      requestkey={["ASSET_REQUEST_KEY"]}
      keytype={0}
      type="video"
      aspectRatio="asset"
    />
  );
}

Usage with 3D

import { CLViewer } from "cliplister-viewer";

export function App() {
  return (
    <CLViewer
      customerId="YOUR_CUSTOMER_ID"
      requestkey={["ASSET_REQUEST_KEY"]}
      type="3d"
      keytype={0} // 0 is for EAN of a related Product, see the "Props" section for other supported keytypes
      aspectRatio="16:9"
      backgroundColor="#fff"
      threeDParams={{
        cameraControls: boolean,
        autoRotate: boolean,
        arEnabled: boolean,
        arPreferred: boolean,
        qrEnabled: boolean,
      }}
    />
  );
}

Usage with 360

import { CLViewer } from "cliplister-viewer";

export function App() {
  return (
    <CLViewer
      customerId="YOUR_CUSTOMER_ID"
      requestkey={["ASSET_REQUEST_KEY"]}
      type="360"
      keytype={0} // 0 is for EAN of a related Product, see the props section for other supported keytypes
      aspectRatio="asset"
      threeSixtyParams={{
        layer: number,
        speedX: number,
        speedY: number,
        multilvl: boolean,
        inverted: boolean,
      }}
    />
  );
}

Usage with Precheck

import { useMemo } from "react";
import {
  CLViewer,
  usePrecheck,
  PrecheckAssetTypeEnum,
  type PrecheckOptions,
  type PrecheckResult,
  type PrecheckItem,
} from "cliplister-viewer";

  // You can use the "data" returned from the Precheck Hook for your custom UI, 
  // You don't necessarily have to use "<CLViewer/>", This examples uses <CLViewer/>, only for illustration purpose.
export function App() {

  const options: PrecheckOptions = {
    encryptKey: "YOUR_ENCRYPT_KEY",
    apiToken: "YOUR_API_TOKEN",
    ean: "EAN_FOR_ASSET",
    lang: "commaSeparatedStringOfLanguage", // e.g. "es,##,en" (ISO 639-1)
    returnType: [
      PrecheckAssetTypeEnum.VIDEO,
      PrecheckAssetTypeEnum.ASSET_3D,
      PrecheckAssetTypeEnum.ASSET_360,
    ],
  };
  const { data, loading } = usePrecheck(options);

  // Note: use the same language(s) as your real integration. The `lang` value
  // filters which assets are returned.

  const results: PrecheckResult[] = data ?? [];
  const assets = useMemo<PrecheckItem[]>(() => {
    return results.flatMap((item) => [
      ...item.videos,
      ...item.assets3D,
      ...item.assets360,
    ]);
  }, [results]);

  if (loading) {
    return <div>Loading...</div>;
  }

  return (
    <>
      {assets.map((asset) => (
        <CLViewer
          key={asset.cluuid}
          customerId="YOUR_CUSTOMER_ID"
          asset={asset}
          aspectRatio="asset"
          type={asset.type}
        />
      ))}
    </>
  );
}

PrecheckAssetTypeEnum values:

• PrecheckAssetTypeEnum.VIDEO - Include video assets.
• PrecheckAssetTypeEnum.ASSET_3D - Include 3D assets (maps to API value "3D").
• PrecheckAssetTypeEnum.ASSET_360 - Include 360 assets (maps to API value "360view").

Usage with refs

Use a ref to access the viewer instance after initialization:

import { useRef } from "react";
import { CLViewer, type CliplisterViewer } from "cliplister-viewer";

export function App() {
  const viewerRef = useRef<CliplisterViewer | null>(null);

  return (
    <CLViewer
      ref={viewerRef}
      customerId="YOUR_CUSTOMER_ID"
      requestkey={["ASSET_REQUEST_KEY"]}
      onViewerReady={(viewer)=> {
        // In addition to the ref usage, you can also get the player instance with this callback
      }}
    />
  );
}

Play/pause with the viewer instance and Ref

import { useRef } from "react";
import { CLViewer, type CliplisterViewer } from "cliplister-viewer";

export function App() {
  const viewerRef = useRef<CliplisterViewer | null>(null);

  const play = () => viewerRef.current?.play?.();
  const pause = () => viewerRef.current?.pause?.();

  return (
    <>
      <CLViewer ref={viewerRef} customerId="YOUR_CUSTOMER_ID" requestkey={["ASSET_REQUEST_KEY"]} />
      <button type="button" onClick={play}>Play</button>
      <button type="button" onClick={pause}>Pause</button>
    </>
  );
}

The CliplisterViewer type includes all viewer instance API methods. Use it on the ref to discover and call any available method from the Cliplister Viewer API.

CLViewer component

CLViewer loads the Cliplister Viewer script and initializes a viewer instance once the script is available. If customerId is missing, the component logs a warning and returns null.

Props

• customerId: string - Required Cliplister customer id.

• requestkey?: string[] - Asset key(s). Pass an array for multiple assets. If omitted an attempt is made to auto-detect an EAN/GTIN in the page's metadata.

• keytype?: number - Optional key type override. If omitted, the component infers 0 for EAN-13 keys and 10000 otherwise. If keytype is not provided: 0 when requestkey is a valid EAN-13, otherwise 10000. Allowed values:

  • 0 = requestkey is a GTIN / EAN.
  • 10000 = requestkey is a customer-specific key.
  • 30000 = requestkey is a cluuid.

• languages?: string[] - Preferred language list for a specific asset (ISO 639-1).

• type?: "video" | "3d" | "360" - Optional content type hint. Defaults to "video".

• asset?: PrecheckItem - Precheck asset; overrides requestkey, keytype, and type.

Type definitions

• Types are exported from cliplister-viewer (e.g. import type { PrecheckItem } from "cliplister-viewer").
• PrecheckItem = { type: "video" | "3d" | "360"; asset: VideoAsset | Asset3D | Asset360; cluuid: string }.
• VideoAsset = { id: string; title: string; language: string; cluuid: string; rating: number; clipTypeId: number; clipTypeName: string; links: AssetLink[] } (language uses ISO 639-1).
• Asset3D = { id: string; title: string; language: string; rating: number; links: AssetLink[] } (language uses ISO 639-1).
• Asset360 = { id: string; title: string; language: string; rating: number; links: AssetLink[] } (language uses ISO 639-1).

Video-only props

• autoplay?: boolean - Whether the viewer should start playing automatically. Autoplay is blocked in browsers/environments that disallow autoplay when audio is not muted; set mute: true when using autoplay.
• mute?: boolean - Mute audio when the viewer starts.
• backgroundvideo?: boolean | "always" - Treat the video as background content. Enables autoplay + muted with no controls and uses a static image fallback on mobile unless set to "always" (always render video).
• loop?: boolean - Loop playback.

Viewer props

• playButton?: { source: string; height?: number; width?: number } - Custom play button image.
• previewImage?: { source: string; backgroundSize?: string } - Custom preview image.
• aspectRatio?: string - e.g, Viewer aspect ratio string. e.g. "16:9", defaults to "asset" (aspect ratio of the asset).
• backgroundColor?: string - Background color for the viewer container.

3D / 360 props

• threeDParams?: { cameraControls?: boolean; autoRotate?: boolean; arEnabled?: boolean; arPreferred?: boolean; qrEnabled?: boolean } - 3D stage options. Details:
  • cameraControls: enable camera/orbit controls.
  • autoRotate: auto-rotate the model when idle.
  • arEnabled: enable AR entry points when supported.
  • arPreferred: prefer AR mode when available.
  • qrEnabled: show QR code entry when AR is available.
• threeSixtyParams?: { layer?: number; speedX?: number; speedY?: number; multilvl?: boolean; inverted?: boolean } - Turntable options for 360 assets. Details:
  • speedX (1–9): horizontal turning speed.
  • speedY (1–9): vertical turning speed.
  • multilvl: enables up/down rotation if available.
  • inverted: turns with or against the mouse (single axis inversion).

Lifecycle / control props

• onViewerReady?: (viewer: CliplisterViewer) => void - Callback invoked once the viewer is initialized.
• reloadkey?: string | number | boolean - Change this value to force the viewer to reload.
• ref?: React.Ref<CliplisterViewer | null> - Ref for accessing the viewer instance.
• innerControlsSrc?: string - External controls template source for video.

Script loading

The component injects the Cliplister viewer script from:

https://mycliplister.com/merge?cliplister=1.14&clviewer=1.46&videostage=1.32&clstage3d=1.7&controls3d=1.4&qrcode=1.4&modelviewer=4.0.0&clstageimage360=1.10&turntable=1.3&bufferingspinner=1.6&zoom360=1.7

If the script is already present on the page, it reuses the existing instance.