概要
/api/public/strategy/evaluate に POST して、レスポンスをレンダリングします。
このページでは2つの実装パターンを解説します。
- PDPコンテキスト - 商品ページにセクションを配置し、現在表示中の商品を使ってAPIを呼び出し、返されたレコメンデーションのカルーセルをレンダリングします。
- カートコンテキスト - カスタムカート内にアップセルブロックをレンダリングし、現在のカート内のすべてのラインアイテムを使ってAPIを呼び出し、返された商品をレンダリングします。
必要なもの
- Strategy APIキー。 Aftersellで Settings → Product Strategy に移動し、Security Token カード内のトークンをコピーします（これがStrategy APIキーです）。
- Strategy ID。 AftersellのStrategyエディタで実行したいStrategyを開き、そのIDをコピーします。
- テーマコードへのアクセス。 ShopifyテーマにLiquidセクション（PDP）またはブロック（カスタムカート）を追加します - Online Store → Themes → … → Edit code。
PDPコンテキスト：セクションスニペット
インストール
- Shopify管理画面で Online Store → Themes に移動し、テーマの … をクリックして Edit code を選択します。
- Sections フォルダの下に
aftersell-upsell-carousel.liquidという名前の新しいファイルを作成します。 - 下のスニペットを新しいファイルに貼り付け、
YOUR_STRATEGY_API_KEYをAftersellのAPIキーに置き換えます。 - 保存します。
- 商品テンプレート（通常は
templates/product.jsonまたはsections/main-product.liquid）を開き、カルーセルを表示したい位置に Aftersell Carousel セクションを追加します。テーマエディタから商品ページに直接ドラッグすることもできます。 - セクションの設定に Strategy ID を貼り付けます。
セクションが送信する内容
- products - 現在表示中の商品を含む単一要素の配列（productId、variantId、quantity、price、handle、title、vendor、productType、tags、collections、sellingPlan）。
- cart - 買い物客の現在のカートの小計、アイテム数、ライン数（カートが空の場合は省略）。
- cartToken - APIがこの評価を同一セッションに紐付けられるようにします。
- customer - タグ、国、州、ロケール、注文数、累計購入金額、マーケティング許諾フラグ。ただし買い物客がログインしている場合のみ。
- session -
shop.currencyからの通貨コード。
session オブジェクトに追加してください。
スニペット
カスタマイズ
{% schema %} ブロックで設定を追加・削除してください。
CSSは .aftersell-* クラス名の下にスコープされており、Splide駆動の4アップカルーセル（768pxで2アップ、480pxで1アップに切り替わる）を含んでいます。テーマに合わせて自由に編集してください - API呼び出しの動作にCSSは一切必要ありません。
カートコンテキスト：カスタムカートアップセルブロック
cart.liquid のようなテーマテンプレートです。API呼び出しの形とレスポンス処理はPDPの例と同一で、products 配列だけが異なります。
構造は次のようになります。
/api/public/strategy/evaluate への fetch 呼び出しは、上記のPDPパターンから変わりません - products 配列が [productContext] からカート由来の配列に置き換わるだけです。
Strategyがレスポンスを返したときの動作
evaluationId は、この評価の一意のIDです。これを取得してレンダリングする商品に添付すると、その結果生じた注文を、それを生んだレコメンデーションに正確にアトリビューションできます - 下記のアトリビューションを参照してください。
products 配列をどのようにレンダリングするかは、完全にテーマコード次第です。上記のPDPスニペットは、バリアントピッカーとカート追加ボタンを備えたカードのカルーセルとしてレンダリングします。カスタムカートブロックなら、ドロワー内に縦のリストとしてレンダリングするかもしれません。
リクエストとレスポンスの完全なスキーマについては、Evaluate Strategy APIリファレンスを参照してください。
商品が返されない場合
products: []）、その処理はあなたのコード次第です。上記のPDPスニペットはカルーセル全体を非表示にします。カスタムカートブロックであれば、カートのデフォルトのアップセルリストにフォールバックしたり、単に何もレンダリングしないという選択肢もあります。
空のレスポンスを避けるには、Strategyに Catch all を設定して、常に返せるフォールバック商品を用意してください。Catch allの設定方法については、Strategyの構築ページを参照してください。
カスタム統合のヒント
- コンテキストはLiquidで構築する。 Liquidはレンダリング時に実行され、Shopifyのオブジェクトグラフ全体（product、cart、customer、shop、request）にアクセスできます。クライアントサイドの呼び出しに頼らず、サーバーサイドでペイロードを埋めるのに活用してください。
- APIキーを公開リポジトリに置かない。 キーはテーマコードに含まれてブラウザに配信されます - それ自体は問題ありません。ただし、同じテーマを公開リポジトリに貼り付けたり、バンドルを外部に共有したりしないでください。
- Catch allを使う。 スロットが消えるとストアフロントの体験は壊れて見えます。安全なデフォルト商品を少数含めたCatch allがUIの一貫性を保ちます。
- 意味のある場所でキャッシュする。 Strategies APIはサーバーサイドで軽いキャッシュを行います（
meta.servedFromCache）が、トラフィックの多いPDPでは、クライアント側でも呼び出しをデバウンスまたはメモ化するとよいでしょう（例：同一セッションで同じ商品が2回レンダリングされたときに再呼び出ししない）。
アトリビューション
/cart/add.js 呼び出しがカートアイテムにラインアイテムプロパティを添付します。
評価へのアトリビューション
evaluationId を取得し、__as_offer_id プロパティとしてラインアイテムに添付します。AfterSellはこのキーを読み取るため、これでタグ付けされた注文はレポート上で特定の評価にアトリビューションされます。
evaluate() ハンドラで、レスポンスからIDを保持します。
__as_offer_id のダブルアンダースコアはそのまま残してください - これはAfterSellが探すキーであり、アンダースコアプレフィックスによって買い物客からは隠されます。evaluationId が存在しない場合（たとえば商品が返されなかった場合）は、空の値を送るのではなくプロパティ自体をスキップしてください。