CordovaからCapacitorへの移行時の非互換調査

こんにちは。コドモンプロダクト開発部の関です。こちらの記事はコドモン Advent Calendar 2024 の15日目の記事です🎅

こちらの記事にもありますが、コドモンの保護者向けモバイルアプリはCordovaからCapacitorにアプリ基盤を移行しました。この記事では、移行作業の中で行った非互換調査について紹介します。CordovaからCapacitorに移行しようとしているプロジェクトがどの程度あるかはわかりませんが、非互換調査で参考になる情報はいくつかあるのではないかと思い、ブログを執筆することにしました。 CordovaからCapacitorへの移行の道のりについてはまた別の記事で紹介したいと考えています。

どのような観点で調査したか

非互換調査は次の観点を完了基準として実施しました。

利用者が影響を受ける非互換が明らかになっていること
対応方針が決まっていること
修正箇所が洗い出されていること

利用者が非互換の影響を受ける場合は、非互換の影響をなるべく小さくする方法や利用者への案内、問い合わせ対応などを検討する必要があります。特に利用者への案内を行う場合は、ある程度の期間を設けて事前に通知する必要があるので、リードタイムのボトルネックになる可能性が高く、早めに対応しなければなりません。対応方針の決定と修正箇所の洗い出しは、作業計画の見通しを立てるために重要になってきます。

利用者が影響を受ける非互換の調査

OSバージョン

移行先のCapacitorのバージョンは当時の最新メジャーバージョンのv6をターゲットにしていました。Capacitor v6が対象とするOSバージョンは次の通りです。

iOS13以降
Android 5.1以降

現行のCordovaアプリをコドモンが正式にサポートしている動作確認環境は、Capacitor v6が対象とするOSバージョンよりも新しいOSバージョンになっていました。

見た目や挙動の違い

見た目については、主にCordovaアプリでプラグインが関連している以下の箇所が影響を受ける可能性がありました。これらは現行アプリと極力差異が発生しないように検証を重ねつつ、事前に社内で情報共有を行いました。

アイコン
ステータスバー
スプラッシュスクリーン

他にも、プラグインの実装依存によって挙動が変わる箇所の影響調査を行いました。プラグイン利用箇所の非互換に調査結果を添付しますが、例えばアプリ内ブラウザにリロードやシェアなどのインターフェースが追加されるといった変化についてまとめました。

修正箇所の洗い出し

Web Storageの移行

現行のCordovaアプリは古いcustom schemeであるfile://を維持していましたが、移行によりこのcustom schemeを維持できなくなります。その結果Web Storageにアクセスできなくなることから、Web Storageの移行が必要になりました。
この問題に対応するために、事前に現行のアプリでWeb Storageの内容をアプリ固有の領域に保存し直す修正をリリースし、新アプリ基盤移行後はアプリ固有の領域に対して読み書きする実装に変更しています。

通信に関する非互換

CordovaとCapacitorはそれぞれ、アプリからの通信がネイティブを経由するケースが存在し、実装が異なります。実際にエンコードの処理の違いにより、JavaScriptでエンコードを行う処理が必要になる箇所が存在しました。
非互換は以下の形で洗い出しました。

自動テストを一通り実施
パラメーターの型（数値、文字列、配列、ネストしたオブジェクトなど）を一通り検証
現行アプリで特殊な形態の通信（バイナリデータ送受信など）を一通り検証

プラグイン利用箇所の非互換

Cordovaアプリがプラグインで実現している箇所には、以下のような非互換の可能性があるので、どのような観点で調査したかで挙げた完了基準に従い、一つひとつ調べていきました。

アイコン、ステータスバー、スプラッシュスクリーンなど見た目に関わる変化
内部ブラウザなど内部実装の違いによる挙動の変化
開いているダイアログを一斉に閉じる機能など、プラグインのインターフェースの違いによる利用できる機能の差異

多くは互換性のあるプラグインで置き換えていけばよいのですが、非互換のあるものは代替プラグインの仕様に合わせるのか、個別の実装を行うのかなどの検討が必要になってきます。

プラグイン利用箇所以外の非互換

Cordovaアプリには、プラグイン利用箇所以外にもCordovaプラットフォーム固有のコードの書き方になっている箇所があります。また、コドモンの保護者向けモバイルアプリはモバイルアプリとWeb版を同一ソースコードで提供しているので、Cordovaプラットフォーム上で動作しているのかを判別する必要もあります。このようなコードの記述も移植する必要があるので、該当箇所の調査を行いました。

プラグイン利用箇所以外に必要な修正の調査 — プラグイン利用箇所以外に必要な修正

設定値の移植

Cordovaアプリはビルド時にiOS ／Androidそれぞれのプロジェクトを都度生成、上書きします。具体的には、Cordovaプロジェクトの設定ファイルであるconfig.xmlの内容をもとに、プロジェクトを生成し、各プラットフォームの設定ファイル（例えば、iOS の Info.plist や Android の AndroidManifest.xml）を必要に応じて更新します。一方で、CapacitorはiOS ／Androidのプロジェクトを最初に生成した後、それぞれのプロジェクトを直接編集するスタイルになっています。そのため、config.xmlの内容をiOS ／Androidそれぞれのプロジェクトに移植する必要があります。また、プラグインについてはpackage.jsonに設定値を持つものが存在します。この設定値はビルドスクリプトによって各プラットフォームの設定ファイルに展開されるものがあります。
そこで、Cordovaの設定値をCapacitorアプリにどのように反映すればよいか、次の調査方針に従って調査しました。

それぞれのプラットフォームの既定値であれば明示的に設定はしない
プラグイン固有の設定についてはプラグインの非互換調査に含める

調査結果は次のようになりました。

大半は移植の必要がないという結果になりましたが、設定値についてはどのような意図で設定されたものかを知る手掛かりがほとんど無く、現行アプリの挙動を正としながら設定を一つひとつ調べていきました。

さいごに

移行作業の過程で今回の資料をまとめましたが、Capacitorのバージョンアップや次のアプリ基盤移行、仕様調査の際にも参考になると考えています。ですので、移行が完了したタイミングで調査結果を最新化しています。今回の移行作業では、過去の経緯が残されてなくて調査に苦労した点も省みて、改善を進めていきたいと考えています。