コンテンツにスキップ

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 はログを書きません。代わりにコードから確認します。

  1. 端末またはシミュレーターでアプリを実行し、同意アラートを承諾して、アプリを操作します(タップ、 スクロール、スワイプ)。組み込みモデルが必要とする 8 アクション以上行ってください。

  2. たとえばデバッグボタンから、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()))
}
  1. 画面に触れている間 processed が増え、actions が 8 に達すると getClassification().result が .insufficient から変わるはずです。ready が false の場合や何も増えない場合は、 トラブルシューティングを参照してください。

モーションセンサーのないシミュレーターでは sensorRate は 0 です。

リリース前に

  • [ ] アテステーションを使う場合、appKey が設定されている — オプションを参照
  • [ ] 同意アラートが表示される、または独自の同意フローが setConsent を呼び出す — ユーザー同意を参照
  • [ ] 判断ポイントで分類を読み取り、.bot、.undetermined、.insufficient のフォールバックがある — ヒューマンスコアリングを参照
  • [ ] パスワードや支払いの画面で取得を一時停止している — 機密性の高い画面を参照
  • [ ] ログアウト時に reset() を呼び出している — セッションを参照
  • [ ] アテステーションを使う場合、App Attest ケイパビリティが追加されている — アテステーションを参照
  • [ ] attest() と renewAttestation() をメインスレッドで呼び出していない
  • [ ] アプリのプライバシーマニフェストが SDK をカバーしている — プライバシーマニフェストを参照

本番環境への移行も参照してください。

次のステップ