カスタム拡張機能のトラブルシューティング
この記事では、カスタム拡張機能を作成する際に発生する可能性が最も高い問題に対する解決策を、開発中に発生する順序で紹介します。
クイックチェックリスト
何か機能しない場合は、まずこれらを確認してください。
-
Node.jsはバージョン 18または20 （
node --version）です。 -
（
aio login）で正しい組織/プロジェクト/ワークスペース （aio console where）にサインインしています。 -
拡張ポイント名は、バージョン
fusion/nav-organization/1を含め、正確に一致します。 -
getWidget()のurlは、アプリのルートと一致します。 -
表示されているUIから
attach({ id })が呼び出されます。 -
Fusionで適切な拡張機能セットを確認します。
- ステージのビルドを確認するには、ステージにデプロイし、Fusion プロファイルのステージ拡張機能スイッチをオンにします（製品設定/Fusion プロファイル/環境設定）。
- 公開された拡張機能を確認するには、実稼動環境にデプロイして承認を得ます。
エラー1060: 「拡張ポイントが存在しません」
完全メッセージ： CoreConsoleAPISDK ... 1060: Extension point 'fusion/nav-organization/1' does not exist （aio app deploy中）
意味： Fusion拡張ポイントは、お使いのAdobe組織に対してまだ有効になっていません（「オンボーディング」）。 Adobeは、デプロイ時に、拡張ポイントが組織のカタログに存在することを検証します。 これは、コードまたはYAMLに関する問題として not です。
修正： Fusion チームに、IMS組織の拡張ポイント （fusion/nav-organization/1またはfusion/nav-team/1）のオンボーディングを依頼します。 オンボーディングをリクエストする際には、以下を含めます。
- IMS組織id （
XXXX@AdobeOrg）、 - 必要な拡張ポイント,
- Developer Console プロジェクトとワークスペースの名前。
オンボーディングが確認されたら、aio app deployを再実行します。
“Awaiting initial message from target iframe” / パネルは永遠に回転します
意味： Fusionは表示されたUIを開きましたが、ハンドシェイクを完了しなかったため、Fusionがタイムアウトしました。
一般的な原因：
attachは登録コンポーネント内にのみ存在し、表示ウィジェット内には存在しません。getWidget()のurlは、ウィジェットの代わりに登録 コンポーネント（または空白ページ）をレンダリングするルートを指しています。attachに渡されたidは、registerで使用されているidとは異なります。 これらは同じである必要があるので、両方をConstants.jsに保持します。
修正： visible コンポーネントがattach({ id })を呼び出していることを確認します。
useEffect(() => {
attach({ id: extensionId }).catch(console.error);
}, []);
詳しくは、 カスタム拡張機能UIの作成を参照してください。
Fusionにナビゲーションボタンが表示されない
カスタム拡張機能のナビゲーションボタンがFusionに表示されない場合は、次の項目を順番に確認します。
- 適切な拡張機能セットをお探しですか？ デフォルトでは、公開された拡張機能のみが表示され、実稼動環境にデプロイされ、承認されています。 ステージのビルドをテストする場合は、Fusion プロファイル（製品設定/Fusion プロファイル/環境設定）のステージ拡張機能スイッチをオンにしてリロードします。 ステージ項目には （ステージ） というラベルが付いています。
詳しくは、 カスタム拡張機能を公開を参照してください。 - 取り消されたか、取り消されたか？ 失効または取り消された拡張機能が、エラーなしでFusionに表示されなくなります。 以前に動作していたボタンが消えた場合は、コードの問題を探す前に、Adobe Exchangeで引き続きアクティブであることを確認します。
- 正しいワークスペースにデプロイされていますか？ ステージテスト スイッチを使用しているときに、実際に読み込んでいるワークスペースであるステージワークスペースにデプロイします。
- 正しい組織にデプロイされていますか？ デプロイ先のsame IMS組織のアカウントでFusionにログインします。
- 正しいセクションですか？
fusion/nav-organization/1は 組織 の下に表示され、fusion/nav-team/1は チーム の下に表示されます（最初にチームを選択する必要があります）。 - 拡張機能ポイント名のタイプミスはありますか？
app.config.yamlとフォルダーのext.config.yamlのインクルードパスの両方で正確にfusion/nav-organization/1を読み取る必要があります。
ボタンが表示されますが、パネルは空白です
ボタンが表示されていてパネルが空白の場合は、次の点を確認します。
- ルートの不一致：、
getWidget()のurl、/index.html#/my-widgetなど）はApp.jsの<Route>と一致する必要があります。 不一致は、コンポーネントのないページを読み込みます。 - JavaScript エラー： ブラウザーの開発者向けツール （F12） > コンソール タブを開き、iframeからエラーが発生していないか探します。 報告されたエラーを修正し、再デプロイします。
getWidget()のヘッダーが見つからないか、重複しています：hideWidgetHeaderが、FusionでUIの上にタイトルを表示するかどうかを制御します。 独自のヘッダーをレンダリングする場合は、trueに設定します。
iframeがブロックされています（コンテンツセキュリティポリシー/「フレーム拒否」）
Fusionでは、Adobeでホストされている拡張機能のみが許可されます。これは、aio app deployがデフォルトでファイルを保存するApp Builder CDN （*.adobeio-static.net）です。 カスタムドメインなど、別の場所でUIをホストする場合、Fusionは読み込みを拒否します。 ドキュメントに従ってApp Builderを通じてデプロイするか、Fusion チームにドメインを許可リストに加えるできるかどうかを尋ねます。
コンテキストが空または古い
- 読み込み直後に空です： コンテキストを読み取る後
attach解決します。前ではありません。 それまでは、「接続…」状態を表示します。 - ユーザーが組織またはチームを切り替える際に更新されない：
contextchangeイベントを購読し、ハンドラー内のキーを再読します。 詳しくは、「カスタム拡張機能UIの構築」の記事のFusionのコンテキスト共有を参照してください。 - 日付が間違っています：日付フィールドは、
Date個のオブジェクトではなく、ISO 文字列として届きます。new Date(...)でそれらをラップします。 Fusionのコンテキストリファレンスの記事の日付を参照してください。
APIの呼び出しがCORS エラーで失敗する
現象： UIがWorkfront/Fusion APIを直接呼び出すと、ブラウザーコンソールに「Access-Control-Allow-Origin」ヘッダーが表示されない（またはリクエストがブロックされる）。
修正： ブラウザーからこれらのAPIを呼び出さないでください。 独自のApp Builder ランタイムアクション （サーバーサイド、CORSなし）を通じて呼び出しをルーティングし、ゲストが相対する同一オリジン URLを使用してアクションを呼び出すようにします。 詳しくは、WorkfrontとFusion APIの呼び出しを参照してください。
有効なトークンがある場合でも、プロキシアクションは401を返します
意味： require-adobe-auth: trueでは、Adobeのゲートウェイは、アクションが実行される前に呼び出しを検証し、それを拒否したり、アップストリームに必要なカスタムヘッダーをドロップしたりして、401として表示することができます。
修正： アクション およびでrequire-adobe-auth: falseを設定し、自分で認証を強制します。 Authorization人のベアラーを要求し、それを上流に転送し、厳格な目標許可リストに加えるを維持します。 require-adobe-auth: true vs. falseを参照してください。
Fusion GET /api/v3/hooksは400を返します
意味： フック エンドポイントは チーム スコープ であるため、teamIdは必須のクエリ パラメーターです。
修正： /api/v3/hooks?teamId=<team.id>への電話。 フックは、アクティブなチームでのみ返されます。 組織をカバーするには、チームをループ化して結合します。 シナリオは、対照的に、organizationIdを受け入れます。 Fusion v3 APIの詳細を参照してください。
aio のエラー
aio: command not found: CLIがPATHにインストールされていないか、インストールされていません。npm install -g @adobe/aio-cliを再実行してから、新しいターミナルを開きます。- まったく新しいノードバージョンでビルド/デプロイに失敗しました。ノード 18または20 LTSを使用してください。 非常に新しい非LTS リリースでは、ツールチェーンが壊れることがあります。
- 「You are not a developer」 / 組織を表示できません： Adobeの組織管理者は、Developer ロールとApp Builder アクセスを許可する必要があります。 詳しくは、UI拡張機能ツールとアカウントの設定を参照してください。
- 401 / デプロイまたは発見中に無効なトークン： セッションが期限切れになっているか、環境を混在しています。
aio logoutを実行してからaio loginを実行し、aio console whereを確認して、読み込むワークスペースにデプロイします。
サポート情報の収集
診断をより迅速にするために、次の情報を収集します。
- 実行した正確なコマンドとfull エラー出力。
- お客様のIMS組織ID、プロジェクト、およびワークスペース。
- ターゲットにしている拡張ポイント。
aio app deployが成功したかどうか、および拡張機能が 公開 かどうか（またはステージテストの場合は、ステージング拡張機能スイッチがオンになっているかどうか）。- Fusionでパネルを開くときに、ブラウザーコンソール （F12）でエラーが発生しました。