POS拡張機能で動作バージョンを特定する新API
shopify.extension.version でデバイス上のビルドを即座に識別
API バージョン 2026-10 以降を対象とした POS UI 拡張機能において、shopify.extension.version フィールドが新たに利用可能になりました。商業者デバイスで稼働中の公開ビルド名を拡張機能側から読み取れるため、オフラインキャッシュ環境でのバージョン特定・デバッグ作業が大幅に改善されます。
1変更内容：Before / After
2業務に活かせる具体ユースケース
- 課題
- 複数店舗の POS デバイスがそれぞれ異なるキャッシュ済みビルドを動かしており、不具合発生時にどのビルドが原因か特定できない。
- 打ち手
- 拡張機能の起動時に
shopify.extension.versionを読み取り、バックエンドログへ送信するコードを追加する。 - 効果
- サポート問い合わせ時にバージョン名がログに残るため、再現手順の特定と修正対象ビルドの絞り込みが即座に行える。
- 技術メモ
- 値は文字列の等値比較のみに使用。数値的な大小比較はできない仕様。ローカル開発時は
undefinedになるため null チェックを忘れずに。
- 課題
- 段階的ロールアウト中に一部店舗だけ旧ビルドが残っており、新機能フラグを適切に制御できていない。
- 打ち手
- 拡張機能内で
extension.versionを取得し、特定のビルド名と等値比較して UI の出し分けを行う。 - 効果
- デバイス側のキャッシュ状態に関わらず、正確なビルドに応じた機能制御が実現し、誤った UI の表示を防げる。
- 技術メモ
-
shopify app deploy実行時に Dev Dashboard 上で付与されるビルド名が value として返る。名前の命名規則は記載なし。
- 課題
- 新バージョンをデプロイした後、オフライン運用中のデバイスが古いキャッシュで動き続け、デプロイ完了を確認できない。
- 打ち手
- 管理画面ツールと連携し、各デバイスから送信された
extension.version値を集計してデプロイ進捗ダッシュボードを構築する。 - 効果
- 全店舗のデバイスが新ビルドに切り替わった時点を把握でき、古いビルドのサポート終了タイミングを安全に判断できる。
- 技術メモ
- POS はバンドルをキャッシュしてオフライン実行するため、デプロイ直後でも古いバージョン名が返り続けるケースがある点に注意。
3技術者向けポイント
| 項目 | 詳細 |
|---|---|
| 対象 API バージョン | 2026-10 以降のみ。それ以前のバージョンをターゲットにした拡張機能は変更なし |
| フィールド名 | shopify.extension.version |
| 値の性質 | 不透過な文字列 (opaque name)。バージョン番号ではないため、等値比較のみ有効。ソート・大小比較は不可 |
| ローカル開発時の挙動 | ローカル開発サーバーから起動した場合は undefined を返す。必ず undefined ガードを実装すること |
| 表示場所との対応 | Dev Dashboard の Versions ページに表示されるビルド名と同一。shopify app deploy 実行時に決まる |
| 既存拡張機能への影響 | 対応は不要。新フィールドを使いたい場合のみ API バージョンを 2026-10 に上げる |
実装チェックリスト
- 必須 API バージョンを 2026-10 に指定
-
注意
undefined時のフォールバック処理を追加 - 推奨 バージョン名をログ・分析基盤へ送信
- 禁止 値を数値として比較・ソートしない
影響範囲まとめ
- POS UI Extensions のみ対象
- チェックアウト・その他 UI 拡張は対象外 (記載なし)
- 既存アプリの動作変更なし
- Liquid テーマへの影響なし
POS デバイスのオフラインキャッシュ環境でも動作ビルドを正確に把握できるようになり、マルチデバイス運用の品質管理・デバッグコストを大幅に削減できます。
Source: https://shopify.dev/changelog/identify-the-published-version-running-in-a-pos-extension | 公開日: 2026年10月12日
Share:
POS拡張画面の遷移完了を正確に検知する新イベント
Global Catalog REST API 2026年11月に完全停止