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,
  assetId,
  customId,
  stageId,
  branch,
  cache,
  showConfigurator,
  display, 
  configurationId,
  initialConfiguration,
  showAR,
  showShare,
  showLoadingProgress,
  showLoadingThumbnail,
   enabled,
   waitToShow,
   loadingImage,
   loadingComponent,
  onLoadingProgress,
  locale,
  allowMobileVerticalOrbit,
  compression,
  publishStage,
  classnames,
  analyticsCustomId
}

Required Parameters

authToken
The public access token. Instructions for creating tokens found here.

el
The HTML element that will contain the player.

assetId
The UUID of the asset to be loaded. Best practice is to use a Catalog Item's ID. Must be a Catalog Item to leverage advanced buyer analytics

customId
The custom ID of the asset to be loaded. This is set by the user in the platform. This can be used instead of the assetId parameter.

Optional Parameters

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.)

branch (optional)
The branch your embedded asset resides in. If not specified, it will default to main.

cache(optional)
The caching options for the player - an object that has two key:value pairs. Integer for maxAge in milliseconds and String for scope.

showConfigurator (optional)
Determines if we render the configurator.

display (optional)
Override the org's default player type. Can be image or webgl.

configurationId (optional)
Rather than providing an entire configuration object, you can initialize a default configuration based on the configuration's ID or ShortID.

initialConfiguration (optional)
An object setting up an initial configuration.

🚧
initialConfiguration
Be careful using the hasChanged conditional operator in rule logic. hasChanged is only meant to trigger when an attribute is changed, and not to be triggered on load for initialConfiguration.

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. You can provide an object:

{
  enabled: boolean;
  waitToShow: number;
  loadingImage: boolean; // hide dot.gif in 2D player loading. 
  loadingComponent: (progress:number) => ReactComponent; // allow user to render component to replace dot.gif in player. 
}

showLoadingProgress (optional)
Determines if we show the progress bar during load. You can provide additional parameters to this:

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.

publishStage: (optional)
'published' or 'draft'. See below for more information.

classnames: (optional)
Override classnames for player UI component by providing an object:

{
  loading: String, // override css on player loading component.
  mobile: String, // override css on player in moblie view.
  share: String || { button: String, popup: String }, //  override css on share button and share popup. string for share button only.
  fullscreen: String, // override css on fullscreen button.
  ar: String || { button: String, popup: String }, // override css on ar button and ar popup. string for ar button only.
  help: String // override css on help button.
}

analyticsCustomId: (optional)
Custom session ID to populate client_provided_id column in Advanced Buyer Analytics.

Publishing & Cache Keys

Publishing and Draft states are available in Catalog items to control what is accessible externally. Catalog Items are created as Drafts by default and can be Published when they are ready. Publishing automatically updates cache keys.

Set the publishStage embed parameter to draft or published to control what Items are accessible client-side, including sub-items of a Product configurator. If no parameter is set, no restrictions will be enforced.

Player bundle

Please note that you can embed the Threekit player at either of the following URLs:
https://${env}.threekit.com/app/js/threekit-player.js
or
https://${env}.threekit.com/app/js/threekit-player-bundle.js

It is recommended that you use the threekit-player.js script, which will load dependencies as needed. If your system has stricter security requirements and blocks requests from external systems, the bundle may be required.

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",  // you can also use { customId: CUSTOM_ID }
        initialConfiguration: {
         'Attribute Name': {
            assetId: '4a9f7980-78a4-4ace-8cda-f2799936c4dc',
            configuration: { 'key' : 'value'}
          }},
        cache: {
         maxAge: 31536000, //milliseconds
         scope: "v1.0"
        },
        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 preview environment.

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:

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 }.

The 2D Player

The 2D player will be initialized when the embed parameter display is set to image. The Player API and Configurator API are shared between player-types, however, not all of the Player API's Submodules apply to the 2D player.

Compression Parameters

{
    "imageFormat": "string",
    "imageResolution": "string",
    "imageQuality": 100, // number,
    "zoomImageFormat": "string",
    "zoomImageResolution": "string",
    "zoomImageQuality": 100, // number
    "zoomImageLoadingDelay": 10, // number
}

Embedding the Threekit Player in a Mobile App

Introduction

When there is need for increased control over Ul in the mobile environment, one option is to make a native app for the configurator instead of using the browser. The ThreeKit Player can be embedded natively on a mobile app by using a component that supports web content. These components behave like browsers in terms of caching.

Android

WebView
Link Ul elements to the configurator by using the evaluateJavascript function.
Additional documentation on caching and intercepting fetch requests.

iOS

WKWebView
Link Ul elements to the configurator by using the evaluateJavaScript function.

React Native

Install and use the react-native-webview module.
Link Ul elements to the configurator by using the injectJavaScript method (found in link above).