Tutorial de demostración sobre la creación de una extensión personalizada en Fusion

Esta demostración le guiará por la creación de una extensión personalizada, su implementación y su ejecución en Fusion.

Incluye:

Comenzar desde la plantilla en lugar de un --standalone-app vacío significa que se genera el bootstrap de la SPA para usted: index.js, exc-runtime.js, App.js con el enrutamiento y ErrorBoundary, y una muestra ExtensionRegistration. Los pasos activos de la demostración son redireccionar la configuración y editar dos archivos, que es exactamente como se creó el fusion-uix-guest real.

Antes de comenzar

Esto solo debe hacerse una vez, y puede hacerse fuera de la cámara antes de la demostración.

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)

Dos cosas deben ser ciertas en la organización de demostración:

Paso 1: Generar la aplicación a partir de la plantilla genérica

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

Obtendrá un conjunto de archivos, incluidos los siguientes:

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)

Paso 2: Añadir la biblioteca de invitados de Fusion

La plantilla ya incluye React, React Spectrum y exc-app. Añada la biblioteca que hable con el host de Fusion:

npm install @adobe/uix-guest

Paso 3: Reasigne la configuración a Fusion

Abra app.config.yaml y cambie solo la clave de punto de extensión del punto de shell de Experience Cloud al de Fusion (deje la ruta de acceso $include tal cual):

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

No es necesario cambiar nada más en la configuración. El nombre de carpeta dx-excshell-1 es interno y no afecta a Fusion, por lo que puede dejarlo. Cambiar el nombre también significaría actualizar cualquier ruta de acción. Omita eso para la demostración.

Paso 4: Editar los archivos de registro y widget

Todas las rutas son de menos de src/dx-excshell-1/web-src/src/components/.

ExtensionRegistration.js

El archivo generado registra una muestra de Experience Cloud Shell. Reemplace su methods por el contrato de Fusion dashboard.getWidget para que Fusion sepa su título y dónde se encuentra la interfaz de usuario:

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;

Si Constants.js no existe al lado, créelo:

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

DashboardWidget.js

Cree este archivo. Completa el protocolo de enlace y muestra el contexto de Fusion activo:

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

El enrutador generado ya envía index / index.html a ExtensionRegistration. Añada una ruta para el widget e impórtelo:

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

La ruta de acceso de ruta (widget) debe coincidir con el hash de getWidget().url (/index.html#/widget). Mantenga el index.js / exc-runtime.js generado y el resto de App.js exactamente como se encuentra en el andamiaje, ya que ese es el bootstrap que desea que proporcione la plantilla.

Paso 5: Generación

aio app build

Esto compila el front-end y ejecuta el vínculo de metadatos que genera app-metadata.json. Corrija los errores antes de continuar.

Paso 6: Implementación en fase

aio console workspace select     # choose Stage
aio app deploy

deploy aloja su interfaz de usuario en la red de distribución de contenido (CDN) de Adobe y registra el extremo de la extensión en el espacio de trabajo de ensayo, que es lo que permite que Fusion lo descubra. La CLI imprime la dirección URL del extremo, como https://<project>-stage.adobeio-static.net.

Paso 7: Activar las pruebas de fase y mostrar la extensión en Fusion

Iteración durante la demostración

Realice un cambio y, a continuación, vuelva a compilar y a implementar. Los usuarios verán la extensión actualizada la próxima vez que la abran.

aio app build && aio app deploy

Vaya a Producción después de la demostración

El escenario es suficiente para la demostración. Para realizar el lanzamiento en toda la organización, cambie al espacio de trabajo de producción e implemente y envíe la solicitud de aprobación. La solicitud debe enviarse con una función de administrador del sistema. Para ver el proceso completo, consulte Versión para producción.

Seguimiento de demostración (opcional)

Durante la demostración en directo, puede que desee añadir los siguientes puntos: