Embed a Component

This guide provides directions on how to build a Trimble Connect embedded component leveraging the Workspace API.

Implement the login flow

Integrating a Trimble Connect component into your product requires configuring Trimble ID login. An access token will get generated when you log in using your Trimble ID. Your product will pass the access token to the Trimble Connect component. After the Trimble Connect component receives the access token, it will get embedded into your product.

Initialize the Workspace API

After embedding the Trimble Connect component into your application, you need to initialize the workspace API. When you initialize, a communication channel will be created between your product and the Trimble Connect component. Your product will also create a function that defines the action that needs to be performed for each event Trimble Connect creates.

When your product calls an API, Trimble Connect will respond by creating promises or events. Some API calls may not trigger an event. When your product receives an event, the corresponding action will be carried out.

Pass authentication to the component

When you embed a Connect component in an iframe, the valid accessToken must be passed to the component using embed.setTokens. Your product needs to refresh the accessToken whenever needed. If the access token expires or when the session becomes invalid, the Trimble Connect component will pass the extension.sessionInvalid event.

Your product should refresh the access token and send it to the Trimble Connect component using the embed.setTokens API.

Initialize the specific component

After passing the access token to the Trimble Connect component, your product needs to initialize the component by calling the respective API. For example, if you are embedding the 3D viewer, you need to use the following API:

API.embed.init3DViewer({projectId: "projectId_here"})

By setting parameters such as project ID, model IDs, and view ID within this call, you can load specific project data directly, thereby bypassing manual project and model selection. If these properties are omitted, the application will default to displaying a project selector to the user.

Interact with the content

When you embed a Trimble Connect component into your product, you can use the Workspace API methods to interact with components and can also program your product to respond to events triggered by the component.

See Create an Embedded Component for more information.