Skip to main content

​
概要

Aftersellのネイティブサーフェス（購入後、チェックアウト、Upcart）もパッケージ化された統合も要件に合わない場合は、ShopifyテーマからStrategies APIを自分で呼び出し、返された商品を自由な方法でレンダリングできます。 パターンはどのケースでも同じです。Liquidからコンテキストペイロードを構築し（現在の商品、カート内容、顧客フィールドなどのShopify属性がレンダリング時に埋め込まれるように）、それを /api/public/strategy/evaluate に POST して、レスポンスをレンダリングします。 このページでは2つの実装パターンを解説します。
  • PDPコンテキスト - 商品ページにセクションを配置し、現在表示中の商品を使ってAPIを呼び出し、返されたレコメンデーションのカルーセルをレンダリングします。
  • カートコンテキスト - カスタムカート内にアップセルブロックをレンダリングし、現在のカート内のすべてのラインアイテムを使ってAPIを呼び出し、返された商品をレンダリングします。
両者の違いは商品コンテキストの形です。PDPでは単一の商品、カートではすべてのラインアイテムの配列になります。

​
必要なもの

  1. Strategy APIキー。 Aftersellで Settings → Product Strategy に移動し、Security Token カード内のトークンをコピーします（これがStrategy APIキーです）。
  2. Strategy ID。 AftersellのStrategyエディタで実行したいStrategyを開き、そのIDをコピーします。
  3. テーマコードへのアクセス。 ShopifyテーマにLiquidセクション（PDP）またはブロック（カスタムカート）を追加します - Online Store → Themes → … → Edit code。
Strategy APIキーはクライアントサイドのテーマコードに置かれるため、ページのソースを表示する誰からも見えます。ストアフロント向けの公開クレデンシャルとして扱い、意図しない形で露出した場合はAftersellの Settings → Product Strategy からローテーションしてください。

​
PDPコンテキスト：セクションスニペット

このパターンでは、商品ページにShopifyセクションを追加します。ページのレンダリング時に、Liquidが現在の商品、カート、顧客属性をペイロードに埋め込み、JavaScriptがStrategies APIにPOSTして、返された商品をSplideカルーセルでレンダリングします。

​
インストール

  1. Shopify管理画面で Online Store → Themes に移動し、テーマの … をクリックして Edit code を選択します。
  2. Sections フォルダの下に aftersell-upsell-carousel.liquid という名前の新しいファイルを作成します。
  3. 下のスニペットを新しいファイルに貼り付け、YOUR_STRATEGY_API_KEY をAftersellのAPIキーに置き換えます。
  4. 保存します。
  5. 商品テンプレート（通常は templates/product.json または sections/main-product.liquid）を開き、カルーセルを表示したい位置に Aftersell Carousel セクションを追加します。テーマエディタから商品ページに直接ドラッグすることもできます。
  6. セクションの設定に Strategy ID を貼り付けます。

​
セクションが送信する内容

各PDPビューごとに、ペイロードには以下が含まれます。
  • products - 現在表示中の商品を含む単一要素の配列（productId、variantId、quantity、price、handle、title、vendor、productType、tags、collections、sellingPlan）。
  • cart - 買い物客の現在のカートの小計、アイテム数、ライン数（カートが空の場合は省略）。
  • cartToken - APIがこの評価を同一セッションに紐付けられるようにします。
  • customer - タグ、国、州、ロケール、注文数、累計購入金額、マーケティング許諾フラグ。ただし買い物客がログインしている場合のみ。
  • session - shop.currency からの通貨コード。
このセクションはデフォルトではUTMパラメータを送信しません。PDPでUTMベースのターゲティングを行いたい場合は、クライアントサイドで取得してfetchの前に session オブジェクトに追加してください。

​
スニペット

Shopifyの商品ページにレンダリングされたStrategy駆動の商品カルーセル

​
カスタマイズ

セクションのスキーマは、マーチャントが編集可能な4つの設定を公開しています：Strategy ID、Heading、CTA Button Label、Max Products to Show。テーマエディタにさらに設定項目を公開したい場合は、{% schema %} ブロックで設定を追加・削除してください。 CSSは .aftersell-* クラス名の下にスコープされており、Splide駆動の4アップカルーセル（768pxで2アップ、480pxで1アップに切り替わる）を含んでいます。テーマに合わせて自由に編集してください - API呼び出しの動作にCSSは一切必要ありません。

​
カートコンテキスト：カスタムカートアップセルブロック

このパターンは構造的にはPDPのものと同じですが、1つ重要な違いがあります。商品コンテキストの配列が、現在表示中の商品ではなくカートのラインアイテムから構築される点です。Strategyは買い物客が追加したすべてのアイテムを受け取り、カート全体に基づいたレコメンデーションを返します。 実装は、カスタムカートのコードがある場所に置きます - カートドロワーをレンダリングするLiquidセクション、ヘッドレスストアフロントのカスタムブロック、または cart.liquid のようなテーマテンプレートです。API呼び出しの形とレスポンス処理はPDPの例と同一で、products 配列だけが異なります。 構造は次のようになります。
ペイロードの残り（cart、customer、session、cartToken）と /api/public/strategy/evaluate への fetch 呼び出しは、上記のPDPパターンから変わりません - products 配列が [productContext] からカート由来の配列に置き換わるだけです。

​
Strategyがレスポンスを返したときの動作

レスポンスの形は、どちらのコンテキストを送信した場合でも同じです。
evaluationId は、この評価の一意のIDです。これを取得してレンダリングする商品に添付すると、その結果生じた注文を、それを生んだレコメンデーションに正確にアトリビューションできます - 下記のアトリビューションを参照してください。 products 配列をどのようにレンダリングするかは、完全にテーマコード次第です。上記のPDPスニペットは、バリアントピッカーとカート追加ボタンを備えたカードのカルーセルとしてレンダリングします。カスタムカートブロックなら、ドロワー内に縦のリストとしてレンダリングするかもしれません。 リクエストとレスポンスの完全なスキーマについては、Evaluate Strategy APIリファレンスを参照してください。

​
商品が返されない場合

Strategyが商品を返さない場合（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 呼び出しがカートアイテムにラインアイテムプロパティを添付します。
これらのプロパティはラインアイテムとともにShopifyの注文まで引き継がれ、ラインアイテムのレコードに表示されます。下流で収益のアトリビューション、注文のフィルタリング、ラインアイテムプロパティを読み取る分析ツールへの入力などに利用できます。 これらのキーと値は慣例であって必須ではありません - ここに何を入れてもAPI呼び出しは同じように動作します。自身のアトリビューションモデルに合わせて変更してください。例：
アンダースコア（_）で始まるプロパティキーは、カートとチェックアウトのUIには表示されませんが、注文には添付されます。買い物客に見せたくないアトリビューション専用のメタデータには、アンダースコアプレフィックスを使ってください。
カートコンテキストの実装でも同じパターンを適用してください - カスタムアップセルブロックから行うどのカート追加呼び出しにも、必要なプロパティを自由に持たせることができます。

​
評価へのアトリビューション

「Strategyから来た」というだけでなく、商品を推薦した正確な評価まで注文を紐付けるには、レスポンスから evaluationId を取得し、__as_offer_id プロパティとしてラインアイテムに添付します。AfterSellはこのキーを読み取るため、これでタグ付けされた注文はレポート上で特定の評価にアトリビューションされます。 evaluate() ハンドラで、レスポンスからIDを保持します。
次に、カート追加のプロパティに含めます。
__as_offer_id のダブルアンダースコアはそのまま残してください - これはAfterSellが探すキーであり、アンダースコアプレフィックスによって買い物客からは隠されます。evaluationId が存在しない場合（たとえば商品が返されなかった場合）は、空の値を送るのではなくプロパティ自体をスキップしてください。