Adobe PDF Embed API で addAnnotations が {} エラーで失敗する時の対処法

Adobe PDF Embed API を使ってアノテーションをプログラムから追加しようとした際、エラーに遭遇し、解決するまでに時間がかかったので備忘録として残します。

遭遇した問題

Adobe PDF Embed API の addAnnotations メソッドを呼び出した際、Promise の catch ブロックで以下のような中身のないエラーオブジェクトが返され、アノテーションの追加に失敗しました。

Failed to add annotation: {}

実装状況（失敗時）

Next.js (App Router/Client Component) で実装しており、ビューワーの設定は以下の通りでした。

const previewConfig = {
    enableSearchAPIs: true,
    embedMode: "SIZED_CONTAINER", // ここがポイント
    showAnnotationTools: true,
    enableAnnotationAPIs: true,
};

const previewFilePromise = adobeDCView.previewFile(
    {
        content: { location: { url: url } },
        metaData: { 
            fileName: "Document.pdf",
            id: "example-pdf-id" // Annotation APIに必須のID
        },
    },
    previewConfig
);

アノテーションの追加コードは、previewFile の Promise が解決した後に getAnnotationManager() を取得して実行していました。

previewFilePromise.then((adobeViewer) => {
    adobeViewer.getAnnotationManager().then((annotationManager) => {
        annotationManager.addAnnotations([/* ダミーのアノテーションデータ */])
            .catch((err) => console.error("Failed to add annotation:", err)); // ここで {} が出る
    });
});

調査したこと

1. metaData.id の確認: Annotation API を利用する場合、previewFile の引数に一意の id を含める必要があります。これは設定済みでした。
2. 有効化フラグ: showAnnotationTools: true と enableAnnotationAPIs: true は両方設定済みでした。
3. アノテーションのスキーマ: quadPoints や boundingBox の座標形式、target.source が metaData.id と一致しているかなどを入念にチェックしましたが、問題は見当たりませんでした。
4. APIキー: APIキーが正しく設定されているか確認しました。

解決策

ビューワーの embedMode を "SIZED_CONTAINER" から "FULL_WINDOW" に変更したところ、嘘のようにエラーが消え、正常にアノテーションが表示されるようになりました。

const previewConfig = {
    // ...
    embedMode: "FULL_WINDOW", // SIZED_CONTAINER から変更
    // ...
};

まとめ

Adobe PDF Embed API のドキュメントを確認すると、プログラムによるアノテーション操作（Annotation APIs）は FULL_WINDOW モードの機能としてのみ明記されており、SIZED_CONTAINER ではサポート対象に含まれていません。設定フラグとしては存在するため「APIなら動くのでは？」と思いがちですが、実際には動作が不安定になったり、今回のように {} エラーで失敗したりするケースがあるようです。

もし addAnnotations で {} という虚無のエラーに悩まされている方がいたら、一度 embedMode を FULL_WINDOW に変えて、公式にサポートされている環境で動作を確認してみることをお勧めします。