Embedded UI

The KeyShot web user interface can be embedded in other applications for asset selections. This type of integration allows the KeyShot UI to be spawned in other applications for selecting and using KeyShot assets.

This type of integration is typically used for the more manual integration which has a lower throughput. Examples of this could be

• E-mail campaign tools

• Creative tools like Photoshop and InDesign

• Templating tools

Architecture

The Unified DAM Connector can be inserted into any host application as an iframe to easily provide access to assets from your single source of truth

To embed the UI the following URL must be used

https://customer-mediamanager-url/embedded/

Which would spawn the following view

There are two main differences between this view and the standard which are as follows

• The download button is replaced with an insert button

• This view is allowed through CSP to be embedded

Besides the two differences the UI is exactly the same as the standard one and it comes with the full feature set.

Using the embedded view

The embedded view can be used in any application that supports iframing components. To use the embedded view, simply add the following Iframe

<iframe src="https://customer-mediamanager-url/embedded/"></iframe>

This can of course be customized further with standard html.

The important and more complicated thing is to actually use the assets. Whenever a user hits the insert button in the UI, the iframe post a message to the parent in which it is embedded.

The 3 important message types are:

1. DigizuiteInitPostMessage - So you know it is the Digizuite Iframe

2. DigizuiteChangeUrlPostMessage - If the user tries to change URL

3. DigizuiteAssetPostMessage - When a user clicks on asset. When multi-select you receive more.

Defined as follows

export enum MessageType {
  AssetMessage = 'AssetMessage',
  ChangeUrl = 'ChangeUrl',
  SmartPickerInitialized = 'SmartPickerInitialized'
}

export interface DigizuitePostMessage {
  messageType: MessageType;
}

export class DigizuiteInitPostMessage implements DigizuitePostMessage {
  messageType = MessageType.SmartPickerInitialized;
}

export class DigizuiteChangeUrlPostMessage implements DigizuitePostMessage {
  messageType = MessageType.ChangeUrl;
  mmUrl: string;
}

export class DigizuiteAssetPostMessage implements DigizuitePostMessage {
  messageType = MessageType.AssetMessage;
  assets: AssetMessage[];
}

export interface AssetMessage {
  assetId: number;
  assetType: string;
  selectedQualityId: number;
  itemId: number;
  title: string;
  description: string;
  downloadUrl: string;
  thumb: string;
  extension: string;
  lastModifiedTimeInMs: number;
  hashSha1: string;
  isCustomFormat: boolean;
}

Listening to these events are what creates the actual integration.

Most importantly is the AssetMessage which is what is posted on insert. This message contains the following highlighted properties

• assetId- the unique id of the selected asset

• extension - the extension of the source. This is not the extension of the selected insert quality and not the extension of the thumbnail (i.e. It may be a .mp4 having a .webp thumbnail)

• thumb- A thumbnail URL that per default expire after 15 minutes

• selectedQualityId - The ID of the format that is inserted

• downloadUrl - This is the download url of whatever was inserted

• hashSha1 - This is the SHA-1 hash of the source asset. This is again not to be confused with the SHA-1 of whatever is inserted.

Using the above it is possible to download the bytes of whatever was inserted and use that in the integration.

Listening to these events depends on the framework in which the UI is embedded, but the basic Javascript would look like this

window.addEventListener("message", (event) => {
      if (event && event.data && event.data.messageType) {
            .......
      }
}, false);

And an example using Angular

  @HostListener('window:message', ['$event'])
  onMessageReceived(event: any) {
    console.log(`${this.onMessageReceived.name}`, event);

    if (event && event.data && event.data.messageType) {
      const message: DigizuitePostMessage = event.data;
      if (message.messageType === MessageType.SmartPickerInitialized) {
        this.initializeSmartPicker();
      } else if (message.messageType === MessageType.ChangeUrl) {
        const baseUrl = message.mmUrl.endsWith('/') ? message.mmUrl.slice(0, -1) : message.mmUrl;
        this.setNewTempUrl(baseUrl + '/embedded');
      } else if (message.messageType === MessageType.AssetMessage) {
        const asset = message.asset;
        this.assetReceived.emit(asset);
      }
    }
  }