pixxio-app

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. You don't need to learn our APIs.

The Plugin SDK must be embedded in an iframe. A pixx.io user can log in inside the Plugin SDK and select files. When files are selected in the Plugin SDK, a list of files is sent to your plugin. The list contains a download link and some metadata. Your plugin is then responsible for downloading the files.

Because your plugin handles the file downloads, it must send download progress information 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/v2/de/
English: https://plugin.pixx.io/static/v2/en/

Quick Start (5 minutes)

These steps are sufficient for a working integration:

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

Minimal integration example

<iframe
  id="pixxio-plugin-sdk"
  src="https://plugin.pixx.io/static/v2/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

Receive onSdkReady
Optionally configure SDK
User selects files
Receive downloadFiles or directLinksCreated
Send success or failure status back to the SDK

Communication Plugin <> Plugin SDK

We use PostMessage for communication.

The Plugin SDK sends and receives various messages as JavaScript objects. The structure is always the same:

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.

Parameters

Name	Type	Comment
files	`array`	The files to download

The type of files looks like this:

interface File {
  id: number;
  downloadURL: string;
  fileName: string;
  fileSize: number;
  originalWidth: number;
  originalHeight: number;
  previewFileWidth: number;
  previewFileHeight: number;
  downloadFormat: string; // original | preview | the file extension
  subject: string | undefined;
  description: string | undefined;
  metadata?: { [key: string]: any };
  licenseReleases: {
    expires: string;
    licenseRelease: {
      license: {
        provider: string;
      };
      name: string;
    };
  }[];
}

Example

{
  "sender": "pixxio-plugin-sdk",
  "method": "downloadFiles",
  "parameters": [
    {
      "id": 1,
      "downloadURL": "https://demo.px.media/.../demo.jpg",
      "fileName": "demo.jpg",
      "fileSize": 223651
    },
    {
      "id": 2,
      "downloadURL": "https://demo.px.media/.../demo.jpg",
      "fileName": "demo.jpg",
      "fileSize": 515546
    }
  ]
}

`directLinksCreated`

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

Parameters

Name	Type	Comment
files	`array`	The files with direct links

The type of files looks like this:

interface File {
  id: number;
  directLink: string;
  fileName: string;
  fileSize: number;
  originalWidth: number;
  originalHeight: number;
  previewFileWidth: number;
  previewFileHeight: number;
  directLinkFormat: string; // original | preview | the file extension
  subject: string | undefined;
  description: string | undefined;
  metadata?: { [key: string]: any };
  licenseReleases: {
    expires: string;
    licenseRelease: {
      license: {
        provider: string;
      };
      name: string;
    };
  }[];
}

Example

{
  "sender": "pixxio-plugin-sdk",
  "method": "directLinksCreated",
  "parameters": [
    {
      "id": 1,
      "directLink": "https://demo.px.media/.../demo.jpg",
      "fileName": "demo.jpg",
      "fileSize": 223651
    },
    {
      "id": 2,
      "directLink": "https://demo.px.media/.../demo.jpg",
      "fileName": "demo.jpg",
      "fileSize": 515546
    }
  ]
}

`onSdkReady`

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

Note: Incoming login messages before onSdkReady are ignored.

Parameters

None

Example

{
  "sender": "pixxio-plugin-sdk",
  "method": "onSdkReady",
  "parameters": []
}

`loginSuccess`

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

Parameters

Name	Type	Comment
mediaspaceDomain	`string`	The domain of the pixx.io mediaspace
refreshToken	`string`	The refresh-token provided by pixx.io

Example

{
  "sender": "pixxio-plugin-sdk",
  "method": "loginSuccess",
  "parameters": [
    {
      "mediaspaceDomain": "demo.px.media",
      "refreshToken": "1213456789abc"
    }
  ]
}

`logoutSuccess`

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

Parameters

None

Example

{
  "sender": "pixxio-plugin-sdk",
  "method": "logoutSuccess"
}

`onError`

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

Parameters

Name	Type	Comment
error	`object`	The error object

Example

{
  "sender": "pixxio-plugin-sdk",
  "method": "onError",
  "parameters": [
    {
      "errorCode": 1234,
      "errorMessage": "This is an error"
    }
  ]
}

`selectionChange`

The user selected or deselected one or more files. This message is sent whenever the selection changes.

Parameters

Name	Type	Comment
selectedItems	`array`	The currently selected items

The type of selectedItems looks like this:

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

Example

{
  "sender": "pixxio-plugin-sdk",
  "method": "selectionChange",
  "parameters": [
    [
      {
        "id": 1,
        "fileName": "demo.jpg",
        "previewUrl": "https://demo.px.media/.../preview1.jpg"
      },
      {
        "id": 2,
        "fileName": "image.png",
        "previewUrl": "https://demo.px.media/.../preview2.jpg"
      }
    ]
  ]
}

Events from your plugin to the Plugin SDK

You can also send messages to the Plugin SDK. Messages must have the following structure:

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

Example:

iframe.contentWindow.postMessage(
  {
    receiver: 'pixxio-plugin-sdk',
    method: 'login',
    parameters: [
      {
        refreshToken: '123456789abc',
        mediaspaceDomain: 'demo.px.media'
      }
    ]
  },
  'https://plugin.pixx.io'
);

The Plugin SDK currently supports the following events:

`setDownloadProgress`

Notify the Plugin SDK about the current download progress. For large files, we recommend sending an update every 5 seconds.

Parameters

Name	Type	Comment
progress	`number`	Progress in percent e.g. 50% => 50

Example

{
  "receiver": "pixxio-plugin-sdk",
  "method": "setDownloadProgress",
  "parameters": [25]
}

`setDownloadComplete`

Notify the Plugin SDK that the file downloads are complete.

Parameters

None

Example

{
  "receiver": "pixxio-plugin-sdk",
  "method": "setDownloadComplete"
}

`setDownloadFailed`

Notify the Plugin SDK that the file downloads failed.

Parameters

None

Example

{
  "receiver": "pixxio-plugin-sdk",
  "method": "setDownloadFailed"
}

`login`

Parameters

Name	Type	Comment
refreshToken	`string`	The refresh-token provided by pixx.io
mediaspaceDomain	`string`	The domain of the pixx.io mediaspace

Example

{
  "receiver": "pixxio-plugin-sdk",
  "method": "login",
  "parameters": [
    {
      "refreshToken": "123456789abc",
      "mediaspaceDomain": "demo.px.media"
    }
  ]
}

`logout`

Log out the user from the Plugin SDK.

Parameters

None

Example

{
  "receiver": "pixxio-plugin-sdk",
  "method": "logout",
  "parameters": []
}

`setAllowedFileTypes`

Set a filter on all media views by file extensions. Users cannot remove this filter.

Parameters

Name	Type	Comment
fileExtensions	`string[]`	A list of file extensions e.g. ['jpg', 'png']

Example

{
  "receiver": "pixxio-plugin-sdk",
  "method": "setAllowedFileTypes",
  "parameters": [["jpg", "png"]]
}

`setAllowedDownloadFormats`

Restrict available download options. Supported values are original, preview, jpg, png, pdf, tiff, webp.

Parameters

Name	Type	Comment
formats	`string[]`	A list of file extensions e.g. ['jpg', 'png']

Example

{
  "receiver": "pixxio-plugin-sdk",
  "method": "setAllowedDownloadFormats",
  "parameters": [["jpg", "png"]]
}

`showError`

Display an error as a notification.

Parameters

Name	Type	Comment
error	`string`	The error message for the user

Example

{
  "receiver": "pixxio-plugin-sdk",
  "method": "showError",
  "parameters": ["This is an error"]
}

`setButtonText`

Set the text of the primary button in the footer of the Plugin SDK.

Parameters

Name	Type	Comment
text	`string`	The text shown on the button

Example

{
  "receiver": "pixxio-plugin-sdk",
  "method": "setButtonText",
  "parameters": ["Apply selection"]
}

`useDirectLinks`

Enable or disable direct links mode at runtime.

Parameters

Name	Type	Comment
useDirectLinks	`boolean`	true: direct links, false: regular download

Example

{
  "receiver": "pixxio-plugin-sdk",
  "method": "useDirectLinks",
  "parameters": [true]
}

`resetNavigation`

Reset navigation in the Plugin SDK to the start view.

Parameters

None

Example

{
  "receiver": "pixxio-plugin-sdk",
  "method": "resetNavigation"
}

Query Parameters

To initially configure the Plugin SDK, you can use a number of query parameters:

`standaloneLogin`

If login should be performed separately. If this parameter is active, the login page does not automatically navigate to the next page. Instead, it sends the login success via PostMessage.

Example

https://plugin.pixx.io/static/v2/en/login?standaloneLogin=true

`dark`

Switches the Plugin SDK to dark mode.

Example

https://plugin.pixx.io/static/v2/en/login?dark=true

`allowedFileTypes`

Filters media views by file extensions.

Example

https://plugin.pixx.io/static/v2/en/media?allowedFileTypes=jpg&allowedFileTypes=png&allowedFileTypes=tiff

`allowedDownloadFormats`

Filters the selection of possible formats for downloading files. Only the formats provided are available for selection. If no value is specified, all formats are available. Supported values are original, preview, jpg, png, pdf, tiff, and webp.

Example

https://plugin.pixx.io/static/v2/en/media?allowedDownloadFormats=jpg&allowedDownloadFormats=png&allowedDownloadFormats=tiff

`applicationId`

The applicationId is mandatory and must always be provided. If you don't have an applicationId yet, you can request one from our support: support@pixx.io

Example

https://plugin.pixx.io/static/v2/en/media?applicationId=sadfjhoahsdfosahf

`multiSelect`

Whether multi-select is possible in the media view or not.

Example

https://plugin.pixx.io/static/v2/en/media?multiSelect=true

`hideLinks`

Hides various links within the SDK. Supported values are mediaspace and help.

Example

https://plugin.pixx.io/static/v2/en/media?hideLinks=mediaspace&hideLinks=help

`selectButtonText`

Changes the text of the selection button.

Example

https://plugin.pixx.io/static/v2/en/media?selectButtonText=Submit

`metadata`

Controls which metadata is sent with the download. The values used can be any names of metadata configured in the mediaspace.

Note: Only values from the important metadata (importantMetadata) of the file are transferred.

Example

https://plugin.pixx.io/static/v2/en/media?metadata=Alt-Text&metadata=Custom_Field

`useDirectLinks`

The directLinksCreated event is triggered instead of the downloadFiles event. As a result, direct links (see directLinksCreated) are then available.

Example

https://plugin.pixx.io/static/v2/en/media?metadata=Alt-Text&useDirectLinks=true

`hideSelectionFooter`

Hides the selection footer in the Plugin SDK, which normally shows the number of selected files.

Example

https://plugin.pixx.io/static/v2/en/media?hideSelectionFooter=true

`hideAvatar`

Hides the avatar section in the header of the Plugin SDK.

Example

https://plugin.pixx.io/static/v2/en/media?hideAvatar=true

`backgroundColor`

Overrides the SDK background color. Suitable for visual adaptation to the host plugin.

Example

https://plugin.pixx.io/static/v2/en/media?backgroundColor=%23f4f6f8

Troubleshooting

`onSdkReady` never arrives

Possible causes:

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

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.

CHANGELOG

v2 - ⚠️ Breaking Changes

The parameter structure was changed from positional arguments to a single configuration object.

v1: parameters: [refreshToken, userIdentifier, mediaspace]
v2: parameters: [{ refreshToken: string, mediaspaceDomain: string }]

Details:

❌ userIdentifier was removed.
🔄 mediaspace was renamed to mediaspaceDomain.
📦 Parameters are now passed as an object, no longer as a flat list.