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

Methods

on()

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

Signature

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

Parameters

Return Value

void

Example Usage

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

Return Value

void

Example Usage

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://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

DialogOptions

ButtonLabels

The input dialog variant accepts an additional field object.

Input Dialog Additional Option

Field

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

Confirmation Dialog Example Usage

import addOnUISdk from "https://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://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);
  }
}

data-slots=text

data-variant=info

showColorPicker()

Shows the Adobe Express color picker based on specific options passed in.

Signature

showColorPicker(anchorElement: HTMLElement, options?: ColorPickerOptions): Promise<void>;

Parameters

ColorPickerOptions

Return Value

Returns a void Promise.

Example Usage

const colorPickerButton = document.getElementById("color-picker-button");

colorPickerButton.addEventListener("click", () => {
  addOnUISdk.app.showColorPicker(colorPickerButton, {
    title: "Add-on's Color Picker",
    placement: ColorPickerPlacement.left,
    eyedropperHidesPicker: true,
    disableAlphaChannel: false,
  });
});

colorPickerButton.addEventListener(ColorPickerEvent.colorChange, (event) => {
  console.log("Color change event received!", event.detail.color;);
});

hideColorPicker()

Hides the Adobe Express color picker.

Signature

hideColorPicker(): Promise<void>;

Return Value

Returns a void Promise.

Example Usage

const colorPickerButton = document.getElementById("color-picker-button");

colorPickerButton.addEventListener("click", () => {
  addOnUISdk.app.showColorPicker(colorPickerButton, {
    title: "Add-on's Color Picker",
    placement: ColorPickerPlacement.left,
    eyedropperHidesPicker: true,
    disableAlphaChannel: false,
  });
  setTimeout(() => {
    console.log("Hiding Color Picker after 10 seconds...");
    addOnUISdk.app.hideColorPicker();
  }, 10000);
});

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.

Signature

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

Parameters

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;

Example Usage

import addOnUISdk from "https://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.

data-slots=text

data-variant=info

Signature

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

Parameters

dragCallbacks

DragPreviewCallback Type Definition

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

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[]>;

DragCompletionData

Returned as part of an array from the DragCompletionCallback, and contains the blob object to be added, as well as optional attributes for media content.

MediaAttributes

Required for audio content only.

ImportAddOnData

Add-on-specific metadata that can be attached to imported media and retrieved later via the document sandbox APIs.

Return Value

DisableDragToDocument

DisableDragToDocument Type Definition

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

type DisableDragToDocument = () => void;

DragStartEventData Object

The payload data sent to the dragStart event handler.

Properties

DragEndEventData

The payload data sent to the App dragEnd event handler.

* Important Event Handling Notes<br/>

• 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.

data-slots=text

data-variant=info

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.

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.

<br/>