Developer Changelog / App Events

App Events が Shopify 管理画面に対応
Admin UI extensions と埋め込みアプリから emit() できるように

Checkout・Customer Account に続き、Shopify admin でも shopify.appEvents.emit() が使えるようになった。3 つのサーフェスすべてでアプリの利用状況を追跡できる。新しい任意の API なので、対応は不要。

このページの構成
  1. 何が変わるのか(30秒で理解)
  2. 仕組み図解 : イベントが届くまでの流れ
  3. 呼び出し方と「送ってはいけないデータ」
  4. 対象になるもの/ならないもの
  5. レート制限と課金の扱い
  6. 導入手順(5ステップ)
  7. 技術者が押さえるべき5つのポイント
  8. 業務に活かせる3つのユースケース
  9. 提案で使える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仕組み図解 : イベントが届くまでの流れ

Admin UI extension API 2027-01 以降 埋め込みアプリ App Bridge 経由 emit(handle, attrs) Shopify アプリとショップを 自動で付与 トークン・shop ID 不要 受理 Dev Dashboard : Logs admin からのイベント admin からのイベント バックエンドからのイベント まとめて表示される アプリのバックエンド 同じく送信した イベント (課金はこちらから)
イベントには送信元の拡張や、操作したスタッフを示す情報は含まれない。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 tab

埋め込みアプリ

制限は同じ。ただし 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 を渡す設計が要らない。

2027-01

2. 拡張はバージョン、埋め込みアプリは App Bridge が条件

Admin UI extension は 2027-01 未満だと shopify.appEvents が無い。埋め込みアプリは API バージョン不問で、App Bridge があればよい。

false

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 などの属性に入れる。
旧 token + shop ID emit ()
USE CASE 2

埋め込みアプリの利用計測を「認証なし」で実装する

課題
App Home の画面操作を計測するために、フロントからバックエンドへ送るエンドポイントや、ショップ識別の仕組みを自前で作る必要がある。
打ち手
App Bridge を使っている埋め込みアプリのページから shopify.appEvents.emit() を呼ぶだけにする。
効果
アクセストークンも shop ID も不要。計測用エンドポイントの新規実装なしで、ショップごとのイベントが Dev Dashboard に集まる。
技術メモ
埋め込みアプリは API バージョン指定不要。制限は 1 admin タブ内でアプリ全体の共有枠(20 件バースト+毎秒 2 件)なので、送信ポイントは絞る。
admin 利用ログ backend billing event
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 サーフェスで利用状況を追跡できる。
課金報告はこれまで通りバックエンドから。」