Procedura dettagliata sulla dimostrazione della creazione di un’estensione personalizzata in Fusion

Questa demo illustra come creare un’estensione personalizzata, distribuirla ed eseguirla in Fusion.

Include:

Partendo dal modello anziché da un --standalone-app vuoto, il bootstrap dell’applicazione a pagina singola viene generato automaticamente: index.js, exc-runtime.js, App.js con routing e ErrorBoundary e un esempio di ExtensionRegistration. I passaggi live nella demo consistono nel retargeting della configurazione e nella modifica di due file, che è esattamente il modo in cui è stato creato l’effettivo fusion-uix-guest.

Prima di iniziare

Questa operazione deve essere eseguita una sola volta e può essere eseguita off-camera prima della dimostrazione.

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)

Nell’organizzazione demo devono essere vere due cose:

Passaggio 1: generare l’app dal modello generico

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

Riceverai un set di file, tra cui:

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)

Passaggio 2: aggiungere la libreria guest di Fusion

Il modello include già React, React Spectrum ed exc-app. Aggiungi la libreria che parla con l’host Fusion:

npm install @adobe/uix-guest

Passaggio 3: ridestinare la configurazione a Fusion

Apri app.config.yaml e cambia solo la chiave del punto di estensione dal punto di Experience Cloud Shell a quello di Fusion (lascia il percorso $include immutato):

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

Non è necessario modificare altri elementi nella configurazione. Il nome della cartella dx-excshell-1 è interno e non influisce su Fusion, pertanto è possibile lasciarlo. Rinominare significherebbe anche aggiornare eventuali percorsi di azione. Saltalo per la demo.

Passaggio 4: modificare i file di registrazione e widget

Tutti i percorsi si trovano in src/dx-excshell-1/web-src/src/components/.

ExtensionRegistration.js

Il file generato registra un esempio di Experience Cloud Shell. Sostituisci methods con il contratto Fusion dashboard.getWidget in modo che Fusion conosca il tuo titolo e dove si trova l’interfaccia utente:

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;

Se Constants.js non esiste accanto ad esso, crealo:

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

DashboardWidget.js

Crea questo file. Completa l’handshake e mostra il contesto live di Fusion:

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

Il router generato invia già index / index.html a ExtensionRegistration. Aggiungi una route per il widget e importala:

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

Il percorso della route (widget) deve corrispondere all’hash in getWidget().url (/index.html#/widget). Mantieni index.js / exc-runtime.js generato e il resto di App.js esattamente come scaffolded, perché è l’avvio che desideri che il modello fornisca.

Passaggio 5: generare

aio app build

In questo modo viene compilato il front-end e viene eseguito l’hook dei metadati che genera app-metadata.json. Correggi eventuali errori prima di continuare.

Passaggio 6: distribuisci nell’ambiente di staging

aio console workspace select     # choose Stage
aio app deploy

deploy ospita la tua interfaccia utente sulla rete CDN di Adobe e registra l’endpoint dell’estensione nell’area di lavoro di Stage, consentendo a Fusion di individuarlo. CLI stampa l’URL dell’endpoint, ad esempio https://<project>-stage.adobeio-static.net.

Passaggio 7: attivare il test dello staging e visualizzare l’estensione in Fusion

Iterazione durante la demo

Apporta una modifica, quindi genera e ridistribuisci. La prossima volta che lo aprono, gli utenti visualizzano l’estensione aggiornata.

aio app build && aio app deploy

Vai alla produzione dopo la demo

La fase è sufficiente per la dimostrazione. Per rilasciare l’approvazione a livello di organizzazione, passa all’area di lavoro Produzione, distribuisci e invia la richiesta di approvazione. La richiesta deve essere inviata utilizzando il ruolo Amministratore di sistema. Per informazioni sull’intero processo, vedere Versione in produzione.

Demo talk-track (opzionale)

Durante la demo live potrebbe essere utile effettuare le seguenti operazioni: