Options
All
  • Public
  • Public/Protected
  • All
Menu

Trimble Connect 3D Viewer - Workspace API

Workspace API Documentation

The Workspace API of Trimble Connect 3D Viewer allows the client applications to interact with the 3D Viewer. It utilizes window.postMessage() to facilitate the communication. There are two methods to utilize the Workspace API:

  • The client application embeds the 3D Viewer in an iframe.
  • The client application is embedded inside the 3D Viewer as a side panel.

Authentication

When the client application embeds the 3D Viewer in an iframe, the valid accessToken should be passed to the 3D Viewer using the accessToken query parameter. Optionally the refreshToken query parameter can also be passed. In this case, the accessToken refresh responsibility is passed to the 3D Viewer. Keep in mind that the accessToken refresh responsibility cannot be shared between the client application and 3D Viewer, only one application should perform the refresh. If the accessToken is refreshed by 3D Viewer, 3D Viewer will emit an extension.accessToken event with the new accessToken. If the refreshToken is not passed to the 3D Viewer, it is the client application's responsibility to handle the accessToken refresh. 3D Viewer will help in the process by emitting the extension.sessionInvalid event when the accessToken expired or was invalidated. After the accessToken is refreshed by the client application, it can be passed back to the 3D Viewer by calling the viewer.setAccessTokens API with the new accessToken.

When the client application is embedded inside the 3D Viewer, the accessToken should be retrieved from 3D Viewer by calling the extension.requestPermission API. This call will initially display a message requesting for the user consent for the client application to use the accessToken. If the user consents, the call will return the accessToken which can then be used by the client application. In this case, the 3D Viewer application will handle the tokens, including the tokens refresh. When the accessToken is refreshed, the 3D Viewer will emit an extension.accessToken event with the new accessToken.

Quick Start

  1. Add the component as a dependency to your project:

    npm i workspace-api --save

For ES6-module-friendly consumers, you can import the modules directly, or import them from the root module. It is also possible to directly import the IIFE module from the URL of the 3D Viewer application.

<script src="https://3d.connect.trimble.com/trimbleconnect.workspace.api.js" />

  1. Put together the 3D Viewer and the client application:

    Page structure

    • Embed the 3D Viewer inside the application using an iframe

      <iframe
        src="https://3d.connect.trimble.com/?accessToken=[...]&refreshToken=[...]"
        id="viewer"
        sandbox="allow-scripts allow-modals allow-forms allow-same-origin"
        width="100%"
        height="700px" />
    • Embed the application inside the 3D Viewer

      Pass the (comma-separated) URL(s) of the client application(s) via a GET parameter to the 3D Viewer. The client applications will be displayed as a tab page on the left side panel. The following parameters are supported:

      • extensionmanifest: A comma-separated list of client application manifests. The data structure of the manifest file should be the JSON representation of the ExtensionSetting interface
      • extension: A comma-separated list of client application URLs. Each extension URL will be embedded in an iframe, which is displayed in a separate tab page
      • extensionicon: A comma-separated list of icon URLs (which will be used as the icon for the extension tab page)
      • extensiontitle: A comma-separated list of extension titles (which will be used as the tooltip for the tab page)

      Each extension tab page will use the icon and title with the same index. Thus, if extensionicon and/or extensiontitle is defined, the number of the comma-separated parameters must equal to the number of the comma-separated extension URLs defined in extension parameter. For instance:

      https://3d.connect.trimble.com/?extension=extension1Url,extension2Url&extensionicon=icon1Url,icon2Url&extensiontitle=title1,title2

      • Extension with URL extension1Url will have the icon1Url and title title1
      • Extension with URL extension2Url will have the icon2Url and title title2
  2. Initiates the connection between the client application and 3D Viewer

    • Embed the 3D Viewer inside the application using an iframe: This should be done after the iframe has been loaded. The connection initiation should be done in an async function as the connection is only established once the user has selected a Trimble Connect project in the 3D Viewer.

      viewer.onload = async function () {
      var API = await Workspace.connect(viewer, (event, data) => {
          console.log("Event: ", event, data);
        };
      • In order to automatically select certain project/model after Trimble Connect 3D Viewer application has started, the model ID (and model ID) could be passed as parameters in the URL
        • https://<3D Viewer URL>/?*projectId=MyProjectId*

        • https://<3D Viewer URL>/?*projectId=MyProjectId&modelId=ModelId1,ModelId2*

    • Embed the application inside the 3D Viewer: Directly issue the connect request to the parent window (3D Viewer) that is hosting the application:

      var API = await Workspace.connect(window.parent, (event, data) => {
      console.log("Event: ", event, data);
      });
  1. All the APIs will be exposed through the return value of connect method.

The workflow of the Workspace API can be illustrated as below:

Workspace API Workflow

Usage with TypeScript

The Trimble Connect 3D Viewer - Workspace API bundles TypeScript v2 definition files for use in TypeScript projects and to support tools that can read .d.ts files.

Examples

Check out the example client application for more details!

Configuration from 3D Viewer

It is possible to configure extensions that are used for each Connect Project via 3D Viewer Extensions Settings. Basically, it is possible to define a new extension manually or through an extension definition (a manifest)

  • Manually: Specify all extension parameters manually
    • Click on Advanced text button
    • Specify the extension title, extension URL (and other metadata)
  • Extension URL: The URL to the extension manifest file, which is a JSON file that specifies all extension parameters (e.g. Extension title, Extension URL...). The data structure follows the ExtensionSetting interface. For example:
      {
          "url": "https://my.awesome.app/extension",
          "title": "This is my extension",
          "infoUrl": "https://my.awesome.app/extension/help.html"
      }