Content Publisher intent implementation guide

Publish Canva designs directly to external platforms.

This guide helps you implement the Content Publisher intent to publish Canva designs to external platforms.

The Content Publisher intent is provided as a preview. Preview intents are unstable and may change without warning. You can't release public apps using a preview intent until it's stable.

Architectural overview

The following diagram demonstrates the Content 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.

OutputType

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

PublishRef

PublishRef is 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. It is passed between settings, preview, and publishing steps, and has a maximum size of 5 KB.

PreviewMedia

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

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.

Creating a content publisher

Step 1: Enable the intent

Before an intent can be implemented, it must be enabled. Enabling an intent informs Canva of when and where the app should be invoked throughout the user experience.

You can configure intents for your app with either the Developer Portal or the Canva CLI:

Navigate to an app via the Your apps⁠(opens in a new tab or window) page.
On the Intents page, find the "Available intents" section.
For the "Content Publisher" intent, click Set up.
In the "Implement in your code" dialog that appears, click Done. The following sections in this guide will walk you through implementing the intent in your code.

Set up your app to use the Canva CLI to manage settings via the canva-app.json file.
Set the intent.content_publisher property to be enrolled. For more information, see canva-app.json.

For example, the following enables the Content Publisher intent.
```
{
  "intent": {
    "content_publisher": {
      "enrolled": true
    }
  }
}
```
JSON

Step 2: Enable the required scopes

In the Apps SDK, certain methods require certain scopes to be enabled. If an app attempts to call methods without the required scopes being enabled, the SDK will throw an error.

The Content Publisher intent requires the following scopes:

Design read (canva:design:content:read)

To learn more, see Configuring scopes.

Step 3: Register the intent

Before an intent can be implemented, it must be registered. Registering the Content Publisher intent establishes how the content will be published and what UI to display for configuring the publish settings.

To register the intent, call the prepareContentPublisher method as soon as the app loads:

import { prepareContentPublisher } from "@canva/intents/content";

// Register the content publisher when your app loads
 prepareContentPublisher({
  getPublishConfiguration: async () => {
    // Implement the logic to get the publish configuration
  },
  renderSettingsUi: (params) => {
    // Implement the UI for settings view
  },
  renderPreviewUi: (params) => {
    // Implement the UI for preview view
  },
  publishContent: async (params) => {
    // Implement the logic to publish the content
  },
});

TSX

Intents must only be registered once. To learn more, see Technical requirements.

Step 4: Provide output types

To provide the content formats your platform supports (for example, Instagram Reel, Post, Story) and their media requirements, use the getPublishConfiguration method.

const outputTypes: OutputType[] = [{
  id: "post",
  displayName: "Feed Post",
  mediaSlots: [{
      id: "media", displayName: "Media", fileCount: { exact: 1 }, accepts: { image: { format: "png", aspectRatio: { min: 4 / 5, max: 1.91 / 1 } } },
    }]
}];

async function getPublishConfiguration(): Promise<GetPublishConfigurationResponse> {
  return {
    status: "completed",
    outputTypes,
  };
}

TYPESCRIPT

Step 5: Render publish settings UI

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

import type {
  RenderSettingsUiRequest,
  SettingsUiContext,
} from "@canva/intents/content";
import { FormField, Rows, Text, TextInput } from "@canva/app-ui-kit";
import { useEffect, useState } from "react";
import * as styles from "styles/components.css";

// Define the structure of settings that your app serializes into the publishRef string
interface PublishSettings {
  caption: string;
}

// Settings UI component for configuring publish settings
export const SettingUi = ({
  updatePublishSettings,
  registerOnSettingsUiContextChange,
}: RenderSettingsUiRequest) => {
  const [settings, setSettings] = useState<PublishSettings>({
    caption: "",
  });
  const [settingsUiContext, setSettingsUiContext] =
    useState<SettingsUiContext | null>(null);

  // Listen for settings UI context changes (e.g., when output type changes)
  useEffect(() => {
    const dispose = registerOnSettingsUiContextChange((context) => {
      setSettingsUiContext(context);
    });
    return dispose;
  }, [registerOnSettingsUiContextChange]);

  // Update publish settings whenever they change
  // This notifies Canva of the current settings and validity state
  useEffect(() => {
    updatePublishSettings({
      publishRef: JSON.stringify(settings),
      validityState: validatePublishRef(settings),
    });
  }, [settings, updatePublishSettings]);

  return (
    <div className={styles.scrollContainer}>
      <Rows spacing="2u">
        <Text>{settingsUiContext?.outputType.displayName}</Text>
        <FormField
          label="Caption"
          control={(props) => (
            <TextInput
              {...props}
              value={settings.caption}
              onChange={(caption) =>
                setSettings((prev) => ({ ...prev, caption }))
              }
            />
          )}
        />
      </Rows>
    </div>
  );
};

// Validates the publish settings to enable/disable the publish button
// Returns "valid" when all required fields are filled
const validatePublishRef = (publishRef: PublishSettings) => {
  // caption is required
  if (publishRef.caption.length === 0) {
    return "invalid_missing_required_fields";
  }
  return "valid";
};

const root = createRoot(document.getElementById("root") as Element);
prepareContentPublisher({
  getPublishConfiguration,
  // Render the settings UI where users configure publishing options
  renderSettingsUi: ({
    updatePublishSettings,
    registerOnSettingsUiContextChange,
  }) => {
    root.render(
      <AppUiProvider>
        <SettingUi
          updatePublishSettings={updatePublishSettings}
          registerOnSettingsUiContextChange={registerOnSettingsUiContextChange}
        />
      </AppUiProvider>,
    );
  },
  renderPreviewUi: (params) => {
    // Implement the UI for preview view
  },
  publishContent: async (params) => {
    // Implement the logic to publish the content
  },
});

TSX

Step 6: Render preview UI

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

import type { OutputType, PreviewMedia } from "@canva/intents/content";
import { useEffect, useState } from "react";
import * as styles from "./preview_ui.css";

// Main preview UI component that receives preview updates when settings or pages change.
// preview UI is more flexible to align with your platform's design system, so it is not constrained to the Canva design system.
export const PreviewUi = ({ registerOnPreviewChange }: RenderPreviewUiRequest) => {
  const [previewData, setPreviewData] = useState<{
    previewMedia: PreviewMedia[];
    outputType: OutputType;
    publishRef?: string;
  } | null>(null);

  // Register to receive preview updates whenever settings or pages change
  useEffect(() => {
    const dispose = registerOnPreviewChange((data) => {
      setPreviewData(data);
    });
    return dispose;
  }, [registerOnPreviewChange]);

  const { previewMedia, publishRef, outputType } = previewData ?? {};
  const publishSettings = parsePublishSettings(publishRef);

  return (
    <div className={styles.container}>
      {outputType?.id === "post" && (
        <PostPreview previewMedia={previewMedia} settings={publishSettings} />
      )}
    </div>
  );
};

// Deserializes the publishRef string back into the PublishSettings object
const parsePublishSettings = (
  publishRef?: string,
): PublishSettings | undefined => {
  if (!publishRef) return undefined;

  try {
    return JSON.parse(publishRef) as PublishSettings;
  } catch {
    return undefined;
  }
};

// Renders a post preview that is specific to your platform
export const PostPreview = ({ previewMedia, settings }: {
  previewMedia: PreviewMedia[] | undefined;
  settings: PublishSettings | undefined;
}) => {
  // Implement the logic to render the post preview
};

const root = createRoot(document.getElementById("root") as Element);
prepareContentPublisher({
  getPublishConfiguration,
  // Render the settings UI where users configure publishing options
  renderSettingsUi: ({
    updatePublishSettings,
    registerOnSettingsUiContextChange,
  }) => {
    root.render(
      <AppUiProvider>
        <SettingUi
          updatePublishSettings={updatePublishSettings}
          registerOnSettingsUiContextChange={registerOnSettingsUiContextChange}
        />
      </AppUiProvider>,
    );
  },
  // Render the preview UI showing how the content will appear after publishing
  renderPreviewUi: ({ registerOnPreviewChange }) => {
    root.render(
      <AppUiProvider>
        <PreviewUi registerOnPreviewChange={registerOnPreviewChange} />
      </AppUiProvider>,
    );
  },
  publishContent: async (params) => {
    // Implement the logic to publish the content
  },
});

TSX

Step 7: Publish content

Use the publishContent method to publish the content to your platform, invoking your platform's APIs. The publishContent method is called when the user clicks the publish button.

async function publishContent(params: PublishContentRequest): Promise<PublishContentResponse> {
    // Replace this with your actual API integration
    // Example: Upload media to your platform and create a post
    // const uploadedMedia = await uploadToYourPlatform(params.outputMedia);
    // const post = await createPostOnYourPlatform({
    //   media: uploadedMedia,
    //   caption: JSON.parse(params.publishRef).caption
    // });

    return {
      status: "completed",
      externalId: "1234567890", // Your platform's unique identifier for this post
      externalUrl: "https://example.com/posts/1234567890", // Link to view the published content
    };
}

const root = createRoot(document.getElementById("root") as Element);
prepareContentPublisher({
  getPublishConfiguration,
  // Render the settings UI where users configure publishing options
  renderSettingsUi: ({
    updatePublishSettings,
    registerOnSettingsUiContextChange,
  }) => {
    root.render(
      <AppUiProvider>
        <SettingUi
          updatePublishSettings={updatePublishSettings}
          registerOnSettingsUiContextChange={registerOnSettingsUiContextChange}
        />
      </AppUiProvider>,
    );
  },
  // Render the preview UI showing how the content will appear after publishing
  renderPreviewUi: ({ registerOnPreviewChange }) => {
    root.render(
      <AppUiProvider>
        <PreviewUi registerOnPreviewChange={registerOnPreviewChange} />
      </AppUiProvider>,
    );
  },
  publishContent,
});

TYPESCRIPT

Initiating OAuth inside intents

If your app requires OAuth with a third-party identity provider, initiate the OAuth flow from inside the intent action that requires authentication.

For implementation guidance, see Initiating OAuth inside intents.