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

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

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

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

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

Example

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

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

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

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

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

Example

{
  receiver: 'pixxio-plugin-sdk',
  method: 'setFilterFileExtensions',
  parameters: [['jpg', 'png']]
}

showError

Zeigt einen Fehler als Notification an.

Parameters

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