Extensions

設定画面：ショップ構築 / 設定 / Extensions

「Extensions」は、注文確定前・注文完了後など、makeshopが用意したタイミング（Hook）で、ショップ様が開発したプログラムを実行する機能です。
「基幹システムの在庫確認」「注文情報の外部連携」「注文完了画面への案内表示」など、標準機能では実現できないショップ様独自の処理を組み込めます。

利用できるHook

プログラムを開発する

プログラムはWebAssembly（Component Model対応）で作成します。Rust・Goなどで開発できます。
作成方法は「SDKを使ってプログラムを作成する」をご覧ください。

SDKを使ってプログラムを作成する

makeshopが提供するSDKには、各Hookの入出力の型や、外部API呼び出し（Connector）の仕組みがあらかじめ用意されています。処理を書く関数を1つ実装するだけで、プログラム（WebAssembly）を作成できます。

どちらのSDKも、次の3つの実行タイミングに対応しています。

Rustで作成する

• 新しいライブラリcrateを作成します。

  cargo new --lib my-extension
  cd my-extension

• Cargo.tomlに次を追記します。featuresには、実装する実行タイミングのfeatureを1つ指定します。

  [lib]
  crate-type = ["cdylib"]
  
  [dependencies]
  makeshop-extensions-sdk = { version = "0.2", features = ["finalize-checkout-validation-v1"] }

• src/lib.rsに処理を書きます。次の例は、合計金額が100,000円を超える注文を受け付けません。

  use makeshop_extensions::finalize_checkout_validation::{
      Decision, GuestError, Input, fail, pass,
  };
  
  #[makeshop_extensions::hook(finalize_checkout_validation)]
  fn run(input: Input) -> Result<Decision, GuestError> {
      if input.checkout.total_price > 100_000 {
          return fail(vec!["注文金額が上限を超えています。".to_string()]);
      }
      pass()
  }

• ビルドします。target/wasm32-wasip2/release/my_extension.wasm が作成されます。

  rustup target add wasm32-wasip2
  cargo build --release --target wasm32-wasip2

Goで作成する

• 実装する実行タイミングに対応したプロジェクト一式（WIT契約・main packageを含む）を用意します。【要確認：入手方法】

• ビルドツールとSDKを追加します。

  go install github.com/bytecodealliance/componentize-go@v0.3.4
  go get github.com/gmomakeshop/makeshop-extensions-sdk-go

• 処理を書きます。次の例は、合計金額が100,000円を超える注文を受け付けません。

  package export_makeshop_finalize_checkout_validation_handler
  
  import (
  	hook "github.com/gmomakeshop/makeshop-extensions-sdk-go/contract/finalize-checkout-validation/v1/bindings/makeshop_finalize_checkout_validation_handler"
  	witTypes "go.bytecodealliance.org/pkg/wit/types"
  )
  
  func Run(input hook.Input) witTypes.Result[hook.Decision, hook.GuestError] {
  	if input.Checkout.TotalPrice > 100_000 {
  		return witTypes.Ok[hook.Decision, hook.GuestError](
  			hook.MakeDecisionFail([]string{"注文金額が上限を超えています。"}),
  		)
  	}
  	return witTypes.Ok[hook.Decision, hook.GuestError](hook.MakeDecisionPass())
  }

• 実行タイミングに対応するWIT worldを指定してビルドします。target/extension.wasm が作成されます。

  mkdir -p target
  componentize-go -d ./wit -w finalize-checkout-validation-guest build -o target/extension.wasm

作成したプログラムを登録する

作成した.wasmファイルと設定ファイル（「設定ファイルを用意する」を参照）をあわせてアップロードします。手順は「Hookのプログラムを公開する」「注文完了通知（Event）を設定する」をご覧ください。

設定ファイルを用意する

プログラムとあわせて、実行条件を書いた設定ファイル（YAML）を用意します。

シークレットを登録する

設定画面：ショップ構築 / 設定 / Extensions / シークレット

外部APIのAPIキーやパスワードなどの認証情報を登録します。登録した値はプログラムには渡らず、Connectorの認証時にのみ使われます。

Extensions画面の「シークレット」を開き、「新規登録」をクリックします。

• 名前：
  英大文字・数字・アンダースコア（_）のみ使用できます。先頭は英大文字またはアンダースコアにしてください。設定ファイル（YAML）からこの名前で参照します。
• 値：
  認証情報を入力します。登録後は再表示できません。

Hookのプログラムを公開する

設定画面：ショップ構築 / 設定 / Extensions / Hook詳細

対象：注文確定前チェック（finalize_checkout_validation）、注文完了画面コンテンツ（order_completed_content）

• Extensions画面の「Hook」から対象のHookをクリックし、「バージョン」タブを開きます。
• 「新規アップロード」をクリックし、WASMファイルと設定ファイル（YAML）を指定して「アップロード」をクリックします。バージョン番号は自動で採番されます。
• アップロードしたバージョンの「テスト」をクリックし、サンプルペイロードで動作を確認します。
• 問題がなければ「デプロイ」をクリックし、確認画面で「反映」をクリックします。

「テスト実行」では、会員・ゲスト・クーポン・ポイント利用・分割注文などのテンプレートから選んだサンプルペイロード（JSON）で、指定したバージョンを実行します。ペイロードは編集できます。デプロイ済みバージョンや本番の注文には影響しません。

注文完了通知（Event）を設定する

設定画面：ショップ構築 / 設定 / Extensions / Event詳細

注文完了通知は、Event「order_completed」に通知先（Subscription）を追加して設定します。
1つのEventに複数のSubscriptionを作成できます。

• Extensions画面の「Event」から「order_completed」をクリックし、「Subscriptionを追加」をクリックします。
• 名前と優先度を入力し、WASMファイルと設定ファイル（YAML）を指定して「作成」をクリックします。
• 作成したSubscriptionで、バージョンを「デプロイ」します。
• バージョン詳細画面の「テスト配信」で、サンプルの注文完了イベントを1件配信して動作を確認します。
• 問題がなければ「有効化」をクリックします。有効化した後に発生した注文から配信されます。

• 名前：
  同じEvent内で重複しない名前を入力します。小文字英数字と「-」「_」のみ、63文字まで使用できます。作成後は変更できません。
• 優先度：
  「通常」「高」から選択します。
• 配信条件：
  設定ファイル（YAML）の subscription.filter で指定し、デプロイ時に反映されます。指定しない場合は、すべての注文完了イベントを配信します。

Subscription詳細の「配信状況」タブでは、配信ごとのステータス（配信待ち・処理中・再試行待ち・配信済み・dead letterなど）、試行回数、次回試行予定を確認できます。

実行ログを確認する

設定画面：ショップ構築 / 設定 / Extensions / Hook詳細（「実行ログ」タブ）

Hook・Subscriptionの実行履歴を時系列で表示します。
Hook・ステータス・種別・日時・実行IDで絞り込めます。
Subscriptionの実行ログは、配信状況の配信詳細から「実行ログを見る」でも開けます。

【要確認：実際の画面がない】

行をクリックすると、エラー、コネクタートレース（外部API呼び出しの結果と時間）、ランタイムログ（プログラムが出力したログ）を表示します。

注意点

• プログラムの開発は、ショップ様（または委託先の開発会社様）にておこなっていただきます。makeshopにてサポートはいたしかねます。
• プログラムは、makeshopの標準処理の後に追加で実行されます。標準処理を置き換えることはできません。
• 定期実行（バッチ処理）、外部から呼び出せるAPIの作成、ショップ画面のデザイン変更には対応していません。
• プログラムはショップごとに隔離されて実行され、他のショップのデータにはアクセスできません。
• 注文完了通知は、再送により同じ注文が2回以上送られることがあります。受け取る側では、入力のイベントIDを使って重複を除いてください。
• 副管理者が操作するには、「ショップ作成」の権限が必要です。権限がない場合は「この操作を行う権限がありません。」と表示されます。

よくある質問

Q. アップロードしたのにプログラムが実行されません

A. アップロードだけでは実行されません。バージョンを「デプロイ」してください。注文完了通知の場合は、Subscriptionの「有効化」も必要です。

Q. 注文完了画面にコンテンツが表示されません

A. ShadowがONになっていないかご確認ください。実行に失敗した場合も表示されません。実行ログでステータスをご確認ください。

Q. プログラムから外部APIを呼べません

A. 外部APIは、設定ファイルで宣言したConnector経由でのみ呼び出せます。

Q. 登録したシークレットの値を確認したい

A. 登録済みの値は表示できません。必要な場合は、新しい値で更新してください。

Q. 不具合があったので元に戻したい

A. 「バージョン」タブで以前のバージョンを「デプロイ」すると切り戻せます。Hookを止める場合は「解除」、注文完了通知を止める場合はSubscriptionを「無効化」してください。