Présentation de la démonstration de la création d’une extension personnalisée dans Fusion

Cette démonstration explique comment créer une extension personnalisée, la déployer et l’exécuter dans Fusion.

Comprend :

Commencer à partir du modèle plutôt qu’un --standalone-app vide signifie que le Bootstrap de la SPA est généré pour vous : index.js, exc-runtime.js, App.js avec le routage et la ErrorBoundary, et un exemple de ExtensionRegistration. Les étapes en direct de la démonstration consistent à recibler la configuration et à modifier deux fichiers, ce qui est exactement la manière dont le vrai fusion-uix-guest a été créé.

Avant de commencer

Cela ne doit être effectué qu’une seule fois, et peut être effectué hors caméra avant votre démonstration.

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)

Deux choses doivent être vraies dans l’organisation de démonstration :

Étape 1 : générer l’application à partir du modèle générique

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

Vous obtiendrez un ensemble de fichiers, y compris les suivants :

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)

Étape 2 : ajouter la bibliothèque invitée Fusion

Le modèle comprend déjà React, React Spectrum et exc-app. Ajoutez la bibliothèque qui communique avec l’hôte Fusion :

npm install @adobe/uix-guest

Étape 3 : reciblage de la configuration sur Fusion

Ouvrez app.config.yaml et modifiez uniquement la clé du point d’extension du point d’interface d’Experience Cloud vers celui de Fusion (laissez le chemin d’accès au $include en l’état) :

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

Vous n’avez rien à modifier d’autre dans la configuration. Le nom de dossier dx-excshell-1 est interne et n’a aucune incidence sur Fusion. Vous pouvez donc le laisser. Renommer signifie également mettre à jour les chemins d’accès aux actions. Ignorez cette étape pour la démonstration.

Étape 4 : Modifier les fichiers d’enregistrement et de widget

Tous les chemins sont sous src/dx-excshell-1/web-src/src/components/.

ExtensionRegistration.js

Le fichier généré enregistre un exemple d’Experience Cloud Shell. Remplacez son methods par le contrat Fusion dashboard.getWidget afin que Fusion connaisse votre titre et l’emplacement de l’interface utilisateur :

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 n’existe pas à côté, créez-le :

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

DashboardWidget.js

Créez ce fichier. Il termine l’établissement de la liaison et affiche le contexte Fusion actif :

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

Le routeur généré envoie déjà index / index.html à ExtensionRegistration. Ajoutez un itinéraire pour le widget et importez-le :

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

Le chemin d’accès (widget) doit correspondre au hachage dans getWidget().url (/index.html#/widget). Conservez le index.js/la exc-runtime.js généré(e) et le reste du App.js exactement comme prévu, car il s’agit du bootstrap que vous souhaitez que le modèle fournisse.

Étape 5 : création

aio app build

Cette opération compile le front-end et exécute le hook de métadonnées qui génère des app-metadata.json. Corrigez les erreurs avant de continuer.

Étape 6 : déploiement dans l’environnement intermédiaire

aio console workspace select     # choose Stage
aio app deploy

deploy héberge votre interface utilisateur sur le réseau CDN d’Adobe et enregistre le point d’entrée d’extension dans l’espace de travail d’évaluation, ce qui permet à Fusion de le découvrir. L’interface de ligne de commande imprime l’URL du point d’entrée, tel que https://<project>-stage.adobeio-static.net.

Étape 7 : activer le test d’évaluation et afficher l’extension dans Fusion

Itération pendant la démonstration

Apportez une modification, puis recréez et redéployez. Les utilisateurs verront l’extension mise à jour la prochaine fois qu’ils l’ouvriront.

aio app build && aio app deploy

Passage en production après la démonstration

Il suffit de faire une démonstration de l’environnement d’évaluation. Pour publier cette version à l’échelle de l’organisation, basculez vers l’espace de travail de production, déployez et envoyez la demande d’approbation. La demande doit être envoyée avec un rôle Administrateur système. Pour le processus complet, voir Version en production.

Démonstration de la piste de discussion (facultatif)

Vous pouvez faire les points suivants pendant votre démonstration en direct :