Skip to main content
Cart SDK は、ストアフロント上の Aftersell Cart のための JavaScript API です。カートの動作を変更したり、買い物客の行動に反応したり、コードからカートの内容を読み取ったり変更したりできます。 SDK コードは、カスタムスクリプトを通じて、または独自の UI をレンダリングするブロックの場合は Custom code ブロックの React モードを通じて実行します。
マーチャントが SDK に求めることの多くは、すでに設定として存在します。スクリプトを書く前に、カートブロックマーケット/国/通貨による条件、またはカート設定がすでにそれを実現していないか確認してください。それらはカートの再設計後も機能し続けますが、スクリプトはそうとは限りません。

グローバルなエントリーポイント

すべては 1 つのグローバルにぶら下がっています:
このドキュメントのすべてのスニペットは window.aftersell.cart を完全に書き出しています。そのため、どれか 1 つを貼り付けるだけで単独で動きます。一度エイリアスを作って(const cart = window.aftersell.cart;)以降 cart を使うのもまったく有効で、カートの読み込み前でも安全です。ただしスニペットを短縮する場合はその行を含めることを忘れないでください。cart 単体では cart is not defined が投げられます。
4 つの構成要素が仕事をします:

Configure

カートの動作を設定します: ドロワーが開くタイミング、金額のフォーマット方法、Aftersell がカート追加をインターセプトするかどうか。

イベント

起こったことに反応します: カートが読み込まれた、アイテムが追加された、ドロワーが開いた、チェックアウトがクリックされた。

アクション

カートを読み取り、変更します: 開く、アイテムを追加する、数量を更新する、現在の状態を読み取る。

フック

カート自体の動作を変更します: ラインの非表示やラベル変更、並べ替え、追加データの付与、カート追加の制御。
あなたのスクリプトがカート追加で発火しなくなった場合は、まずカート追加のインターセプトから確認してください。Aftersell がなぜ追加を引き受けるのか、そしてフォームをオプトアウトさせるあらゆる方法が説明されています。
さらに 3 つの小さなメンバーがあります:

イベント、アクション、それともフック?

この 3 つは混同しやすく、間違ったものを選ぶことが、スクリプトが作者の期待どおりに動かない最も一般的な原因です: 最も重要な区別: アクションは買い物客の実際のカート(と合計金額)を変更し、フックはレンダリングされるものだけを変更します。フックでラインを非表示にしてもカートと合計には残りますが、アクションで削除すれば実際に取り除かれます。

読み込みの方法とタイミング

カートは 2 段階で読み込まれ、SDK は順序を気にしなくて済むように作られています:
  1. 小さなスタブwindow.aftersell.cart を即座に作成するため、常に存在します。
  2. その直後に完全な SDK が読み込まれて引き継ぎ、スタブをその場でアップグレードするため、先に取得した参照はそのまま使い続けられます。
これにより、呼び出しは 2 つのカテゴリに分かれます:

セットアップの呼び出し: すぐに安全

configure(...)events.on(...)、すべての hooks.register* 呼び出し。起動前はバッファリングされ、SDK が読み込まれると順番に再生されます。スクリプトの冒頭に置いてください。

アクション: ready() を待つ

actions.* の下にあるすべて。ready() の中またはイベントハンドラの中で実行してください。早く呼びすぎるとコンソールに警告を出して何もしませんが、安全です: 非同期のものは解決されるため、.then() チェーンは壊れません。

ready()

ready() は、最初のカート読み込みが確定すると解決される Promise を返します。成功時だけでなく失敗時にも解決されるため、不安定な接続の買い物客でもスクリプトが宙吊りになることはありません。カートが届いたと想定せず、getCart()null でないか確認してください。 カートの読み込み後に ready() を呼ぶと即座に解決されるため、コードのどこでも「カートは今存在する」という汎用のゲートとして安全に使えます。
イベントハンドラの中では ready() は不要です。cart_loadedcart_updateditem_added が発火する時点で、カートは読み込まれておりアクションを安全に呼び出せます。

context

window.aftersell.cart.context は、サーバーがレンダリングした購入者データを保持し、ready() なしで同期的に読み取れます。カートの読み込み前に行う必要があるマーケットや国による分岐に使ってください。
storefront_access_token は、サーバーが cart.context にレンダリングしない唯一の context フィールドです。カートの起動時に context に追加されるため、スクリプトの冒頭で読むと undefined になります。まず window.aftersell.cart.ready() を await してください。
マーケット、国、通貨ごとに異なるブロック設定を表示するには、代わりにカートエディタの条件を使ってください。スクリプトは不要です。完全な Conditions UI は現在 Rewards で提供されています。

shadowRoot

カートは shadow root 内でレンダリングされるため、document.querySelector ではドロワー内の何も見えません。カート内の要素にアクセスするには、shadow root をクエリしてください:
Custom CSS が使うのと同じ公開の cart-external-* クラスを対象にしてください。それらがサポートされたハンドルです。対になる cart-internal-* はカート自身の内部機構なので、external の方をクエリしてください。
shadow root に手を伸ばすのは、どのブロック、設定、フックでも実現できない場合だけにしてください。フックはカートの再設計を生き延びますが、DOM クエリの保守はあなたのコードの問題です。
shadow root はカートが起動してから存在するため、スクリプトの冒頭ではなく、ready() の中またはイベントハンドラの中で読み取ってください。

デバッグ

壊れたスクリプトがカート追加やドロワーを止めることは決してあってはならないため、SDK は失敗をバブルさせずに封じ込めます。失敗がどこに現れるかは、何が壊れたかによります:

スクリプトが throw したとき

カスタムスクリプトは最初のエラーで停止するため、その行より下のすべての configureevents.onhooks.register* は実行されません。カートはそれを明示的に伝えます:
確かに登録したはずのハンドラが発火しないときに探すべきメッセージがこれです。おそらくその行に到達していません。行番号は実行が停止したトップレベルのステートメントであり、throw した内側の関数ではありません。ブラウザのスタックが使えない場合は、推測されるのではなく省略されます。 スクリプトは独自のファイル名でも実行されるため、DevTools では aftersell-cart-init.jsaftersell-cart-cart-update.js として表示されます。Sources パネルから開き、他のファイルと同じようにブレークポイントを設定できます。

デバッグチャンネル

フックの失敗は、買い物客の目に触れないよう意図的にコンソールに出しません。代わりにここに送られます:

次のステップ

Configure

すべてのオプションを、それぞれ例付きで。

イベント

すべてのイベント、発火タイミング、そしてハンドラでやってはいけないこと。

アクション

すべてのアクションを、それぞれスニペット付きで。

フック

すべてのフックと、登録がどのように合成されるか。

カートオブジェクト

カートとそのラインの構造。

ユースケース

よくある要望に対する、完全ですぐ実行できるソリューション。