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:

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

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

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

NameTypeComment
refreshTokenstringThe refresh-token provided by pixx.io
userIdentifierstringThe username or email from the user
mediaspacestringThe 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

NameTypeComment
errorobjectThe error object

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

NameTypeComment
progressnumberProgress 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

NameTypeComment
refreshTokenstringThe refresh-token provided by pixx.io
userIdentifierstringThe username or email from the user
mediaspacestringThe 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

NameTypeComment
fileExtensionsstring[]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

NameTypeComment
formatsstring[]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

NameTypeComment
errorstringThe 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

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