App Events が Shopify 管理画面に対応 Admin UI extensions と埋め込みアプリから emit() できるように
原題: App Events: Send events from Admin UI extensions and embedded apps
- App Events
- Admin UI extensions
- 埋め込みアプリ
- App Bridge
- Dev Dashboard
- Analytics
- Apps
- レート制限
- 新機能
図解 : App Events が Shopify 管理画面に対応(Admin UI extensions/埋め込みアプリからイベント送信) Developer Changelog / App Events App Events が Shopify 管理画面に対応 Admin UI extensions と埋め込みアプリから emit() できるように Checkout・Customer Account に続き、Shopify admin でも shopify.appEvents.emit() が使えるようになった。3 つのサーフェスすべてでアプリの利用状況を追跡できる。新しい任意の API なので、対応は不要。 このページの構成 何が変わるのか(30秒で理解) 仕組み図解 : イベントが届くまでの流れ 呼び出し方と「送ってはいけないデータ」 対象になるもの/ならないもの レート制限と課金の扱い 導入手順(5ステップ) 技術者が押さえるべき5つのポイント 業務に活かせる3つのユースケース 提案で使える1行サマリ 1 何が変わるのか Editions では、App Events は Checkout と Customer Account の UI extensions だけで使えた。 今回 Shopify admin (Admin UI extensions と埋め込みアプリ)にも広がり、 3 つのサーフェスすべてでアプリの利用状況を追跡 できるようになった。 Admin UI extensions API バージョン 2027-01 以降 の拡張から shopify.appEvents.emit() を呼べる。 shopify app dev でプレビュー中の拡張からも送信できる。 埋め込みアプリ(App Home) App Bridge を使うアプリなら、Shopify admin 内のアプリページから同じメソッドを呼べる。特定の API バージョンは不要。 任意の新しい API なので対応は不要。 既存のアプリと拡張は変更なしで動き続ける。 2 仕組み図解 : イベントが届くまでの流れ イベントには 送信元の拡張や、操作したスタッフを示す情報は含まれない 。Dev Dashboard 上では、アプリのバックエンドが送ったイベントと一緒に表示される。 3 呼び出し方と「送ってはいけないデータ」 メソッドは イベントハンドル と、任意の 属性オブジェクト を受け取る。 shopify .appEvents.emit( "description_generated" , { word_count: 120 , placement: "product_details" , }); 自動で付与 アプリとショップ Shopify が各イベントにアプリとショップを付ける。 アクセストークンや shop ID は不要 。 送信禁止 個人を特定できるデータ 属性に入れてはいけないもの : 名前、メールアドレス、電話番号、スタッフ ID、顧客 ID など個人を識別できるデータ。 4 対象になるもの/ならないもの ケース emit() は使える? 補足 Admin UI extension(API 2027-01 以降) 使える shopify app dev でのプレビュー中も送信可能 埋め込みアプリ(App Bridge 利用) 使える 特定の API バージョンは不要 Admin UI extension(2027-01 より前) 使えない shopify.appEvents 自体が存在しない should-render ターゲット/data ターゲット 何も送らない {success: false, error: 'Emit is unavailable.'} で resolve App Events が提供されていない admin 上の埋め込みアプリ 何も送らない 上と同じ結果が返る 5 レート制限と課金の扱い Admin UI extension 拡張ごとに、 最大 20 件のバースト のあと 毎秒 2 件 まで。 埋め込みアプリ 制限は同じ。ただし 1 つの Shopify admin タブ内でアプリ全体の共有枠 。 課金には使われない admin 側のイベントは課金処理の対象外。Shopify App Pricing の利用量報告は バックエンドから billing event を送る 。 上限を超えたときの具体的な挙動(エラー内容・再送の要否など)は記事に記載なし。 emit() の戻り値を必ず確認すること。 6 導入手順(5ステップ) 1 API バージョンを指定 Admin UI extension は shopify.extension.toml に api_version = "2027-01" 以降を設定。 2 emit() を呼ぶ イベントハンドルと、任意の属性を渡す。 3 開発ストアで動かす shopify app dev を実行し、開発ストアで拡張やアプリを使う。 4 戻り値を確認 success が false なら error で原因を読む。 5 Logs で到着を確認 Dev Dashboard の Logs を開き、イベントが届いているか確認。 7 技術者が押さえるべき5つのポイント 1. 認証情報を持たせなくてよい アプリとショップは Shopify が付与する。フロントにアクセストークンや shop ID を渡す設計が要らない。 2. 拡張はバージョン、埋め込みアプリは App Bridge が条件 Admin UI extension は 2027-01 未満だと shopify.appEvents が無い。埋め込みアプリは API バージョン不問で、App Bridge があればよい。 3. 失敗は例外ではなく戻り値で返る should-render/data ターゲットや App Events が無い admin では {success:false, error:'Emit is unavailable.'} で resolve。戻り値をチェックする前提で実装する。 4. 個人を特定する属性は入れない・送信元も残らない 名前/メール/電話番号/スタッフ ID/顧客 ID は禁止。イベント側にも送信元の拡張・スタッフは記録されない。拡張ごとに分けて見たいなら、記事の範囲では属性で区別する以外の手段は記載なし。 5. 計測用と課金用は経路を分ける。レート制限も考慮する admin からのイベントは課金処理されないので、Shopify App Pricing の利用量報告は バックエンドから billing event を送る。また拡張ごとに 20 件バースト+毎秒 2 件、埋め込みアプリは admin タブ単位でアプリ全体の共有枠。 キー入力ごと・スクロールごとの送信は避け、意味のある操作単位で送る のが安全。 8 業務に活かせる3つのユースケース USE CASE 1 admin 内で使われるアプリ機能の利用状況を可視化する 課題 商品詳細画面などに置いた Admin UI extension の機能が、実際どれだけ使われているかが分からない。 打ち手 記事の例のように、生成などの操作完了時に emit("description_generated", { word_count, placement }) を送る。 効果 admin・Checkout・Customer Account の 3 サーフェスにまたがる利用状況を、Dev Dashboard の Logs でバックエンドのイベントとまとめて見られる。 技術メモ 拡張側は api_version = "2027-01" 以降が必須。送信元の拡張は記録されないので、どこから送ったかは placement などの属性に入れる。 USE CASE 2 埋め込みアプリの利用計測を「認証なし」で実装する 課題 App Home の画面操作を計測するために、フロントからバックエンドへ送るエンドポイントや、ショップ識別の仕組みを自前で作る必要がある。 打ち手 App Bridge を使っている埋め込みアプリのページから shopify.appEvents.emit() を呼ぶだけにする。 効果 アクセストークンも shop ID も不要。計測用エンドポイントの新規実装なしで、ショップごとのイベントが Dev Dashboard に集まる。 技術メモ 埋め込みアプリは API バージョン指定不要。制限は 1 admin タブ内でアプリ全体の共有枠(20 件バースト+毎秒 2 件)なので、送信ポイントは絞る。 USE CASE 3 従量課金アプリで「計測」と「課金報告」の役割を整理する 課題 利用量に応じて課金するアプリで、画面上の操作ログと課金に使う利用量が混ざり、どこから何を送るかが曖昧になっている。 打ち手 admin の画面操作は emit() で計測用に送り、Shopify App Pricing の利用量報告は バックエンドから billing event を送る形に分ける。 効果 admin 側イベントは課金処理されない仕様に合い、二重課金や報告漏れを設計段階で防げる。 技術メモ どちらのイベントも Dev Dashboard の Logs に並ぶので、ハンドル名でどちらの経路か判別できるように命名する。 9 提案で使える1行サマリ 「Shopify admin 内の拡張・埋め込みアプリから、 shopify.appEvents.emit() 1 行で利用イベントを送れるようになった。 トークン不要・任意導入・Checkout/Customer Account と合わせて 3 サーフェスで利用状況を追跡できる。 課金報告はこれまで通りバックエンドから。」 source : shopify.dev / changelog / app-events-send-events-from-admin-ui-extensions-and-embedded-apps 公開日 2026-11-18