FinanceKitについて

FinanceKitについて

FinanceKitを財務管理アプリで使用すると、ユーザーの同意を取得しコントロールを提供しつつ、Apple CashやApple Cardなどに関連するデバイス上のデータをシームレスかつ安全に共有できます。口座、トランザクション、残高などの情報への1回限りまたは継続的なアクセスをリクエストする方法のほか、iOSおよびiPadOSで優れた体験を実現する方法についても説明します。

関連する章
- 0:00 - Introduction
- 1:48 - Overview of data types
- 5:03 - Access financial data
- 21:56 - Best practices
リソース
ダウンロード

こんにちは Antonioです Apple Walletチームの iOSエンジニアです現代では家計の管理が重要な役割を持っていますクレジットカードの支払額に対して自身の収入が十分かまたは今月はカプチーノ代にいくら払っているかなど自身の財務データにいつでもアクセスできる必要がありますそこで FinanceKitの出番です
FinanceKit APIは Appleウォレットに保存された財務データの中央リポジトリへのアクセスを提供しますアクセスする財務データはすべてデバイス上のローカルデータでありアクセスにインターネットを必要としませんまた FinanceKitは Apple Card、Savings Apple Cashなどから財務データを集計しますまたプライバシー保護策としてアプリがアクセスできる財務データの種類と金額をデータ所有者が明示的に管理できます FinanceKitは魅力的な財務アプリの構築に使用できる充実した財務データを提供します例えば各口座情報の概要最新の取引履歴を含む利用可能残高の情報入出金や利用可能な借入枠の変更などの金融取引の情報などですこれらの履歴も確認できます一緒に確認していきましょう本セッションでは FinanceKitの概要と財務データにアクセスして表示する上で理解しておくべきことを説明しますまず FinanceKit APIが持つコア構造の概要を見ていきます次に Appleウォレットに保存される豊富な財務データにこのAPIを使用してアクセスする方法を説明します最後にアプリにFinanceKitを統合する際に留意すべきベストプラクティスをいくつかお伝えします
まずはみなさんが利用できる主な要素の概要から説明します FinanceKitは主に3つのデータ型を使用して財務データをモデル化しますその基礎は口座です当座預金口座やクレジットカード Apple CardによるSavingsなどが該当しますすべての口座には残高があります大まかにいうと残高は特定の時点で口座にある金額を指します口座には残高のほかにトランザクションがあります端的にいうとこれは口座への入出金を指します FinanceKitはこれらのモデルに生じたすべての変化をユーザーによる口座開設の時点から金融データの処理に関する現地の法令に準じてトラッキングしますトランザクションは構造体であり有用な一連のフィールドで構成されますフィールドの一つであるIDはすべてのトランザクションに対し一意でありかつ各デバイスに対しても一意ですこのIDは特にトランザクションの経時変化をトラッキングする上で有用です大半のトランザクションには ISO 18245に準拠したマーチャント（加盟店）カテゴリコードがありますこれはアプリで支出カテゴリをトラッキングする場合に役立ちますまた一部の財務データではマーチャント名もあります
すべてのトランザクションにはオリジナルの説明がありますこれは金融機関が提供するコードです一部の財務データでは分かりやすい表示用の説明もありますトランザクションには必ずトランザクションの日付がありますまた金融機関から受領したステータスと情報の詳細度に基づき FinanceKitはトランザクションの投稿日を提供します最後に通貨コードと十進数の値で構成される金額のデータがありますトランザクションが国外で発生した場合金融機関から金額がその国外通貨で提供されますここで重要なのは FinanceKitでは金額に対し通貨の換算を行わない点です FinanceKitのデータは金融機関から受領した金額と通貨のままで提供され借方であるか貸方であるかに関係なく正の十進数の値として保存されますではトランザクションが貸方であるか借方であるかをどのように判断するのでしょうかそのために貸方借方を示すインジケータがありますすべてのトランザクションに口座への入金であるか出金であるかを示す creditDebitIndicatorがあります当然ですがこのインジケータに可能な値は debitまたはcreditですしかし注意すべき点はこの値の解釈が口座の種類によって変わることです
トランザクションが借方であれば資産勘定では口座残高が減少します例えば Apple Cashなどのトランザクションですまた負債勘定のトランザクションでは借入枠が減少します例えばクレジットカードなどですトランザクションの creditDebitIndicatorが貸方であればそのトランザクションによって資産勘定であれば残高が増加し負債勘定であれば借入枠が増加します以上 FinanceKitで使用する最も重要な型を簡単にご紹介しました詳細については利用できるすべてのクラス　構造体フィールドを網羅したドキュメントをご参照ください必要な基礎を説明できたのでエキサイティングなパートに移りましょうこれらの型で表現される財務データに FinanceKit APIでアクセスする方法です財務データへのアクセスは主に3つの部分で構成されていますデータを利用できるかどうかの判断ユーザーが選択した財務データにアクセスするためのピッカーの使用クエリ用のAPIを使用した財務データへの 1回限りまたは長期的なアクセスですでは目的のデバイスが FinanceKitをサポートしているかを判断しまたサポートしている場合制限対象の財務データの有無の判断から始めましょう財務データが利用可能か確認するにはまずFinanceKitをインポートします次に FinanceStoreクラスの isDataAvailableメソッドを使用してデータが利用できるか確認し financialDataの列挙型のケースを渡しますフレームワークがfalseを返した場合財務データに関連するほかの呼び出しはできませんその場合強いシグナルを送るためにフレームワークはアプリを終了します一方フレームワークがtrueを返した場合この値がアプリの起動ごとに変化せず複数のiOSバージョンでも一貫していると見なせることが保証されます
ただし trueが返されてもデバイス上で実際のデータを必ずしも利用できるとは限りません財務データが存在してもデバイスの種類や設定によってはアクセスが制限されることがありますデータを恒常的に利用可能と見なせる場合もデータへのアクセス制限は変動しますアプリがフォアグラウンドで動作していても呼び出しごとに制限は変化し得ます
例えば Appleウォレットアプリが利用できないことや企業のモバイルデバイス管理システムで Appleウォレットへのアクセスが制限されていることがあります
データが制限されるとフレームワークからエラーがスローされますがアプリは終了せずデータが制限されていることが示されますこの時点で財務データに現在アクセスできないことをアプリがユーザーに通知します
財務データが利用可能であることがわかっていればその財務データにアクセスできますこれを迅速かつ容易に実現するにはアプリのユーザーが共有したいトランザクションを FinanceKitのトランザクションピッカーで選択できるようにしますこの新しいビューでは利用できるトランザクションを選択するためのリストをいつアプリに表示するか決定できますアプリのユーザーはトランザクションのリストを表示してアプリからのアクセスを許可する対象を選択しますデフォルトではトランザクションは時系列順に表示されますが画面上部の検索フィールドに入力したフリーテキストに基づく絞り込みや入力中に提示されたトークンを使用した絞り込みもできますなおアプリからトランザクションへのアクセスはトランザクションの共有後すぐに可能になりますがこのアクセス許可は一時的なものです共有されたトランザクションは直接アプリに渡されてすぐに使用されピッカーには記憶も保存もされませんピッカーの使用方法は非常に簡単です PhotosPicker APIの使用経験があれば Transaction Picker APIにもなじみやすいでしょう極めてシンプルな方法で FinanceKitやFinanceKitUIに関連する UIフレームワークをインポートできます次に選択したトランザクションを保持する変数を宣言しますこの例では ViewのStateプロパティを使用しますすでにお話ししたように財務データが利用可能かどうかはアプリ側で判断する必要がありますこの例では Viewのbodyで isDataAvailableを呼び出し selectedItemsのstate変数を 1つ目のパラメータとして TransactionPickerビューに渡します 2つ目のパラメータとして ViewBuilderクロージャを渡しますこの例ではこのクロージャは単にピッカーの表示をトリガするボタンのラベルですこの数行のコードだけでタップするとトランザクションピッカーを表示し選択したトランザクションをアプリで使用可能にするボタンができますこのトランザクションピッカーは出張旅費をトラッキングするアプリなどに最適ですまたは特定のトランザクションへのアクセスをアプリユーザーが選んで許可できるようにする場合やあらゆるトランザクションへのアクセスを私用のものも含め無制限に許可する場合にも有効ですただアプリの中には当然ながらウォレットの財務データにフルアクセスできると極めて便利なものがあります
財務データへのフルアクセスに使用できるクエリのAPIの詳細を見てみましょうこのAPIは継続的なユースケースにもデータのスナップショットにも対応しますクエリのAPIは非同期的に動作しトランザクションだけでなく FinanceKitで利用できるすべての種類の財務データへのアクセスを提供します明白な許可なくデータが共有されないようユーザーの同意が必須ですが承認が行われるとアプリは永続的な接続を確立して利用可能な財務データに常時アクセス可能になります便利なことにこれらのAPIは iOS 17.4以降を搭載する iPhoneで利用できます FinanceKitでは 2種類の方法でデータのクエリを実行できます
1つ目の方法では現在の値に基きタイプごとに一連の財務データを順序つきで返しますこの方法ではプレディケート（述語）ソート記述子上限値オフセットの各パラメータを利用でき順序をつけたタイプごとの一連の財務データを非同期で返してアプリで使用できるようにしますもう1つの方法は変更のみを対象とする APIで機能が少し異なります条件に一致した財務データの配列を返すのではなく取得したいデータに発生した変更の履歴を返しますこれらのAPIは継続的に動作するため金融機関から新しいデータが提供されると変更のみに絞られた更新情報がアプリに取得されます現在クエリのAPIの使用には追加の要件があるのでドキュメントを調べる前にご自身のニーズにトランザクションピッカーで対応できないか確認しましょう要件の1つ目はユーザーに表示する原則的な利用方法の説明をアプリのInfo.plistに追加することですそのためにはプライバシーの箇所にある財務データの利用方法の説明を探すか NSFinancialDataUsageDescription キーを使用して説明を手動で追加します
この説明を入力すると FinanceStoreクラスの共有インスタンスに対して requestAuthorization関数を呼び出すことにより認可をコードによりリクエストできるようになります
認可をリクエストすると財務データへのアクセス許可を求めるシステムアラートが表示されます許可すると共有する口座を選択する画面が表示されます requestAuthorizationの呼び出しの結果が grantedの場合財務データへのクエリが許可されますなおユーザーはこの許可をいつでも設定から取り消せますリクエストの結果がdeniedの場合アクセス取得のリクエストは却下されますまた unknownが返されることもありますこれはユーザーが有効な選択を行う機会がなかった場合に発生します requestAuthorizationの呼び出しではステータスが返されますが authorizationStatus関数ではユーザーへのプロンプトはなく現在のステータスを返すだけです App Storeでアプリを入手できるようにする場合は配信エンタイトルメントをリクエストする必要がありますこのリクエストのための効率的なプロセスを利用できます本セッションの関連リソースにこれに関する情報ページへのリンクがあります認可リクエストのプロセスをコードで見てみましょう FinanceKitのインポート後財務データの有無を確認しある場合のみ以降の処理に進みます共有のFinanceStoreインスタンスに対し認可リクエストを呼び出します該当するシステムダイアログがある場合アプリ画面の上部に表示されますユーザー側で選択を行うとダイアログが閉じこの非同期関数からアプリに新しいステータスが返されます
ユーザーが財務データへのアクセス権を付与したか確認し先へ進むことができます
先ほど見た通りアプリからの認可リクエストに対しユーザーが意思表示しない場合システムアラートが表示されますユーザーがを押すと認可はdeniedのステータスを受け取ります一方を押すと OSが選択可能な口座のリストを表示しますユーザーはどの口座を共有するかをこのリストから選択して口座ごとにアプリで利用できるアクティビティを共有の開始時点も含め指定できますユーザーの考えが変わった場合を押せばアプリは次に必要が生じた際再度認可をリクエストします
一方のボタンを押すと選択が確定され制御がアプリに渡されます
ほかの多くのフレームワークと同様にユーザーがアクセス権の付与または拒否を選択すると同じ認可リクエストがあった際再度の選択は求められませんただしユーザーが後で考えを変えた場合はから財務データへのアクセスを変更できます共有する口座を追加できるほか共有の開始時点も変更できますこれでアプリに対しユーザーの財務データへのアクセス権が付与されたのでデータのクエリの方法を確認しましょうその前に口座について知っておくべきこととして FinanceKitによって公開される主要な財務データタイプがありますその構造を説明します
各口座は列挙型のケースとしてモデル化され全口座に共通のプロパティとその口座タイプに固有のプロパティを持ちますこの構造のため FinanceKitは柔軟性が高く各々の固有のプロパティで各口座タイプをモデル化しつつ共通の中核的要素を維持できます共通のプロパティの1つは一意のローカルIDです口座IDはすべてのトランザクションと残高にも存在するのでこれらの各オブジェクトをそれぞれの口座に容易に関連づけできますどの口座にも金融機関名があります金融機関名は口座が存在する金融機関の名前を表す文字列です表示名はユーザーに表示される口座名です金融機関によっては口座の説明も提供されます口座の主要通貨は 3文字の通貨コードで示されますこれらはすべて口座のモデルに共通のプロパティです負債勘定の口座例えば Apple Card口座のモデル化に使用している口座などの場合は追加のプロパティがあります借り入れできる最大額を示す利用限度額次回決済日最小決済額などのほか期限切れの決済額があればそれも含まれます口座をモデル化する方法がわかったので FinanceStoreから口座のクエリを実行しましょう
まずソート記述子として Account.displayNameを定義しますクエリではソート記述子は必須ではありませんが少なくとも1つは使用することをおすすめします次にSwiftの新しいプレディケートマクロを使用してプレディケートを定義しますこの例では Apple Card、Apple Cash およびSavingsに口座をリンクします
次にソート記述子とプレディケートを引数として渡すクエリを作成しますご覧のようにどの財務データの型にもクエリが関連づけられています最後にクエリを実行して一致する口座をストアから取得します以上口座について確認したので次は残高に関する処理を見てみましょうすでに説明したようにどの口座にも残高が少なくとも1つありユーザーがiOS 17.4にアップグレードした時期によっては複数の残高があります
FinanceKitは残高の履歴記録を保持しますこれは例えば残高のトレンドなどの残高の経時的変化を表示するために使用できますまず残高の構造を確認しましょう残高は 3つのケースで構成される列挙型としてモデル化されます Availableは残高の生成時に保留中のトランザクションを算入するためのものです Bookedでは投稿済みのトランザクションのみを算入します Available & Bookedにはその名の通り 2つの残高を表示する 2つのフィールドがあります
この違いを除けば残高のプロパティはほかのすべての列挙型のケースと共通です本セッションでご紹介したほかの財務データの型と同様に残高にも一意のローカルIDがあります口座IDとともに帰属する口座への残高のマッピングに使用できます FinanceKitは金融機関で残高が計算された日付も AsOfDateプロパティに記録しますこのプロパティを使用して残高が最新であるかの確認もできますもう一つ重要なこととして残高は十進数の値と通貨コードをペアにした金額を1つ以上持ちますなお残高の金額についてはデータを提供するのは金融機関でありフレームワークによる計算ではありませんまたこの金額は正の値で保存されますそのためこのフレームワークでは別途 creditDebitIndicatorプロパティで残高の状態を区別します資産勘定で残高のcreditDebitIndicatorが debitであればその残高はマイナスです逆に残高の値がcreditであれば残高はプラスです負債勘定の残高の creditDebitIndicatorがcreditならその口座はその時点で貸方になっています一方口座に支払い済みの残高があれば口座は借方となります残高の構造を説明したのでデータのクエリを実行してご覧のようなグラフを作成する方法を確認しますこのグラフは最新の利用可能残高の日ごとの変化を示しています getBalances関数で最近の日付から遡って残高を取得するためにまず逆日付順のソート記述子を定義します次に利用可能残高のみ表示されるように結果を絞り込みさらに目的の口座の残高のみに絞り込みます
クエリの作成手順はすでにおなじみですがここではソート記述子とプレディケートを使用するほかに結果の表示件数も制限します
このクエリを実行してその結果が時系列順で表示されるように取得した残高を逆日付順にします以上はスナップショットクエリでしたが次は継続的なクエリについて説明します継続的なクエリが適しているのはデバイスがアップデートを受信するたびにリアルタイムでそのデータを利用する場合やアプリの起動ごとにクエリを再実行する場合です継続的なクエリは Swift asyncのシーケンス上で作成するので更新を簡単に継続的にストリーミング配信できます継続的なクエリが返すのはスナップショットクエリと同様にモデルの配列ではなく変化ですこの変化とはデータベースの前回の状態や初期状態からの差分です変化には次の構成要素がありますまずはモデル挿入の配列で例えば前回の更新以降のすべての新規トランザクションです次はオブジェクト更新の配列です例えば負債勘定での利用限度額の引き上げなどですオブジェクトIDの削除もありますこれはウォレットに存在しなくなった財務データオブジェクトをアプリで削除する場合などですすべての変化では履歴トークンも提供されます履歴トークンは特定の時点における財務データストアのプロキシです履歴トークンは不透明な構造体で Codableに準拠しているため容易にシリアル化できます履歴トークンを使用して継続的なクエリを再開し特定時点以降のストアの更新を取得できます空き領域とパフォーマンスの向上のために履歴の変化をシステムで圧縮できます一般的にこのような圧縮はまれです FinanceKitでは履歴を少なくとも数か月は非圧縮で保持するためですただしアプリで保存された最新のトークンに相当する変化が圧縮されている場合履歴クエリからエラーがスローされることがありますとはいえこれは問題ではありませんフレームワークはデータを失うことなくアプリが通常の動作に復旧できるようにしつつクエリを再開することができます次はトランザクションに対するシンプルな継続的クエリを作成する方法です FinanceKitをインポートした後 transactionHistory APIを使用してトランザクション履歴の非同期シーケンスを定義してから transactionSequenceにおいて for awaitですべての変更をリッスンしますこれでそれらの変更を自由に処理できるようになりますこのサンプルの個人用財務アプリでは起動時に全トランザクションを読み込みます関連づけられた口座で新しいトランザクションが取得されるとただちに画面に表示されますシンプルな継続的クエリの動作を確認しました次に再開可能な機能を使用してみますまず APIで新しい変更を処理するたびに履歴トークンがディスクなどの安全な場所に保存されます保存された履歴トークンを使用するには読み込む必要があります次に読み込んだ最新のトークンを sinceパラメータを使用して履歴クエリに渡しますこの簡潔な変更によりアプリの再起動ごとに継続的なクエリを再開してイベントの重複を排除できるようになります財務データの非同期シーケンスは通常は終了することなくアプリが使用する更新データをリアルタイムで生成しますアプリにおいて再開可能なクエリのみが重要である場合新たな変更をモニタリングするよりも継続的なクエリにパラメータを渡す方が優れたソリューションと言えますこの方法では既存の変更の処理がアプリですべて完了し次第非同期シーケンスは終了しますこのような方法でデバイス上の財務データの有無の判断とアクセス許可が行われます最後にアプリに FinanceKitを統合する際に留意すべきベストプラクティスをいくつかお伝えします繰り返しになりますが財務データは誰にとっても機密性が高い情報ですそのためアプリによる財務データへのアクセスを許可したユーザーの当社への信頼を真摯に受け止めるべきですこの信頼に応えるためにユーザーがデータを削除した場合やアプリによるアクセスを撤回した場合は必ずデータを削除してください
たとえ可能であってもクエリによるデータアクセスは必要最小限にしましょうトランザクションピッカーは当事者双方に有益な財務データへのアクセス方法です貴重なデータが得られるとともにアプリに対する要件が少なく同時にユーザーは安心して共有できるデータのみをアプリに提供できます財務データへのアクセスはハイパフォーマンスな設計でありアプリが財務データすべてにアクセスできるならいつでも非圧縮のスナップショットを取得するのが一見便利に思えますしかしより効率的なのは再開可能な継続的クエリを使用して最新の更新のみを処理する方法ですアプリでの処理が必要なデータの量が大幅に減少するためです以上で FinanceKitを活用して財務アプリを初めて構築する上で必要なすべての情報を解説しました FinanceKitによりユーザーのデバイス上の財務データにアプリからアクセスできます Transaction Picker APIとクエリの APIにはそれぞれ固有のプロセスと要件があり幅広いユースケースに対応できます Apple Developer Forumsではいつでも質問を投稿しアドバイスを得ることができます最後にご意見がありましたらぜひお聞かせくださいフィードバックアシスタントから送信できますご紹介した内容がみなさんのお役に立てば幸いですご視聴ありがとうございましたまたお会いしましょう

5:38 - Check if financial data is available

// Check if financial data is available

import FinanceKit

let available = FinanceStore.isDataAvailable(
    .financialData
)

guard available else {
    // No meaningful action can be performed
    return
}

8:08 - Present the transaction picker

// Present the transaction picker

import SwiftUI
import FinanceKit
import FinanceKitUI

struct TransactionSelector: View {
  @State private var selectedItems: [FinanceKit.Transaction] = []

  var body: some View {
    if FinanceStore.isDataAvailable(.financialData) {
      TransactionPicker(selection: $selectedItems) {
        Text("Show Transaction Picker")
      }
    }
}

12:16 - Requesting authorization for financial data

// Requesting authorization for financial data

import FinanceKit

let store = FinanceStore.shared

guard store.isDataAvailable(for: .financialData) else {
    // No meaningful action can be performed
    return
}

let authStatus = await store.requestAuthorization()

guard authStatus == .authorized else {
    // User did not grant access to financial data, stop here
    return
}

15:24 - Simple query to retrieve all Apple accounts

// Simple query to retrieve all Apple accounts

let store = FinanceStore.shared

let sortDescriptor = SortDescriptor(\Account.displayName)

let predicate = #Predicate<Account> { account in
   account.institutionName == "Apple"
}

let query = AccountQuery(
   sortDescriptors: [sortDescriptor],
   predicate: predicate
)

let accounts : [Account] = try await store.accounts(query: query)

18:12 - Get latest 7 available balances for account

// Get latest 7 available balances for account

func getBalances(account: Account) async throws -> [AccountBalance] {

    let sortDescriptor = SortDescriptor(\AccountBalance.asOfDate, order: .reverse)

    let predicate = #Predicate<AccountBalance> { balance in
        balance.available != nil &&
        balance.accountId == account.id
    }

    let query = AccountBalanceQuery(
        sortDescriptors: [sortDescriptor],
        predicate: predicate,
        limit: 7
    )
    return try await store.accountBalances(query: query).reversed()
}

20:27 - Retrieve all the transaction history for an account

// Retrieve all the transaction history for an account

import FinanceKit

let store = FinanceStore.shared
let account: Account = ...

let transactionSequence = store.transactionHistory(
    forAccountID: account.id
)

for try await change in transactionSequence {
    processChanges(change.inserted, change.updated, change.deleted)
}

21:04 - Use the history token to resume queries

// Use the history token to resume queries

import FinanceKit

let store = FinanceStore.shared
let account: Account = ...
let currentToken = loadToken()

let transactionSequence = store.transactionHistory(
    forAccountID: account.id,
    since: currentToken
)

for try await change in transactionSequence {
    processChanges(change.inserted, change.updated, change.deleted)
    persist(token: change.newToken)
}

21:41 - Non monitoring resumable queries

import FinanceKit

let store = FinanceStore.shared
let account: Account = ...
let currentToken = loadToken()

let transactionSequence = store.transactionHistory(
    forAccountID: account.id,
    since: currentToken,
    isMonitoring: false
)

for try await change in transactionSequence {
    processChanges(change.inserted, change.updated, change.deleted)
    persist(token: change.newToken)
}

特定のトピックをお探しの場合は、上にトピックを入力すると、関連するトピックにすばやく移動できます。

クエリの送信中にエラーが発生しました。インターネット接続を確認して、もう一度お試しください。

関連する章

リソース