POS Extensions / Developer Changelog

POS Extensions に
「UI を持たない」background extension target が登場

新ターゲット pos.app.ready.data は POS セッションの間ずっと動き続け、画面を一切描画せずに POS のイベント監視・データ保存・非視覚系 API の呼び出しができる。「レジ画面に何かを出す」以外の拡張がついに公式サポートされた。

このページの構成
  1. そもそも何ができるようになったのか（30秒で理解）
  2. 仕組み図解 ： POS セッションと background target のライフサイクル
  3. 想定されている 3 つの用途
  4. 使い方 ： イベント購読はほぼ 1 行
  5. サポートされるイベント一覧
  6. 従来の UI ターゲットとの比較
  7. 技術者が押さえるべき5つのポイント
  8. 業務に活かせる3つのユースケース
  9. 提案で使える1行サマリ

1そもそも何ができるようになったのか

これまでの POS UI Extensions は「タイルやモーダルなど、画面のどこかに UI を描く」のが前提だった。
新ターゲット pos.app.ready.data は UI を一切描画せず、POS セッションの開始から終了までずっと動き続ける裏方の実行枠を提供する。

従来 ： UI ターゲット

タイルやモーダルなど、スタッフが目にする UI サーフェスに描画してこそ動く。表示されていない間はロジックも走らせられない。

新 ： background ターゲット

pos.app.ready.data は POS セッション全体で常駐。UI 無しで POS イベントを監視し、バックグラウンドロジックを実行できる。

2仕組み図解 ： POS セッションと background target のライフサイクル

POS セッション開始 セッション終了 pos.app.ready.data ＝ セッションの間ずっと動き続ける（UI 描画なし） transactioncomplete 取引完了を検知 cashtrackingsessionstart 現金管理セッション開始 cashtrackingsessioncomplete 現金管理セッション完了 イベントが起きるたびに addEventListener のハンドラが呼ばれる。スタッフの画面には何も出ない。
Web でいう Service Worker 的な立ち位置をイメージすると近い ： 画面を持たず、イベント駆動で裏方の処理だけを担う実行枠。「レジ画面に描くための拡張」と「レジの出来事に反応するための拡張」が分離できるようになった。

3想定されている 3 つの用途

記事では background target の用途として次の 3 つが明示されている。

イベント監視

取引完了や現金管理セッションの開始・完了など、POS 上の出来事をリアルタイムに購読する。

データ保存

監視したイベントをもとにしたデータストレージ用途。UI 操作を介さずに記録を残せる。

API

非視覚系 background API の呼び出し

UI を描かない background API を呼び出せる。対応 API の詳細は公式の app background target ドキュメント参照。

4使い方 ： イベント購読はほぼ 1 行

やることは shopify.addEventListener() で POS イベントを購読するだけ。Web 標準の addEventListener と同じ感覚で書ける。

// pos.app.ready.data ターゲットの拡張内 shopify.addEventListener('transactioncomplete', (event) => { console.log('Transaction complete', event); });
ハンドラには event オブジェクトが渡される。ここから取引情報等を受け取ってバックグラウンド処理につなげる（event の中身の仕様は記事に記載なし。公式ドキュメントで確認）。

5サポートされるイベント一覧

イベント名発火タイミング使いどころの例
transactioncomplete 取引（決済）が完了したとき 売上発生をトリガにした後続処理・記録
cashtrackingsessionstart 現金管理（キャッシュトラッキング）セッションが開始したとき レジ開け（開局）の検知・記録
cashtrackingsessioncomplete 現金管理セッションが完了したとき レジ締め（閉局）の検知・記録

※ 記事に列挙されているのは上記 3 イベント（「Supported events include」表記のため、網羅リストかは記載なし）。最新の一覧と best practices は公式の app background target ドキュメントを参照。

6従来の UI ターゲットとの比較

項目UI ターゲット（従来）pos.app.ready.data（新）
UI 描画 あり タイル・モーダル等に描画 なし 一切のサーフェスを描画しない
実行期間 UI が表示されている間 POS セッション全体 で常駐
起動のきっかけ スタッフの操作（タイルタップ等） セッション開始で自動的に稼働
主な役割 情報表示・スタッフとの対話 イベント監視・データ保存・非視覚系 API 呼び出し

7技術者が押さえるべき5つのポイント

.data

1. ターゲット名は pos.app.ready.data

拡張の target にこれを指定すると background 実行枠になる。「.data」サフィックスが UI 非描画の目印。

2. ライフサイクルは「POS セッション全体」

スタッフの操作で起動する UI 拡張と違い、セッションの間ずっと生きている。常駐前提でリスナー登録や状態の持ち方を設計する。

3. インターフェースは shopify.addEventListener()

Web 標準風のイベントリスナー API。イベント名の文字列（'transactioncomplete' 等）を購読し、ハンドラで event を受ける。

4. 現時点で明示されているイベントは 3 つ

transactioncomplete ／ cashtrackingsessionstart ／ cashtrackingsessioncomplete。「取引」と「現金管理」というレジ運用のコアイベントから始まっている。

Docs

5. 詳細仕様は記事には無い ＝ ドキュメント確認が前提

event オブジェクトの中身、呼び出せる background API の一覧、対応する POS ／ API バージョン、UI 拡張との併用方法は記事に記載なし。実装前に公式の app background target ドキュメントと best practices を必ず確認すること。

8業務に活かせる3つのユースケース

POS
USE CASE 1

取引完了を起点にした店舗データの自動連携

課題
店舗の売上データを外部システム（CRM・ポイント基盤・分析基盤など）へ渡すのに、バッチ同期やスタッフの手動操作を挟んでいてタイムラグと抜け漏れがある。
打ち手
pos.app.ready.data で常駐し、transactioncomplete を購読。取引完了のたびにイベント情報を受け取って後続処理を発火する。
効果
スタッフの操作ゼロ・UI 表示ゼロで、取引発生をほぼリアルタイムに捕捉できる。レジ業務のオペレーションを一切変えずに済む。
技術メモ
event オブジェクトに含まれる取引データの範囲は記事に記載なし。外部送信の可否・方法も含め、実装前に app background target ドキュメントで確認。
¥ 開局 → 閉局
USE CASE 2

レジ開け・レジ締めの記録を自動化する現金管理ログ

課題
多店舗運営で「いつレジを開けて、いつ締めたか」の記録が店舗任せの手書き・スプレッドシート運用になっており、本部から実態が見えない。
打ち手
cashtrackingsessionstart ／ cashtrackingsessioncomplete を background で購読し、現金管理セッションの開始・完了をデータとして保存する。
効果
開閉局の事実が自動で残り、店舗横断での運用実態の把握や監査対応の下地になる。スタッフへの追加教育は不要。
技術メモ
イベントに含まれる金額等の詳細フィールドは記事に記載なし。データ保存の具体的な API（何にどう書けるか）もドキュメント側の確認が必要。
タイル UI 拡張 ＋ background 役割分担で設計
USE CASE 3

既存 POS アプリの「常駐ロジック」を UI から分離して再設計

課題
既存の POS UI Extensions アプリで、本来は裏で動いてほしい処理（記録・監視系）まで「スタッフがタイルを開いたとき」にしか実行できず、実行漏れが起きる。
打ち手
監視・記録系のロジックを pos.app.ready.data に移し、UI 拡張は表示と対話に専念させる構成へリファクタリング。
効果
「スタッフが開き忘れたら動かない」問題が解消。UI とバックグラウンドの責務が分かれ、拡張の設計が Web アプリ（画面＋Service Worker）に近い形に整理できる。
技術メモ
UI ターゲットとの併用可否・データ共有方法は記事に記載なし。best practices を含め app background target ドキュメントで設計方針を確認してから着手する。

9提案で使える1行サマリ

「POS Extensions に UI を描かない常駐枠 pos.app.ready.data が追加。
取引完了・レジ開閉のイベントを addEventListener で購読し、
スタッフの操作ゼロで記録・連携などのバックグラウンド処理を回せる。」