Embedded apps & UI

Integration flow

Third-party applications are embedded in MuseDAM through an iframe. Register the app, obtain MuseDAM_APP_ID and MuseDAM_APP_SECRET, and provide an /auth/${token} route.

1. MuseDAM generates a token and sends the user to the embedded app route.
2. The app backend decrypts and validates the token, including user, team, and expiresAt.
3. Map the MuseDAM user and team to your accounts and create an app session.
4. Use postMessage in the frontend to open asset, folder, and member selectors.

The source documentation does not fully specify the encryption algorithm or IV constants. Obtain the complete authentication implementation from MuseDAM. Keep the app secret on the backend; decoding a token alone does not validate it.

Embedding and messaging

Configure CSP frame-ancestors to allow your actual MuseDAM domain and ensure X-Frame-Options does not conflict. Use the exact parent window origin for postMessage. Validate event.origin, event.source, source, target, type, and dispatchId on received messages.

Open the Mainland China production component test page (login required)

Message protocol

Basic message structure

Third-party app → MuseDAM (request)

{
    source: "musedam-app",        // Child app identifier
    target: "musedam",            // Parent window identifier
    type: "action",               // Request type
    timestamp: "2024-12-19T10:30:00.000Z", // ISO timestamp
    dispatchId: "dispatch_1234567890_abc123", // Unique request ID
    action: "folder-selector-modal-open",    // Action type
    args: { /* Request parameters */ }
}

MuseDAM → Third-party app (response)

{
    source: "musedam",            // Parent window identifier
    target: "musedam-app",        // Child app identifier
    type: "action_result",        // Response type
    timestamp: "2024-12-19T10:30:01.000Z", // ISO timestamp
    dispatchId: "dispatch_1234567890_abc123", // Matching request ID
    action: "folder-selector-modal-open",     // Matching request action
    args: { /* Original request parameters */ },
    result: {                     // Response result
        success: true,
        data: { /* Result data */ }
    }
}

Fields

Error codes

When result.success is false, result.code may be:

Supported actions

Request and response types

IAssetLite fields

Folder selector

• action: folder-selector-modal-open

• args type:

  typescriptCopy

  {
      initialSelectedFolders?: Array<{ id: number; name: string }>;
      // Whether to show all assets
      allMaterials?: boolean;
  }

• result.data type:

  typescriptCopy

  {
      selectedFolders: Array<{ id: number; name: string }>;
      allMaterials: boolean;
  }

• Example:

  typescriptCopy

  // Request
  {
      action: "folder-selector-modal-open",
      args: {
          initialSelectedFolders: [{ id: 123, name: 'Design assets' }],
          allMaterials: false
      }
  }
  
  // Successful response
  {
      result: {
          success: true,
          data: {
              selectedFolders: [
                  { id: 123, name: 'Design assets' },
                  { id: 456, name: 'Product images' }
              ],
              allMaterials: false
          }
      }
  }
  
  // Cancellation response
  {
      result: {
          success: false,
          code: "cancelled",
          message: "Operation canceled by user"
      }
  }

Member and department selector

• action: member-selector-modal-open

• args type:

  typescriptCopy

  {
      selectedItems?: {
          members?: Array<{ id: string; name: string }>;
          departments?: Array<{ id: string; name: string }>;
          groups?: Array<{ id: string; name: string }>;
      };
  }

• result.data type:

  typescriptCopy

  {
      members: Array<{ id: string; name: string;departmentsName?:string;avatarUrl?:string }>;
      departments: Array<{ id: string; name: string }>;
      groups: Array<{ id: string; name: string }>;
  }

• Example:

  typescriptCopy

  // Request
  {
      action: "member-selector-modal-open",
      args: {
          // Selected items
          selectedItems: {
              members: [{ id: "user_123", name: "Alex", departmentsName:"Muse, Design", avatarUrl:"https://"}],
              departments: [{ id: "dept_001", name: "Design" }]
          }
      }
  }
  
  // Successful response
  {
      result: {
          success: true,
          data: {
              members: [
                  { id: "user_123", name: "Alex" },
                  { id: "user_456", name: "Sam" }
              ],
              departments: [{ id: "dept_001", name: "Design" }],
              groups: []
          }
      }
  }
  
  // Cancellation response
  {
      result: {
          success: false,
          code: "cancelled",
          message: "Operation canceled by user"
      }
  }

Asset selector

• action: assets-selector-modal-open

• args type:

  typescriptCopy

  enum EAssetType {
      image = 'image',           // Images
      video = 'video',           // Videos
      audio = 'audio',           // Audio
      js = 'js',                 // Design source files
      document = 'document',     // Text documents
      PDocument = 'PDocument',   // Presentations
      excel = 'excel',           // Spreadsheets
      font = 'font',             // Fonts
      zip = 'zip',               // Archives
      dll = 'dll',               // Applications
      code = 'code',             // Code
      model = 'model',           // Models
      triD = 'triD',             // 3D
      url = 'url',               // Webpages
      unknown = 'unknown',       // Unknown files
  }
  {
    initialSelectedAssetIds?: number[];
    /**
     * Allowed asset types. Omit to allow all types.
     * Values follow the asset type field: image, video, audio, js, document, PDocument, excel, font, zip, dll, code, model, triD, url.
     */
    allowedTypes?: EAssetType[];
    /**
     * Per-type quantity limits. When provided, only listed types are selectable; omit limit for unlimited items of that type.
     * When used with allowedTypes, allowedTypes is the allowlist and dataLimit only adds quantity limits.
     */
    dataLimit?: Array<{
      type: EAssetType;
      limit?: number;
    }>;
    /**
     * Initial list filters, matching the homepage filter bar. Users can still change filters in the selector.
     */
    filters?: {
      types?: EAssetType[];
      extensions?: string[];
      size?: {
        min?: number;
        max?: number;
        unit?: 'KB' | 'MB' | 'GB';
      };
      dimension?: {
        minWidth?: number;
        maxWidth?: number;
        minHeight?: number;
        maxHeight?: number;
      };
    };
  }

• result.data type:

  typescriptCopy

  
  {
      selectedAssets: IAssetLite[];
  }

• Example:

  typescriptCopy

  // Request
  {
      action: "assets-selector-modal-open",
      args: {
          initialSelectedAssetIds: [123, 456],
          allowedTypes: ['image'],
          filters: {
              types: ['image'],
              size: { min: 100, max: 10240, unit: 'KB' },
              dimension: { minWidth: 512, minHeight: 512 },
          },
      }
  }
  
  // Successful response
  {
      result: {
          success: true,
          data: {
              selectedAssets: [
                  { id: 123, name: 'logo.png', type: 'image' },
                  { id: 456, name: 'banner.png', type: 'image' }
              ]
          }
      }
  }
  
  // Cancellation response
  {
      result: {
          success: false,
          code: "cancelled",
          message: "Operation canceled by user"
      }
  }

Navigate to a page

• action: goto

• args type:

  typescriptCopy

  {
    url: string;
  }

• Description: The parent app navigates when it receives this message. No response is required.

• Example:

  typescriptCopy

  // Request
  {
      action: "goto",
      args: {
          url: "https://example.com/target-page",
          target:"_blank"
      }
  }

Synchronize paths

• action: syncPath

• args type:

  typescriptCopy

  {
    path: string;
  }

• Description: The parent app updates the current page's hash path. No response is required. This synchronizes iframe routing state with the parent window URL.

• Example:

  typescriptCopy

  // Request
  {
      action: "syncPath",
      args: {
          path: "#path=/tagging/settings"
      }
  }