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:

{
  allowMobileVerticalOrbit,
  analyticsCustomId,
  assetId,
  authToken,
  branch,
  cache,
  classnames,
  compression,
  configuration,
  configurationId,
  connectorSnappingDistance,
  customId,
  display,
  el,
  enabled,
  imageFitMode,
  initialConfiguration,
  loadingComponent,
  loadingImage,
  locale,
  onAnnotationChange,
  onLoadingProgress,
  placeholder,
  pricing,
  publishStage,
  showAR,
  showConfigurator,
  showLoadingProgress,
  showLoadingThumbnail,
  showShare,
  stageConfiguration,
  stageId,
  tools,
  waitToShow
}

Required Parameters

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

authToken

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

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.

el

The HTML element that will contain the player.

Optional Parameters

allowMobileVerticalOrbit: boolean

Parameter toggles vertical orbit on mobile devices, default value is false.

analyticsCustomId: string

Custom session ID to populate client_provided_id column in Advanced Buyer Analytics.

branch: string

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

cache: { maxAge: integer, scope: string } - Deprecated

Manual override for the caching options for the player - an object that has two key:value pairs. Integer for maxAge in milliseconds and String for scope. Not recommended for use anymore. Instead use the cache scope generated by the Publish feature as outlined below.

classnames

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

compression

This is intended to override the compression settings used by the the 2D player, found under Org Settings -> Performance.

As value it expects an object of the following type:

type CompressionSettings = {
    //Basic Image Compression Settings
    imageFormat?: string;
    imageResolution?: string;
    imageQuality?: number;
    //Refined and Zoom Image Settings
    zoomImageFormat?: string;
    zoomImageResolution?: string;
    zoomImageQuality?: number;
    zoomImageLoadingDelay?: number;
}

configuration

Load the item/asset with the specific configuration listed here. Pass a Configuration Object as defined in the Configurator API.

configurationId: string

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

connectorSnappingDistance: number

This is an override for the connector snapping distance found in the Org Settings -> Player Settings. It expects a number that represents the on-screen pixel distance for snapping.

display: 'webgl' | 'image'

Override the org's default player type. Can be image for the 2D player or webgl for the 3D player. This is used only by the main player bundle. The 2D specific player bundle will always display the 2D player.

imageFitMode: 'fitWidth' | 'fitHeight' | 'cover' | 'contain'

Set the 2D Player Image Fill option to one of the four listed values. This controls how the images served by the 2D player will fill the player embed area.

initialConfiguration

An object setting up an initial configuration.

🚧

Warning!

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.

locale

Parameter determines the language of the embed

onAnnotationChange: ( annotations: AnnotationType[], parentElement?: HTMLElement ) => void;

Callback to override the HTML of the annotations, if custom annotations are desired.

onLoadingProgress

Callback to receive loading progress information.

placeholder: URL

Specify a URL to a placeholder image to display while the player is loading.

pricing: boolean

Enable or disable the use of the pricing feature.

publishStage: 'published' | 'draft'

Embedding the player with either Published or Draft Items. Also tells the player whether to serve cached assets or not.
By default it will set its value to the publish state of the initialized asset. If the asset is Published, then publishStage: 'published'. If the initialized asset is Draft, then publishStage: 'draft'.

See below for more information.

showAR

Parameter to show/hide the built-in AR Button, default value is false.

showConfigurator

Determines if we render the configurator.

showLoadingProgress

Determines if we show the progress bar during load. You can provide additional parameters to this.

showLoadingThumbnail

Parameter to display a snapshot while the player is loading, default value is false. You can provide an object:

type LoadingThumbnail = {
  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. 
}

showShare: boolean

Parameter to show/hide the built-in Share Button, default value is false

stageConfiguration

Load the stage with the specific configuration listed here. Pass a Configuration Object as defined in the Configurator API.

stageId: string

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

tools: string[]

Set the available player tools. See the Tools documentation for more information.

Caching & Publishing

The Publish state of Catalog items is used to control both what is accessible on the front-end as well as the individual cache scope. Catalog Items are created as Drafts by default and can be Published when they are ready.

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.

In addition to controlling the visibility of options to the front-end, the act of publishing an item will also create a cache scope for that item (keyed by the publish timestamp). This cache scope can then be used by the CDNs serving the assets to store a cached version of the item and its referenced assets when they are first requested.

👍

Caching Enabled

The cache scope (key) of items generated by the publish feature can only be used when the player is embedded in one of the following two ways:

1. With the publishStage: 'published' parameter
2. When initializing the player with a published item without specifying the publishStage embed parameter (by default the publishStage parameter inherits its value from the publish state of the initialized item).

Initializing the player with publishStage: 'published' and a Draft item will result in an error.

❗️

Caching Disabled

The use of Draft items with the publishStage: 'draft' will mean that caching is disabled altogether, unless you are using the deprecated cache embed parameter.

Cache override

The cache embed parameter acts as a manual override of the individual cache scope generated by the Publish feature. Thus, if the cache parameter is set on the player embed, it will create new cache scope independent of the published cache scope. This is an old method that is now deprecated and not recommended anymore. Only use the publishStage parameter to enable caching as explained above.

Using both the cache parameter as well as publishStage: 'published' will have the scope generated by the cache parameter overriding the scope set by the publish timestamp.

Player Bundles

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

This bundle is used for both the 3D and the 2D player. Only use this one for the 2D player in case you need to embed both the 3D and the 2D player on the same page.

📘

Tip:

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 threekit-player-bundle.js 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'}
          }},
        publishStage: 'published',
        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.

Optimized 2D Player Bundle

Use the following bundle if you need to embed only the 2D player on a page.

This is an optimized version of the player bundle, which will load faster on initial load.

https://${env}.threekit.com/app/js/threekit-player-2d.js

📘

Important!

The 2D-only player needs to be initialized using window.threekitPlayer2D, instead of window.threekitPlayer as the regular bundle.

Preloading the Player

We recommend that you preload the player bundle ahead of time whenever possible.

For example, if you are using a PLP (Product Listing Page) prior to the user accessing the individual PDPs (Product Display Pages), then you could preload the player bundle on the PDP page after everything else has been loaded on that page. This allows the user to access the PDP pages with the player bundle already cached, making the player loading experience even faster.

This can be accomplished using the rel="prefetch" option on <link> elements as documented here.

In addition to that, we add importance="low" in order to delay the download until after the rest of the page has completed loading, in order to minimize the impact on the PLP load.

Example

<head>
    <!-- Other head elements -->
    <link rel="prefetch" href="https://preview.threekit.com/app/js/threekit-player.js" as="script" importance="low">
</head>

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.

The 2D Player can be used with either the main player bundle or the optimized 2D only bundle.

Compression Settings

You can set the compression parameter in your Threekit embed with an object containing the following parameters, which will overwrite the your org's default settings.

{
  //Basic Image Settings
    "imageFormat": "String",
    "imageResolution": "String",
    "imageQuality": 100, // 0-100,
  //Refined and Zoom Image Settings
    "zoomImageFormat": "String",
    "zoomImageResolution": "String",
    "zoomImageQuality": 100, // 0-100
    "zoomImageLoadingDelay": 10, // seconds
}

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

Avoid the following

Editing the player HTML content

Once the threekit player is embedded, it will generate its own html content within the parent div element. Please refrain from targeting this content for direct editing.

Example output:

Embedding Multiple Players

Avoid trying to embed multiple players, especially when it comes to using the same item assetId. This will likely cause several issues, both in terms of performance and functionality.