Appleが、WWDC24において「FinaceKitについて」を公開しています。

財務管理は現代生活において非常に重要な部分です。収入をクレジットカードの支払額と照らし合わせたり、単純に今月カプチーノにいくら使ったかを把握するにしても、財務データにタイムリーにアクセスする必要があります。そこで「FinanceKit」の出番です。

FinanceKit APIは、Apple Walletに保存されている財務データの中央リポジトリへのアクセスを提供します。

アクセスする財務データはすべてデバイス上のローカルなもので、アクセスにインターネットは必要ありません。

さらに、FinanceKitは、Apple CardとSavings、Apple Cashを含む複数のソースからの財務データを集約します。 そして最後に、FinanceKitは、アプリがどの金融データにアクセスするか、またどの程度アクセスするかについて、データ所有者が明確にコントロールできるようにすることで、プライバシーを保護します。

FinanceKitは、魅力的な金融アプリを構築するために使用できる豊富な金融情報セットを提供します。

これには、各口座のハイレベルな詳細情報、最新の既知の変更時刻を含む利用可能な残高情報、お金の出し入れや利用可能なクレジットの変更などの金融取引へのアクセスが含まれます。また、すべての履歴も見ることができます。

FinanceKitは、財務データをモデル化するために3つの主要なデータタイプを公開しています。

根幹にあるのは口座です。これは当座預金口座、クレジットカード、あるいはApple Cardの普通預金口座などを表します。

どの口座にも残高があり、これは特定の時点での口座の金額を表します。

残高に加え、口座にはトランザクションが含まれます。

トランザクションとは、要するに、口座へのお金の出入りを表すものです。

FinanceKit は、ユーザーが口座を開設してから、金融データの取り扱いに関する現地の法律に従って、これらすべてのモデルがどのように変化したかを追跡します。

現在、取引は多くの有用なフィールドを含む構造体です。トランザクションごとに一意であるだけでなく、デバイスごとにも一意である識別子を含みます。

このIDは、あるトランザクションが時間とともにどのように変化していくかを追跡するのに特に有用です。

ほとんどのトランザクションは、ISO 18245に準拠したマーチャントカテゴリーコードを提供します。

これは、あなたのアプリが支出カテゴリーを追跡する場合に有用であり、財務データで利用可能であれば、マーチャント名に有用です。

すべての取引にはオリジナルの取引説明が含まれます。これは金融機関から提供されたもので、可能であれば表示しやすい説明も利用できます。

取引には常に取引日が含まれ、金融機関から受け取った情報の状態と深さに応じて、FinanceKit は取引が計上された日付を提供します。

そして最後に、取引は通貨コードと小数値からなる金額を提供します。取引が海外で発生した場合、金融機関は外貨建ての金額も提供します。

ここで重要なのは、これらの金額について、FinanceKitは通貨間の変換を行っていないということです。FinanceKitのデータは、金融機関から受け取ったそのままの形で提供され、デビットかクレジットかにかかわらず、正の小数値として保存されます。そのため、ある取引が貸方か借方かをどうやって判断するのか疑問に思うかもしれません。そこでクレジット・デビット・インディケーターが登場します。

すべての取引には、借方または貸方のインジケータ・プロパティがあり、それを読み取ることで、指定した口座にお金が動いたか、それとも口座からお金が動いたかを示すことができます。

財務データへのアクセスは主に3つの部分で構成されています。

・データの可用性を判断すること ・ピッカーを使ってユーザーが選択した財務データセットにアクセスすること ・クエリAPIを使って財務データへの1回限りまたは長期間のアクセスを作成することです。

まず、あるデバイスがFinanceKitをサポートしているかどうか、そしてサポートしている場合、財務データが制限されているかどうかを判断する方法について説明します。

財務データの利用可能性を確認するには、まずFinanceKitをインポートする必要があります。

次に、Finance StoreクラスのisDataAvailableメソッドを使用し、financialData列挙型のケースを渡して、データが利用可能かどうかをチェックします。もしフレームワークがfalseを返したら、他の財務データ関連の呼び出しを行ってはいけません。このようなシナリオでは、フレームワークはアプリを終了します。

一方、trueを返した場合、この値はアプリの起動の間で変わることはなく、iOSのバージョンにわたって一定であるとみなすことができるという確信を持って、アプリを続行しても問題ありません。

trueを返しても、実際のデータがデバイス上でアクセス可能であることを保証するものではないことに留意してください。

財務データが利用可能であったとしても、デバイスやデバイス構成によってはアクセスが制限される可能性があります。

財務データが利用可能であったとしても、デバイスやデバイス構成によってはアクセスが制限される可能性があります。

データの可用性は一定として扱うことができますが、データの制限は一過性のものである可能性があり、アプリがフォアグラウンドにある間でも、呼び出しの間にその値が変わる可能性があります。

例えば、Apple Walletアプリが利用できない場合や、企業のモバイルデバイス管理システムによってApple Walletへのアクセスが制限されている場合などです。

データが制限された場合、フレームワークは終了せずに、データが制限されたことを示すエラーを投げます。

この時点で、あなたのアプリは財務データに現在アクセスできないことをユーザーに通知することができます。

財務データが利用可能であるという知識があれば、財務データにアクセスする準備が整います。これを行う迅速で簡単な方法は、あなたのアプリを使用している人が、FinanceKitのトランザクションピッカーを介して、あなたと共有したいトランザクションを選択できるようにすることです。

この新しいビューは、利用可能なトランザクションの選択可能なリストを表示するタイミングを決定する機能をアプリに提供します。

query APIは非同期で、トランザクションだけでなく、FinanceKitを通じて利用可能なすべての財務データ型へのアクセスを提供します。明示的な許可なくデータが共有されることがないよう、ユーザーの同意が必要です。しかし、その承認があれば、あなたのアプリは利用可能な財務データに継続的にアクセスできる持続的な接続を持つことができます。

また、これらのAPIはiOS 17.4以降を搭載したiPhoneで利用可能です。

さて、FinanceKitでデータを照会するには2つの方法がある。

1つ目は、財務データ型を現在の値に基づいて並べ替えたコレクションを返す方法です。

述語、ソート・ディスクリプタ、リミット、オフセット・パラメータを受け付け、非同期で財務データ型の順序付きコレクションを返し、アプリで使用することができます。

また、少し異なる方法で動作する変更専用APIもあります。これらのクエリーは、一致する財務データの配列を返す代わりに、目的のデータで発生した変更の履歴を返します。

そして、これらは長期間実行することができる。そのため、あなたのアプリは、金融機関から新しいデータが届くとすぐに、変更のみの更新を得ることができます。

また、少し異なる方法で動作する変更のみのAPIもあります。これらのクエリは、一致する財務データの配列を返す代わりに、目的のデータで発生した変更の履歴を返します。

そして、このクエリは長時間実行することができる。そのため、あなたのアプリは、金融機関から新しいデータが届くとすぐに、変更のみの更新を得ることができます。

さて、これらのAPIを使用するには、いくつかの追加要件があります。そのため、ドキュメントに入る前に、トランザクション・ピッカーがあなたのニーズに合わないことを確認したい。まず、アプリのinfo.plistに顧客に表示される静的な利用説明を追加する必要があります。

これは、privacyの下にあるFinancial Data Usage Descriptionを探すか、NS Financial Data Usage Descriptionキーで手動で追加することで行うことができます。

リクエスト認可の呼び出しの結果は、ユーザーがいつでも設定からこのアクセスを取り消すことができることを念頭に置いて、金融データを照会するための許可を持っていることを意味し、付与されることができます。

アクセスが拒否された場合、結果は拒否されます。そして最後に、ユーザーが意味のある選択をする機会がなかった場合、結果はunknownを返す可能性があります。

request authorizationを呼び出すとステータスが返されますが、authorizationStatus関数は、ユーザーにプロンプトを表示することなく、単に現在のステータスを返します。

自分のアプリをApp Storeで公開したいと決めたら、配布権限をリクエストする必要があります。

他の多くのフレームワークのように、ユーザーがアクセスを許可するか拒否するかの選択をした場合、認可を要求する際に再度プロンプトが表示されることはありません。

しかし、後日気が変わった場合は、設定から財務データへのアクセスを変更することができます。

そこから、より多くのアカウントを共有したり、最も早い共有日を変更することもできます。

勘定科目がどのような構造になっているかを見てみましょう。

口座はenumケースとしてモデル化され、すべての口座に共通するプロパティと、特定の口座タイプに固有のプロパティがあります。

こうすることで、FinanceKitは共通のコアを維持しつつ、それぞれの口座タイプに固有のプロパティを柔軟にモデル化できるようになります。

これらの共通プロパティの一つは、ローカル一意識別子です。口座識別子はすべての取引と残高にも存在するため、これらのオブジェクトのそれぞれを含む口座に関連付けるのは非常に簡単です。

各口座には機関名（口座が属する機関の名前を表す文字列）、表示名（顧客に表示する口座の名前）、口座説明（機関がサポートしている場合）があります。口座の主要通貨は3文字の通貨コードで示されます。

これらはすべて、口座モデルに存在する共通のプロパティです。口座が負債口座である場合、例えばApple Cardの口座モデルに使用されるものであれば、追加プロパティを持ちます。

Long-running queriesは、あなたのアプリが、あなたのデバイス上で受信されるとすぐにライブアップデートを消費することに興味がある場合、またはアプリの起動の間にクエリを再開可能にしたい場合に表示されます。ロングランクエリは、Swift の非同期シーケンス上に構築され、更新の継続的なストリームを簡単に配信することができます。

スナップショットクエリのようにモデルの配列を返す代わりに、ロングランクエリは変更を返します。変更は、挿入されたモデルの配列（例えば、前回の更新以降のすべての新規トランザクション）、更新されたオブジェクトの配列（例えば、クレジット限度額が増加した負債口座）、および削除されたオブジェクトの識別子で構成されます。

すべての変更は履歴トークンも提供します。

これは、開設時にすべての取引を読み込むパーソナル・ファイナンス・アプリケーションの例である。そして、関連する口座に新しい取引があると、すぐに画面に表示されます。

さて、単純な長時間実行クエリがどのように機能するかを見たので、再開可能機能を使ってみましょう。

まず最初に、APIから新しい変更を処理するたびに、履歴トークンをディスクのような安全な場所に保存します。

保存された履歴トークンを使うには、それをロードしなければなりません。それから、sinceパラメータを使って、履歴クエリに最新のトークンを渡すことができます。

この簡単な変更で、我々のアプリはリランチの間に長く実行されたクエリを再開することができ、イベントの重複をなくすことができます。

金融データの非同期シーケンスは通常終了しないので、アプリが消費するライブアップデートを生成できます。

再開可能なクエリのみがアプリケーションにとって重要である場合、最適な解決策は、新しい変更を監視しないように長時間実行するクエリにパラメータを渡すことです。そうすることで、非同期シーケンスはアプリが既存の変更をすべて処理した時点で終了します。

以上、デバイス上の財務データにアクセスできる可用性を判断する方法と、FinanceKitをアプリに統合する際に留意すべきベストプラクティスを紹介しました。