Skip to main content
イベントを使うと、カートで何かが起こったときにコードを実行できます。window.aftersell.cart.events の下にあります。 購読はセットアップの呼び出しなので、ready() を待つ必要はなく、スクリプトの冒頭で安全に行えます。

利用可能なイベント

購読

events.on(event, handler) はハンドラを登録し、購読を解除する関数を返します:
  • events.once(event, handler): 一度だけ発火し、その後自動的に購読解除されます。
  • events.off(event, handler): 特定のハンドラを削除します。
throw したハンドラは隔離され、コンソールにログが記録されます。他のハンドラは引き続き実行されます。

2 つのルール

イベントに関するバグのほぼすべては、次のどちらかに行き着きます。

ガードなしで cart_updated からカートを変更しない

cart_updated ハンドラの中でカートを変更すると、cart_updated が再び発火します。そのハンドラが再びカートを変更すると、無限ループになります。買い物客はカートが暴れ回るのを眺め、ページは Shopify を叩き続けます。
cart_updatedcart_loaded から無条件にアクションを呼び出してはいけません。 これから作ろうとする状態のチェックでガードし、2 回目のパスでは何もしないようにしてください。
カートには 1 つのセーフティネットがあります。同一のカートを生む更新は何も発行しないため、何も変わらない再取得がサイクルを再開させることはありません。これは意図しない no-op ループからは守ってくれます。ただし、毎回本当にカートを変更するハンドラからは守ってくれません

ペイロードは読み取り専用として扱う

1 つのイベントのすべてのハンドラは同じオブジェクトを受け取ります。それを書き換えると、あなたの後に実行されるハンドラ(ストア上の他のアプリのハンドラを含む)が見るものが変わってしまいます。
実際にカートを変更するにはアクションを使ってください。ラインのレンダリング方法を変えるには registerLineTransform を使ってください。

cart_loaded

ページ上でカートが最初に読み込まれたときに一度だけ発火します。ペイロードは完全なカートオブジェクトです。
用途: カートの初期状態に対して実行する必要があるすべての処理。無料ギフトの調整、ウィジェットの初期化、ページ読み込み時のカート内容のアナリティクスへの送信などです。 cart_loaded は遅れて購読した場合にも再送されます。 カートの読み込み後に購読した場合、ハンドラは現在のカートを引数に即座に呼び出されます。購読の順序は問題にならないため、スクリプトがカートより先に実行されたかどうかを気にする必要はありません。
ページ読み込み時にもその後の変更ごとにも正しく動く必要があるロジックは、同じ関数で cart_loadedcart_updated両方を購読してください。これが「X をカートと同期させ続ける」ための標準パターンです。

cart_updated

初回読み込み、カートの内容が変わるたびに発火します。ドロワーから、あなた自身のアクションから、テーマから、あるいは別のアプリからの変更であっても同様です。ペイロードは完全なカートオブジェクトです。
用途: カートの外にあるもの(カスタムの合計表示、進捗バー、ヘッダーのバッジ、変更ごとのアナリティクスイベントなど)を同期させ続けることです。 同一のカートを生む更新は何も発行しません。ドロワーを開き直す、タブを戻す、同じ内容を返す再取得では発火しません。
この中でアクションを呼ぶ前に、2 つのルールを読み直してください。

item_added

カートに新しいラインが現れたときに発火します。ペイロードは { item } で、itemカートラインです。
用途: サードパーティのアナリティクスツールでのカート追加トラッキング。SDK の最も一般的な用途がこれです。カート追加のトラッキングを参照してください。 このイベントの導出方法について知っておくべき 2 点:
数量の変更は追加ではありません。 カートは数量ではなくラインの差分から追加と削除を判定します。買い物客がラインを 1 から 3 に増やすと、item_added ではなく cart_updated が発火します。数量の増加も捕捉する必要がある場合は、cart_updated ハンドラ内で以前の状態と比較してください。
また、ページ読み込み時点ですでにカートにあったアイテムに対しては発火しません。それらは cart_loaded 経由で届きます。複数の異なる商品を一度に追加すると、イベントはラインごとに 1 回ずつ発火します。

item_removed

カートからラインが消えたときに発火します。ペイロードは { item } で、消える直前のラインなので、keyvariantIdtitle を引き続き読み取れます。
用途: 追加時に行った処理を元に戻すことです。フラグのクリア、買い物客が断ったオファーの再表示、削除のアナリティクスへの送信などです。 item_added と同じ注意点があります。ゼロにならずに数量を減らすことは削除ではありません。

cart_opened と cart_closed

ドロワーが開いたとき、閉じたときに発火します。ペイロードはありません。
用途: 閲覧トラッキング、ドロワーの背後にある動画やカルーセルの一時停止、ページのクラスの切り替えなどです。 どちらも初回のページ読み込みでは発火せず、実際の開閉時にのみ発火します。

checkout

買い物客がチェックアウトボタンをクリックしたとき、ブラウザが遷移する直前に発火します。ペイロードはありません。
用途: チェックアウト意図のトラッキング。
このハンドラからチェックアウトをキャンセルすることはできません。 このイベントはゲートではなく通知です。コードが何をしようと、遷移は行われます。ハンドラは高速かつ同期的に保ってください。await や遅いネットワーク呼び出しは、ページがアンロードされる前に完了しない可能性があります。確実に送信する必要があるものには navigator.sendBeacon を使ってください。

SDK の外からのリッスン

すべてのイベントは、window 上の DOM CustomEvent としてもディスパッチされるため、window.aftersell.cart に触れずにリッスンできます。テーマファイル、サードパーティアプリ、カートとは独立して読み込まれるスクリプトから使う場合に便利です。 命名に注意してください。バスは snake_case を使い、DOM イベントは aftersell:cart: プレフィックスの後に kebab-case を使います。
ペイロードは event.detail に届き、カートオブジェクトと一致します。イベントは window 上でディスパッチされるため、ページ上のどこにあるリスナーでも受信できます。カートは shadow root 内でレンダリングされますが、shadow の境界がイベントの経路に入ることはありません。ディスパッチごとにペイロードはクローンされるため、event.detail を書き換えるリスナーが他に影響を与えることはなく、throw するリスナーが SDK を妨げることもありません。
cart-loaded は DOM 上では再送されません。 バスは遅れて購読した場合に cart_loaded を再送しますが、その経路は DOM ディスパッチをバイパスするため、カートの読み込み後に登録された window.addEventListener('aftersell:cart:cart-loaded') は決して発火しません。スクリプトの読み込み順序が保証されない場合は、再送が行われる window.aftersell.cart.events.on('cart_loaded', …) を使うか、あわせて aftersell:cart:cart-updated もリッスンしてください。

Shopify 標準カートイベント

それとは別に、カートは自身がカートを変更するたびに Shopify の標準カートイベントdocument 上で発行します。これにより、テーマのコードや他のアプリは、テーマの変更に反応するのと同じ方法で Aftersell の変更に反応できます:
ペイロードは event.detail にはありません。 detail{ source: 'aftersell' } のみを保持します。これは、カートがループする代わりに自身のイベントを無視するためのタグです。上の表のすべては、イベントオブジェクトに直接代入されているため、event.detail.action ではなく event.action を読んでください。
各イベントは、Shopify の標準に合わせて、基盤となる書き込みが完了したときに Aftersell が確定させる promise も持ちます。これは await するもので、resolve するものではありません。これらは document 上でディスパッチされてバブルするため、window のリスナーでも受信できます。

次のステップ

  • カートオブジェクト: 上記のペイロードの完全な構造。
  • アクション: ハンドラからカートを変更する方法。
  • フック: カートに反応するのではなく、レンダリング方法を変更するためのもの。
  • ユースケース: アナリティクストラッキング、無料ギフトなどの完全な例。