addOnUISdk.app

Provides access to the Adobe Express host application's objects and methods to provide features such as content import and export through the document object, OAuth 2.0 authorization flows with the oauth object, theme and locale detection with the ui object, current logged in user info and more. It also provides access to methods to show modal dialogs, enable drag and drop of content and subscribe and unsubscribe to events.

Objects

Attribute	Name	Type	Description
readonly	currentUser	object	Represents the current user accessing the host application
	devFlags	object	Represents flags which can be used to simulate certain behavior during development.
readonly	document	object	Represents the active document of the host application.
readonly	oauth	object	Provides access to the OAuth methods needed to implement OAuth 2.0 for user authorization.
readonly	ui	object	Represents the host UI (Adobe Express UI).

Methods

on()

Subscribe to an event (ie: listen for an event).

Signature

on(name: string, handler: eventHandler): void

Parameters

Name	Type	Description	Valid Values
`name`	`string`	Event to subscribe to.	See Events
`handler`	callback `function`	Handler that gets invoked when the event is triggered.	`(data) => {}`

Return Value

void

Example Usage

addOnUISdk.app.on("themechange", (data) => {
  applyTheme(data.theme);
});
Copied to your clipboard
addOnUISdk.app.on("themechange", (data) => {
  applyTheme(data.theme);
});

off()

Unsubscribe from an event (ie: stop listening for an event).

Signature

off(name: string, handler: eventHandler): void

Parameters

Name	Type	Description	Valid Values
`name`	`string`	Event to unsubscribe to.	See Events
`handler`	callback `function`	Handler that was used during event subscription.	`(data) => {}`

Return Value

void

Example Usage

addOnUISdk.app.off("themechange", (data) => {
  applyTheme(data.theme);
});
Copied to your clipboard
addOnUISdk.app.off("themechange", (data) => {
  applyTheme(data.theme);
});

startPremiumUpgradeIfFreeUser()

Displays the in-app monetization upgrade flow.

Signature

startPremiumUpgradeIfFreeUser(): Promise<boolean>

Return Value

Returns a resolved Promise with a value of true if the user is premium or completed the flow, and false if the user is a free user and cancelled the upgrade.

Example Usage

import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";
 
addOnUISdk.ready.then(async () => {
  const isPremiumUser = await addOnUISdk.app.startPremiumUpgradeIfFreeUser();
  if (!isPremiumUser) {
    // User did not upgrade, show error dialog
  }
});
Copied to your clipboard
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";
 
addOnUISdk.ready.then(async () => {
  const isPremiumUser = await addOnUISdk.app.startPremiumUpgradeIfFreeUser();
  if (!isPremiumUser) {
    // User did not upgrade, show error dialog
  }
});

showModalDialog()

Shows a modal dialog based on specific options passed in.

Signature

showModalDialog(dialogOptions: DialogOptions): Promise<DialogResult>

Parameters

Name	Type	Description
`dialogOptions`	`object`	`DialogOptions` object payload

`DialogOptions`

Name	Type	Description
`variant`	`string` Variant	The type of dialog to show.
`title`	`string`	Dialog title
`description`	`string`	Description for the dialog.
`buttonLabels?`	`object` ButtonLabels	The optional button labels to use in the dialog.

`ButtonLabels`

Name	Type	Description
`primary?`	`string`	Primary action label. Default label is "OK".
`secondary?`	`string`	Secondary action label.
`cancel?`	`string`	Cancel action label.

The input dialog variant accepts an additional field object.

Input Dialog Additional Option

Name	Type	Description
`field`	object `Field`	Input field object

`Field`

Name	Type	Description
`label`	`string`	Label for the input field
`placeholder`	`string`	Specifies a short hint that describes the expected value of the field
`fieldType`	`string`	Currently always the value "text".

Return Value

Returns a Promise DialogResult object with the button type that was clicked, or an error. When using the "input" dialog variant, an additional fieldValue property will be in the response object and will contain the value of the field the user input text to.

`DialogResult`

Name	Type	Description
`buttonType`	`string` `ButtonType` constant	The button type clicked
`fieldValue`	`string`	The input from the user.

Confirmation Dialog Example Usage

import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";
 
// Wait for the SDK to be ready
await addOnUISdk.ready;

async function showConfirmDialog() {
    try {
        // Confirmation Dialog Example
        let dialogOptions = {
            variant: "confirmation",
            title: "Enable smart Filters",
            description: "Smart filters are nondestructive and will preserve your original images.",
            buttonLabels: { primary: "Enable", cancel: "Cancel" },
        };    
        const result = await addOnUISdk.app.showModalDialog(dialogOptions);
        console.log("Button type clicked " + result.buttonType); 
    } catch (error) {
        console.log("Error showing modal dialog:", error);
    }
}
Copied to your clipboard
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";
 
// Wait for the SDK to be ready
await addOnUISdk.ready;

async function showConfirmDialog() {
    try {
        // Confirmation Dialog Example
        let dialogOptions = {
            variant: "confirmation",
            title: "Enable smart Filters",
            description: "Smart filters are nondestructive and will preserve your original images.",
            buttonLabels: { primary: "Enable", cancel: "Cancel" },
        };    
        const result = await addOnUISdk.app.showModalDialog(dialogOptions);
        console.log("Button type clicked " + result.buttonType); 
    } catch (error) {
        console.log("Error showing modal dialog:", error);
    }
}

Input Dialog Example Usage

import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";
 
// Wait for the SDK to be ready
await addOnUISdk.ready;

async function showInputDialog() {
    try {
        // Input Dialog Example
        let inputDialogOptions = {
            variant: "input",
            title: "Please enter your key",
            description: "Your API key",
            buttonLabels: { cancel: "Cancel" },      
            field: {
                label: "API Key",
                placeholder: "Enter API key",    
                fieldType: "text",
            },
        }

        const inputDialogResult = await addOnUISdk.app.showModalDialog(inputDialogOptions);
        if (inputDialogResult.buttonType === "primary") {
            console.log("Field value " + inputDialogResult.fieldValue); // returns the input the user entered if they didn't cancel
        }
    } catch (error) {
        console.log("Error showing modal dialog:", error);
    }
}
Copied to your clipboard
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";
 
// Wait for the SDK to be ready
await addOnUISdk.ready;

async function showInputDialog() {
    try {
        // Input Dialog Example
        let inputDialogOptions = {
            variant: "input",
            title: "Please enter your key",
            description: "Your API key",
            buttonLabels: { cancel: "Cancel" },      
            field: {
                label: "API Key",
                placeholder: "Enter API key",    
                fieldType: "text",
            },
        }

        const inputDialogResult = await addOnUISdk.app.showModalDialog(inputDialogOptions);
        if (inputDialogResult.buttonType === "primary") {
            console.log("Field value " + inputDialogResult.fieldValue); // returns the input the user entered if they didn't cancel
        }
    } catch (error) {
        console.log("Error showing modal dialog:", error);
    }
}

See the use case implementations for an example of the custom modal dialog.

registerIframe()

Allows an iframe hosted within an add-on to register its intent to communicate with the add-on SDK. While iframes can be used for embedding media without SDK interaction, registerIframe() is needed for those requiring SDK capabilities. It marks a transition to a more controlled approach, where add-ons must explicitly opt-in to this level of integration.

IMPORTANT: This method is currently experimental only and should not be used in any add-ons you will be distributing until it has been declared stable. To use this method, you will first need to set the experimentalApis flag to true in the requirements section of the manifest.json.

Signature

registerIframe(element: HTMLIFrameElement): [UnregisterIframe]()

Parameters

Name	Type	Description
`element`	`HTMLIFrameElement`	The iframe to register.

Return Value

UnregisterIframe

`UnregisterIframe` Type Definition

Callback function that unregisters the previously registered iframe, ceasing its direct communication with the add-on SDK. Returns void.

type UnregisterIframe = () => void;
Copied to your clipboard
type UnregisterIframe = () => void;

Example Usage

import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";
 
function RegisterIframe(elementId: string) {
  const iframe = document.getElementById(elementId);
  try {
    unregisterIframe = addOnUISdk.app.registerIframe(iframe);
  }
  catch(error) {
    console.log("Failed to register iframe with the SDK:", error);
  }
}
 
addOnUISdk.ready.then(() => {
  let unregisterIframe: UnregisterIframe = RegisterIframe("iframe1");
  // ...
  unregisterIframe();
  unregisterIframe = RegisterIframe("iframe2");
  // ...
  unregisterIframe();
});
Copied to your clipboard
import addOnUISdk from "https://new.express.adobe.com/static/add-on-sdk/sdk.js";
 
function RegisterIframe(elementId: string) {
  const iframe = document.getElementById(elementId);
  try {
    unregisterIframe = addOnUISdk.app.registerIframe(iframe);
  }
  catch(error) {
    console.log("Failed to register iframe with the SDK:", error);
  }
}
 
addOnUISdk.ready.then(() => {
  let unregisterIframe: UnregisterIframe = RegisterIframe("iframe1");
  // ...
  unregisterIframe();
  unregisterIframe = RegisterIframe("iframe2");
  // ...
  unregisterIframe();
});

enableDragToDocument()

Allows for drag and document functionality to be enabled on an element such as an image, video or audio.

IMPORTANT: If the content being dragged is an animated GIF, it will be added as an animated GIF to the document, as long as it fits the size criteria for animated GIF's. In the event that it doesn't fit the size criteria, an error toast will be shown to the user.

Signature

enableDragToDocument(element: HTMLElement, dragCallbacks: DragCallbacks): [DisableDragToDocument]()

Parameters

Name	Type	Description
`element`	`HTMLElement`	The element to enable for drag and drop.
`dragCallbacks`	dragCallbacks	An object containing a preview and completion callback

`dragCallbacks`

Name	Type	Description
`previewCallback`	`DragPreviewCallback`	Callback to provide the preview image
`completionCallback`	`DragCompletionCallback`	Callback to provide the content to be added to the document

`DragPreviewCallback` Type Definition

Callback used to get the preview image for the drag & drop action. Returns a URL object.

type DragPreviewCallback = (element: HTMLElement) => URL;
Copied to your clipboard
type DragPreviewCallback = (element: HTMLElement) => URL;

`DragCompletionCallback` Type Definition

Callback to provide the content (image/gif/video/audio) to be added to the document post drag & drop action. Returns DragCompletionData array.

type DragCompletionCallback = (element: HTMLElement) => Promise<DragCompletionData[]>;
Copied to your clipboard
type DragCompletionCallback = (element: HTMLElement) => Promise<DragCompletionData[]>;

`DragCompletionData`

Returned as part of an array from the DragCompletionCallback, and contains the blob object to be added, as well as a MediaAttributes object with the title of the audio content (for audio only).

Name	Type	Description
`blob`	`Blob`	Blob (image/video/audio) to be added to the document
`attributes?`	`MediaAttributes`	Attributes to pass when adding the audio to the page (ie: `title`, which is mandatory).

`MediaAttributes`

Required for audio content only.

Name	Type	Description
`title`	`string`	Media title (mandatory for audio import).

Return Value

DisableDragToDocument

`DisableDragToDocument` Type Definition

Callback to undo the changes made by enableDragToDocument. Returns void.

type DisableDragToDocument = () => void;
Copied to your clipboard
type DisableDragToDocument = () => void;

`DragStartEventData` Object

The payload data sent to the dragStart event handler.

Properties

Name	Type	Description
`element`	`HTMLElement`	Element for which the drag event started

`DragEndEventData`

The payload data sent to the App dragEnd event handler.

Name	Type	Description
`element`	`HTMLElement`	Element for which the drag event ended
`dropCancelled`	`boolean`	If drop occurred/drag ended at invalid position
`dropCancelReason?`	`string`	Reason for drop cancellation

* Important Event Handling Notes

Since the addOnUISdk uses pointer event handlers to perform drag operations, you should ensure that you don't attach any pointer event handlers that prevent default or stop propagation. Adding those types of handlers will kill the built-in handlers and cause the events not to work.
You should not attach click event listeners to drag-enabled elements in the capture phase, as the addOnUISdk attaches a cancelClickEvent handler to drag-enabled elements to ensure that the automatic click (pointer down + pointer up automatically fires a click event) doesn't fire. Adding other handlers to this same element will cause them to be triggered on drag & drop completion.
TIP: Use Chrome devTools to check the handlers attached to the element and its ancestors to identify any which may be causing conflicts with drag and drop handlers.

See the Drag & Drop use case implementation for example usage, and the code samples provided for reference.

Events

The table below describes the events triggered from the add-on SDK. Use the addOnUISdk.app.on() method to subscribe to events, and the addOnUISdk.app.off() method to unsubscribe from them. See the on() method reference for more details.

Type	Description
localechange	string	Triggered when there is a locale change at the host side.
themechange	string	Triggered when there is a theme change at the host side.
dragstart	string	Triggered when the user starts dragging an item for which drag behavior is enabled.
dragend	string	Triggered when the drag operation ends.
documentIdAvailable	string	Triggered when the document id is available in the application.
documentTitleChange	string	Triggered when the document title is changed in the application.

Errors

The table below describes the possible error messages that may occur when using the core addOnUISdk.app methods, with a description of the scenario that will return them.

Error Message	Error Scenario
Incorrect type: element must of type `HTMLElement`	Element passed to `enableDragToDocument` is not an instance of `HTMLElement`.
Incorrect return type: `PreviewCallback` must return an object of type `URL`	`previewCallback` function doesn't return URL.
Incorrect return type: `CompletionCallback` should return an array of `DragCompletionData`	`completionCallback` doesn't return `DragCompletionData[]`.
Dialog already open with instanceID: `${this._instanceId}`	Dialog is already open.
Dialog options parameter: title is undefined	Title is undefined.
Dialog options parameter: description is undefined	Description is undefined.
Dialog options parameter: variant is undefined	Variant is undefined.
Invalid dialog variant: `${variant}`	Invalid dialog variant.
Input dialog field is undefined	Text field property is undefined for input variant.
Field property is valid only for input dialog	If text field property is present for variant other than input.
Input dialog field label is undefined	Field label is undefined for input dialog variant.
Invalid dialog field type: `${field.fieldType}`	Field type is invalid for input dialog variant.
Dialog already open with instanceID:`${this._instanceId}`	If the dialog is already open.
Dialog options parameter: title is undefined	Title is undefined.
Dialog options parameter: src is undefined	Source is undefined.
Invalid dialog variant: `${variant}`	Invalid dialog variant.

Add-on UI SDK

currentUser

Last updated 9/13/2024

Was this helpful?

Yes

addOnUISdk.app

Objects.css-83mclq{margin-left:var(--spectrum-global-dimension-size-100);}

Methods

on().css-jmmyhj{margin-left:var(--spectrum-global-dimension-size-50);}

Signature

Parameters

Return Value

Example Usage

off()

Signature

Parameters

Return Value

Example Usage

startPremiumUpgradeIfFreeUser()

Signature

Return Value

Example Usage

showModalDialog()

Signature

Parameters

DialogOptions

ButtonLabels

Input Dialog Additional Option

Field

Return Value

DialogResult

Confirmation Dialog Example Usage

Input Dialog Example Usage

registerIframe()

Signature

Parameters

Return Value

UnregisterIframe Type Definition

Example Usage

enableDragToDocument()

Signature

Parameters

dragCallbacks

DragPreviewCallback Type Definition

DragCompletionCallback Type Definition

DragCompletionData

MediaAttributes

Return Value

DisableDragToDocument Type Definition

DragStartEventData Object

Properties

DragEndEventData

Events

Errors

Objects

on()

`DialogOptions`

`ButtonLabels`

`Field`

`DialogResult`

`UnregisterIframe` Type Definition

`dragCallbacks`

`DragPreviewCallback` Type Definition

`DragCompletionCallback` Type Definition

`DragCompletionData`

`MediaAttributes`

`DisableDragToDocument` Type Definition

`DragStartEventData` Object

`DragEndEventData`