How the Asset Picker integration works
The CMP Asset Picker is a component you embed in a third-party application so its users can browse and select assets from the Storyteq CMP DAM without leaving that application. This page explains how the Asset Picker is embedded, how it determines which assets a user sees, and how selected assets are returned to the host application. It is intended for integrators and developers.
How the Asset Picker is embedded
You can embed the Asset Picker in either of two ways.
-
As a web component: load a script and place an
<asset-picker>element in your page. The Asset Picker renders inline as a custom HTML element, and you configure it through element attributes. -
As an iframe: point an iframe at the hosted Asset Picker URL and pass configuration as URL parameters.
The web component suits applications where you control the page markup and want the Asset Picker to render as part of your own DOM. The iframe suits applications that embed external content in a frame, including plugin platforms built on browser-like technology.
For the attributes, parameters, and host URLs that each method accepts, see Asset Picker parameters reference.
How internal and external integrations work
The Asset Picker operates in one of two modes, depending on how it is configured. The mode determines which assets a user sees, which CMP API the Asset Picker calls, how the user is authenticated, and how failures are reported.
Internal integrations
In an internal integration, the host application supplies authentication and identifies a fixed collection of assets in advance. The collection is defined by a Lens: a managed asset view configured in Luma Admin by a user with the appropriate privileges. When the Asset Picker opens, the host application passes the lens ID, domain, domain ID, and API key, and the Asset Picker requests assets from the internal Luma endpoints.
The user does not sign in. They see exactly the assets contained in the configured lens. CA is an example of an internal integration.
If an asset is not available, an internal integration shows an error notification and marks the affected asset, so the user knows it was not added to their work.
External integrations
In an external integration, the assets a user sees are determined by their own CMP account rather than by a preconfigured lens. The user signs in with their company credentials, and the Asset Picker displays the assets they are authorised to see in CMP. External integrations call the Luma v2 endpoints, selected through the API integration setting. Figma and Jira are examples of external integrations.
External integrations authenticate users through the Identity Broker, which routes each user to their organisation’s identity provider, including single sign-on. The integration never handles the user’s credentials directly. For the sign-in flow from the user’s perspective, see Sign in to the CMP Asset Picker. For how authentication works, see Authentication in external integrations.
Unlike an internal integration, an external integration cannot report success or failure until the third-party application has processed the returned assets. Once the third party responds, the Asset Picker shows which assets succeeded and which failed. The Asset Picker window stays open so the user can review any failures, while assets that succeeded are already added.
How selected assets are returned
When a user confirms their selection, the Asset Picker returns the chosen assets to the host application, which handles them in one of two ways.
Some integrations insert a copy of each asset into the host application, so the asset becomes part of that document. Figma and Jira work this way.
Other integrations reference each asset by its URL in CMP rather than storing a copy. For this, the Asset Picker uses the existing public URL functionality in CMP, so referenced assets do not expire. Integrations that authenticate with a service account are subject to a separate link validity period.