Salesforce Commerce Cloud のカートリッジをアップグレードする方法

このページで学べること

Klaviyo Salesforce Commerce Cloud カートリッジのアップグレード方法をご確認ください。

23.7.0 より古いカートリッジ バージョンを使用していますか？バージョン 23.7.0 以降に直ちにアップグレードすることをおすすめします。古いバージョンのカートリッジでは、廃止され現在は想定どおりに動作しない Klaviyo の v1 および v2 API を使用しています。常に最新バージョン（現在は 25.7.0）へのアップグレードをおすすめします。

始める前に

バージョン 23.7.0 には、イベントのトリガー方法に関するアーキテクチャ変更を含む、いくつかの重要な改善が含まれています。23.70 より前の任意のバージョンからそれより後の任意のバージョンへアップグレードする際の特別な考慮事項を、以下に詳述します。

現在の外部連携を理解する

現在の SFCC 外部連携と、ウェブサイト向けにどのような変更またはカスタマイズが行われた可能性があるかを把握しておくことが重要です。最も重要なのは、Klaviyo に送信する特定のイベントデータが変更または拡張されているかどうか、またカスタムイベントを追加したかどうかを検討することです。

イベントデータを組み立てるコードを、Klaviyo の以前のカートリッジのバージョン（Klaviyo の Github で利用可能）と比較することをおすすめします。外部連携が大幅にカスタマイズされていない場合、現在のデータ組み立て関数は int_klaviyo_core/cartridge/scripts/utils/klaviyo/klaviyoUtils.js にあり、注文確認 の場合は int_klaviyo_core/cartridge/scripts/utils/klaviyo/emailUtils.js にあります。

新しいカートリッジのインストール後に再適用できるよう、カスタマイズ内容をメモしておいてください。

SFCC サンドボックスを Klaviyo テスト アカウントに接続する

SFCC 本番環境に紐づくアカウントとは別に、テスト用のセカンダリ Klaviyo アカウントをまだ作成していない場合は、作成してください。次に、新しいアカウントに SFCC サンドボックス環境を接続します。新しい Klaviyo カートリッジでコードベースをアップグレードする前に、イベントがセカンダリ Klaviyo アカウントに正常に送信および受信されていることを確認できるよう、このステップは以前の Klaviyo カートリッジ バージョンを使用して完了することをおすすめします。

以前の Klaviyo カートリッジ コードを削除します

外部連携が大幅にカスタマイズされていない場合は、コードベースから 2 つの Klaviyo カートリッジフォルダ（int_klaviyo_core と、Site Genesis の場合は int_klaviyo、SFRA の場合は int_klaviyo_sfra）を削除するだけで、以前の Klaviyo 外部連携の大部分を削除できます。ただし、テンプレート ファイルや、場合によっては JavaScript ファイルに追加されている可能性のある Klaviyo 固有のコードも削除する必要があります。

Site Genesis 用

Site Genesis の Standard 外部連携では、footer_UI.isml に次のコードが追加されます。

<isinclude template="components/footer/klaviyoFooter"/>

また、minicart.isml に次のブロックが追加されます。cart.isml と、その他のすべての「cart」isml ファイル：

<isif condition="${pdict.CurrentHttpParameterMap.cartAction == 'add' || pdict.CurrentHttpParameterMap.cartAction
  == 'update'}">
   <isinclude url="${URLUtils.url('Klaviyo-RenderKlaviyoAddToCart')}"/>
</isif>

SFRA 向け

SFCC の Standard 外部連携では、pageFooter.isml に次のコードが追加されます：

<isinclude template="klaviyo/klaviyoFooter"/>

また、Cart.js コントローラーの AddProduct ルートに次のコードが追加されます：

 if(dw.system.Site.getCurrent().getCustomPreferenceValue('klaviyo_enabled')){
   var KlaviyoUtils = require('*/cartridge/scripts/utils/klaviyo/klaviyoUtils');
 KlaviyoUtils.trackAddToCart();
}

Site Genesis と SFRA のいずれの場合も、カートリッジ フォルダと上記のコードスニペットを削除した後、コードベース内で “Klaviyo.” という単語を検索することをおすすめします。新しいカートリッジのインストール後に元に戻す必要があるカスタマイズを示している可能性があるため、削除する前に、コードベースに残っている Klaviyo 関連コードが何をしているのかを必ず把握してください。

サービスを削除

前の外部連携では、管理 > 操作 > サービス に KlaviyoTrackService、KlaviyoTrackProfile、KlaviyoTrackCredentials が作成されています。新しい Klaviyo カートリッジを外部連携するプロセスにより、別の名前の新しいサービスが作成されるため、これら 3 つはいずれも安全に削除できます。

古いサービスを削除することは必須ではありませんが、今後の混乱を避けるために整理しておくことをおすすめします。

レビューサイトの設定

新しい Klaviyo カートリッジを統合するプロセスでは、以前の Klaviyo サイト設定の一部が保持され、さらに新しい設定も追加されます。Merchant tools > Site Preferences > Custom Preferences > klaviyo の Klaviyo 設定グループでサイト設定をご確認いただき、ウェブサイト専用のカスタム設定が追加されていないか確認してください。独自の設定を追加するためにカートリッジをカスタマイズした場合、それらを保持しておく必要があります。参考までに、以前の Klaviyo 外部連携に組み込まれている 4 つのサイト設定を以下に示します。

• Klaviyo 有効（ID: klaviyo_enabled）
  Klaviyo がオンかオフかを示すフラグです。
• Klaviyo アカウント (ID: klaviyo_account)
  Klaviyo の公開 API キー、またはサイト ID。
• Klaviyo 非公開 API キー (ID: klaviyo_api_key)
  Klaviyo の非公開 API キー。
• Klaviyo の画像タイプ（ID: klaviyo_image_size）
  大、大きい、小、サムネイルなど。

新しいカートリッジを設定する前に、[Administration] > [Site Development] > [Site Import & Export] でエクスポートして、現在のサイト設定をバックアップすることをおすすめします。[Sites] を展開し、次に [Site Name] を展開してから、ファイル名を入力してエクスポートする前に Site Preferences のボックスにチェックを入れます。後で新しいカートリッジをインストールしても、現在の Klaviyo 設定に悪影響が出ることはありませんが、今後の参照用にバックアップしておくことをおすすめします。

カートリッジパスから Klaviyo カートリッジを削除します。

Administration > Sites > Manage Sites > [Site Name] > Settings で、カートリッジパスから int_klaviyo_core と、int_klaviyo（Site Genesis）または int_klaviyo_sfra（SFRA）のいずれかを削除してください。この手順を実行しない場合、SFCC が既に存在しない読み込み対象のカートリッジを探すことが原因でエラーが発生します。

デベロッパー コンソールとサーバーサイド ログでエラーを確認してください

この時点で、コードベース内に Klaviyo のコードは一切残っていないはずです。フロントエンドを確認し、検索結果、PLP、PDP などのページにアクセスして、商品のカート追加、チェックアウトの開始、チェックアウトの完了などのアクションを実行することをおすすめします。その際、新しいエラーが生成されていないか、開発者コンソールを確認してください。リクエスト ログでも同じことを行ってください。Klaviyo に関連する新しいエラーが表示されている場合、以前の Klaviyo のコードがまだ完全には削除されていない可能性が高いです。新しいエラーの発生元を特定し、削除する前に記録しておくことが重要です。

新しい Klaviyo カートリッジをインストールする

Salesforce Commerce Cloud のスタートガイドに記載されている手順に従い、新しいカートリッジをコードベースに統合します。完了する必要のない手順がある場合があります。たとえば、SFCC インスタンスでは、OCAPI 部分の接続がすでに確立されている場合とそうでない場合がありますが、一般的には各外部連携手順に従ってください。両方の Klaviyo カートリッジを必ず置き換え、コードスニペットを追加し直す必要があります。

metadata.zip をインポートした後は、以前のバージョンのカートリッジで作成された 4 つに加えて、新しいサイト環境設定が 4 つ追加されます。以前の環境設定は新しいものをインポートしても影響を受けていないはずですが、続行する前にすべての Klaviyo サイト環境設定が正しいことを念のため再確認することをおすすめします。

バージョン 23.7.0 より前のカートリッジからアップグレードするため、新しいサイト設定の「SFCC としてイベントをラベル付け」および「カートに追加イベントを『カートに追加』として送信」は、それぞれ「いいえ」と「はい」に設定する必要があります。これにより、「Salesforce Commerce Cloud」メトリック ラベルなしでイベントの送信が継続され、（新しい「カートに追加」ではなく）「カートに追加」イベントタイプが使用されます。これら 2 つのサイト設定が誤って設定されていると、レポート作成が中断し、さらに、Klaviyo の既存フローが中断する可能性があります。

すぐに使えるイベントがすべて動作していることを確認してください。

以前の外部連携から任意のカスタマイズを追加し直そうとする前に、Klaviyo カートリッジの新しいインストールが正しく動作していることを必ず確認してください。フロントエンドを使用して サイト検索、カテゴリ閲覧、商品閲覧、カートに追加、チェックアウト開始、注文確認のイベントを生成し、その後 Klaviyo アカウントで、これらのイベントが正しくトラッキングされていることを確認してください。

Klaviyo イベントを生成するすべてのページで、外部連携に関連している可能性のある新しいエラーがないか、開発者コンソールを確認してください。[管理] > [運用] > [サービス] > [KlaviyoEventService - 詳細] の[Communication Log Enabled] チェックボックスをオンにして詳細なサービス ロギングを有効にし、その後サーバー側のログ ファイルを確認して、エラーがないこと、および各イベントタイプのイベントデータが適切に生成されていることを確認してください。

イベントデータを本番環境と比較する

これで、テスト用と本番用の Klaviyo アカウントにおけるイベントデータを比較し、不足がないこと、および現在の値が想定されるタイプと一致していることを確認してください。新しい外部連携によって、レポート作成やフローに影響が出るかどうかを判断することが重要です。以前の cartridge バージョンと比較して、追加のプロパティが設定され、Klaviyo に送信されるようになっていることがわかります。

サイト固有のカスタマイズを追加し直す

Klaviyo コードにカスタマイズを再度追加できるようになりました。最新の Klaviyo カートリッジには大規模な構造およびアーキテクチャの変更があるため、カスタム コードを Klaviyo カートリッジに直接コピー＆ペーストするだけで済む可能性は低いです。

Klaviyo カートリッジ内の各イベント タイプには getData 関数があり、各イベント タイプにちなんで命名された別個のスクリプト ファイル内にあります。これらのファイルは int_klaviyo_core/cartridge/scripts/klaviyo/eventData フォルダ内にあり、各イベントに渡されるデータ オブジェクトを追加または更新するために変更する可能性が最も高い場所です。新しいカスタム イベントを作成する場合は、サーバーサイド コントローラーにコードを追加する（つまり、SiteGen に直接追加するか、SFRA で server.append を介して追加する）という既存のパターンに従い、新しいイベント専用のスクリプト ファイルから getData 関数を呼び出し、その後 trackEvent 関数を使用して KlaviyoEventService 経由でそのデータを Klaviyo に送信することを推奨します。

達成できること

これで Salesforce Commerce Cloud 用の Klaviyo カートリッジがアップグレードされました。

その他のリソース