Weegloo Docs - App-Erstellung

Um eine selbst erstellte Web-App als Market App in den Marktplatz hochzuladen, müssen Sie die App zunächst bauen und das daraus entstehende Ergebnis vorbereiten. Zu diesem Vorgang gehört es, mit HTML und JavaScript eine statische Website zu bauen und das Build-Ergebnis auf der Kommandozeile zu überprüfen.

Eine Market App ist eine App, die Sie in den Marktplatz hochladen und in einem anderen Space installieren. In ihrer Form ist sie eine statische Web-App wie beim Web Hosting. Wenn Sie ein vorab gebautes Bündel von Bildschirmdateien hochladen, erscheinen diese Bildschirme genau so, sobald ein Besucher die Seite aufruft.

Es gibt einen Unterschied zu einer gewöhnlichen Web-App, und daraus ergibt sich eine Regel, die Sie beim Bauen einhalten müssen. Diese Seite behandelt diesen Unterschied, die Regel und die Überprüfung vor dem Hochladen.

Beim Installieren werden die Ressourcen in den Space der installierenden Person kopiert

Wenn eine Market App installiert wird, werden nicht nur die App-Bildschirme kopiert, sondern auch die Ressourcen, die beim Veröffentlichen mit ausgewählt wurden (Content Type, Content, Media usw.) werden in den Space der installierenden Person kopiert. Stellen Sie sich vor, Sie haben eine Produktkatalog-App für ein Bekleidungsgeschäft erstellt und hochgeladen. Wenn jemand diese App installiert, werden zusammen mit den App-Bildschirmen auch der Produkt-Content Type und das Produkt-Content in den Space dieser Person kopiert.

Die kopierten Ressourcen erhalten im installierenden Space eine neue Kennung. Auch das Delivery Access Token, das zum Lesen der Inhalte verwendet wird, wird im installierenden Space neu erstellt. Deshalb liest die installierte App nicht aus dem Space des Erstellers, sondern aus ihrer eigenen Kopie, die in den Space der installierenden Person kopiert wurde. Nach Abschluss der Installation funktioniert die App allein mit den Ressourcen des installierenden Space.

Warum die Zugriffsinformationen fest in den Build eingebettet werden

Eine installierte Market App hat keinen Server. Da es sich um statisches Hosting wie beim Web Hosting handelt, gibt es keine Server-Laufzeit, die für jede Anfrage den Bildschirm berechnet, und die Inhalte werden geholt, indem der Browser direkt die WEEGLOO Delivery API (CDA, Content Delivery API) aufruft. Deshalb muss im Build-Ergebnis (den Bildschirmdateien) schriftlich festgehalten sein, aus welchem Space was und mit welchem Berechtigungswert gelesen werden soll.

Das Problem ist, dass die Ressourcen beim Installieren, wie zuvor beschrieben, unter einer neuen Kennung kopiert werden. Die in den Build-Dateien eingetragenen Werte sind die Kennung und das Token des Ersteller-Space, doch am Installationsort muss die neu kopierte Kopie gelesen werden. Bleiben die alten Werte unverändert, zeigt die App auf die falsche Stelle.

Deshalb tauscht WEEGLOO diese Werte bei der Installation stellvertretend aus. Beim Veröffentlichen wird im Build-Text vorab gesucht, an welcher Stelle die Kennung, das Token und die Ressourcen-Kennungen des Ersteller-Space eingetragen sind, und bei der Installation wird diese Stelle durch den neuen Wert der Kopie im installierenden Space ersetzt. Dadurch zeigt die installierte App automatisch auf den installierenden Space.

Dieser Austausch findet nur für die Ressourcen statt, die mit der App zusammen eingebunden wurden. Daher müssen Sie die Ressourcen, die ein Bildschirm liest (Content Type, Delivery Access Token usw.), beim Veröffentlichen lückenlos mit einbinden. Lassen Sie etwas aus, wird diese Kennung nicht ersetzt und bleibt am Installationsort als falscher Wert zurück. Was Sie mit einbinden müssen, wird in der Ressourcenauswahl unter App-Veröffentlichung behandelt.

Dieser automatische Austausch hat eine Voraussetzung: Der Wert muss als eine einzige, unversehrte Zeichenfolge genau so im Build-Text enthalten sein. Denn der Veröffentlichungsschritt sucht diese Zeichenfolge buchstabengetreu und notiert ihre Position. Wenn Sie den Wert zerteilen, ihn zur Laufzeit erzeugen oder von außen beziehen lassen, kann der Veröffentlichungsschritt ihn nicht finden, und dann findet bei der Installation auch kein Austausch statt, sodass die installierte App nicht funktioniert.

Es gibt drei Werte, die fest in den Build eingebettet (und bei der Installation ersetzt) werden.

Die sys.id des ursprünglichen Space (spaceId): aus welchem Space gelesen werden soll.
Das Delivery Access Token des ursprünglichen Space: ein schreibgeschützter Berechtigungswert, mit dem die veröffentlichten Inhalte dieses Space gelesen werden können.
Die sys.id der Ressourcen, auf die die App verweist: zum Beispiel die sys.id des Content Type, der die Produkte enthält, also die Ressourcen-Kennungen, auf die der Client-Code zeigt.

Werte als Literal inline einbetten

Entscheidend ist, dass die drei oben genannten Werte im Build-Ergebnis als eine einzige, unversehrte Zeichenfolgen-Literal (intact literal substring) erscheinen müssen. Wenn Sie die gebaute Textdatei (JS, HTML, JSON usw.) öffnen, muss der Wert unzerteilt und unverändert genau so an einem Stück sichtbar sein. Nur dann kann der Veröffentlichungsschritt diesen Wert finden und seine Position notieren, und der Installationsschritt kann diese Stelle durch den neuen Wert ersetzen.

Im Folgenden ein Beispiel für eine im Client-Code abgelegte Konfiguration. Die Werte zeigen nur das Format als Beispiel und müssen durch echte Berechtigungswerte ersetzt werden.

// weegloo.config.js: Diese Werte erscheinen unverändert im Build-Ergebnis
export const WEEGLOO = {
  spaceId: "spc_xxxxxxxxxxxxxxxx",                 // sys.id des ursprünglichen Space
  deliveryAccessToken: "dat_xxxxxxxxxxxxxxxxxxxx",  // Delivery Access Token des ursprünglichen Space
  productContentTypeId: "ct_xxxxxxxxxxxx",          // sys.id des Content-Type, den die App liest
};

Der Browser ruft mit diesen Werten direkt die CDA auf.

fetch(`https://cda.weegloo.com/v1/spaces/${WEEGLOO.spaceId}/contents`, {
  headers: { Authorization: `Bearer ${WEEGLOO.deliveryAccessToken}` },
});

Die folgenden Vorgehensweisen dürfen Sie nicht verwenden. Sie alle führen dazu, dass der Wert nicht als unversehrtes Literal im Build-Ergebnis verbleibt, sodass der Veröffentlichungsschritt den Wert nicht finden kann. Dann findet bei der Installation kein Austausch statt, und die installierte App kann die Kopie in ihrem eigenen Space nicht lesen.

Abfrage von Laufzeit-Umgebungsvariablen. Eine installierte App hat keinen Server und keine Laufzeitumgebung, die den Wert injizieren könnte, und der Wert verbleibt auch nicht buchstäblich im Build-Text.
```
// Nicht möglich: Diese Umgebungsvariable existiert am Installationsort nicht
deliveryAccessToken: process.env.DELIVERY_ACCESS_TOKEN
```
Holen per Laufzeit-fetch. Wenn Sie den Wert von irgendwoher beziehen lassen, verbleibt er nicht im Build-Text, und es gibt auch keine Stelle, von der er bezogen werden könnte.

Zerteilen durch Zeichenketten-Verkettung. Der Wert erscheint nicht an einem Stück, sodass der Veröffentlichungsschritt ihn nicht findet.

// Nicht möglich: "dat_xxxxxxxxxxxxxxxxxxxx" verbleibt nicht als eine einzige Substring im Build-Ergebnis
deliveryAccessToken: "dat_" + "xxxxxxxxxxxxxxxxxxxx"

Als Platzhalter oder leer lassen. Das Befüllen des Werts erledigt WEEGLOO bei der Installation. Dieser Austausch ersetzt jedoch den tatsächlichen, im Build eingebetteten Wert an seiner Stelle, sodass es bei einem Leerfeld oder einer Behelfsmarkierung keinen Wert zum Finden gibt und somit kein Austauschziel vorhanden ist. Zum Zeitpunkt der Erstellung des Build-Ergebnisses muss der echte Wert buchstabengetreu enthalten sein.

Legen Sie die Werte unbedingt in einer Textdatei (JS, HTML, JSON usw.) ab. In Binärdateien wie Bildern oder Schriften dürfen Sie sie nicht einfügen. Das Finden und Ersetzen der Werte findet nur in Textdateien statt.

Auch der Bundler ist zu überprüfen. Manche Bundler zerteilen oder verändern Zeichenfolgen-Literale im Zuge der Optimierung. Verlassen Sie sich nicht allein auf den Quellcode, sondern öffnen Sie das tatsächliche Build-Ergebnis und prüfen Sie, ob der Wert als unversehrtes Literal verbleibt (siehe nächster Abschnitt).

Das Token mit minimalen Rechten ausstellen

Das in den Build eingebettete Delivery Access Token wird im Browser unmittelbar offengelegt. Jeder, der die App installiert, kann diesen Wert in den Build-Dateien der App sehen (ebenso wird das Token offengelegt, das nach der Installation in diesem Space neu erstellt wird). Daher müssen Sie dieses Token mit einer minimal berechtigten SpaceRole ausstellen, die nur die Content Type lesen kann, die die App tatsächlich lesen muss. Stellen Sie es nicht mit der Rolle Administrator aus. Wird ein Token mit Administratorrechten im Browser offengelegt, ist der gesamte ursprüngliche Space gefährdet.

Wie Sie eine minimal berechtigte SpaceRole erstellen und mit dieser Rolle ein Delivery Access Token ausstellen, wird unter Token behandelt.

Überprüfung vor der Veröffentlichung

Prüfen Sie vor dem Hochladen nicht im Kopf, sondern im tatsächlichen Build-Ergebnis, ob die Werte korrekt eingetragen sind. Suchen Sie im gebauten Ordner mit grep jeweils nach der ursprünglichen spaceId, dem Token und der Ressourcen-sys.id und sehen Sie nach, ob sie als unversehrtes Literal erscheinen.

grep -r "DATxxxxxxxxxxxxxxxx" dist/

Es genügt, wenn der gesuchte Wert im Build-Ergebnis an einem Stück (unzerteilt und unverändert) erscheint. Prüfen Sie dies für alle drei eingebetteten Werte (spaceId, Delivery Access Token, referenzierte Ressourcen-sys.id). Wird auch nur einer davon von grep nicht erfasst, kann der Veröffentlichungsschritt diesen Wert ebenfalls nicht finden und er wird bei der Installation nicht ersetzt (entweder hat der Bundler den Wert verändert oder er ist durch eine Laufzeitabfrage entfallen). Greifen Sie in diesem Fall auf den vorangehenden Abschnitt „Werte als Literal inline einbetten" zurück und korrigieren Sie es so, dass der Wert als unversehrtes Literal verbleibt.

Einschränkungen des statischen Builds

Das Build-Ergebnis einer Market App unterliegt denselben statischen Einschränkungen wie das Web Hosting.

Es gibt keine Server-Laufzeit. Sie müssen als statischen Export bauen (kein SSR).
Nach dem Entpacken dürfen es höchstens 100 Dateien sein.
Ganz oben im Bündel (im Stammverzeichnis) muss eine index.html liegen.
Aufrufe der WEEGLOO API (CDA usw.) erfolgen direkt aus dem Browser.

Ausführliche statische Einschränkungen und die Regeln für das Dateibündel werden unter Website-Bereitstellung behandelt.

Die gebauten Bildschirme werden im App Bundle eingebunden

Das geprüfte Build-Ergebnis wird beim Veröffentlichen in das App Bundle (ein nach Versionen gebündeltes Paket der App) eingebunden. Auch die im Veröffentlichungsbildschirm mit ausgewählten Ressourcen werden in dasselbe Bündel eingebunden und bei der Installation in den installierenden Space kopiert. Das Vorgehen zum Veröffentlichen und Hochzählen der Version wird unter App-Veröffentlichung behandelt.

Wenn die App eigene Mitglieder aufnimmt

Bis hierher ging es um den Fall, dass öffentliche Inhalte, die jeder lesen darf, per CDA gelesen werden. Wenn die App eine eigene Mitgliedsregistrierung und -anmeldung aufnimmt, verwenden Sie ServiceLogin und das offizielle Client-SDK. In diesem Fall ruft der Browser nicht die CDA, sondern die ACDA (App Content Delivery API) mit dem Token des Mitglieds auf. Konfiguration und Anbindung werden unter Service-Mitglieder-Anmeldung behandelt.

Die Authentifizierungsweise einer installierten Market App behandelt App Auth, und die Nutzer mit Zugriffsrecht auf die installierte App behandelt App Member.

Nächste Schritte

App-Veröffentlichung: behandelt das Vorgehen im Content-Studio, um die erstellte App (App Bundle) in den Marktplatz hochzuladen.
Website-Bereitstellung: behandelt die Grundlagen des Web Hosting wie statischen Build, das Limit von 100 Dateien und die index.html im Stammverzeichnis.
Token: behandelt, wie Sie ein in den Build inline einzubettendes Delivery Access Token mit einer minimal berechtigten SpaceRole ausstellen.
API-Referenz: behandelt technische Spezifikationen wie das Anfrageformat der CDA (Delivery API), die App-Bildschirme beim Laden von Inhalten aufrufen, und bei Apps mit eigenen Mitgliedern der ACDA.