DEA SDK for iOS¶
アプリのセッションが実在の人物によるものかどうかを検出します。SDK は iOS アプリのすべてのウィンドウで タッチ、スタイラス、ポインター、スクロール、端末の動きの入力を観測し、セッションを端末上でスコアリング します。
このページの内容: 前提条件 · インストール · SDK を初期化する · 同意を求める · 分類を使う · セットアップの確認 · リリース前に · 次のステップ
前提条件¶
- このアプリの
appIdとappKey— アカウントとキーを参照 - デプロイメントターゲットが iOS 13.0 以降
- Swift 5.9 以降の Xcode
- App Attest によるアテステーションを使う場合: 端末が iOS 14.0 以降
- SwiftUI の同意アラートを使う場合: iOS 15.0 以降(UIKit アプリは iOS 13 から表示できます)
SDK は iOS 端末(arm64)と iOS シミュレーター(arm64 と x86_64)向けにビルドされます。
インストール¶
SDK は同じリリースの 3 つの Swift パッケージからなります。SDK 本体の DeaSDK、いくつかの共有型
(Consent、SessionInfo、JSONValue、CaptureEvent、KeyClass)を定義する DeaBase、そして
DeaAutomationDetection です。DeaSDK は他の 2 つに完全に同じバージョンで依存します。アプリの
ターゲットは DeaSDK と DeaBase をリンクし、DeaAutomationDetection は DeaSDK に付いてきます。
それらの型を使うファイルでは DeaBase も import してください。
注: パッケージは以下の DEA のリリース URL からアーカイブとしてダウンロードします。Xcode に追加する Git の URL はなく、CocoaPods trunk にも公開されていません。
パッケージをダウンロードする¶
ベンダリングしたパッケージを置くフォルダーから:
mkdir -p Vendor/DEA && cd Vendor/DEA
for slot in base automation-detection sdk; do
curl -fsSL "https://sdk.dep-protocol.com/0.26.0/ios/$slot/dea-$slot-0.26.0.tar.gz" | tar -xz
done
これで 3 つのパッケージフォルダー dea-base-0.26.0、
dea-automation-detection-0.26.0、dea-sdk-0.26.0 が並んで作成されます。各パッケージは
他のパッケージをこの相対パスで参照するため、まとめて置いてください。アップグレードするには、新しい
リリースの 3 つのアーカイブをダウンロードし、プロジェクトが新しいフォルダーを指すようにします。
Xcode¶
dea-sdk-0.26.0 と dea-base-0.26.0 をローカルパッケージとして追加し(File > Add
Package Dependencies... > Add Local...)、DeaSDK と DeaBase のプロダクトをアプリのターゲットに
リンクします。
Package.swift¶
dependencies: [
.package(path: "Vendor/DEA/dea-sdk-0.26.0"),
.package(path: "Vendor/DEA/dea-base-0.26.0"),
],
targets: [
.target(name: "App", dependencies: [
.product(name: "DeaSDK", package: "dea-sdk-0.26.0"),
.product(name: "DeaBase", package: "dea-base-0.26.0"),
]),
]
プラットフォームのセットアップ¶
取得のためのセットアップは不要です。SDK は権限のプロンプトも Info.plist のエントリも必要としません。
タッチはパッシブなジェスチャーレコグナイザーで、動きは Core Motion のデバイスモーションで読み取り、
どちらもユーザーに許可を求めません。アプリデリゲートを変更したり、何かを swizzle したりすることもありません。
アテステーションには追加のセットアップ(App Attest ケイパビリティ)が あります。
プライバシーマニフェスト¶
警告: SDK にはプライバシーマニフェスト(
PrivacyInfo.xcprivacy)が含まれていません。SDK が行う ことは、アプリ自身のプライバシーマニフェストでカバーする必要があります。
SDK は次の API を呼び出します。これらは Apple が理由の申告が必要な API(required-reason API)として 挙げているものです。
| API | Apple のカテゴリ | SDK が呼び出す理由 |
|---|---|---|
UserDefaults |
NSPrivacyAccessedAPICategoryUserDefaults |
ユーザーの同意の回答を保持する |
ProcessInfo.systemUptime |
NSPrivacyAccessedAPICategorySystemBootTime |
スクロールとホバーの入力に、タッチと同じクロックでタイムスタンプを付ける |
stat、lstat |
NSPrivacyAccessedAPICategoryFileTimestamp |
SDK の起動時とアテステーションの際に、ジェイルブレイクが残すファイルを確認する |
SDK が記録・保存・送信するものはプライバシーとネットワークで 説明しています。
SDK を初期化する¶
アプリ全体で DeaSdk を 1 つだけ作成し、取得がセッション全体をカバーするように、アプリの起動直後に
start() を呼び出します。インスタンスは、すべての画面から到達できる場所に保持してください。
import DeaSDK
enum Dea {
/// The app's one DEA SDK instance. Nil until `start()` has run.
private(set) static var sdk: DeaSdk?
static func start() {
guard sdk == nil else { return }
let dea = DeaSdk(
options: DeaSdkOptions(appId: "YOUR_APP_ID", appKey: "YOUR_APP_KEY")
)
dea.start()
sdk = dea
}
}
appId と appKey は、DEA がこの iOS アプリ向けに発行したペアです
(アカウントとキーを参照)。分類の読み取りは DEA に要求を送らず、
appKey も使いません。アテステーションには必要で、これがないと DEA に接続せずに
.unsupported を返します。オプションを参照してください。
このガイドの例では、この Dea.sdk ホルダーを使います。
注: このガイドのサンプルは Swift 5 言語モード向けに書かれています。Swift 6 言語モードでは、 ホルダーのプロパティを
nonisolated(unsafe) private(set) static var sdk: DeaSdk?と宣言してください。
SwiftUI¶
import SwiftUI
@main
struct MyApp: App {
init() {
Dea.start()
}
var body: some Scene {
WindowGroup {
ContentView()
}
}
}
UIKit¶
import UIKit
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
Dea.start()
return true
}
}
start()は起動時にメインスレッドで一度だけ呼び出します。2 回目の呼び出しは何もしません。後から 作成されるウィンドウ(アラート、iPad の 2 つ目のシーン)は、表示された時点で取り込まれます。- インスタンスは 1 つだけ作成します。 共有シングルトンはありません。作成した
DeaSdkはそれぞれ 独立して取得を行うため、作成した 1 つを保持してください。ステージングビルドまたはテストビルドでは、 異なるオプションで 2 つ目のインスタンスが作られると、最初のインスタンスがsdk.init_repeatedをログに 記録します。 - イニシャライザは決して throw しません。スコアリングエンジン
を読み込めない場合でも SDK は起動し、
readyがfalseになり、coreFaultが理由を示します。 モデル更新、自動化の検出、証明も停止します。トラブルシューティングを参照してください。 automationDetection: trueの場合、自動化がアプリを操作している確かな兆候を最初に見つけた時点で、SDK は すべてのアカウントとビルドで直ちに停止します。何も取得、スコアリング、署名、登録されず、分類は.insufficientのままです。停止はreset()または新しい起動(アプリの再起動、またはdispose()の後の 新しいDeaSdk)まで続き、その間stoppedはnilではありません。ジェイルブレイクされた iPhone でも SDK は停止します(テストビルドを除く)。 自動化の検出と root 化・ジェイルブレイクされた端末を参照してください。- 取得はグローバルです。すべてのウィンドウのすべてのタッチ、トラックパッドとマウスのスクロール、 ポインターのホバー、モーションセンサー、アプリのライフサイクルが対象です。ラップするビューも、登録する ものもありません。
- 作成時に SDK はバックグラウンドで、より新しいスコアリングモデル が DEA のサーバーにないかを確認します。この確認を待つものはありません。 オプションを参照してください。
- ユーザーが同意するまで何も記録されません。 次のステップを参照してください。
同意を求める¶
デフォルトでは、SDK はユーザーが同意するまで何も記録しません。このステップは必須です。同意を求めない アプリはデータを収集せず、分類も得られません。
SDK には既成のアラートが用意されています。SwiftUI(iOS 15 以降)では、最初の画面に付加します。
import DeaBase
import DeaSDK
import SwiftUI
struct ContentView: View {
@State private var askingConsent = false
var body: some View {
let home = Text("Home")
.onAppear {
if let dea = Dea.sdk, !dea.consent.isAnswered {
askingConsent = true
}
}
if let dea = Dea.sdk {
home.deaConsent(dea.consent, asking: $askingConsent) { agreed in
print("DEA consent: \(agreed)")
}
} else {
home
}
}
}
UIKit では、最初のビューコントローラーから求めます。
import DeaSDK
import UIKit
class HomeViewController: UIViewController {
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
Dea.sdk?.requestConsent(from: self) { agreed in
print("DEA consent: \(agreed)")
}
}
}
回答は端末に保存されます。独自の UI を使う、文言を変える、再度求めるには、 ユーザー同意を参照してください。
分類を使う¶
判断を下す瞬間に分類を読み取ります。
import DeaSDK
func onSignUp(_ form: SignUpForm) {
let result = (try? Dea.sdk?.getClassification())?.result ?? .insufficient
switch result {
case .human:
submitSignUp(form)
case .bot, .undetermined, .insufficient:
showChallenge() // your fallback: a captcha, a delay, a manual review
}
}
SignUpForm、submitSignUp、showChallenge は自分のものに置き換えてください。
getClassification() は、まずアプリがすでに受け取った入力のスコアリングが終わるのを待ち(通常は
何もありません)、次にスコアを読み取って、読み込まれているモデルのしきい値に対して分類します。
ネットワークは呼び出しません。.insufficient は、セッションがまだ
十分でないこと、つまりモデルが求める数より
アクションが少ないことを意味します。組み込みモデルでは 8 です
(証拠を参照)。このとき value は nil です。
.undetermined は、スコアがモデルの 2 つのしきい値の間にあることを意味します。これらを .human や
.bot と同じように扱うのではなく、それぞれの場合にアプリが何をするかを決めてください。スコアとしきい値の
仕組みはスコアリングの仕組みで説明しています。
セットアップの確認¶
本番用 SDK はログを書きません。代わりにコードから確認します。
-
端末またはシミュレーターでアプリを実行し、同意アラートを承諾して、アプリを操作します(タップ、 スクロール、スワイプ)。組み込みモデルが必要とする 8 アクション以上行ってください。
-
たとえばデバッグボタンから、SDK の状態を出力します。
import DeaSDK
if let dea = Dea.sdk {
print("ready:", dea.ready) // true
print("fault:", dea.coreFault ?? "none") // none
print("consent:", dea.consent.decision) // granted
print("session:", dea.sessionInfo.session) // a UUID
print("sdk:", dea.sessionInfo.sdk.version) // the SDK version
print("model:", dea.modelInfo) // the model scoring now
print("motion Hz:", dea.sessionInfo.device.sensorRate) // 50 on a device
print("processed:", dea.coreCounts.samples) // grows as you touch
print("score:", String(describing: try? dea.getClassification()))
}
- 画面に触れている間
processedが増え、actionsが 8 に達するとgetClassification().resultが.insufficientから変わるはずです。readyがfalseの場合や何も増えない場合は、 トラブルシューティングを参照してください。
モーションセンサーのないシミュレーターでは sensorRate は 0 です。
リリース前に¶
- [ ] アテステーションを使う場合、
appKeyが設定されている — オプションを参照 - [ ] 同意アラートが表示される、または独自の同意フローが
setConsentを呼び出す — ユーザー同意を参照 - [ ] 判断ポイントで分類を読み取り、
.bot、.undetermined、.insufficientのフォールバックがある — ヒューマンスコアリングを参照 - [ ] パスワードや支払いの画面で取得を一時停止している — 機密性の高い画面を参照
- [ ] ログアウト時に
reset()を呼び出している — セッションを参照 - [ ] アテステーションを使う場合、App Attest ケイパビリティが追加されている — アテステーションを参照
- [ ]
attest()とrenewAttestation()をメインスレッドで呼び出していない - [ ] アプリのプライバシーマニフェストが SDK をカバーしている — プライバシーマニフェストを参照
本番環境への移行も参照してください。
次のステップ¶
- ユーザー同意 — アラートをカスタマイズする、または独自の UI を使う
- ヒューマンスコアリング — 判断ポイントで分類を読み取る
- 機密性の高い画面 — パスワードや支払いの画面で取得を一時停止する
- セッション — ログアウト時に新しいセッションを開始する
- オプション — SDK が受け付けるすべてのオプション
- プライバシーとネットワーク — SDK が記録・保存・送信するもの
- トラブルシューティング