Beispielanleitung zum Erstellen einer benutzerdefinierten Erweiterung in Fusion

In dieser Demo wird erläutert, wie Sie eine benutzerdefinierte Erweiterung erstellen, bereitstellen und in Fusion ausführen.

Zu diesem Datensatz gehören:

Ausgehend von der Vorlage und nicht von einer leeren --standalone-app wird der SPA-Bootstrap für Sie generiert: index.js, exc-runtime.js, App.js mit Routing und ErrorBoundary sowie eine ExtensionRegistration. Die Live-Schritte in der Demo bestehen darin, die Konfiguration erneut anzusprechen und zwei Dateien zu bearbeiten, was genau dem entspricht, wie die echte fusion-uix-guest erstellt wurde.

Vorbereitung

Dies muss nur einmal durchgeführt werden und kann vor der Demo außerhalb der Kamera erfolgen.

node --version          # must be 18 or 20
aio --version           # @adobe/aio-cli installed
aio login               # signs you into your Adobe org
aio console org select  # pick the org you'll demo in (same org as Fusion)

In der Demo-Organisation müssen zwei Dinge zutreffen:

Schritt 1: App aus der generischen Vorlage generieren

aio app init my-fusion-extension --template @adobe/generator-app-excshell
cd my-fusion-extension

Sie erhalten eine Reihe von Dateien, einschließlich der folgenden:

my-fusion-extension/
|-- app.config.yaml
|-- src/dx-excshell-1/
    |-- ext.config.yaml
    |-- web-src/src/
        |-- index.js          // SPA bootstrap (exc-app Runtime + React render)
        |-- exc-runtime.js    // Experience Cloud Shell runtime glue
        |-- components/
            |-- App.js                    // Router + ErrorBoundary (generated)
            |-- ExtensionRegistration.js  // sample registration (generated)

Schritt 2: Fusion-Gastbibliothek hinzufügen

Die Vorlage enthält bereits React, React Spectrum und Exc-App. Fügen Sie die Bibliothek hinzu, die mit dem Fusion-Host spricht:

npm install @adobe/uix-guest

Schritt 3: Targeting der Konfiguration auf Fusion

Öffnen Sie app.config.yaml und ändern nur den Schlüssel des Erweiterungspunkts vom Experience Cloud-Shell-Punkt zum Fusion-Pfad (lassen Sie den $include unverändert):

extensions:
  fusion/nav-organization/1:                 # was: dx/excshell/1
    $include: src/dx-excshell-1/ext.config.yaml

Sie müssen nichts anderes in der Konfiguration ändern. Der Ordnername dx-excshell-1 ist intern und wirkt sich nicht auf Fusion aus, sodass Sie ihn beibehalten können. Das Umbenennen würde auch bedeuten, dass alle Aktionspfade aktualisiert werden. Überspringen Sie das für die Demo.

Schritt 4: Registrierungs- und Widget-Dateien bearbeiten

Alle Pfade befinden sich unter src/dx-excshell-1/web-src/src/components/.

ExtensionRegistration.js

Die generierte Datei registriert ein Experience Cloud Shell-Beispiel. Ersetzen Sie die methods durch den Fusion dashboard.getWidget-Vertrag, damit Fusion Ihren Titel und den Wohnort der Benutzeroberfläche kennt:

import { Text } from "@adobe/react-spectrum";
import { register } from "@adobe/uix-guest";
import metadata from "../../../../app-metadata.json";
import { extensionId } from "./Constants";

function ExtensionRegistration() {
  const init = async () => {
    await register({
      id: extensionId,
      metadata,
      methods: {
        dashboard: {
          getWidget() {
            return {
              id: extensionId,
              title: "My Fusion tool",          // label on the Fusion nav button
              description: "Hello from App Builder",
              url: "/index.html#/widget",       // route to the visible UI (4b)
              widgetSize: { defaultWidth: 6, defaultHeight: 6 },
              hideWidgetHeader: false,
            };
          },
        },
      },
    });
  };
  init().catch(console.error);

  return <Text>Registering with Fusion...</Text>;
}

export default ExtensionRegistration;

Wenn Constants.js daneben nicht vorhanden ist, erstellen Sie es:

module.exports = { extensionId: "my-fusion-extension" };

DashboardWidget.js

Erstellen Sie diese Datei. Dadurch wird der Handshake abgeschlossen und der Live Fusion-Kontext angezeigt:

import { useEffect, useState } from "react";
import { Flex, Heading, Text, View } from "@adobe/react-spectrum";
import { attach } from "@adobe/uix-guest";
import { extensionId } from "./Constants";

const KEYS = ["imsOrgId", "imsUserId", "organization", "team", "user"];

export default function DashboardWidget() {
  const [ctx, setCtx] = useState(null);

  useEffect(() => {
    attach({ id: extensionId })
      .then((guest) => {
        const read = () =>
          KEYS.reduce((acc, k) => ({ ...acc, [k]: guest.sharedContext.get(k) }), {});
        setCtx(read());
        guest.addEventListener("contextchange", () => setCtx(read()));
      })
      .catch((e) => console.error("attach failed", e));
  }, []);

  return (
    <View padding="size-300">
      <Heading level={2}>Hello from App Builder</Heading>
      {!ctx ? (
        <Text>Connecting to Fusion...</Text>
      ) : (
        <Flex direction="column" gap="size-100" marginTop="size-200">
          <Text>User: {ctx.user?.name ?? ctx.imsUserId}</Text>
          <Text>Organization: {ctx.organization?.name} (id {ctx.organization?.id})</Text>
          <Text>Team: {ctx.team?.name ?? "-"}</Text>
        </Flex>
      )}
    </View>
  );
}

App.js

Der generierte Router sendet bereits index/index.html an ExtensionRegistration. Fügen Sie eine Route für das Widget hinzu und importieren Sie sie:

import DashboardWidget from "./DashboardWidget";
// ...inside <Routes>, alongside the existing ExtensionRegistration routes:
<Route exact path="widget" element={<DashboardWidget />} />

Der Routenpfad (widget) muss dem Hash in getWidget().url (/index.html#/widget) entsprechen. Behalten Sie die generierten index.js/exc-runtime.js und den Rest der App.js exakt als Strukturvorlage bei, da dies der Bootstrap ist, den Sie von der Vorlage bereitstellen wollten.

Schritt 5: Erstellen

aio app build

Dadurch wird das Frontend kompiliert und der Metadaten-Hook ausgeführt, der app-metadata.json generiert. Beheben Sie etwaige Fehler, bevor Sie fortfahren.

Schritt 6: Staging-Bereitstellung

aio console workspace select     # choose Stage
aio app deploy

deploy hostet Ihre Benutzeroberfläche im CDN von Adobe und registriert den Erweiterungsendpunkt im Staging-Arbeitsbereich, über den Fusion sie ermitteln kann. Die CLI druckt die Endpunkt-URL, z. B. https://<project>-stage.adobeio-static.net.

Schritt 7: Aktivieren Sie das Staging-Testing und zeigen Sie die Erweiterung in Fusion an

Iteration während der Demo

Nehmen Sie eine Änderung vor und erstellen Sie dann erneut und stellen Sie erneut bereit. Benutzer sehen die aktualisierte Erweiterung, wenn sie sie das nächste Mal öffnen.

aio app build && aio app deploy

Nach der Demo zur Produktion wechseln

Die Bühne reicht aus, um es vorzuführen. Um die Veröffentlichung organisationsweit durchzuführen, wechseln Sie zum Arbeitsbereich Produktion , stellen Sie bereit und senden Sie die Genehmigungsanfrage. Die Anfrage muss mit der Rolle eines Systemadministrators gesendet werden. Den vollständigen Prozess finden Sie unter Version für die Produktion.

Demo-Talktrack (optional)

Während der Live-Demo sollten Sie die folgenden Punkte beachten: