💳

【Shopify.dev和訳】Apps/Checkout/Payment methods/Configuration

2021/09/12に公開約14,200字

この記事について

この記事は、Apps/Checkout/Payment methods/Configurationの記事を和訳したものです。

記事内で使用する画像は、公式ドキュメント内の画像を引用して使用させていただいております。

Shopify アプリのご紹介

Shopify アプリである、「商品ページ発売予告アプリ | リテリア Coming Soon」は、商品ページを買えない状態のまま、発売日時の予告をすることができるアプリです。Shopify で Coming Soon 機能を実現することができます。

https://apps.shopify.com/shopify-application-314?locale=ja&from=daniel

Shopify アプリである、「らくらく日本語フォント設定|リテリア Font Picker」は、ノーコードで日本語フォントを使用できるアプリです。日本語フォントを導入することでブランドを演出することができます。

https://apps.shopify.com/font-picker-1?locale=ja&from=daniel

Payment methods スクリプトの構成スキーマ

コードを再利用可能にするために、スクリプト内のハードコードされた変数を構成に置き換えることができます。構成により、マーチャントとスタッフは、Shopify admin にバリューとオプションを入力することでスクリプトをカスタマイズできます。スクリプトが実行されると、これらのバリューはキーと値のペアの入力としてスクリプトに渡されます。

script.json の構造 | Anatomy of script.json

スクリプトのプロパティは、スクリプトの設定ファイル(script.json)で定義します。このscript.jsonファイルには、title、description、configuration などのスキーマのスクリプトの設定が含まれています。スクリプトが configuration のバリューを使用しない場合でも、編集する必要がある必須ファイルです。

script.json
{
  "version": 1,
  "title": "My new script title",
  "description": "My script description",
  "configurationUi": true,
  "configuration": {
    "type": "single",
    "schema": [
      {
        "key": "configurationKey",
        "name": "My configuration field",
        "type": "single_line_text_field",
        "helpText": "This is some help text",
        "defaultValue": "This is a default value"
      }
    ]
  }
}
Properties 必須(required?) 説明
version はい スキーマのバージョン。このバリューは編集しないでください。
title はい スクリプトのタイトル。
description はい スクリプトの簡単な説明。
configurationUi はい Shopify admin がスクリプトの UI をレンダリングするかどうかを指定します。configurationUitrueのとき、UI がレンダリングされます。有効なバリュー:trueまたはfalse
configuration はい スクリプトの構成のスキーマについて説明します。スクリプトが configuration を使用していない場合は、typeにはsingleschemaには[]を設定してください。
type(必須)-configuration のタイプを指定します。有効な値:singleおよびlist
schema(必須)-configuration を定義する配列。configurationUitrueのとき、この配列の性質は Shopify admin における input UI コンポーネントとしてレンダリングされています。
 ・key(必須)-configuration のキー。この値は、スクリプトで使用されている configuration キーと一致する必要があります。このプロパティは、レンダリングされた UI には表示されません。
 ・name(必須)-configuration の名前。input コンポーネントのラベルとしてレンダリングされます。
 ・type(必須)-UI でレンダリングする input コンポーネントのタイプ。有効なバリュー:single_line_text_field
 ・helpText(オプション)-マーチャントが UI コンポーネントに何を入力するかを知るのに役立つヒントテキスト。灰色のテキストとして表示されます。
 ・defaultValue(オプション)-UIコンポーネントのデフォルト値。通常のテキストとして表示されます。

使用上の注意

  • スクリプトで使用する configuration ごとに、script.jsonschema配列を定義します。スクリプトのconfiguration.get呼び出しのkeyが、schema配列のkeyエントリの値と一致することを確認してください。
  • 入力としてサポートされているのは、テキスト(文字列)フィールドのみです。空のフィールドは""として保存されます。
  • テキストマークアップはサポートされていません。イタリック、太字、下線などのフォントの書式設定はサポートされていません。作業リンクもサポートされていません。
  • Shopify admin UI は、入力された値を検証しません。スクリプトに検証を追加する必要があります。
    • キャストデータ型を入力し、値の形式を確認します。すべての構成値は文字列として保存されます。スクリプトが configuration の値が数値型であることを期待している場合、コードはそれを変換する必要があります。safeParseInt関数を使用して、キャスト文字列を整数に入力します。スクリプトが値が特定の形式であることを期待している場合は、スクリプトでこの形式を確認してください。
    • 空の文字列と欠落している configuration の値を確認してください。使用はconfiguration.exists欠損値をチェックします。

次のセクションでは、configuration を使用するスクリプトと使用しないスクリプトの例を示します。configuration は、単一の値または値のリストを受け入れることができます。

Single value configurations

次の例では、スクリプトは各 configuration が単一の値であることを想定しています。

src / script.ts
...
  const nameToMatch = configuration.get('nameToMatch')!;
  const renameTo = configuration.get('renameTo')!;
  const paymentMethods = input.paymentMethods;
  const renameProposals = renameMatchingPaymentMethod(paymentMethods, nameToMatch, renameTo);
  return new PaymentRename.Result(renameProposals);
}

function renameMatchingPaymentMethod(
  paymentMethods: Domain.PaymentMethod[],
  nameToMatch: string,
  renameTo: string,
): PaymentRename.RenameProposal[] {
  const renameProposals: PaymentRename.RenameProposal[] = [];
  for (let i = 0; i < paymentMethods.length; i++) {
    const paymentMethod = paymentMethods[i];
    if (paymentMethod.name == nameToMatch) {
      const renameProposal = new PaymentRename.RenameProposal(paymentMethod, renameTo);
      renameProposals.push(renameProposal);
    }
  }
  return renameProposals;
}
...

上記のスクリプトに対応するscript.jsonファイルは次のようになります。

script.json
{
  "version": "1",
  "title": "Rename payment method",
  "description": "Rename specific payment methods",
  "configurationUi": true,
  "configuration": {
    "type": "single",
    "schema": [
      {
        "key": "nameToMatch",
        "name": "Payment option",
        "helpText": "Name of the payment method to rename.",
        "type": "single_line_text_field"
      },
      {
        "key": "renameTo",
        "name": "Rename To",
        "helpText": "Rename to this",
        "defaultValue": "Invoice Net-30",
        "type": "single_line_text_field"
      }
    ]
  }
}

上記の例では、configuration の値は次のキーとバリューのペアとして保存されます。

{
  "nameToMatch": "PayPal",
  "renameTo": "Best Option"
}

configuration のリスト

ConfigurationListオブジェクトを使用して、リスト構成を処理します。次の例では、スクリプトは configuration がリストであることを想定しています。

src / script.ts
...
export function paymentMethodsHandler(input: PaymentMethods.Input, configuration: Configuration) {
  // スクリプトはConfigurationアイテムのリストを想定しているため、ConfigurationListクラスを使用して値にアクセスできます
  const configurationList = new ConfigurationList(configuration);
  // Configurationリストを繰り返し処理します
  for (let i = 0; i < configurationList.length; i++) {
    // リストから単一の構成を取得します
    const configuration = configurationList[i];
    // バリューが存在することを確認します
    if (configuration.exists('myConfigurationValue')) {
      // バリューを取得する
      const myConfigurationValue = configuration.get('myConfigurationValue');
    }
  }
}
...

上記のスクリプトに対応するscript.jsonファイルは次のようになります。

script.json
{
  "version": 1,
  "title": "Hide payment methods by country",
  "description": "Hide payment methods when the customer's billing address matches the specified countries.",
  "configurationUi": true,
  "configuration": {
    "type": "list",
    "schema": [
      {
        "key": "myConfigurationValue",
        "name": "Country",
        "type": "single_line_text_field",
        "helpText": "2-letter country code",
      }
    ]
  }
}

上記の例では、configuration の値は次のキーとバリューのペアとして保存されます。

{
  "length": 2,
  "myConfigurationValue[0]": "CA",
  "myConfigurationValue[1]": "US"
}

configuration を使用しない

次の例は、configuration を使用しないスクリプトの configuration スキーマです。

script.json
{
  "version": "1",
  "title": "Rename first payment method",
  "description": "Renames the first payment method in a checkout.",
  "configurationUi": true,
  "configuration": {
    "type": "single",
    "schema": []
  }
}

次のステップ

  • マーチャントがチェックアウト時に顧客に提供する支払い方法名をカスタマイズできるようにするpayment methods scriptを作成します。
  • マーチャントが顧客タグに基づいてチェックアウト時に顧客に提供された配送方法を非表示にできるshipping methods scriptを作成します。

Shopify アプリのご紹介

Shopify アプリである、「商品ページ発売予告アプリ | リテリア Coming Soon」は、商品ページを買えない状態のまま、発売日時の予告をすることができるアプリです。Shopify で Coming Soon 機能を実現することができます。

https://apps.shopify.com/shopify-application-314?locale=ja&from=daniel

Shopify アプリである、「らくらく日本語フォント設定|リテリア Font Picker」は、ノーコードで日本語フォントを使用できるアプリです。日本語フォントを導入することでブランドを演出することができます。

https://apps.shopify.com/font-picker-1?locale=ja&from=daniel

Discussion

ログインするとコメントできます