addOnUISdk.app.document

Provides access to the methods needed for retrieving document metadata, importing content such as images, audio and video into the document, and for exporting content from the current document.

General Methods

id()

Retrieves the id of the document.

Signature

id(): Promise<string | undefined>

Return Value

A resolved Promise containing the id of the document.

data-slots=text

data-variant=info

Example Usage

data-slots=heading, code

data-repeat=1

import addOnUISdk from "https://express.adobe.com/static/add-on-sdk/sdk.js";

function setId(id) { /* ... */ }

addOnUISdk.ready.then(() => setId(await addOnUISdk.app.document.id()));

addOnUISdk.app.on("documentIdAvailable", data => {
  setId(data.documentId);
});

title()

Retrieves the title/name of the document.

Signature

title(): Promise<string>

Return Value

A resolved Promise containing the title (ie: name) of the document.

data-slots=text

data-variant=info

Example Usage

data-slots=heading, code

data-repeat=1

import addOnUISdk from "https://express.adobe.com/static/add-on-sdk/sdk.js";

function setTitle(title) { /* ... */ }

addOnUISdk.ready.then(() => setTitle(await addOnUISdk.app.document.title()));

addOnUISdk.app.on("documentTitleChange", data => {
  setTitle(data.documentTitle);
});

getPagesMetadata()

Retrieve the metadata for all of the pages in the document.

Signature

getPagesMetadata(options: PageMetadataOptions): Promise<PageMetadata[]>

Parameters

Return Value

A resolved Promise containing a PageMetadata array containing all of the pages in the document.

Example Usage

data-slots=heading, code

data-repeat=2

import addOnUISdk from "https://express.adobe.com/static/add-on-sdk/sdk.js";

// Wait for the SDK to be ready
await addOnUISdk.ready;

// Get metadata of all the pages
async function logMetadata() {
  try {
    const pages = (await addOnUISdk.app.document.getPagesMetadata({
        range: addOnUISdk.constants.Range.specificPages,
        pageIds: [
            "7477a5e7-02b2-4b8d-9bf9-f09ef6f8b9fc",
            "d45ba3fc-a3df-4a87-80a5-655e5f8f0f96"
        ]
    })) as PageMetadata[];
    for (const page of pages) {
      console.log("Page id: ", page.id);
      console.log("Page title: ", page.title);
      console.log("Page size: ", page.size);
      console.log("Page has premium content: ", page.hasPremiumContent);
      console.log("Page has audio content: ", page.hasAudioContent);
      console.log("Page has video content: ", page.hasVideoContent);
      console.log("Page has animated content: ", page.hasAnimatedContent);
      console.log("Page has timelines: ", page.hasTemporalContent);
      if (page.hasTemporalContent)
          console.log("Page includes temporal content with a duration of: ", page.temporalContentDuration);
      console.log("Pixels per inch: ", page.pixelsPerInch);
      console.log("Is page print ready: ", page.isPrintReady);
      console.log("Is page blank: ", page.isBlank);
      console.log("Template details: ", page.templateDetails);
    }
  }
  catch(error) {
    console.log("Failed to get metadata:", error);
  }
}

Page id: 772dc4b6-0df5-469f-b477-2a0c5445a6ef
Page title: My First Page
Page size: { width: 2550, height: 3300 }
Page has premium content: false
Page has audio content: false
Page has video content: true
Page has animated content: false
Page has timelines: true
Page includes temporal content with a duration of: 100
Pixels per inch: 72
Is page print ready: true
Is page blank: false
Template details of page: { id: 'urn:aaid:sc:VA6C2:0ccab100-a230-5b45-89f6-7e78fdf04141', creativeIntent: 'flyer' }

runPrintQualityCheck()

Tells Express to run a print quality check to determine if the document is ready for printing and updates the quality metadata with the result. For instance, if the document is not ready for printing, the isPrintReady property of the page metadata will be set to false.

data-slots=text

data-variant=warning

Signature

runPrintQualityCheck(options: PrintQualityCheckOptions): void

Parameters

Return Value

void

Example Usage

data-slots=heading, code

data-repeat=2

import addOnUISdk from "https://express.adobe.com/static/add-on-sdk/sdk.js";

// Reference to the active document
const { document } = addOnUISdk.app;

// Run Print Quality Check
function runPrintQualityCheck() {
  try {
    document.runPrintQualityCheck({
      range: addOnUISdk.constants.Range.entireDocument,
    });
    console.log("Print quality check completed successfully");
  } catch (error) {
    console.log("Failed to run print quality check");
  }
}

Print quality check completed successfully

TemplateDetails

Retrieve the details about the template used to create the document.

PrintQualityCheckOptions

The options to pass into the print quality check.

PageMetadata

The metadata of a page.

PageMetadataOptions

This object is passed as a parameter to the getPagesMetadata method and includes the range and optional pageIds for which you want to retrieve metadata for.

getSelectedPageIds()

Retrieves the currently selected page ids in the document.

Signature

getSelectedPageIds(): Promise<string[]>

Return Value

A resolved Promise containing an array of string ids representing the currently selected pages in the document.

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;

// Get the currently selected page ids
async function getSelectedPages() {
  try {
    const selectedPageIds = await addOnUISdk.app.document.getSelectedPageIds();
    console.log("Selected page ids:", selectedPageIds);

    if (selectedPageIds.length === 0) {
      console.log("No pages are currently selected");
    } else {
      console.log(`${selectedPageIds.length} page(s) selected:`, selectedPageIds);
    }
  } catch (error) {
    console.log("Failed to get selected page ids:", error);
  }
}

// Example: Get metadata for selected pages only
async function getSelectedPagesMetadata() {
  try {
    const selectedPageIds = await addOnUISdk.app.document.getSelectedPageIds();

    if (selectedPageIds.length > 0) {
      const metadata = await addOnUISdk.app.document.getPagesMetadata({
        range: addOnUISdk.constants.Range.specificPages,
        pageIds: selectedPageIds
      });

      metadata.forEach((page, index) => {
        console.log(`Selected page ${index + 1}: ${page.title} (${page.id})`);
      });
    } else {
      console.log("No pages selected");
    }
  } catch (error) {
    console.log("Failed to get selected pages metadata:", error);
  }
}

// Call the functions
getSelectedPages();
getSelectedPagesMetadata();

link()

Retrieves the document link.

data-slots=text

data-variant=warning

Signature

link(options: LinkOptions): Promise<string | undefined>

Return Value

A resolved Promise containing the link of the document.

data-slots=text

data-variant=info

Example Usage

data-slots=heading, code

data-repeat=1

import addOnUISdk from "https://express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(async () => {
  try {
    // Get the current document link
    const documentLink = await addOnUISdk.app.document.link("document");
    console.log("Document link:", documentLink);

    // Get the published document link
    const publishedLink = await addOnUISdk.app.document.link("published");
    console.log("Published link:", publishedLink);
  } catch (error) {
    console.log("Failed to get document links:", error);
  }

  // Listen for document link availability changes
  addOnUISdk.app.on("documentLinkAvailable", (data) => {
    console.log("Document link availability changed. Link value:", data.documentLink);
  });

  // Listen for published document link availability changes
  addOnUISdk.app.on("documentPublishedLinkAvailable", (data) => {
    console.log("Published link availability changed. Link value:", data.documentPublishedLink);
  });
});

LinkOptions

The options to pass into the link method.

isPresentation()

Returns true if the document is a presentation.

data-slots=text

data-variant=warning

Signature

isPresentation(): Promise<boolean>

Return Value

A resolved Promise containing true if the document is a presentation, false if not.

Example Usage

data-slots=heading, code

data-repeat=1

import addOnUISdk from "https://express.adobe.com/static/add-on-sdk/sdk.js";

addOnUISdk.ready.then(async () => {
  try {
    // Get if the document is a presentation
    const isPresentation = await addOnUISdk.app.document.isPresentation();
    console.log("Is presentation:", isPresentation);
  } catch (error) {
    console.log("Failed to get is presentation:", error);
  }
});

Import Content Methods

addImage()

Adds an image/gif/PSD/AI/SVG file to the current page.

Signature

addImage(imageBlob: Blob, attributes?: MediaAttributes, importAddOnData?: ImportAddOnData): Promise<void>

Parameters

Return Value

A resolved promise if the image was successfully added to the canvas; otherwise, it will throw an error with the rejected promise.

Example Usage

// Add image(blob) to the current page
async function addImageFromBlob(blob) {
  try {
    await document.addImage(blob, {title: "Sample Image", author: "Creator"});
  } catch (error) {
    console.log("Failed to add the image to the page.");
  }
}

// Add image(url) to the current page
async function addImageFromURL(url) {
  try {
    const blob = await fetch(url).then((response) => response.blob());
    await document.addImage(blob, {title: "Sample Image", author: "Creator"});
  } catch (error) {
    console.log("Failed to add the image to the page.");
  }
}

// Add image with custom add-on metadata
async function addImageWithMetadata(blob) {
  try {
    await document.addImage(
      blob,
      { title: "Custom Image", author: "Creator" },
      {
        nodeAddOnData: {
          customId: "img_123",
          category: "photos"
        },
        mediaAddOnData: {
          sourceUrl: "https://example.com/image.jpg",
          license: "CC0"
        }
      }
    );
  } catch (error) {
    console.log("Failed to add the image to the page.");
  }
}

data-slots=text

data-variant=info

addAnimatedImage()

Adds an animated image (gif) to the current page.

Signature

addAnimatedImage(imageBlob: Blob, attributes?: MediaAttributes, importAddOnData?: ImportAddOnData): Promise<void>

Parameters

Return Value

A resolved promise if the animated image was successfully added to the canvas; otherwise, it will throw an error with the rejected promise.

Example Usage

// Add animated image(blob) to the current page
async function addAnimatedImageFromBlob(blob) {
  try {
    await document.addAnimatedImage(blob, {title: "Animated GIF", author: "Creator"});
  } catch (error) {
    console.log("Failed to add the animated image to the page.");
  }
}

data-slots=text

data-variant=info

addVideo()

Adds a video to the current page.

Signature

addVideo(videoBlob: Blob, attributes?: MediaAttributes, importAddOnData?: ImportAddOnData): Promise<void>

Parameters

Example Usage

async function addVideoFromBlob(blob) {
  try {
    await document.addVideo(blob, {title: "Sample Video", author: "Creator"});
  } catch (error) {
    console.log("Failed to add the video to the page.");
  }
}

async function addVideoFromURL(url) {
  try {
    const blob = await fetch(url).then((response) => response.blob());
    await document.addVideo(blob, {title: "Sample Video", author: "Creator"});
  } catch (error) {
    console.log("Failed to add the video to the page.");
  }
}

addAudio()

Adds audio to the current page.

Signature

addAudio(audioBlob: Blob, attributes: MediaAttributes): Promise<void>

Parameters

Return Value

A resolved promise if the audio was successfully added to the canvas; otherwise will throw an error with the rejected promise.

Example Usage

async function addAudioFromBlob(blob) {
  try {
      await document.addAudio(blob, {title: "Jazzy beats", author: "Jazzy"});
  }
  catch(error) {
      console.log("Failed to add the audio to the page.");
  }
}

async function addAudioFromURL(url) {
  try {
      const blob = await fetch(url).then(response => response.blob());
      await document.addAudio(blob, {title: "Jazzy beats", author: "Jazzy"});
  }
  catch(error) {
      console.log("Failed to add the audio to the page.");
  }

MediaAttributes

ImportAddOnData

Represents add-on-specific data that can be attached to imported media assets (nodes). This data provides a way for add-ons to store custom metadata with imported assets across multiple import APIs. Note: This support is not present for PSD/AI assets.

data-slots=text

data-variant=info

Refer to the import images how-to and the import-images-from-local in the code samples for general importing content examples.

importPdf()

Imports a PDF as a new Adobe Express document.

Signature

importPdf(blob: Blob, attributes: MediaAttributes & SourceMimeTypeInfo): void;

Parameters

Return Value

None

SourceMimeTypeInfo

Mime type details for importing media

SupportedMimeTypes

A constant representing the mime type of the original source asset that was converted to PDF.

• docx: "docx"
• gdoc: "gdoc"

data-slots=text

data-variant=info

When you call importPdf() with a converted file, you can pass the original file's mime type ("docx" or "gdoc") in the sourceMimeType parameter. This ensures that the import consent dialog displays "Import a document" instead of "Import a PDF" to the user, preventing confusion about why their Word document or Google Docs file is being referred to as a PDF.

Important: Do not pass the original Word documentor Google Docs file directly to importPdf(). Your add-on must first convert these files to PDF format, then use this parameter solely to customize the dialog message for better user experience.

Example Usage

import addOnUISdk from "https://express.adobe.com/static/add-on-sdk/sdk.js";

// Reference to the active document
const { document } = addOnUISdk.app;

// Import a regular PDF file
async function importPdf(pdfBlob) {
  try {
    document.importPdf(pdfBlob, { title: "Sample.pdf" });
  } catch (error) {
    console.log("Failed to import the pdf.");
  }
}

// Import a PDF that was converted from a Word document
// The sourceMimeType parameter ensures the dialog shows "Import a document" instead of "Import a PDF"
async function importConvertedWordDoc(convertedPdfBlob) {
  try {
    document.importPdf(convertedPdfBlob, {
      title: "Converted Document.pdf",
      sourceMimeType: "docx"
    });
  } catch (error) {
    console.log("Failed to import the converted Word document.");
  }
}

// Import a PDF that was converted from a Google document
async function importConvertedGoogleDoc(convertedPdfBlob) {
  try {
    document.importPdf(convertedPdfBlob, {
      title: "Converted Google Doc.pdf",
      sourceMimeType: "gdoc"
    });
  } catch (error) {
    console.log("Failed to import the converted Google document.");
  }
}

importPresentation()

Imports a presentation as a new Adobe Express document. Note: Currently Express only supports PowerPoint presentations with a pptx extension.

Signature

importPresentation(blob: Blob, attributes: MediaAttributes): void;

Parameters

Return Value

None

Example Usage

import addOnUISdk from "https://express.adobe.com/static/add-on-sdk/sdk.js";

// Reference to the active document
const { document } = addOnUISdk.app;

const mediaAttributes = { title: "Sample.pptx" }; // only Pptx is supported by Express

// Import a presentation. Note: this will be imported as a new Adobe Express presentation.
function importPresentation(blob, mediaAttributes) {
  try {
    document.importPresentation(blob, mediaAttributes);
  } catch (error) {
    console.log("Failed to add the presentation to the document.");
  }
}

// Import a powerpoint presentation from a URL. Note: this will be imported as a new Adobe Express presentation.
async function importPresentationFrom(url) {
  try {
    const blob = await fetch(url).then((response) => response.blob());
    document.importPresentation(blob, { title: "Sample.pptx" });
  } catch (error) {
    console.log("Failed to add the presentation to document.");
  }
}

Image requirements

When importing images, the following limits apply for all types except gif images:

• Maximum dimension: 8192px (width or height)
• Maximum file size: 80MB (desktop) or 40MB (mobile)
• Maximum pixel count: 65 million pixels (width × height)

Supported formats: AI, GIF, HEIC, JPEG, JPG, PNG, PSB, PSD, PSDT, SVG, and WEBP.

See the full image requirements for more details.

For gif images, the technical requirements are listed here and summarized below for quick reference:

• Maximum resolution: 1080px
• Maximum size: 10 MB
• Maximum GIFs per scene: 7

data-slots=header, text1, text2

data-variant=info

** See the FAQ's for the specific file formats allowed for imported content.

Errors

The table below describes the possible error messages that may occur when using the import methods, with a description of the scenario that would cause them to be returned.

Export Content Methods

createRenditions()

Generate renditions of the current page, specific pages or the entire document in a specified format for export.

Signature

createRenditions(renditionOptions: RenditionOptions, renditionIntent?: RenditionIntent): Promise<Rendition[]>

Parameters

NOTE: The default value for renditionIntent is export. If it's set to preview, it also requires the renditionPreview flag to be set to true in the manifest requirements section. Additionally, when implementing the premium content flows where you present a dialog or option to allow the user to upgrade, you must be sure to also include the following permissions in the sandbox attribute of your manifest.json to allow the Adobe Express pricing page to load properly:

"permissions": {
    "sandbox": ["allow-popups-to-escape-sandbox", "allow-popups", "allow-downloads"]
}

Refer to the manage premium content how-to for more specific details on options for handling the export of premium content.

RenditionOptions

JpgRenditionOptions

Extends the RenditionOptions object and adds the following additional options for jpg renditions:

PngRenditionOptions

Extends the RenditionOptions object and adds the following additional options for png renditions:

Requested Size Notes

• The supported size is from 1 x 1 to 8192 x 8192.
• Aspect ratio is maintained while scaling the rendition based on the requested size.
• Up-scaling is currently not supported.
• If the requested size is invalid, it will be ignored and the original size rendition will be created.
• Some examples of what the actual exported sizes will be, depending on the page size and requested size are in the table below for reference.

PptxRenditionOptions

Extends the RenditionOptions object with the specific format for pptx renditions:

data-slots=text

data-variant=info

PdfRenditionOptions

Extends the RenditionOptions object and adds the following additional options for pdf renditions:

Bleed

Represents a bleed for a page. In printing, bleed is printing that goes beyond the edge of where the sheet will be trimmed. In other words, the bleed is the area to be trimmed off. If the value is left undefined, then no bleed will be assumed.

PdfPageBoxes

Represents all of the PDF page boxes (MediaBox, BleedBox, CropBox, TrimBox).

PdfPageBox

Represents a PDF page box.

PdfPageBoxMargins

Represents margins for a PDF page box.

Mp4RenditionOptions

Extends the RenditionOptions object and adds the following additional options for mp4 renditions:

Return Value

A Promise with an array of page Rendition objects (see PageRendition). The array will contain one item if the currentPage range is requested, an array of specific pages when the specificPages range is requested, or all pages when the entireDocument range is specified. Each rendition returned will contain the type, title,metadata for the page and a blob of the rendition itself. Note: If you requested PDF or PPTX for the format with a larger range than currentPage, a single file will be generated which includes the entire range. When the format is JPG/PNG/MP4, an array of files will be generated that represents each page.

Example Usage

data-slots=heading, code

data-repeat=2

import addOnUISdk from "https://express.adobe.com/static/add-on-sdk/sdk.js";

// Wait for the SDK to be ready
await addOnUISdk.ready;

// Display preview of all pages in the UI of your add-on
async function displayPreview() {
  try {
    const renditionOptions = {
      range: addOnUISdk.constants.Range.entireDocument,
      format: addOnUISdk.constants.RenditionFormat.png,
      backgroundColor: 0x7faa77ff,
    };
    const renditions = await addOnUISdk.app.document.createRenditions(
      renditionOptions,
      addOnUISdk.constants.RenditionIntent.preview
    );
    renditions.forEach((rendition) => {
      const image = document.createElement("img");
      image.src = URL.createObjectURL(rendition.blob);
      document.body.appendChild(image);
    });
  } catch (error) {
    console.log("Failed to create renditions:", error);
  }
}

// Export document as PowerPoint presentation
async function exportAsPowerPoint() {
  try {
    const renditionOptions = {
      range: addOnUISdk.constants.Range.entireDocument,
      format: addOnUISdk.constants.RenditionFormat.pptx,
    };
    const renditions = await addOnUISdk.app.document.createRenditions(
      renditionOptions,
      addOnUISdk.constants.RenditionIntent.export
    );

    // Download the PPTX file
    const rendition = renditions[0]; // PPTX exports as single file
    const url = URL.createObjectURL(rendition.blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = `${rendition.title}.pptx`;
    a.click();
    URL.revokeObjectURL(url);
  } catch (error) {
    console.log("Failed to export as PowerPoint:", error);
  }
}

import addOnUISdk from "https://express.adobe.com/static/add-on-sdk/sdk.js";

// Wait for the SDK to be ready
await addOnUISdk.ready;

// Display preview of all pages in the AddOn UI
async function displayPreview() {
  try {
    const renditionOptions: PngRenditionOptions = {
      range: Range.entireDocument,
      format: RenditionFormat.png,
      backgroundColor: 0x7faa77ff,
    };
    const renditions = await addOnUISdk.app.document.createRenditions(
      renditionOptions,
      RenditionIntent.preview
    );
    renditions.forEach((rendition) => {
      const image = document.createElement("img");
      image.src = URL.createObjectURL(rendition.blob);
      document.body.appendChild(image);
    });
  } catch (error) {
    console.log("Failed to create renditions:", error);
  }
}

// Export document as PowerPoint presentation
async function exportAsPowerPoint() {
  try {
    const renditionOptions: PptxRenditionOptions = {
      range: Range.entireDocument,
      format: RenditionFormat.pptx,
    };
    const renditions = await addOnUISdk.app.document.createRenditions(
      renditionOptions,
      RenditionIntent.export
    );

    // Download the PPTX file
    const rendition = renditions[0]; // PPTX exports as single file
    const url = URL.createObjectURL(rendition.blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = `${rendition.title}.pptx`;
    a.click();
    URL.revokeObjectURL(url);
  } catch (error) {
    console.log("Failed to export as PowerPoint:", error);
  }
}

Rendition

A rendition object representing a page in the document, returned from createRenditions. See

PageRendition

An extension of Rendition, returned in the response to createRenditions. This object includes everything in Rendition, as well as:

** See the FAQs for the file formats and mime types supported for exported content.

data-slots=text

data-variant=info

exportAllowed()

Determines whether the current document can be exported based on its review status in review and approval workflows.

Signature

exportAllowed(): Promise<boolean>

Return Value

A resolved Promise containing a boolean value indicating whether export is allowed (true) or restricted (false) based on the document's review status.

data-slots=text

data-variant=info

Important: This restriction only applies to renditions created with RenditionIntent.export or RenditionIntent.print. Renditions created with RenditionIntent.preview are always allowed, regardless of the export status, as they are intended for preview purposes only.

User Experience Note: If you attempt to create export/print renditions without checking exportAllowed() first, and the document doesn't allow exports, users will see an error dialog with the message "Request approval" and "Get approval from your viewers before sharing this file". Using exportAllowed() allows you to provide a more graceful user experience by checking permissions proactively.

Example Usage

import addOnUISdk from "https://express.adobe.com/static/add-on-sdk/sdk.js";

// Check export permissions before creating non-preview renditions
async function handleExportRequest() {
  try {
    const canExport = await addOnUISdk.app.document.exportAllowed();

    if (canExport) {
      // Create rendition for export/download
      const rendition = await addOnUISdk.app.document.createRenditions(
        { range: addOnUISdk.constants.Range.currentPage, format: addOnUISdk.constants.RenditionFormat.png },
        addOnUISdk.constants.RenditionIntent.export
      );
      // ... handle download
    } else {
      // Show preview only since export is restricted
      console.log("Export restricted - showing preview only");
      const previewRendition = await addOnUISdk.app.document.createRenditions(
        { range: addOnUISdk.constants.Range.currentPage, format: addOnUISdk.constants.RenditionFormat.png },
        addOnUISdk.constants.RenditionIntent.preview
      );
      // ... show preview in UI only
    }
  } catch (error) {
    console.log("Failed to check export permissions:", error);
  }
}

// Set up UI based on export permissions
addOnUISdk.ready.then(async () => {
  const exportAllowed = await addOnUISdk.app.document.exportAllowed();

  // Note: The "document" in the next two lines refers to the UI of your add-on (in the HTML file) versus the addOnUISdk.app.document object from the API
  const downloadButton = document.getElementById('download-btn');
  const previewButton = document.getElementById('preview-btn');

  // Download button only available if export is allowed
  downloadButton.disabled = !exportAllowed;
  downloadButton.title = exportAllowed ? "Download rendition" : "Download restricted - document under review";

  // Preview button is always available
  previewButton.disabled = false;
});

Errors

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