記事のサマリー(TL;DR)
- ShopifyはAdmin UI拡張機能と埋め込みアプリ(App Home)から
shopify.appEvents.emit()を呼び出してアプリイベントをShopifyに送信できるようにしました。これにより、Checkout・Customer Account UI拡張機能・Shopify adminの3つの表面すべてでアプリ使用状況を追跡できるようになります。 - 対象となるのは、API version 2027-01以降を使用するAdmin UI拡張機能、およびApp Bridgeを使用する埋め込みアプリです。これは新規のオプションAPIであり、既存のアプリや拡張機能は変更なしで動作を継続するため、対応は必須ではありません。
- イベントは課金処理の対象外であり、Shopify App Pricingの利用状況を報告する場合は、アプリのバックエンドから別途課金イベントを送信する必要があります。
対象範囲と制限事項
この変更は、API version 2027-01以降のAdmin UI拡張機能を持つアプリ、およびApp Bridgeを使用する埋め込みアプリに適用されます。埋め込みアプリについては特定のAPIバージョンは不要です。これより前のAPIバージョンのAdmin UI拡張機能にはshopify.appEventsは存在しません。
should-renderターゲットおよびdataターゲットでは、emit()は何も送信せず、{success: false, error: 'Emit is unavailable.'}を返します。埋め込みアプリについても、Shopify adminがApp Eventsを提供していない場合は同様の結果になります。
送信できるイベントの件数には上限があります。各Admin UI拡張機能は、最大20件のバーストに続き、1秒あたり2件まで送信できます。埋め込みアプリにも同じ上限が適用され、これは1つのShopify admin タブ内でアプリ全体で共有されます。
属性には、氏名、メールアドレス、電話番号、スタッフID、顧客IDなど、個人を特定できるデータを含めてはいけません。
詳細
変更内容
shopify.appEvents.emit()は、新たに2つの表面で利用可能になりました。
- Admin UI拡張機能:API version 2027-01以降を使用する拡張機能から
shopify.appEvents.emit()を呼び出せます。shopify app devでプレビューしている拡張機能からもイベントを送信できます。 - 埋め込みアプリ(App Home):App Bridgeを使用するアプリは、Shopify admin内のアプリのページから同じメソッドを呼び出せます。
このメソッドは、イベントハンドルと、属性を含むオプションのオブジェクトを引数に取ります。
shopify.appEvents.emit("description_generated", {
word_count: 120,
placement: "product_details",
});
Shopifyはアプリとショップの情報を各イベントに自動的に付加するため、アクセストークンやショップIDを含める必要はありません。
Shopifyが受理したイベントは、アプリのバックエンドから送信されたイベントとともにDev Dashboardのログで確認できます。イベントは、送信元の拡張機能や、それを使用したスタッフメンバーを識別する情報を含みません。
なお、Admin UI拡張機能および埋め込みアプリからのイベントは課金処理の対象にはなりません。Shopify App Pricingに利用状況を報告する場合は、アプリのバックエンドから課金イベントを送信する必要があります。
対応方法
既存のアプリや拡張機能は変更なく動作を継続するため、対応は必須ではありません。Shopify adminからイベントを送信したい場合は、以下の手順を実施します。
- Admin UI拡張機能の場合、
shopify.extension.tomlでapi_version = "2027-01"以降を設定する。 - イベントハンドルとオプションの属性を指定して
shopify.appEvents.emit()を呼び出す。 shopify app devを実行し、開発ストアで拡張機能またはアプリを使用する。emit()の結果を確認する。successがfalseの場合は、errorで原因を確認する。- Dev Dashboardの「Logs」を開き、イベントが届いていることを確認する。
関連ドキュメント
- Send events from Admin UI extensions
- Send events from embedded apps with App Bridge
- Monitoring and logs in the Dev Dashboard
[“Shopify”, “Admin UI extensions”, “App Bridge”, “App Events”, “Dev Dashboard”, “Shopify App Pricing”]