🛒

Shopify Checkout UI extensionsでCart attributesの情報を表示させる方法

2024/08/16に公開

Shopifyストアのサンキューページでカート属性（Cart attributes）を表示させる際、これまで追加スクリプトを利用する手法が一般的でした。
しかし、この手法は現在非推奨となっており、チェックアウト拡張機能（Checkout Extensibility）の利用が推奨されています。

チェックアウト拡張機能を使ってサンキューページや注文状況ページで取得したカート属性を表示させるには、従来の手法と比べて少し複雑ですが、以下の手順で実装できます。

Checkout UI extensionsでカスタムアプリを作成する
カート属性値を出力するUIコンポーネントを作成する
設定ファイルを修正する
ローカル環境でカスタムアプリを起動する
カスタムアプリをデプロイする

1. Checkout UI extensionsでカスタムアプリを作成する

チェックアウト拡張機能にはカスタマイズの用途に応じていくつかの機能が用意されており、今回は「Checkout UI extensions」を使います。

Checkout UI extensions動作イメージ

Checkout UI extensionsは、チェックアウトページのUIを拡張するための機能で、サンキューページや注文状況ページでコンポーネントを表示させることができます。以前はShopify Plusプランのみで利用可能でしたが、現在はベーシックプラン以上で利用可能です。

Extension-only appでカスタムアプリの開発環境をセットアップします。すでにカスタムアプリが手元にある場合はgenerate extensionの箇所から始めてもらっても問題ありません。

Extension-only appとはShopify管理画面にアプリ画面を持たず、拡張機能に特化したアプリのことです。拡張機能アプリ全体がShopifyへホストされるため、アプリ用のインフラを別途用意する必要がありません。CLIでのテーマ構築に近い感覚で開発ができます。

以下コマンドでカスタムアプリの初期設定を行います。
ここではパッケージマネージャーにpnpmを利用します。お好みのものを利用してください。

pnpm create @shopify/app

対話モードでプロジェクト名やインストール先のストアなど適宜入力してください。ここではTypeScript環境で進めます。

プロジェクトが作成されたら、対象ディレクトリに移動して以下コマンドを実行します。

pnpm shopify app generate extension

どのタイプの拡張機能を作成するか尋ねられるので、Checkout UIを選択します。
拡張機能に名前を付けて、初期化します。ここではReact TypeScript環境で進めます。

extensionsディレクトリに必要ファイルが生成されているはずです。

2. カート属性値を出力するUIコンポーネントを作成する

カスタムアプリの開発環境が整ったら、カート属性値を出力するUIコンポーネントを作成します。

前提条件

カート属性値を取得するためには、カート画面でカート属性を利用したフォーム実装が必要になります。想定されるカート属性に応じて、属性名は調整してください。

ここでは配送日時指定の情報がカート属性で管理されていることを例にして実装してみます。
カート属性名は以下で設定していることを想定します。

delivery_date: 配送希望日
delivery_time: 配送希望時間

Checkout.tsx ファイルを展開して以下のように編集します。

extensions/拡張機能名/src/Checkout.tsx

import {
  Heading,
  BlockStack,
  Text,
  useTranslate,
  useAttributeValues,
  reactExtension,
} from "@shopify/ui-extensions-react/checkout";

export default reactExtension("purchase.thank-you.block.render", () => (
  <Extension />
));

function Extension() {
  const translate = useTranslate();
  const [delivery_date, delivery_time] = useAttributeValues([
    "delivery_date",
    "delivery_time",
  ]);

  return (
    <BlockStack
      padding="tight"
      border="base"
      cornerRadius="base"
      background="base"
    >
      <Heading>{translate("title")}</Heading>
      <Text size="base">
        {translate("deliveryDate")}: {delivery_date || "指定なし"}
      </Text>
      <Text size="base">
        {translate("deliveryTime")}: {delivery_time || "指定なし"}
      </Text>
    </BlockStack>
  );
}

Components

コンポーネントは以下を利用していますが、必要に応じて変更してください。

React Hooks

フックは以下を利用しています。

useTranslate フックは、多言語対応に利用しているため、利用しなくても構いません。利用する場合は、locales フォルダー内のファイル情報を以下のように修正してください。

extensions/拡張機能名/locales/en.default.json

{
  "title": "Delivery Date and Time",
  "deliveryDate": "Delivery Date",
  "deliveryTime": "Delivery Time"
}

extensions/拡張機能名/locales/ja.json

{
  "title": "配達希望日時",
  "deliveryDate": "配達日",
  "deliveryTime": "配達時間"
}

useAttributeValuesはカート属性値を取得するために必要です。以下のように属性名を指定して利用してください。

const [delivery_date, delivery_time] = useAttributeValues([
    "delivery_date",
    "delivery_time",
  ]);

reactExtension はコンポーネントを出力する上で必須の関数です。第一引数にターゲットを指定します。ターゲットは、拡張機能が適用される場所を意味します。

ここではサンキューページに出力させたいのでpurchase.thank-you.block.renderを指定しています。

3. 設定ファイルを修正する

shopify.extension.toml ファイルを開き、ターゲットを修正します。コンポーネントだけでなく、tomlファイルにもターゲット登録が必要になるため要注意です。

extensions/拡張機能名/shopify.extension.toml

[[extensions.targeting]]
module = "./src/Checkout.tsx"
target = "purchase.thank-you.block.render"

4. ローカル環境でカスタムアプリを起動する

ローカル環境でカスタムアプリを起動します。

pnpm dev

起動後にpでプレビューを開き、サンキューページにカート属性値が表示されていることを確認します。

› Press p │ preview in your browser

アプリブラウザプレビュー

サンキューページプレビューイメージ例
サンキューページ実装イメージ

サンキューページだけでなく、注文状況ページなどでもextensionを追加し、ターゲットを変更することで同様にカート属性値を表示できます。

export default reactExtension(
  "customer-account.order-status.block.render",
  () => <Extension />
);

[[extensions.targeting]]
module = "./src/Checkout.tsx"
target = "customer-account.order-status.block.render"

注文状況ページプレビューイメージ例
注文状況ページ実装イメージ

5. カスタムアプリをデプロイする

ローカル環境での開発が完了したら、カスタムアプリをデプロイします。

pnpm run deploy

パートナーダッシュボードの「アプリ管理」にアプリが反映されていることを確認してください。アプリをストアにインストールして、確認してみましょう。ストア管理画面の「チェックアウト」にカスタマイズ動線が設置されています。

アプリブロックを追加して、要素が表示されていることを確認します。

アプリブロック追加イメージ

補足

Checkout UI extensionsで利用可能なコンポーネントは厳密に制限されています。そのため、独自のUIコンポーネントやHTMLタグを利用することはできません。

利用不可能なタグを記載してエラーが発生していてもフロント画面にはエラーメッセージが表示されません。ターミナルでエラーメッセージを都度確認してみることをオススメします。

まとめ

Checkout UI extensionsを使ってカート属性値を表示させる方法を紹介しました。チェックアウト拡張機能を使うことで、より安全に柔軟なカスタマイズができます。

ただし、プランによって適用可能な範囲が異なるため、事前に利用可能な範囲を確認をしてから実装を進めてください。この記事で紹介する内容は、ベーシックプラン以上であれば利用可能です。（2024/08/16時点）

チェックアウトのカスタマイズ機能プラン比較（2024/08/16）