Design publisher

Design Publisher is a type of intent that enables users to publish Canva designs directly to external platforms.

When users want to publish their designs to an external platform, they can configure their publish settings and preview the content before publishing.

The following diagram demonstrates the Design Publisher workflow. There are two app iframe views: one for the publish settings UI and one for the preview UI. The publish intent platform handles the communication between the app views and Canva.

The OutputType identifies a distinct type of output that a third-party platform expects. These could be formats like an Instagram Story or a YouTube Video, or outputs like a Mailchimp Email or an ad type on Meta Ads.

Key concepts:

• OutputType: Defines a specific type of output that an app supports for an external platform (e.g., Instagram Reel, Mailchimp Email).
• MediaSlot: Describes a grouping of one or more files required to produce that output.
• FileRequirement: Defines constraints on those files (e.g., format, size, aspect ratio).

PreviewMedia provides real-time file previews to render in your app's preview UI iframe during the publish flow. These previews update dynamically as users modify their publish settings.

Key concepts:

• Preview Files: Media representations that can be in various states (loading, ready, error, and so on).
• Video Optimization: Videos start as lightweight thumbnails and can be upgraded to full videos on demand.
• Live Updates: Previews refresh automatically when users change settings.

OutputMedia represents the final exported files that will be sent to an external platform during the publish operation. These are the production-ready files that match the requirements you specified in your app's OutputType configuration.

Key concepts:

• OutputFiles: The actual media files exported from Canva designs.

With the design publisher intent, your app needs to implement 4 actions:

Provide the content formats your platform supports (e.g., Instagram Reel, Post, Story) and their media requirements.

Users see these options when choosing a post type through Canva UI components.

getOutputTypes: () => Promise<GetOutputTypesResponse>;

Renders your app's custom config UI for users to configure platform-specific settings (e.g., captions, hashtags, privacy settings).

• publishRef: An opaque string to store all the settings you require to publish on your platform. Your app is responsible for serializing and deserializing this string.
  • Passed between settings, preview, and publishing steps
  • Maximum size: 5 KB
• updatePublishSettings: Callback to update settings back to Canva.
• Receives SettingsUiContext that updates in real-time through registerOnSettingsUiContextChange.

renderSettingsUi: (request: RenderSettingsUiRequest) => void;

export type RenderSettingsUiRequest = {
  /** Callback function to update the publish settings. */
  updatePublishSettings: (
    publishSettings: PublishSettings,
  ) => Promise<UpdatePublishSettingsResponse>;

  /**
   * Registers a callback to be called when the settings UI context is changed.
   * @param callback - The callback to be called when the settings UI context is changed.
   * @returns A disposer function that cleans up the registered callback.
   */
  registerOnSettingsUiContextChange: (callback: (context: SettingsUiContext) => void) => Disposer;
};

Displays a live app preview UI showing how the design will appear on your target platform.

• Receives PreviewMedia that updates in real-time through registerOnPreviewChange. See more details about PreviewMedia in the preceding sections.
• Videos start as thumbnails to optimize performance and can request video upgrades through requestPreviewUpgrade to upgrade from thumbnails to full videos.
• Your app must handle all preview states (loading, ready, error, and so on).

renderPreviewUi: (request: RenderPreviewUiRequest) => void;

/** Configuration required for rendering the preview UI. */
export type RenderPreviewUiRequest = {
  /** Function to upgrade the thumbnail preview ids to full preview media. */
  requestPreviewUpgrade: (previewIds: string[]) => void;

  /** Registers a callback to be called when the preview data is updated. */
  registerOnPreviewChange: (
    callback: (opts: {
      previewMedia: PreviewMedia[];
      /** The output type that the preview data is for */
      outputType: OutputType;
      publishRef?: string;
    }) => void,
  ) => Disposer;
};

Executes the final publish to your platform with the following parameters:

• publishRef: Your settings from the configuration step.
• outputType: The output type that the publish request is for.
• outputMedia: Final exported files matching your requirements. See more details in the OutputMedia section.

publishDesign: (request: PublishDesignRequest) => Promise<PublishDesignResponse>;

/** Parameters required for publishing a design. */
export type PublishDesignRequest = {
  /** The platform-specific settings reference for publishing */
  publishRef?: string;
  /** The output type that the publish request is for */
  outputType: OutputType;
  /** The exported files to be published */
  outputMedia: OutputMedia[];
};