Home App

warning: Die Home-App wird in absehbarer Zeit nicht mehr unterstützt. Verwende anstatt einer Kachel in Zukunft ein Widget.

Funktionsumfang der Home-App

Die Home-App ist die zentrale HTTP-Schnittstelle zum Bereitstellen von Features auf der Startseite der d.3ecm-Umgebung.

Verwenden der API-Funktionen

Nachfolgend erfährst du, wie du die Programmierschnittstelle der Home-App für eigene Entwicklungen nutzen kannst.

Bereitstellen von Features

Mit dieser Funktion kannst du Features (Kacheln) bereitstellen, die mit der Home-App auf der Startseite dargestellt werden.

Folgende Anforderungen müssen erfüllt sein, damit die Features deiner App auf der Startseite angezeigt werden:

• Die App muss an der HttpGateway-App registriert sein (nur On-Premises).
• Die App muss eine Linkrelation (featuresdescription) zu den Features ausliefern.
• Die App muss Features mithilfe des Feature-Objekts beschreiben und ausliefern.

info: Die Home-App schickt bei Anfragen an deine App die aktuelle Benutzersitzung mit. Die Home-App verwendet dafür den Header Authorization und ein Bearer-Token. Nähere Informationen dazu findest du in der API-Dokumentation zur Identityprovider-App.

Ausliefern einer Linkrelation (featuresdescription) zu den Features

Damit die Home-App die Features deiner App anzeigt, muss deine App die Features mithilfe der Linkrelation featuresdescription übermitteln. In der Antwort auf die GET-Anfrage der Home-App muss deine App die Linkrelation unter der Basisadresse mit dem Content-Type: application/hal+json ausliefern.

Repräsentation der Ressource:

{
  "_links": {
    "featuresdescription": {
      "href": string
    }
  }
}

info: Beachte auch weitere Informationen zum Aufbau der _links-Eigenschaft.

Eine Antwort im JSON-Format sieht beispielsweise so aus:

{
  "_links": {
    "featuresdescription": {
      "href": "/exampleapp/features"
    }
  }
}

Beschreibung des Features-Objekts

Unter der URL href muss deine App auf eine GET-Anfrage mit dem Anforderungsheader "Accept: application/hal+json" ein JSON-Objekt mit folgenden Angaben ausliefern.

Repräsentation der Ressource:

{
  "features": [
    {
      "id": string,
      "url": string,
      "title": string,
      "subtitle": string,
      "iconURI": string,
      "summary": string,
      "description": string,
      "color": string,
      "badge": object,
      "scriptURL": string,
    }
  ]
}

info: Die Textfarbe der Kachel wird automatisch von der Home-App berechnet. Kacheln mit ähnlichen Hintergrundfarben erhalten möglicherweise unterschiedliche Textfarben.

Nachfolgend ist ein Beispiel für ein Features-Objekt, das ein Feature enthält.

{
  "features": [
    {
      "url": "/exampleapp/awesomefeature",
      "title": "Awesome Feature",
      "subtitle": "subtitle of feature tile",
      "iconURI": "/exampleapp/path/to/icon-thumbsup.png",
      "summary": "short summary of feature functionality",
      "description": "longer description of feature functionality, will be shown on tile hover",
      "color": "#ccc",
      "badge": {
        "count": 3
      },
      "scriptURL": "/exampleapp/feature-update.js"
    }
  ]
}

Aktualisieren einer Kachel per JavaScript

Du kannst eine Kachel auch per JavaScript dynamisch aktualisieren. Dazu muss deine App unterhalb der Eigenschaft scriptURL eine URL zu einer JavaScript-Ressource ausliefern.

Im Kontext des Scripts kannst du dazu die postMessage-Funktion verwenden. Gib für den Schlüssel type den Wert "feature" an und für den Schlüssel data ein Objekt mit den Kachel-Eigenschaften, welche du ändern möchtest.

postMessage({
  type: "feature",
  data: {
    title: "foo",
    subtitle: "bar",
    summary: "new summary",
    description: "new description",
    badge: { count: 2 },
  },
});

info: Das Script wird von einem Web Worker ausgeführt, welcher in einem eigenen Kontext arbeitet. Aus diesem Grund kann innerhalb des Scripts nicht auf das window-Objekt zugegriffen werden.

Die Kachel wird partiell aktualisiert, d.h. es werden nur die übergebenen Werte geändert.

Du kannst folgende Eigenschaften einer Kachel per JavaScript aktualisieren:

• title
• subtitle
• summary
• description
• badge.count

Bereitstellen einer Beispielanwendung

Angenommen, du bist Entwickler einer fiktiven Feedback-App. Du möchtest für die App eine Kachel auf der Startseite bereitstellen.

Die Basisadresse ist https://example.com und die Feedback-App ist unter https://example.com/feedback/ erreichbar.

Die Home-App stellt eine GET-Anfrage an die Feedback-App auf https://example.com/feedback/:

Request

GET /feedback/ HTTP/1.1
Host: example.com
Accept: application/hal+json

Die Feedback-App antwortet darauf mit folgender Beispielantwort:

Response

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/hal+json

{
  "_links": {
    "featuresdescription": {
      "href": "/feedback/features"
    }
  }
}

Die Home-App stellt nun eine zweite Anfrage an die Feedback-App mit der URL https://example.com/feedback/features.

Request

GET /feedback/features
Host: example.com
Accept: application/hal+json

Die Feedback-App antwortet mit folgender Beispielantwort, die ein Feature enthält:

Response

HTTP/1.1 200 OK
Content-Type: application/hal+json

{
  "features": [
    {
      "url": "/exampleapp/awesomefeature",
      "title": "Awesome Feature",
      "subtitle": "subtitle of feature tile",
      "iconURI": "/exampleapp/icons/thumbsup.png",
      "summary": "short summary of feature functionality",
      "description": "longer description of feature functionality, will be shown on tile hover",
      "color": "#ccc",
      "badge": {
        "count": 3
      },
      "scriptURL": "/exampleapp/feature-update.js"
    }
  ]
}

Das Feature der Feedback-App wird nun als Kachel zusammen mit Features weiterer Apps auf dem Startbildschirm angezeigt.

info: Wegen des Cache-Verhaltens der Home-App kann es einen Moment dauern, bis die Kachel auf dem Startbildschirm angezeigt wird.