アプリはこれらのイベントを document で発火するため、document.addEventListener でリッスンしてください。コードはテーマのアセットに追加するか、theme.liquid の </body> の上に記述します。
| イベント | detail | 発火するタイミング |
|---|---|---|
gpoRenderCompleted | { form, product } | オプションのレンダリングが完了したとき |
gpoElementChanged | {} | 顧客がオプションを変更したとき |
gpoProductPriceUpdated | {} | 表示価格が再計算されたとき |
gpoValidated | { success } | カートへの追加時に検証が実行されたとき |
gpoAddedToCart | {} | 商品とそのアドオンがカートに追加されたとき |
gpoRenderCompleted
オプションのフィールドがDOMに追加されると発火します。カスタマイズの基本となるイベントです。 アプリは非同期でレンダリングするため、DOMContentLoaded で実行されるコードはオプションが存在する前に実行され、何も見つかりません。
detail には、オプションがレンダリングされた商品フォームである form と、対象の商品である product が含まれます。
document.addEventListener('gpoRenderCompleted', function (event) { const { form, product } = event.detail; if (!form) return; // この商品に適用されるオプションセットがない
// ここからオプションのフィールドを安全に取得できる form.querySelectorAll('.gpo-form__group').forEach(function (group) { group.classList.add('my-theme-option'); });});オプションが再レンダリングされるたびに再度発火します。たとえば、商品を再レンダリングするテーマでバリエーションを変更した後や、GPOConfigs.initialize() を呼び出した後です。2回実行されても問題がないようにハンドラーを記述してください。
gpoElementChanged
顧客がオプションを変更するたびに発火します。フィールドへの入力、スウォッチの選択、チェックボックスのオンなどです。
document.addEventListener('gpoElementChanged', function () { const engraving = document.querySelector('[name="properties[Engraving text]"]'); const note = document.querySelector('.my-engraving-note'); if (!engraving || !note) return;
note.hidden = engraving.value.trim() === '';});テキストフィールドではキー入力のたびに発火するため、ネットワークリクエストや重い再レイアウトなど、負荷の高い処理にはデバウンスを使ってください。
gpoProductPriceUpdated
顧客が選択したオプションを含めるように、アプリが表示価格を書き換えた後に発火します。固定バー、サマリーブロック、分割払いの目安など、独自の価格表示を同期させるために使います。
document.addEventListener('gpoProductPriceUpdated', function () { const main = document.querySelector('[data-gpo-product-unit-price]'); const sticky = document.querySelector('.my-sticky-bar .price'); if (main && sticky) sticky.textContent = main.textContent;});ページに表示される価格はプレビューです。顧客への実際の請求額はチェックアウト時にShopifyが適用するため、この金額を最終的な金額として扱わないでください。価格の適用方法をご覧ください。
gpoValidated
顧客がカートに追加しようとし、アプリがオプションを検証したときに発火します。必須オプションが空、文字数の上限超過、選択数の不足など、問題がある場合は detail.success が false になります。
document.addEventListener('gpoValidated', function (event) { if (event.detail.success) return;
// カートへの追加がブロックされた if (window.analytics) { window.analytics.track('Option validation failed', { product: window.GPOConfigs?.product?.handle }); }});最初のエラーメッセージまで自動スクロールがオンの場合、アプリが最初のエラーまで自動でスクロールするため、ご自身で実装する必要はありません。ウィジェットの動作をご覧ください。
gpoAddedToCart
商品とアドオン商品が追加された後に発火します。この時点で実際にカートが変更されているため、カートを開く処理や分析に適しています。
document.addEventListener('gpoAddedToCart', function () { fetch(window.Shopify.routes.root + 'cart.js') .then(function (res) { return res.json(); }) .then(function (cart) { document.querySelector('.my-cart-count').textContent = cart.item_count; });});商品に紐づくアドオンは独立したカートの行になるため、1回のカート追加で複数の行が追加されることがあります。1つの商品が追加されたと想定せず、カートを読み直してください。メイン商品とアドオンを統合するをご覧ください。
注意事項
- 5つのイベントはすべて、アプリ埋め込みが有効になっている必要があります。有効でない場合、アプリは動作せず、何も発火しません。
- イベントには、ページ上にすでにある情報以外の顧客データは含まれません。商品、カート、顧客の情報は window.GPOConfigs から読み込んでください。
- ここで追加したコードはご自身で保守する必要があります。テーマやアプリの更新後にストアフロントの動作がおかしくなった場合は、まずこのコードを確認してください。
このページは役に立ちましたか?
フィードバックありがとうございます。 足りなかった情報を教える
問題を報告