pixxio-app

pixx.io Plugin SDK

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ümmen.

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/v1/de/
English: https://plugin.pixx.io/static/v1/en/

Kommunikation Plugin <> Plugin SDK

Zur Kommunikations benutzen wir PostMessage.

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

Nachrichten vom Plugin

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

Nachrichten an das Plugin:

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

Empfangen von postMessage-Nachrichten

window.addEventListener('message', (event) => {
  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;
  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;
  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": "downloadFiles",
  "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

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
refreshToken	`string`	The refresh-token provided by pixx.io
userIdentifier	`string`	The username or email from the user
mediaspace	`string`	The domain of the pixx.io mediaspace

Example

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

Example

`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;
}

Example

{
  "sender": "pixxio-plugin-sdk",
  "method": "selectionChange",
  "parameters": [
    [
      {
        "id": 1,
        "fileName": "demo.jpg"
      },
      {
        "id": 2,
        "fileName": "image.png"
      }
    ]
  ]
}

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, userIdentifier, mediaspace]
  },
  '*'
);

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'
}

`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
userIdentifier	`string`	The username or email from the user
mediaspace	`string`	The domain of the pixx.io mediaspace

Example

{
  receiver: 'pixxio-plugin-sdk',
  method: 'login',
  parameters: ['123456789abc', 'admin', '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.

Parameters

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

Example

{
  receiver: 'pixxio-plugin-sdk',
  method: 'setFilterFileExtensions',
  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"]
}

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/v1/de/login?standaloneLogin=true

`dark`

Schaltet das Plugin-SDK in den Dark-Mode.

Example

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

`allowedFileTypes`

Filtert die Medien-Ansichten nach diesen File-Extensions.

Example

https://plugin.pixx.io/static/v1/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.

Example

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

`applicationId`

Die ApplicationId muss mitgegeben werden.

Example

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

`multiSelect`

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

Example

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

`hideLinks`

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

Example

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

`selectButtonText`

Ändert den Text des Auswahl-Buttons.

Example

https://plugin.pixx.io/static/v1/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.

Example

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

`useDirectLinks`

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

Example

https://plugin.pixx.io/static/v1/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/v1/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