目次
Shopifyは2026年10月31日、顧客アカウントのフルページ拡張で、画面遷移イベントの意味を 2027-01から変更すると発表しました。遷移先をevent.fromから読み取る実装は、更新後に前の画面を表示するおそれがあります。担当者はAPI版を上げる前に、現在のページをshopify.navigation.currentEntryから取得する形へ修正してください。
本稿は2026年11月10日に確認した一次資料に基づく移行解説です。2027-01は確認時点でリリース候補版であり、現在の安定版2026-10に同じ変更が一斉適用されたという発表ではありません。以下のコードは未実行の実装例、検証表と切り分けは本サイトの提案です。
スポンサーリンク
対象は顧客アカウントのフルページ拡張
Shopifyの変更告知が対象として挙げるのは、customer-account.page.renderとcustomer-account.order.page.renderです。顧客向けの独立ページや注文にひも付く独立ページを追加しているアプリは確認対象になります。テーマの通常ページやPOSのカート処理まで、このイベント変更の対象だと広げて判断しないでください。
調査では、各拡張のshopify.extension.tomlと対象モジュールを対応付けます。currententrychangeのハンドラーだけでなく、共通のルーターへイベントを渡す関数、そこから画面名やデータ取得先を決めるコードまで追います。eventを別の変数名で受け取る箇所もあるため、event.fromという文字列の検索結果だけで完了とはしません。
Customer account UI extensionsの設定資料では、api_versionを[[extensions]]内に指定した場合、ルート階層の値より優先すると説明しています。ファイル先頭の版だけを見て、すべての拡張が同じ版で動くと判断しないことが大切です。対象ターゲット、実効API版、ルートを決める関数を一覧にすると確認漏れを減らせます。
遷移元と現在のページを使い分ける
2026-10以前では、対象イベントのfromは遷移先と同じ値でした。2027-01からは、顧客が離れた履歴エントリーを示します。例えば一覧Aから詳細Bへ進んだとき、新版でfromを描画の根拠にすると、URLの遷移に対して表示がAのまま残る原因になります。型としてURLを読めても、そのURLが何を指すかが変わる点に注意します。
遷移先の描画にはcurrentEntryを使います。一方、離れた画面を記録する目的でfromを利用しているコードは、その用途とAPI版を別に確認します。すべてのfrom参照を機械的に置換すると、本来必要だった遷移元の情報まで失います。「表示するページ」と「離れたページ」のどちらが必要かを、呼び出し箇所ごとに決めてください。
公式告知では、shopify.navigation.currentEntryを使う修正は2025-10以降で利用でき、API版の更新より先に適用できるとしています。これはAPI提供開始の範囲であり、古い版を現在の推奨配備先とする意味ではありません。すでにcurrentEntryやuseNavigationCurrentEntryを使っている拡張は、この変更による影響を受けないと案内されています。
スポンサーリンク
初期表示とイベント後の同期を同じ関数に集める
遷移イベントだけ直すと、直接ページを開いた最初の表示が古い状態のままになる可能性が残ります。次は、現在のエントリーを読む関数を初期化とイベント処理で共有する例です。renderRouteとrenderUnavailableはアプリ側で用意する関数であり、Shopifyが提供するAPIではありません。
function bindRoute(renderRoute, renderUnavailable) {
const sync = () => {
const entry = shopify.navigation.currentEntry;
if (!entry.url) {
renderUnavailable();
return;
}
renderRoute(new URL(entry.url));
};
shopify.navigation.addEventListener('currententrychange', sync);
sync();
return () => {
shopify.navigation.removeEventListener('currententrychange', sync);
};
}Navigation APIのリファレンスでは履歴エントリーのurlは取得できない場合にnullとなります。この例では、その場合に前の画面を正常な現在ページとして残さず、取得不能を表示する処理へ分けています。実際には読み込み中、対象外ルート、取得不能をアプリのUI設計に合わせて区別し、空文字を有効なページとして扱わないようにします。
返す解除関数は、利用するフレームワークの破棄処理から呼び出します。再表示のたびに別のリスナーを追加すると、一度の遷移で描画やデータ取得が重複する原因になります。登録時と同じ関数を解除へ渡し、初期化と後片付けの責任を同じ場所に置く構成を勧めます。
この例はURL全体を描画関数へ渡します。pathnameだけで十分なルーターもありますが、検索条件をsearchに保持するアプリでは、同じパスでクエリーだけ変わる操作も扱う必要があります。既存のURL解釈を確認せずpathnameへ統一すると、今回の修正とは別に絞り込み状態を失うため、読み取り元の変更とルート設計の変更を分けてレビューします。
表示の同期とデータ取得の競合を分ける
現在のURLを正しく読めても、前の画面の通信結果が後から届けば表示は食い違います。例えばAからBへ進み、さらにCへ進んだ後でBの読み込みが終わる場面です。遷移ごとの識別子を保持し、結果を反映する直前に現在の要求と一致するか確認するなど、古い結果を捨てる設計を別に用意します。
ここでevent.fromへ戻して表示を合わせようとすると、遷移元と遷移先の問題が混ざります。先に現在エントリー、選んだルート、表示中のデータの識別情報を分けて観測します。通信の開始順と完了順を意図的に変える試験はアプリ側の競合を見つけるためのもので、Shopifyのイベントが順不同になると断定する根拠ではありません。
また、入力途中の値をページ間で保持する場合は、URL、履歴エントリーのstate、コンポーネント内の状態を混同しないようにします。Navigation APIにはupdateCurrentEntryによる現在の履歴状態の更新がありますが、ルートを変える操作とは別です。今回の移行で状態保存の方式まで一括変更せず、入力保持の既存仕様が維持されるかを回帰試験へ入れます。
スポンサーリンク
二つのルートと履歴操作で移行を確かめる
まず開発ストアで、識別しやすい一覧Aと詳細Bを用意します。遷移前後で現在エントリーと表示見出しが一致することを確認し、同じコードを現行の安定版と2027-01ので比較します。単にクリックが成功したかではなく、最後に見えているページが移動先かを合格条件にします。
| 操作 | 確認する結果 |
|---|---|
| Aを直接開く | 遷移イベント待ちにならずAを初期表示する |
| AからBへ進む | 現在エントリーとBの見出し・データが一致する |
| 戻る・進む | 履歴で選ばれた画面と入力保持の仕様が一致する |
| 同じパスの検索条件を変える | クエリーに依存する一覧条件を更新する |
| BからCへ素早く移る | Bの遅い応答でCを上書きしない |
| 拡張を再表示する | リスナーや読み込みが重複しない |
履歴のpush、replace、traverseもアプリが使う範囲で確認します。新しい履歴を積む操作と現在の履歴を置き換える操作は、戻るときの期待が異なります。試験記録には開始画面、操作、期待する履歴、最終画面を残します。fromの値だけを観測して、画面と業務データの一致を確認せず合格にしないことが重要です。
公式のテスト・配備手順に従い、顧客アカウントを有効にした開発ストアとテスト顧客を用意し、shopify app devでプレビューします。注文にひも付くページを扱う場合は、その顧客で確認できるテスト注文も用意します。単体テストでURLの選択を確かめても、ホスト上の戻る操作や拡張の再表示まで確認したことにはならないため、プレビューでの結果を分けて残します。
画面が変わらないときの切り分け
最初に、実際に開いている拡張と変更したターゲットが一致しているかを見ます。次に、イベントが届いたか、currentEntryから読んだURLは何か、ルーターがどの画面を選んだかを順に確認します。URLがBなのにAを選ぶならルート解釈、Bを選んだのにAが見えるなら状態の反映や古い応答を疑います。この順序なら、API版だけを何度も変える調査を避けやすくなります。
試験用ログはルート名、遷移種別、要求の識別子など必要な範囲に絞ります。顧客のURLやクエリーを本番で丸ごと収集する設計を追加する必要はありません。開発ストアで値の意味を確認した後は、公開後の調査に必要な分類へ整理し、顧客データを含まないテスト用の入力で再現手順を残してください。
コード修正とAPI版更新を段階に分ける
進め方は、対象の棚卸し、現在エントリーを使う修正、現行版での回帰確認、2027-01での比較、配備後確認です。現行版で修正コードを試せる利点を使い、コードとAPI版を同時に切り替えたため原因が分からなくなる状況を減らします。差し戻し用には直前のアプリ版と設定を記録し、戻した後も表示と実データを確認します。
ShopifyのAPIバージョニング資料は、リリース候補版を開発用とし、本番利用には推奨していません。2027-01へ直ちに本番を移すことを本稿は勧めません。現在の対応版で修正を先行させ、安定版の提供時にリリースノートと差分を再確認して採用を判断します。新しい型定義でできたことと、利用者の履歴操作が期待どおりであることを、別の完了条件にしてください。
関連記事
Shopify POSのカート更新に関する移行解説では、別の拡張面でAPI版と実行結果を分けて検証する方法を扱っています。POS側の仕様は本稿の顧客アカウント拡張には適用されませんが、複数の拡張を保守する際の確認計画として参照できます。
スポンサーリンク
参考資料
Shopify：currententrychangeの変更告知（2026年10月31日）
Shopify：Navigation API（2027-01リリース候補版）
Shopify：Customer account UI extensionsの設定とテスト
Shopify：顧客アカウントのフルページ拡張の構築
Shopify：APIバージョニング
