コンテンツにスキップ

API リファレンス

import DeaSDK
import DeaBase // for Consent, SessionInfo, JSONValue and the other shared types

共有インスタンスはありません。DeaSdk を 1 つ作成して保持してください。 クイックスタートを参照してください。

DeaSdk

init(options:)

init(options: DeaSdkOptions)

SDK を作成し、セッションを開始します。取得は start() まで始まりません。決して throw しません。 スコアリングエンジンを読み込めない場合もインスタンスは作成され、ready が false になり、coreFault が理由を示します。モデル更新が有効な場合、バックグラウンドで 新しいモデルの確認も開始します。オプションを参照してください。

start

func start()

グローバルな取得を開始します。できるだけ早く、メインスレッドで一度だけ呼び出します。dispose() の後は 何もしません。

options

let options: DeaSdkOptions

このインスタンスの作成時に渡されたオプション。

appKey

var appKey: String? { get }

SDK が X-App-Key として送るアプリキー。appKey オプションを トリムしたもの、または渡されていない場合は nil。

ready

var ready: Bool { get }

SDK がスコアリングできるかどうか。false のとき、取得は続きますがスコアはなく、分類は .insufficient で、coreFault が理由を示します。

coreFault

private(set) var coreFault: String?

SDK がスコアリングできない理由、または nil。

getClassification

func getClassification() throws -> Classification

唯一のスコア読み取りです。すでに受け取った入力のスコアリングが終わるのを待ち、次にスコア、その背後にある 証拠の量、読み込まれたモデルのしきい値を 1 つのスナップショットとして読み取り、.human、.bot、 .undetermined、.insufficient のいずれかに分類します。ネットワークは呼び出しません。保留中の入力の スコアリングにかかる時間だけブロックします(通常は何もありません)。そのため、毎フレームではなく判断の 前に呼び出してください。

スコアリングエンジンが読み込まれる前(ready が false)は Classification.unloaded (.insufficient、value は nil)を返し、throw しません。

Throws: 読み込まれたモデルが bot しきい値を持たないとき ThresholdMissing。 ヒューマンスコアリングを参照してください。

drain

func drain()

アプリがすでに受け取った入力のスコアリングが終わるまで待ちます。getClassification() はこれを自分で 行います。

modelInfo

var modelInfo: ModelInfo { get }

現在スコアリングしているモデル。そのバージョン(SDK に組み込まれたモデルでは 0)と由来です。 オプションを参照してください。

checkForModel

func checkForModel(force: Bool = false, completion: ((ModelCheck) -> Void)? = nil)

最後に回答を得た確認から 1 日が経過していれば、DEA のモデルサーバーに今すぐ新しいモデルを問い合わせ ます。そうでなければ、要求なしで .notDue を返します。SDK は作成時とアプリがフォアグラウンドに戻った ときにすでに確認しているため、これを呼び出す必要はありません。

パラメータ 型 説明
force Bool 最後の確認が 1 日以内でも問い合わせる。人がボタンを押す場合向けで、スケジュール実行には使わない
completion ((ModelCheck) -> Void)? 確認がどう終わったかとともに、メインスレッド以外で呼び出される

決して throw せず、ブロックもしません。modelUpdates: false では completion は .cancelled を 受け取ります。

modelChanges

@discardableResult
func modelChanges(_ listener: @escaping (ModelInfo) -> Void) -> () -> Void

この実行中に新しいモデルがスコアリングを始めるたびに、メインスレッド以外で listener を呼び出します。 返されたクロージャを呼ぶとリッスンを停止します。

var consent: Consent { get }

ユーザーの現在の同意の回答。ユーザー同意を参照してください。

setConsent

func setConsent(_ granted: Bool, remember: Bool = true)
パラメータ 型 説明
granted Bool ユーザーが同意したかどうか
remember Bool 回答を端末に保存する。false ではこの実行中だけ保持する

すぐに効果が現れます。同意すると記録が始まり、撤回すると停止します。

requestConsent

func requestConsent(
    from presenter: UIViewController,
    copy: ConsentCopy = ConsentCopy(),
    remember: Bool = true,
    completion: @escaping (Bool) -> Void
)

UIKit。ユーザーが回答していなければ presenter から同意アラートを表示し、回答を記録し、それとともに completion を呼び出します。保存された回答があり remember: true の場合は、すぐに completion を 呼び出し、何も表示しません。

pause

func pause()

記録を停止します。セッションは保持されます。 機密性の高い画面を参照してください。

resume

func resume()

pause() の後に記録を再開します。同意を上書きしません。

setMotion

func setMotion(_ on: Bool)
var motion: Bool { get }

モーションセンサーをオフにする、または再びオンにします。Core Motion は init から dispose() まで、 取得の一時停止中も動き続けます。setMotion(false) はそれを止めます。モーションがオフの間、スコアリング エンジンはモーションの読み取り値を受け取らず、タッチをモーション値ゼロでスコアリングするため、分類が 変わることがあります。motion はセンサーがオンかどうかを読み取ります。

captureEvent

func captureEvent(_ name: String, data: [String: JSONValue]? = nil) -> Bool
パラメータ 型 説明
name String 1 〜 64 文字
data [String: JSONValue]? 省略可。JSON として最大 1024 バイト

戻り値: 記録されたとき true。制限を超えた、取得が一時停止中、同意がない、SDK が破棄済みのとき false。カスタムイベントを参照してください。

captureKey

func captureKey(
    _ keyClass: KeyClass,
    pressed: Bool = true,
    mods: Int = 0,
    repeat: Bool = false,
    field: String? = nil
)
パラメータ 型 説明
keyClass KeyClass キーの種類。文字そのものは決して渡さない
pressed Bool false は解放を報告する。events に .keyUp が必要
mods Int 押されている修飾キー(KeyMod のビット)。ソフトキーボードは報告しない: 0
repeat Bool 押下が自動リピートかどうか
field String? 入力先のテキストフィールドの名前

1 回のキーストロークを報告します。events オプションに .keyDown がなければ何もせず、他のすべての取得と同様に、一時停止中と同意前も何もしません。パスワードフィールド では決して呼び出さないでください。タイピングを報告する を参照してください。

reset

func reset()

現在のセッションを終了し、新しいセッションを開始します。SDK がダウンロードしたモデルは引き続き使われ ます。セッションを参照してください。

sessionInfo

var sessionInfo: SessionInfo { get }

現在のセッション id、端末、SDK バージョン。

coreCounts

var coreCounts: CoreCounts { get }

診断用。このセッションで SDK が処理した取得イベントの数です。samples はユーザーの操作に合わせて 増えます。取得が機能していることの確認に使ってください。

attest

func attest() -> Attestation

端末キーを DEA に登録します。期限切れの直前までキャッシュされ、最初の呼び出しの後は自動で更新されます。 appKey が渡されていない場合は、要求なしで .unsupported を返します。 決して throw しません。ブロックします。 メインスレッド以外で呼び出してください。 アテステーションを参照してください。

renewAttestation

func renewAttestation() -> Attestation

現在の結果が有効でも、今すぐ再登録します。失敗した場合は以前の有効な結果を保持します。ブロックします。

storedAttestation

func storedAttestation() -> Attestation?

このインストールがすでに保持している登録を、まだ有効であれば、ネットワーク要求なしで読み取ります。 attest() が再登録する必要がある場合は nil。キーチェーンを読み取るため、メインスレッド以外で呼び出して ください。

forgetAttestation

func forgetAttestation()

このインストールの登録と、拒否された試行の後の待機を忘れるため、次の attest() は最初から登録します。 端末キーは保持します。自動更新は次の attest() まで停止します。

lastAttestation

var lastAttestation: Attestation? { get }

最後のアテステーション結果。最初の attest() の前は nil。

nextAttestationRefresh

var nextAttestationRefresh: Date? { get }

自動更新が次に実行される時刻。最初の attest() の前と、キーを保持できない端末では nil。

広告

iOS には Web の ads.session_opened() のような広告モジュールはありません。以下の 3 つの呼び出しがあり、 1 つの広告イベントについて現在のスコアを端末キーで証明に署名します。各呼び出しは署名の前に DEA に 使い捨てのノンスを求めるため、それぞれブロックします。メインスレッド以外で呼び出してください。 証明は appId を含みません。DEA は端末キーからアプリを取得します。インプレッション、 クリック、終了の順序については広告を参照してください。

sendProof

func sendProof(
    event: ProofEvent,
    sessionId: String? = nil,
    attestation: Attestation? = nil,
    adUnit: String? = nil,
    appScopedUid: String? = nil,
    extra: [String: Any] = [:],
    update: Bool = false
) -> RecordOutcome

1 つの証明に署名し、DEA の記録サービスに送ります。POST /api/sessions、または update: true では PUT /api/sessions/{sessionId} です。

パラメータ 型 説明
event ProofEvent 広告イベント。event_type として署名される
sessionId String? 広告セッション。session_id として署名される。インプレッションでは "" を渡し、DEA が新しい id で応答する。クリックと終了ではその id を渡す。nil は SDK 自身のセッション id(sessionInfo.session)に署名するが、これは広告セッションではない
attestation Attestation? 証明に署名される tier だけを決める。platformAttested で合格した期限内の登録なら B、それ以外は C。nil は SDK が保持する登録を使う
adUnit String? 広告ユニット。ad_unit として署名される
appScopedUid String? アプリにスコープされたユーザーの匿名 id。app_scoped_uid として署名される
extra [String: Any] 独自のフィールド。証明の隣、署名の外側にあるリクエストボディで送られる。JSON 値のみ。証明を置き換えることはない
update Bool PUT /api/sessions/{sessionId} として送る。インプレッションが開いた広告セッションの終了

DEA が応答しないか 5xx で応答した場合、SDK は 2、4、8、16 秒後(それぞれ最大 1 秒を加えて)に証明を 再送し、最大 5 回送り、証明の 90 秒の有効期間を超えて送ることはありません。4xx の応答は最終です。 すべての試行が失敗すると、呼び出しは約 2 分ブロックすることがあります。

戻り値: RecordOutcome。分類がまだ .insufficient、端末キーがない、スコアリングエンジンが動いて いない、appKey がない(何も送られない)、DEA が証明を拒否した、 どの送信も通らなかった場合、accepted は false で、said が理由を示します。 証明が記録されなかった理由を読み取るを 参照してください。

Throws: なし。

record

func record(
    event: ProofEvent,
    sessionId: String? = nil,
    attestation: Attestation? = nil,
    adUnit: String? = nil,
    appScopedUid: String? = nil,
    extra: [String: Any] = [:],
    update: Bool = false
) -> Bool

同じパラメータの sendProof で、accepted だけを返します。DEA が証明を受け付けたとき true。 ブロックします。

getProof

func getProof(
    event: ProofEvent,
    sessionId: String? = nil,
    attestation: Attestation? = nil,
    adUnit: String? = nil,
    appScopedUid: String? = nil
) -> SignedProof?

1 つの証明に署名し、送らずに返します。独自の方法で証明を届けるアプリ向けです。sendProof のパラメータ を受け取ります。DEA にノンスを求めるためブロックします。appKey がない場合や DEA がノンスを渡さない 場合、証明はノンスなしで署名されます。

戻り値: 証明。何も署名されなかった場合は nil。分類がまだ .insufficient、端末キーがない、 スコアリングエンジンが動いていない場合です。

dispose

func dispose()

取得、モデル更新の確認、アテステーションの自動更新を停止し、SDK を解放します。破棄したインスタンスは 再び開始できません。新しく作成してください。

SwiftUI

deaConsent

@available(iOS 15.0, *)
func deaConsent(
    _ consent: Consent,
    asking: Binding<Bool>,
    copy: ConsentCopy = ConsentCopy(),
    remember: Bool = true,
    onAnswer: @escaping (Bool) -> Void
) -> some View

View モディファイア。asking が true の間、同意アラートを表示し、回答を consent に記録し、 onAnswer を呼び出します。保存された回答は確認しません。consent.isAnswered が false のときだけ asking を設定してください。

パラメータ 説明
consent SDK の consent
asking アラートを表示するかどうか
copy アラートの文言
remember 回答を保存する。false ではこの実行中だけ保持する
onAnswer ユーザーの回答とともに呼び出される

型

DeaSdkOptions

フィールド 型 デフォルト 説明
appId String — DEA の appId
requireConsent Bool true ユーザーが同意するまで何も記録しない
consent Consent? nil(UserDefaults に保存) 同意の回答の保持先
appKey String? nil DEA の appKey。X-App-Key として送られる。アテステーションと広告に必要
registryAppId String? nil 0.20.8 以降非推奨で、無視される。証明は appId を含まない
onLog ((LogEntry) -> Void)? nil 本番ビルドでは呼び出されない
modelDirectory URL? nil(Application Support) ダウンロードしたモデルの保持先
modelUpdates Bool true 新しいモデルを確認してダウンロードする
modelTimeout TimeInterval 30 1 回のモデル要求にかけられる秒数
events [CaptureEvent] CaptureEvent.pointerKinds 取得する入力の種類
idleMotionMs Int 3000 誰も画面に触れていない間のモーション読み取り間隔
motionRate Int 50 要求するモーションセンサーのレート(Hz)。最小 25
touchMarginMs Int 200 各タッチの前後でフルレートのモーションを保持する時間(ms)

残りのフィールドは予約済みです。オプションを参照してください。

DeaSdkError

非推奨で、throw されることはありません。init(options:) は throw しません。本番用の appId で 予約済みの integrations オプションを設定しても無視されます。

Classification

フィールド 型 説明
result ClassificationResult 答え
value Double? 0 から 1 までのヒューマンスコア。result が .insufficient のときに限り nil
actions Int value の根拠となる操作の数。.insufficient の間の「あと N アクション」表示に使える
botThreshold Double? 読み込まれたモデルの bot しきい値。モデルの読み込み前は nil
humanThreshold Double? 読み込まれたモデルの human しきい値。モデルが設定していない場合は nil で、そのときは botThreshold 以上のすべての読み取りが .human
modelVersion Int? しきい値の由来となるモデル。組み込みモデルでは 0。モデルの読み込み前は nil

Classification.unloaded は、スコアリングエンジンの読み込み前に返される値です。

ClassificationResult

この順序で判定されます。

ケース 条件
.insufficient エンジンまたはモデルが読み込まれていない、またはセッションのアクションがモデルの求める数(組み込みモデルでは 8)より少ない。value は nil
.human value が humanThreshold 以上
.bot value が botThreshold 未満
.human humanThreshold が nil で、value が botThreshold 以上
.undetermined value が botThreshold 以上かつ humanThreshold 未満

しきい値は読み込まれたモデルからのみ得られます。アカウントや SDK の何もこれを上書きしません。

このリリースへの移行: Classification.sufficient はなくなり、ClassificationResult に 4 つ目の ケースが追加されました。

以前 このリリース
c.sufficient == false c.result == .insufficient
十分でない間の c.value: 数値 nil
ClassificationResult は 3 ケース 4 ケース: すべての switch で .insufficient を処理する
humanThreshold なしで value が botThreshold 以上: .undetermined .human

ThresholdMissing

Error。読み込まれたモデルが bot しきい値を持たないとき、getClassification() が throw します。

フィールド 型 説明
modelVersion Int しきい値を持たないモデル

ModelInfo

フィールド 型 説明
version Int モデルのバージョン。SDK に組み込まれたモデルでは 0
source ModelSource .embedded(組み込み)、.cache(以前ダウンロードし、起動時に読み込んだ)、.network(この実行中にダウンロードした)のいずれか

ModelCheck

フィールド 型 説明
outcome ModelCheckOutcome 確認がどう終わったか。以下を参照
refusal ModelLoad? スコアリングエンジンがファイルを拒否したときの、その内容
detail String? 確認が失敗またはキャンセルされた理由
ModelCheckOutcome 意味
.loaded 新しいモデルがダウンロードされ、現在スコアリングしている
.unchanged 新しいものは公開されていない
.notPublished この SDK がダウンロードできるモデルを DEA が公開していない
.notSupported 新しいモデルが公開されているが、この SDK バージョンでは読めない
.notDue 最後に回答を得た確認から 1 日未満で、force が false だった
.refused スコアリングエンジンがダウンロードしたファイルを拒否した。実行中のモデルは変わらない
.failed 使える回答がない。オフライン、タイムアウト、予期しないステータス、または公開されたサイズやチェックサムと一致しないファイル
.cancelled モデル更新が動いていない、または SDK が破棄された

DeaBase から。

メンバー 型 説明
decision ConsentDecision .unknown、.granted、.denied のいずれか
isAnswered Bool ユーザーが回答したかどうか
isGranted Bool ユーザーが同意したかどうか
set(_:remember:) Void 回答を記録する。DeaSdk.setConsent と同じ
forget() Void 保存された回答を消去し、ユーザーに再度尋ねる
onChange(_:) () -> Void 判断が変わると新しい判断でリスナーを呼び出す。返されたクロージャを呼ぶと停止する
init(store:decision:) ConsentStore の上に Consent を構築する。オプションを参照
Consent.granted() Consent すでに同意済みの回答。保存されない

ConsentStore

DeaBase から。read() -> ConsentDecision と write(_ decision: ConsentDecision) を持つプロトコル。 実装: DefaultsConsentStore(UserDefaults に保存、デフォルト)と MemoryConsentStore(この実行中のみ)。

ConsentCopy

フィールド 型 説明
title String アラートのタイトル
body String 説明文
recorded [String] 記録されるもの。空にするとセクションが非表示になる
notRecorded [String] 決して記録されないもの。空にするとセクションが非表示になる
recordedLabel String recorded の見出し
notRecordedLabel String notRecorded の見出し
closing String 締めの一文
accept String 承諾ボタン
decline String 拒否ボタン

すべてのフィールドに英語のデフォルトがあります。変更するものだけを渡してください。

SessionInfo

DeaBase から。

フィールド 型 説明
session String 現在のセッション id(UUID)
device DeviceRecord 現在の端末情報
sdk.version String SDK バージョン
sdk.core String スコアリングエンジンのビルド
startedAt Int セッションの開始時刻(Unix ミリ秒)

DeviceRecord

DeaBase から。

フィールド 型 説明
runtime Runtime .ios
os OperatingSystem オペレーティングシステム
surface Surface 画面サイズ(ポイント単位、width、height)
pixelRatio Double ポイントあたりのピクセル数
rotation Int 画面の回転: 0、90、180、270
maxTouchPoints Int 画面が対応する同時タッチ数
sensorRate Int 要求したモーションレート(Hz)。モーションデータが届いた後に設定され、それまでは 0

CaptureEvent

DeaBase から。events オプションに列挙する入力の種類: .pointerDown、.pointerMove、.pointerUp、.pointerCancel、.wheel、.keyDown、.keyUp。 CaptureEvent.pointerKinds は最初の 5 つです。

KeyClass

DeaBase から。captureKey が報告するキーの種類: .letter、.digit、.space、.delete、 .navigation、.modifier、.other。KeyClass.of(_ character: String) は、入力された 1 文字を .letter(あらゆる文字体系)、.digit、.space、.other のいずれかに分類します。

JSONValue

DeaBase から。captureEvent のペイロードに入る値: .null、.bool、.int、.double、.string、 .array([JSONValue])、.object([String: JSONValue])。文字列、整数、浮動小数点数、Boolean のリテラルは 自動的に変換されます。

CoreCounts

セッションごとに数えられます。reset() で再び 0 から始まります。

フィールド 型 説明
samples Int スコアリング対象の入力を生み出した取得イベント
skipped Int 受け付けられたが、その時点ではスコアリング対象の入力を生み出さなかったイベント: カスタムイベント、ライフサイクルの変化、スクロールとホバー、イベントの順序を保つために短時間保留された入力
rejected Int 拒否されたイベント。0 より大きければ DEA に報告する価値のあるバグ
faults Int SDK が回復した内部エラー
dropped Int 端末が追いつけずにスキップされたイベント

Attestation

フィールド 型 説明
supported Bool キーを作成でき、appKey が渡されているかどうか
verdict Attestation.Verdict .passed、.failed、.unsupported のいずれか
platformAttested Bool App Attest トークンがキーとともに送られ、DEA が受け付けたかどうか
platformTokenSpent Bool 結果にかかわらず、この試行で App Attest アテステーションを使ったかどうか
expiresAt Int? 期限(エポック秒)
kid String? キーの識別子
tier String? DEA が割り当てた信頼ティア
integrity String? DEA の応答に含まれる場合、端末の整合性についての DEA の判定
backing String? キーの保管場所: secure_enclave または software
detail String? アテステーションが合格しなかった理由

ProofEvent

証明が記録する広告イベント。event_type として署名されます。

ケース rawValue タイミング
.adImpression ad.impression 広告が画面に表示された
.adClick ad.click 広告がクリックされた
.adEnded ad.ended 広告が消えた

RecordOutcome

sendProof が返すもの。

フィールド 型 説明
accepted Bool DEA が証明を受け付けたかどうか
signed SignedProof? 署名された証明。何も署名されなかった場合は nil
isSigned Bool 証明が署名されたかどうか
said String? DEA の応答、または何も署名・送信されなかった理由。DEA が空の応答で証明を受け付けた場合は nil
sessionId String? DEA の応答にある session_id。指定がなければ nil。受け付けられたインプレッションはここに広告セッションの id を持つ。クリックと終了はそれで送る

SignedProof

getProof が返すもの、および RecordOutcome.signed。フィールドは署名された内容のコピーで、証明から 読み戻したものです。

フィールド 型 説明
proof String 証明。コンパクト JWS: header.payload.signature
score Double 署名されたヒューマンスコア、h_score
evidenceAt Int スコアの背後にある証拠の終端時刻(エポック秒)、h_ts
windows Int スコアの根拠となるアクション数、h_wc
modelVersion Int? スコアリングしたモデル、h_mv。SDK に組み込まれたモデルでは 0
sessionId String 署名された session_id
event ProofEvent 署名されたイベント
header [String: Any]? デコードされたヘッダー: alg、typ、kid
claims [String: Any]? 署名されたとおりの、デコードされたクレーム
signature String? 署名セグメント(base64url)

sdkVersion

let sdkVersion: String

SDK バージョン。sessionInfo.sdk.version と同じです。