Embedding the Threekit Player

The Threekit player can be embedded in another webpage by loading it inside a div element

Embedding the Threekit Player

The Threekit player can be embedded in another webpage by loading it inside a div element. After loading the threekit-player.js script, call the threekitPlayer({ ... }) function, which returns a Promise to the player. Pass in the following object as a parameter:

{
  authToken,
  el,
  cache,
  stageId,
  assetId,
  showConfigurator,
  initialConfiguration,
  showLoadingThumbnail,
  showLoadingProgress,
  onLoadingProgress,
  showAR,
  showShare,
  locale,
  allowMobileVerticalOrbit,
  compression
}

authToken: the public access token. Instructions for creating tokens found here.
el: the HTML element that will contain the player.
stageId (optional): the UUID of the scene asset. Necessary when including a Model Asset within a Scene Asset when embedding the player (Scene Setup is required when using this parameter.)
assetId: the UUID of the asset to be loaded.
cache: the caching options for the player. It contains the maxAge and scope for assets caching.
showConfigurator (optional): determines if we render the configurator.
display: 'image' (optional): load 2D Player upon initialization
initialConfiguration (optional): an object setting up an initial configuration.
showAR (optional): parameter to show/hide the built-in AR Button, default value is false.
showShare (optional): parameter to show/hide the built-in Share Button, default value is false
showLoadingThumbnail (optional): parameter to display a snapshot while the player is loading, default value is false
showLoadingProgress (optional): determines if we show the progress bar during load.
onLoadingProgress (optional): callback to receive loading progress information.
locale (optional): parameter determines the language of the embed
allowMobileVerticalOrbit (optional): parameter toggles vertical orbit on mobile devices, default value is false.
compression: (optional): override organization's compression setting for renders in 2D player.

Example

<div id="player"></div>
<script src="https://preview.threekit.com/app/js/threekit-player.js"></script>
<script>
     window
      .threekitPlayer({
        authToken: "01234567-89ab-cdef-0123-456789abcdef",
        el: document.getElementById("player"),
        stageId: '27b9cd7e-2bb2-4a18-b788-160743eb4b33',
        assetId: "e12a45f7-8b39-cd06-e12a-45f78b39cd06",
        initialConfiguration: {
         'Attribute Name': {
            assetId: '4a9f7980-78a4-4ace-8cda-f2799936c4dc',
            configuration: { 'key' : 'value'}
          }},
        showConfigurator: true,
        showAR: true,
      })
      .then(async function(player) {
        window.player = player;
      });
</script>

Upon embedding the Threekit player, ensure the source URL references the appropriate Threekit environment. For example, the script above points to 'preview..', thus the token and referenced assets, etc. would need to be from an instance on the 'admin' environment.

Configuring the player

Use player.getConfigurator() to get a configurator instance for the player. That configurator provides several methods, getConfiguration, getAttributes, and setConfiguration.

configurator.getConfiguration(): returns an object with the current configuration.

configurator.getAttributes(): returns the list of attributes.

configurator.setConfiguration(configuration, evaluateRules): set a configuration specified by the configuration object. The evaluateRules parameter is a boolean, set to true by default.

Query Parameters

An initial configuration may be provided by setting the tkcsid query parameter to the configurations' ID or short ID. The ID and short ID for a saved configuration can be found on the Threekit platform.

http://example.com/?tkcsid=EXIPiBA56

showLoadingProgress

{
  enabled,
  waitToShow,
}

onLoadingProgress takes a callback as its value. The callback's only argument is a number, representing the progress ratio ( from 0.0 to 1.0 ). The callback will be called whenever the loading progresses. The progress ratio is only approximate.

showLoadingProgress can be either a boolean (true|false), or an object with the following properties:

Compression

{
  imageFormat: 'webp' | 'png'
  imageResolution: string ,
  imageQuality: number
}

enabled: determines if we show the loading bar.
waitToShow (optional): amount of time (in ms) to wait before showing the progress bar. Defaults to 500ms.
If showLoadingProgress is set to a boolean value, it will be treated as { "enabled": value }.