Headless Shopify でカスタマーハブを設定する方法
カスタマーハブをヘッドレス Shopify ストアフロントに接続します。ログインを有効にし、ウィジェット（お気に入り、FAQ）を表示し、アクティブ/最近閲覧した商品エクスペリエンスを強化して、エンゲージメントとコンバージョンを向上させます。
このページで学べること
カスタマーハブをヘッドレス Shopify ストアフロントに接続し、ログイン方法を選択して Hub を公開すると、買い物客はサイト全体でアクセスできるようになります。
Shopify 向け カスタマーハブは、現在標準のストアフロントと Shopify Headless をサポートしています。WooCommerce の場合は、https://help.klaviyo.com/hc/en-us/articles/47792369863451 に移動してください。
始める前に
要チェック
- Storefront API へのアクセスを備えたヘッドレス Shopify ストアフロント（Shopify の Headless Admin での Storefront API（パブリック アクセス トークン／Storefront API パブリック キー））。
- オンサイト JavaScript ローダーで使用される Klaviyo 会社 ID。
- 購入者ログインの決定：Shopify Customer Account API または Klaviyo ワンタイムパスワード（OTP）。
- 既存のアカウントを使用する場合は、ストアフロントのログイン、ログアウト、（任意で）アカウント管理と住所管理のルートを用意してください。
- ストアフロント コードを編集して、変更をデプロイする機能。
- 設定できるユーザー：カスタマーハブ の設定を編集し、ウィジェットを公開できるアカウントの役割（オーナー、管理者、またはコンテンツと API キーへの書き込みアクセス権を持つカスタムの役割）が必要です。
概要
カスタマーハブはサイト全体に表示されるオーバーレイで、お客様がアカウントの操作や便利なショッピングツールにより素早くアクセスできるようにします。ヘッドレス Shopify の場合は、Klaviyo のオンサイトスクリプトを接続し、ログイン方法（Customer Accounts API または Klaviyo OTP）を選択し、必要に応じて次を追加します。
- アクティブな商品：Hub 内で買い物客が閲覧している商品を表示します。
- 最近閲覧した商品：Klaviyo のトラッキングを使用して、最近閲覧した商品を一覧表示します。
- [お気に入り] と [よくある質問] ウィジェット：PDP と Hub 内にレンダリングされます。
ページ内の支援レイヤーによって商品発見とより迅速なチェックアウトを促進し、コンバージョンと生涯価値を向上させたい場合は、カスタマーハブを使用します。
設定
1 -カスタマーハブ設定を構成する
まず、カスタマーハブのスタートガイドに従い、他のセットアップと同様にオンボーディング ウィザードを完了します。完了したら、カスタマーハブ> [設定]に移動します。ヘッドレス Shopify の設定セクションが表示されます。
Headless Shopify configuration をオンにしてから、Shopify の Headless 管理者（Public access token）から Storefront API 公開キーを貼り付けます。
買い物客のログイン で、Shopify Customer Account API（推奨。すべてのストアフロント アプリで Shopify のログインを共有できます）または Klaviyo One Time Password（OTP、Klaviyo でのみ動作し、他のアプリには買い物客をログインさせません）を選択します。
Shopify Customer Account API を選択した場合は、ストアフロントの ログイン、ログアウト、および任意の アカウントを管理/住所を管理 ルート（Hub とサイト間のリダイレクトに使用）も入力します。
公開の表示設定：カスタマーハブ を Live に設定します。
2 -カスタマーハブJavaScript を読み込む（開発者向け手順）
ヒント：すでに Klaviyo のオンサイト機能を実行している場合は、ローダーがすでに設置されている可能性があります。2 つ目のスクリプトを追加する前に確認してください。
次のローダーを使用して /public/customerHub.js（または同等のもの）を作成します（COMPANY_ID を、Company ID とも呼ばれる Klaviyo の 公開 API キー に置き換えます）。
// customerHub.js
// TODO: Configuration
const COMPANY_ID = '';
const script = document.createElement('script');
script.src = `https://static.klaviyo.com/onsite/js/${COMPANY_ID}/klaviyo.js`;
script.async = true;
script.onload = () => { console.log('Klaviyo JS script loaded successfully'); };
script.onerror = () => { console.error('Failed to load Klaviyo JS script'); };
document.body.appendChild(script);オンサイトスクリプトはすべてのページで読み込まれます。コンソール メッセージ「Klaviyo JS script loaded successfully.」を確認してください。 ルート レイアウト（例：root.tsx）で、ローダーを含めます：
// root.tsx
return (
<html>
<body>
<script src="/customerHub.js" defer></script>
</body>
</html>
)このステップの後、window.customerHubApiは Hub が実行されているページで使用できるようになります。
3 -カスタマーハブにアクティブな商品を表示する
Hub に現在の商品が表示されるように、商品詳細ページ（PDP）に hydrate 呼び出しを追加します：
<!-- products.tsx -->
<script type="text/javascript">
(function() {
function waitForCustomerHubApi() {
return new Promise((resolve) => {
const check = () => {
if (window.customerHubApi && window.customerHubApi.hydrateProduct) {
resolve();
} else {
requestAnimationFrame(check);
}
};
check();
});
}
waitForCustomerHubApi().then(() => {
window.customerHubApi.hydrateProduct("your-product-handle");
});
})();
</script>The Hub では、有効にしている場合、買い物客が [チャット] タブで閲覧している PDP の追加の商品カードが表示されるようになります。
4 -カスタマーハブで最近閲覧した商品を有効にする
Viewed Product のトラッキングを実装すると、Hub でRecently viewedアイテムを表示でき、さらに Klaviyo の別の場所でこのメトリックを使用できます。次のトラッキングスニペットはストアフロントにも直接追加できます。手順は Klaviyo Developers ドキュメントのこちらにあります：事前構築済みの Klaviyo 外部連携なしで E コマースプラットフォームを統合する。
5 - アカウントリンクの乗っ取りを有効にする
ストアフロントのヘッダーにあるアカウントアイコンをクリックしてカスタマーハブを開けるようにするには、/account へのリンクを参照する既存の a タグが必要です（その場合は自動的に置き換えます）。または、アイコンリンクを手動で定義して #k-hub を指すようにし、ドロワーを開くこともできます。
6 - Customer Accounts API 認証でカスタマーハブを設定（推奨）
既存のストアフロントのお客様アカウントと認証設定を使用するには、カスタマーハブで、ログイン済みの買い物客のアクセストークンをサービスへ安全に受け渡しするための新しい API ルートをストアフロントに追加する必要があります。重要なのは、新しい API ルートに名前が付けられ、『/api/authenticateCustomerHub』で到達できることです。
注：次のコードスニペットの例は Shopify の Hydrogen フレームワーク向けです。よりカスタマイズされたストアフロントでは追加の回避策が必要になる場合がありますが、一般的なアプローチはここで説明します。
// ./app/routes/api.authenticateCustomerHub.js
// TODO: Configuration
const COMPANY_ID = '';
export async function action({context}) {
// Pull the Customer Account API Client from your storefront's context
const {customerAccount} = context;
try {
// Get the access token for the current customer
const accessToken = await customerAccount.getAccessToken();
if (!accessToken) {
return new Response(JSON.stringify({message: 'User not logged in'}), {
status: 200,
});
}
// Send the access token to the Customer Hub API
const response = await fetch(
'https://atlas-app.services.klaviyo.com/api/onsite/headless-shopify-login',
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
access_token: accessToken,
company_id: COMPANY_ID,
}),
},
);
const responseData = await response.text();
// Return the actual response from Customer Hub with the same status code
return new Response(responseData, {
status: response.status,
headers: {
'Content-Type':
response.headers.get('content-type') || 'application/json',
},
});
} catch (error) {
return new Response(null, {status: 500});
}
}これを設定し、さらに Klaviyo の設定でストアフロントのルートを定義すると、カスタマーハブは既存の認証設定にリンクできるようになり、既存の顧客アカウントへのシームレスな入り口を提供できます。
7 - Favorites ウィジェットを追加する（推奨）
Favorites と FAQs はどちらもカスタマーハブのドロワー内で機能します。ただし、追加のエンゲージメントのために、これらのウィジェットを PDP にも追加できます。
PDP と Hub 内で Favorites のエントリポイントを追加するには：
// products.tsx
// Example identifiers:
// id: gid://shopify/Product/12345
// data-product-id: 12345
const gid = "gid://shopify/Product/12345";
const productId = gid.split('/').pop();
return (
<div
className="kl-hub-favorites-slot"
data-product-id={productId}
/>
)買い物客は PDP で お気に入りに追加 をクリックできるようになりました。アイテムは Hub の お気に入りのアイテム に表示されます。
8 - FAQ ブロックを追加（推奨）
お気に入りの追加と同様に、FAQ ブロックの追加も、商品ページに product ID を渡した div を追加して、Klaviyo で編集・デザインできる FAQ をレンダリングするだけで簡単に行えます。
Klaviyo で設計する商品固有の FAQ ブロックを追加します：
// products.tsx
// Example:
const gid = "gid://shopify/Product/12345";
const productId = gid.split('/').pop();
return (
<div className="klaviyo-faqs-slot" data-product-id={productId} />
)FAQ チップ/ボタンは、設定されていれば PDP に表示されるようになり、Klaviyo で編集可能になります。
ベストプラクティス
- 検証後にのみ本番環境へ公開 — QA が完了するまでステージングを非表示にし、その後 Hub を公開するには Live を設定します。影響：サポートの問題が減り、価値実現までの時間が短縮されます。
- PDP では常にアクティブな商品をハイドレーションする — Hub で商品コンテキストを表示したままにし、カート追加を促します。影響：コンバージョン率、リピート購入率。
- 商品閲覧トラッキングを早期に実装 — 最近閲覧した項目にデータが反映され、閲覧ベースのフローを有効化できます。影響：閲覧復帰によるエンゲージメントと収益。
- [お気に入りに追加] — 手間の少ない保存アクションと、永続的なショートリストを作成します。影響：リピート訪問、カートに追加。
- 反論には FAQ を使用 — 配送、素材、返品に関する質問に本文内で回答し、離脱を減らします。影響：コンバージョン率。
- 可能な場合は Customer Accounts API を使用したサーバーサイド認証を優先してください。ログイン中の買い物客の継続性が向上します。影響：体験の品質、サポートの回避。
成功の測定
結果の確認方法：[分析] > [メトリック] を使用して Viewed Product のアクティビティと、下流のフロー/キャンペーンのパフォーマンスをモニタリングします。E コマース収益ダッシュボードを使用して、カスタマーハブを有効にした後のコンバージョンと平均注文額の変化を追跡します。監視すべき主なメトリック：PDP からのコンバージョン率、カート追加率、Hub を開いたセッション（計測されている場合）、受信者あたりの売上（リピート購入率）、および「商品閲覧」イベントに紐づく閲覧起点の売上。クイック修正チェックリスト：最近閲覧のアクティビティが少ない？Viewed Product トラッキング スニペットが発火し、イベントがプロファイルに紐付けられていることを確認します。Hub からのカート追加が少ない？Active Product のハイドレーションがすべての PDP で実行され、バリエーション/価格が正しいことを確認します。お気に入り追加が少ない？お気に入りスロットを主要な PDP の CTA の近くに移動し、data-product-id が商品と一致していることを確認してください。
トラブルシューティング
症状：サイトにカスタマーハブが表示されません。
考えられる原因： スクリプトが読み込まれていない、または Hub が 非表示 になっています。
修正：customerHub.js が読み込まれていること（コンソールを確認）、会社 ID が設定されていること、カスタマーハブ> Settings で カスタマーハブ の表示が Live になっていることを確
症状：コンソールに「Failed to load Klaviyo JS script.」と表示されます。
考えられる原因：スクリプト URL が正しくない、または 会社 ID がありません。
修正： https://static.klaviyo.com/onsite/js/<COMPANY_ID>/klaviyo.js を確認し、COMPANY_ID が入力されていることを確認してください。
症状：PDP で、ハブに Active Product カードが表示されません。
想定される原因: hydrateProduct が呼び出されていないか、商品ハンドルが誤っています。
修正: 待機ループが実行されていることを確認し、window.customerHubApi.hydrateProduct("<handle>") を呼び出します正しい商品ハンドルで。
症状：最近閲覧したセクションが空です。
考えられる原因: 商品閲覧のトラッキングが実装されていません。
修正：デベロッパーガイドの 「商品閲覧」 トラッキングスニペットを追加し、Klaviyo でイベントを確認してください。
症状：お気に入りまたは FAQ ウィジェットが PDP にレンダリングされません。
考えられる原因： コンテナがない、または属性が誤っています。
修正： 正しい商品 ID を指定して <div class="kl-hub-favorites-slot" data-product-id="..."> および／または <div class="klaviyo-faqs-slot" data-product-id="..."> を追加します。
症状：アカウントアイコンをクリックしても Hub が開きません。
考えられる原因：ヘッダーリンクが /account または #k-hub を指していません。
修正：アカウント アンカーが /account（自動引き継ぎ）を使用していることを確認するか、href="#k-hub" を設定してください。
症状：ショッパーが Hub 内でログイン済みとして認識されません。
考えられる原因：/api/authenticateCustomerHub ルートがない、または API リクエストが失敗しています。
修正：Hydrogen の例（または同等のフレームワーク）を実装し、access_token と company_id を Klaviyo のログイン エンドポイントに送信して、レスポンスを返します。
FAQ
Q: ログインに Shopify Customer Accounts API を使用する必要がありますか？
A: いいえ。代わりに Klaviyo ワンタイム パスワード（OTP） を使用できます。すでに Shopify アカウントを使用している場合は、Customer Accounts API 経由で接続してシームレスに利用できます。
Q: どのストアフロントのルートを提供する必要がありますか？
A：既存のアカウントを使用する場合は、[ログイン] と [ログアウト] のルートを用意します。[アカウントを管理] と [住所を管理] は、より深いリンク設定のために任意です。
Q：ストアフロント 公開 API キーはどこで見つけられますか？
A: Shopify の Headless Admin の Storefront API > Public access token（Storefront API public key とも呼ばれます）にあります。
Q:カスタマーハブでアカウントアイコンを置き換えられますか？
A: はい。ヘッダーのアカウントリンクが /account を使用している場合、カスタマーハブを自動的に開くことができます。また、#k-hub を指定することもできます。
Q： Shopify Hydrogen は必須ですか？
A: いいえ。認証の例では Hydrogen を使用していますが、どのフレームワークでも /api/authenticateCustomerHub にサーバールートを実装して、アクセストークンと company_id を Klaviyo に投稿できます。
Q: お気に入りと FAQ を PDP 上および Hub 内に配置できますか？
A：はい。PDP にそれぞれのコンテナ div を追加します。これらは Hub ドロワーにも表示されます。