01 Principle

How does the Plugin SDK work?

The Plugin SDK is embedded into your application as an iframe. The pixx.io user logs in inside this iframe and selects images or videos from their Mediaspace. As soon as the selection is confirmed, the SDK sends a list of the chosen files — including a download link and some metadata — to your application via postMessage.

The actual download of the files is then handled by your application itself. Since the SDK doesn't see this download, it expects ongoing progress updates from you — which you also send back via postMessage.

All messages follow the same schema: { sender: 'pixxio-plugin-sdk', method: string, parameters?: unknown[] }, or with receiver instead of sender in the other direction.

02 Integration

Two ways to integrate

Full control

Directly via iframe + postMessage

You embed the iframe yourself and implement the messaging protocol directly. Works with any frontend stack, regardless of framework or language.

Fastest start

`@pixx.io/jsdk`

Official JavaScript package that handles iframe embedding and message handling for you. Available via npm.

javascript

npm install @pixx.io/jsdk
import '@pixx.io/jsdk/build/pixxio.jsdk.css';
import PIXXIO from '@pixx.io/jsdk';
const picker = new PIXXIO({
  appKey: 'YOUR_APP_KEY',
  appUrl: 'https://your-mediaspace.pixxio.media',
  modal: true,
  element: document.getElementById('picker-target'),
  language: 'en'
});
// the picker opens as a modal or embedded in "element",
// depending on appUrl the login step can be skipped
// if you already know appUrl + refreshToken

03 Configuration

Configuration via query parameters

If you work directly with the iframe URL, the SDK can be controlled via query parameters:

Parameter	Description
standaloneLogin=true	The login page does not redirect automatically, but reports the login success via `postMessage`
dark=true	Switches the Plugin SDK to dark mode
allowedFileTypes	Filters the media view by file extensions, e.g. `?allowedFileTypes=jpg&allowedFileTypes=png`

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

The SDK is available in German and English — controllable via the language path (/de/ or /en/).

04 Working together

In combination with the API & webhooks

🧩

The Plugin SDK only handles the selection of files within your application. For server-side automation — such as automatically fetching metadata or reacting to later changes — you combine it with the REST API and optionally with webhooks.

Ready to build a picker?

The full documentation, including the messaging protocol and all parameters, can be found right at the SDK.

Go to the Plugin SDK documentation → API Webhooks Automation