pixxio-app

pixx.io Plugin SDK

English Documentation: Here you can access the English documentation.

Ziel des Plugin SDKs ist es, die Entwicklung von Plugins zu vereinfachen, indem wir ein User Interface bereitstellen und damit die Kommunikation mit unserem Server auf ein Minimum beschränken. Du musst dich nicht in unsere APIs einarbeiten.

Das Plugin SDK muss in einem Iframe eingebunden werden. Der pixx.io-Nutzer kann sich innerhalb des Plugin SDKs anmelden und Bilder auswählen. Werden Bilder im Plugin SDK vom Nutzer ausgewählt, wird eine Liste der Bilder an das Plugin geschickt. Die Liste enthält einen Download-Link sowie ein paar Metadaten. Das Plugin muss sich dann um den Download der Dateien kümmern.

Da das Plugin sich um den Download der Dateien kümmert, muss es dem Plugin SDK Informationen über den aktuellen Progress des Downloads schicken.

Das Plugin SDK ist in 2 Sprachen verfügbar. Benutze bitte jeweils die vom Nutzer gewünschte Sprache:

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

Schnellstart (in 5 Minuten)

Diese Schritte reichen in der Praxis aus, um das SDK lauffaehig zu integrieren:

Iframe mit passender Sprache und applicationId einbinden.
Auf onSdkReady warten.
Optional Konfiguration senden (setAllowedFileTypes, setAllowedDownloadFormats, setButtonText, useDirectLinks).
Auf downloadFiles oder directLinksCreated reagieren.
Bei Downloads Fortschritt melden (setDownloadProgress, setDownloadComplete oder setDownloadFailed).

Minimales Integrationsbeispiel

<iframe
  id="pixxio-plugin-sdk"
  src="https://plugin.pixx.io/static/v1/de/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', ['Auswahl uebernehmen']);
      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);
}

Typischer Ablauf

onSdkReady empfangen
Optional SDK konfigurieren
Nutzer waehlt Dateien
downloadFiles oder directLinksCreated empfangen
Erfolg oder Fehler an SDK zurueckmelden

Kommunikation Plugin <> Plugin SDK

Zur Kommunikation benutzen wir PostMessage.

Das Plugin SDK sendet und empfängt verschiedene Nachrichten als JavaScript Objekt. Der Aufbau ist dabei immer gleich:

Nachrichten vom Plugin SDK an das Plugin

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

Nachrichten vom Plugin an das Plugin SDK

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

Empfangen von postMessage-Nachrichten

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

Senden von Daten per PostMessage

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

Events vom Plugin SDK an dein Plugin

`downloadFiles`

Der Nutzer hat Dateien ausgewählt und diese müssen nun vom Plugin heruntergeladen werden.

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`

Der Nutzer hat Dateien ausgewählt und diese werden nun als Direct-Link übergeben.

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`

Das Plugin-SDK ist erst nach dieser Nachricht bereit, Nachrichten via PostMessage zu empfangen

Hinweis: Eingehende login-Nachrichten vor onSdkReady werden ignoriert.

Parameters

None

Example

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

`loginSuccess`

Der Nutzer hat sich erfolgreich bei seinem Mediaspace angemeldet. Auf dieses Event muss nur gehört werden, wenn das Plugin die Nutzerdaten verwalten muss, um zum Beispiel einen Sync im Hintergrund zu ermöglichen.

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`

Der Nutzer hat sich bei seinem Mediaspace abgemeldet. Auf dieses Event muss nur gehört werden, wenn das Plugin die Nutzerdaten verwalten muss. Gespeicherte Nutzerdaten müssen dann gelöscht werden.

Parameters

None

Example

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

`onError`

Es ist ein Fehler im Plugin-SDK aufgetreten. Durch dieses Callback hat das native Plugin die Möglichkeit einen Fehler anzuzeigen.

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`

Der Nutzer hat eine oder mehrere Dateien aus- oder abgewählt. Diese Nachricht wird gesendet, sobald sich die Auswahl ändert.

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 vom Plugin an das Plugin SDK

Du kannst auch Nachrichten an das Plugin SDK senden. Die Nachrichten müssen dabei folgenden Aufbau haben:

{
  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'
);

Folgende Events versteht das Plugin SDK aktuell:

`setDownloadProgress`

Benachrichte das Plugin SDK über den aktuellen Fortschritt des Downloads. Da der Download bei großen Dateien ein wenig dauern kann, empfehlen wir, aller 5 Sekunden ein Update zu senden.

Parameters

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

Example

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

`setDownloadComplete`

Benachrichtige das Plugin SDK, dass der Download der Dateien abgeschlossen ist.

Parameters

None

Example

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

`setDownloadFailed`

Benachrichtige das Plugin SDK, dass der Download der Dateien fehlgeschlagen ist.

Parameters

None

Example

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

`login`

Melde dich im Plugin SDK an. Diese Funktion wird nur benötigt, wenn der Login von der Auswahl der Medien getrennt ist.

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`

Meldet den Nutzer im Plugin-SDK ab.

Parameters

None

Example

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

`setAllowedFileTypes`

Setzt einen Filter auf allen Medien-Ansichten nach diesen File-Extensions. Dieser kann vom Nutzer nicht entfernt werden.

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`

Schränkt die zur Verfügung stehenden Download-Optionen ein. Mögliche Werte sind 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`

Zeigt einen Fehler als Notification an.

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`

Setzt den Text des primären Buttons im Footer des Plugin SDK.

Parameters

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

Example

{
  receiver: 'pixxio-plugin-sdk',
  method: 'setButtonText',
  parameters: ['Auswahl übernehmen']
}

`useDirectLinks`

Aktiviert oder deaktiviert den Modus für Direct Links zur Laufzeit.

Parameters

Name	Type	Comment
useDirectLinks	`boolean`	true: Direct Links, false: regulärer Download

Example

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

`resetNavigation`

Setzt die Navigation im Plugin SDK auf die Startansicht zurück.

Parameters

None

Example

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

Query Parameter

Um das Plugin-SDK initial zu konfigurieren stehen eine Reihe von Query-Parametern zur verfügung:

`standaloneLogin`

Wenn der Login separat ausgeführt werden soll. Ist dieser Schalter aktiv, leitet die Login-Seite nicht automatisch zur nächsten Seite weiter. Statdessen übermittelt sie den Login-Erfolg via PostMessage.

Example

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

`dark`

Schaltet das Plugin-SDK in den Dark-Mode.

Example

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

`allowedFileTypes`

Filtert die Medien-Ansichten nach diesen File-Extensions.

Example

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

`allowedDownloadFormats`

Filtert die Auswahl der möglichen Formate zum Herunterladen von Dateien. Nur die mitgegebenen Formate stehen zur Auswahl. Wenn kein Wert angegeben wird, stehen alle Formate zur Auswahl. Mögliche Werte sind original, preview, jpg, png, pdf, tiff und webp.

Example

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

`applicationId`

Die applicationId ist Pflicht und muss immer mitgegeben werden. Wenn du noch keine applicationId hast, kannst du diese bei unserem Support anfragen: support@pixx.io

Example

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

`multiSelect`

Ob Multi-Select in der Medienansicht möglich ist oder nicht.

Example

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

`hideLinks`

Blendet diverse Links innerhalb des SDK aus. Mögliche Werte sind mediaspace und help.

Example

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

`selectButtonText`

Ändert den Text des Auswahl-Buttons.

Example

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

`metadata`

Steuert, welche Metadaten beim Download mitgeschickt werden. Als Wert können alle Namen der im Mediaspace konfigurierten Metadaten genutzt werden.

Hinweis: Es werden nur Werte aus den wichtigen Metadaten (importantMetadata) der Datei übertragen.

Example

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

`useDirectLinks`

Es wird das directLinksCreated statt dem downloadFiles Event gefeuert. Im Ergebnis stehen dann Direct-Links (siehe directLinksCreated).

Example

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

`hideSelectionFooter`

Blendet den Selection-Footer im Plugin-SDK aus, der normalerweise die Anzahl der ausgewählten Dateien anzeigt.

Example

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

`hideAvatar`

Blendet den Avatar-Bereich im Header des Plugin-SDK aus.

Example

https://plugin.pixx.io/static/v1/de/media?hideAvatar=true

`backgroundColor`

Überschreibt die Hintergrundfarbe des SDK. Geeignet für eine visuelle Anpassung an das Host-Plugin.

Example

https://plugin.pixx.io/static/v1/de/media?backgroundColor=%23f4f6f8

Troubleshooting

`onSdkReady` kommt nie an

Mögliche Ursachen:

Der Listener wird zu spät registriert.
Das Iframe zeigt nicht auf https://plugin.pixx.io/static/v1/....

So behebst du es:

Registriere window.addEventListener('message', ...) direkt beim App-Start.
Prüfe die Iframe-URL im Browser-Inspector.

Es kommen keine Events im Plugin an

Mögliche Ursachen:

event.origin wird auf einen falschen Host geprüft.
Der Sender wird nicht auf data.sender === 'pixxio-plugin-sdk' geprüft.

So behebst du es:

Verwende als erwartete Origin immer https://plugin.pixx.io.
Prüfe zuerst event.origin, dann data.sender, dann data.method.

Das SDK zeigt keine Medien an

Mögliche Ursachen:

applicationId fehlt in der URL.
applicationId ist falsch oder nicht freigeschaltet.

So behebst du es:

Übergib immer applicationId als Query-Parameter.
Teste mit einer bekannten, gültigen applicationId.

Der Auswahl-Flow hängt nach `downloadFiles`

Mögliche Ursachen:

Das Plugin sendet keinen Abschlussstatus zurück.

So behebst du es:

Sende während des Downloads regelmäßig setDownloadProgress.
Sende am Ende immer genau eines von setDownloadComplete oder setDownloadFailed.

Query-Parameter greifen nicht wie erwartet

Mögliche Ursachen:

Parameter-Namen sind falsch geschrieben.
Werte werden nicht als wiederholte Query-Parameter übergeben (z. B. bei Listen).

So behebst du es:

Verwende exakt die dokumentierten Namen wie allowedFileTypes, allowedDownloadFormats, hideLinks.
Übergib Listen als mehrfachen Parameter, z. B. ...&allowedFileTypes=jpg&allowedFileTypes=png.

CHANGELOG

v2 - ⚠️ Breaking Changes

Die Parameter-Struktur wurde von positionalen Argumenten auf ein einzelnes Konfigurationsobjekt umgestellt.

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

Details:

❌ userIdentifier wurde entfernt.
🔄 mediaspace wurde in mediaspaceDomain umbenannt.
📦 Parameter werden nun als Objekt übergeben, nicht mehr als flache Liste.