emit() できるようにCheckout・Customer Account に続き、Shopify admin でも shopify.appEvents.emit() が使えるようになった。3 つのサーフェスすべてでアプリの利用状況を追跡できる。新しい任意の API なので、対応は不要。
API バージョン 2027-01 以降の拡張から shopify.appEvents.emit() を呼べる。shopify app dev でプレビュー中の拡張からも送信できる。
App Bridge を使うアプリなら、Shopify admin 内のアプリページから同じメソッドを呼べる。特定の API バージョンは不要。
メソッドは イベントハンドルと、任意の属性オブジェクトを受け取る。
shopify.appEvents.emit("description_generated", { word_count: 120, placement: "product_details", });
Shopify が各イベントにアプリとショップを付ける。アクセストークンや shop ID は不要。
属性に入れてはいけないもの : 名前、メールアドレス、電話番号、スタッフ ID、顧客 ID など個人を識別できるデータ。
| ケース | 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 上の埋め込みアプリ | 何も送らない | 上と同じ結果が返る |
拡張ごとに、最大 20 件のバーストのあと 毎秒 2 件まで。
制限は同じ。ただし 1 つの Shopify admin タブ内でアプリ全体の共有枠。
admin 側のイベントは課金処理の対象外。Shopify App Pricing の利用量報告はバックエンドから billing event を送る。
emit() の戻り値を必ず確認すること。Admin UI extension は shopify.extension.toml に api_version = "2027-01" 以降を設定。
イベントハンドルと、任意の属性を渡す。
shopify app dev を実行し、開発ストアで拡張やアプリを使う。
success が false なら error で原因を読む。
Dev Dashboard の Logs を開き、イベントが届いているか確認。
アプリとショップは Shopify が付与する。フロントにアクセストークンや shop ID を渡す設計が要らない。
Admin UI extension は 2027-01 未満だと shopify.appEvents が無い。埋め込みアプリは API バージョン不問で、App Bridge があればよい。
should-render/data ターゲットや App Events が無い admin では {success:false, error:'Emit is unavailable.'} で resolve。戻り値をチェックする前提で実装する。
名前/メール/電話番号/スタッフ ID/顧客 ID は禁止。イベント側にも送信元の拡張・スタッフは記録されない。拡張ごとに分けて見たいなら、記事の範囲では属性で区別する以外の手段は記載なし。
admin からのイベントは課金処理されないので、Shopify App Pricing の利用量報告はバックエンドから billing eventを送る。また拡張ごとに 20 件バースト+毎秒 2 件、埋め込みアプリは admin タブ単位でアプリ全体の共有枠。キー入力ごと・スクロールごとの送信は避け、意味のある操作単位で送るのが安全。
emit("description_generated", { word_count, placement }) を送る。api_version = "2027-01" 以降が必須。送信元の拡張は記録されないので、どこから送ったかは placement などの属性に入れる。shopify.appEvents.emit() を呼ぶだけにする。emit() で計測用に送り、Shopify App Pricing の利用量報告はバックエンドから billing event を送る形に分ける。shopify.appEvents.emit() 1 行で利用イベントを送れるようになった。