Apresentação de demonstração da criação de uma extensão personalizada no Fusion

Esta demonstração aborda a criação de uma extensão personalizada, implantação e execução no Fusion.

O serviço inclui:

Começar a partir do modelo em vez de um --standalone-app vazio significa que a inicialização de SPA é gerada para você: index.js, exc-runtime.js, App.js com roteamento e ErrorBoundary, e uma amostra ExtensionRegistration. As etapas ao vivo da demonstração são redirecionar a configuração e editar dois arquivos, que é exatamente como o fusion-uix-guest real foi criado.

Antes de começar

Isso precisa ser feito apenas uma vez e pode ser feito fora da câmera antes da demonstração.

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)

Duas coisas devem ser verdadeiras na organização da demonstração:

Etapa 1: gerar o aplicativo a partir do modelo genérico

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

Você receberá um conjunto de arquivos, incluindo o seguinte:

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)

Etapa 2: Adicionar a biblioteca de convidados do Fusion

O modelo já inclui o React, o React Spectrum e o exc-app. Adicione a biblioteca que conversa com o host Fusion:

npm install @adobe/uix-guest

Etapa 3: Redirecionar a configuração para o Fusion

Abra app.config.yaml e altere somente a chave do ponto de extensão do Shell da Experience Cloud para o Fusion (deixe o caminho $include como está):

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

Não é necessário alterar mais nada na configuração. O nome da pasta dx-excshell-1 é interno e não afeta o Fusion, portanto, você pode deixá-lo. Renomear também significaria atualizar quaisquer caminhos de ação. Pule isso para a demonstração.

Etapa 4: Editar arquivos de registro e widget

Todos os caminhos estão em src/dx-excshell-1/web-src/src/components/.

ExtensionRegistration.js

O arquivo gerado registra uma amostra do Shell da Experience Cloud. Substitua seu methods pelo contrato do Fusion dashboard.getWidget para que o Fusion saiba seu título e onde está a interface do usuário:

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 não existir ao lado dele, crie-o:

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

DashboardWidget.js

Crie este arquivo. Ele conclui o handshake e mostra o contexto do Fusion em tempo real:

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

O roteador gerado já envia index / index.html para ExtensionRegistration. Adicionar uma rota para o widget e importá-lo:

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

O caminho da rota (widget) deve corresponder ao hash em getWidget().url (/index.html#/widget). Mantenha o index.js / exc-runtime.js gerado e o restante do App.js exatamente como andaime, pois essa é a inicialização que você deseja que o modelo forneça.

Etapa 5: criação

aio app build

Isso compila o front-end e executa o gancho de metadados que gera app-metadata.json. Corrija os erros antes de continuar.

Etapa 6: implantar no preparo

aio console workspace select     # choose Stage
aio app deploy

O deploy hospeda sua interface na CDN da Adobe e registra o ponto de extremidade de extensão no espaço de trabalho do Palco, que é o que permite que o Fusion a descubra. A CLI imprime a URL do ponto de extremidade, como https://<project>-stage.adobeio-static.net.

Etapa 7: ativar o Teste de preparo e mostrar a extensão no Fusion

Iterando durante a demonstração

Faça uma alteração, depois recrie e implante novamente. Os usuários verão a extensão atualizada na próxima vez que abrirem.

aio app build && aio app deploy

Ir para a produção após a demonstração

O palco é suficiente para a demonstração. Para liberar recursos em toda a organização, alterne para o espaço de trabalho Produção, implante e envie a solicitação de aprovação. A solicitação deve ser enviada usando uma função de Administrador do sistema. Para ver o processo completo, consulte Versão na Produção.

Demonstração do talk-track (opcional)

Você pode fazer os seguintes pontos durante a demonstração ao vivo: