pixx.io Plugin SDK

German Documentation: Hier gelangst du zur deutschen Dokumentation.

The goal of the Plugin SDK is to simplify plugin development by providing a user interface and minimizing direct communication with our server APIs.

The Plugin SDK must be embedded in an iframe. Users can log in and select files inside the SDK. Once selected, the SDK sends a file list to your plugin. The list contains download links and metadata. Your plugin is responsible for downloading the files.

Because your plugin performs the download, it must report download progress back to the Plugin SDK.

The Plugin SDK is available in 2 languages. Use the language requested by your user:

• Deutsch: https://plugin.pixx.io/static/v1/de/
• English: https://plugin.pixx.io/static/v1/en/

Quick Start (5 minutes)

These steps are sufficient for a working integration:

1. Embed the iframe with the correct language and applicationId.
2. Wait for onSdkReady.
3. Optionally send configuration (setAllowedFileTypes, setAllowedDownloadFormats, setButtonText, useDirectLinks).
4. Handle downloadFiles or directLinksCreated.
5. For downloads, report progress (setDownloadProgress, setDownloadComplete, or setDownloadFailed).

Minimal integration example

<iframe
  id="pixxio-plugin-sdk"
  src="https://plugin.pixx.io/static/v1/en/media?applicationId=YOUR_APPLICATION_ID"
  style="width: 100%; height: 100%; border: 0"
></iframe>

const iframe = document.getElementById('pixxio-plugin-sdk');
const sdkOrigin = 'https://plugin.pixx.io';

function sendToSdk(method, parameters = []) {
  iframe.contentWindow.postMessage(
    {
      receiver: 'pixxio-plugin-sdk',
      method,
      parameters
    },
    sdkOrigin
  );
}

window.addEventListener('message', async (event) => {
  if (event.origin !== sdkOrigin) {
    return;
  }

  const data = event.data;
  if (!data || data.sender !== 'pixxio-plugin-sdk') {
    return;
  }

  switch (data.method) {
    case 'onSdkReady':
      sendToSdk('setButtonText', ['Apply selection']);
      sendToSdk('setAllowedDownloadFormats', [['original', 'jpg', 'png']]);
      break;
    case 'downloadFiles': {
      const [files] = data.parameters ?? [[]];
      await downloadFiles(files);
      break;
    }
    case 'directLinksCreated': {
      const [files] = data.parameters ?? [[]];
      await processDirectLinks(files);
      break;
    }
    case 'onError': {
      const [error] = data.parameters ?? [];
      console.error('Plugin SDK Error', error);
      break;
    }
    default:
      break;
  }
});

async function downloadFiles(files) {
  try {
    for (let i = 0; i < files.length; i++) {
      const file = files[i];
      await fetch(file.downloadURL);
      const progress = Math.round(((i + 1) / files.length) * 100);
      sendToSdk('setDownloadProgress', [progress]);
    }
    sendToSdk('setDownloadComplete');
  } catch {
    sendToSdk('setDownloadFailed');
  }
}

async function processDirectLinks(files) {
  console.log('Received direct links', files);
}

Typical flow

1. Receive onSdkReady
2. Optionally configure SDK
3. User selects files
4. Receive downloadFiles or directLinksCreated
5. Send success or failure status back to the SDK

Communication Plugin <> Plugin SDK

Communication uses PostMessage.

Messages from Plugin SDK to your plugin

interface PluginSdkEvent {
  sender: 'pixxio-plugin-sdk';
  method: string;
  parameters?: unknown[];
}

Messages from your plugin to Plugin SDK

interface PluginSdkEvent {
  receiver: 'pixxio-plugin-sdk';
  method: string;
  parameters?: unknown[];
}

Receiving PostMessage events

window.addEventListener('message', (event) => {
	if (event.origin !== 'https://plugin.pixx.io') {
		return;
	}

	const data = event.data;
	if (data.sender === 'pixxio-plugin-sdk') {
		switch (data.method) {
			case 'downloadFiles':
				// Do stuff
				break;
			...
		}
	}
});

Sending data via PostMessage

iframe.contentWindow.postMessage(
  {
    receiver: 'pixxio-plugin-sdk',
    method: 'login'
  },
  'https://plugin.pixx.io'
);

Events from Plugin SDK to your plugin

downloadFiles

The user selected files that your plugin now needs to download.

directLinksCreated

The user selected files and direct links are provided instead of download URLs.

onSdkReady

The Plugin SDK is only ready to receive PostMessage events after this event.

Note: Incoming login messages before onSdkReady are ignored.

loginSuccess

The user successfully logged in. Handle this event only if your plugin needs to persist credentials for background sync.

logoutSuccess

The user logged out. If your plugin stores user credentials, remove them.

onError

An SDK error occurred. Your plugin can display an error state or notification.

selectionChange

Selection changed (files selected or deselected).

The selected item shape is:

interface SelectedItem {
  id: number;
  fileName: string;
  previewUrl: string;
}

Events from your plugin to the Plugin SDK

Message shape:

{
	receiver: 'pixxio-plugin-sdk';
	method: string;
	parameters?: unknown[];
}

Supported methods:

• setDownloadProgress
• setDownloadComplete
• setDownloadFailed
• login
• logout
• setAllowedFileTypes
• setAllowedDownloadFormats
• showError
• setButtonText
• useDirectLinks
• resetNavigation

Query Parameters

Use these query parameters to configure the SDK initially:

standaloneLogin

Enables separate login flow. If active, the login page does not automatically navigate to the next page and sends login success via PostMessage.

dark

Enables dark mode.

allowedFileTypes

Filters media views by file extension.

allowedDownloadFormats

Restricts selectable download formats. Supported values: original, preview, jpg, png, pdf, tiff, webp.

applicationId

applicationId is mandatory. If you do not have an applicationId yet, contact support: support@pixx.io

multiSelect

Enables or disables multi-select in media views.

hideLinks

Hides links in the SDK. Supported values: mediaspace, help.

selectButtonText

Sets the primary selection button label.

metadata

Controls which metadata fields are returned with downloads.

Note: Only values from importantMetadata are returned.

useDirectLinks

Uses directLinksCreated instead of downloadFiles.

hideSelectionFooter

Hides the selection footer that shows the number of selected files.

hideAvatar

Hides the avatar section in the header.

backgroundColor

Overrides the SDK background color to better match the host plugin UI.

Troubleshooting

onSdkReady never arrives

Possible causes:

• Message listener is registered too late.
• Iframe does not point to https://plugin.pixx.io/static/v1/....

Fix:

• Register window.addEventListener('message', ...) during app startup.
• Verify iframe URL in browser dev tools.

No events arrive in your plugin

Possible causes:

• Wrong event.origin check.
• Missing data.sender === 'pixxio-plugin-sdk' validation.

Fix:

• Always expect https://plugin.pixx.io.
• Validate in this order: event.origin, then data.sender, then data.method.

SDK does not show media

Possible causes:

• Missing applicationId in URL.
• Invalid or not enabled applicationId.

Fix:

• Always send applicationId as query parameter.
• Test with a known valid applicationId.

Selection flow gets stuck after downloadFiles

Possible causes:

• Plugin never sends final download status.

Fix:

• Send setDownloadProgress regularly while downloading.
• At the end, send exactly one of setDownloadComplete or setDownloadFailed.

Query parameters do not work as expected

Possible causes:

• Parameter names are misspelled.
• List values are not passed as repeated query parameters.

Fix:

• Use exact names like allowedFileTypes, allowedDownloadFormats, hideLinks.
• Pass lists as repeated params, e.g. ...&allowedFileTypes=jpg&allowedFileTypes=png.