API リファレンス¶
共有インスタンスはありません。DeaSdk を 1 つ作成して保持してください。
クイックスタートを参照してください。
DeaSdk¶
init(options:)¶
SDK を作成し、セッションを開始します。取得は start() まで始まりません。決して throw しません。
スコアリングエンジンを読み込めない場合もインスタンスは作成され、ready が false になり、coreFault
が理由を示します。モデル更新が有効な場合、バックグラウンドで
新しいモデルの確認も開始します。オプションを参照してください。
start¶
グローバルな取得を開始します。できるだけ早く、メインスレッドで一度だけ呼び出します。dispose() の後は
何もしません。
options¶
このインスタンスの作成時に渡されたオプション。
appKey¶
SDK が X-App-Key として送るアプリキー。appKey オプションを
トリムしたもの、または渡されていない場合は nil。
ready¶
SDK がスコアリングできるかどうか。false のとき、取得は続きますがスコアはなく、分類は
.insufficient で、coreFault が理由を示します。
coreFault¶
SDK がスコアリングできない理由、または nil。
getClassification¶
唯一のスコア読み取りです。すでに受け取った入力のスコアリングが終わるのを待ち、次にスコア、その背後にある
証拠の量、読み込まれたモデルのしきい値を 1 つのスナップショットとして読み取り、.human、.bot、
.undetermined、.insufficient のいずれかに分類します。ネットワークは呼び出しません。保留中の入力の
スコアリングにかかる時間だけブロックします(通常は何もありません)。そのため、毎フレームではなく判断の
前に呼び出してください。
スコアリングエンジンが読み込まれる前(ready が false)は Classification.unloaded
(.insufficient、value は nil)を返し、throw しません。
Throws: 読み込まれたモデルが bot しきい値を持たないとき ThresholdMissing。
ヒューマンスコアリングを参照してください。
drain¶
アプリがすでに受け取った入力のスコアリングが終わるまで待ちます。getClassification() はこれを自分で
行います。
modelInfo¶
現在スコアリングしているモデル。そのバージョン(SDK に組み込まれたモデルでは 0)と由来です。
オプションを参照してください。
checkForModel¶
最後に回答を得た確認から 1 日が経過していれば、DEA のモデルサーバーに今すぐ新しいモデルを問い合わせ
ます。そうでなければ、要求なしで .notDue を返します。SDK は作成時とアプリがフォアグラウンドに戻った
ときにすでに確認しているため、これを呼び出す必要はありません。
| パラメータ | 型 | 説明 |
|---|---|---|
force |
Bool |
最後の確認が 1 日以内でも問い合わせる。人がボタンを押す場合向けで、スケジュール実行には使わない |
completion |
((ModelCheck) -> Void)? |
確認がどう終わったかとともに、メインスレッド以外で呼び出される |
決して throw せず、ブロックもしません。modelUpdates: false では completion は .cancelled を
受け取ります。
modelChanges¶
この実行中に新しいモデルがスコアリングを始めるたびに、メインスレッド以外で listener を呼び出します。
返されたクロージャを呼ぶとリッスンを停止します。
consent¶
ユーザーの現在の同意の回答。ユーザー同意を参照してください。
setConsent¶
| パラメータ | 型 | 説明 |
|---|---|---|
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¶
記録を停止します。セッションは保持されます。 機密性の高い画面を参照してください。
resume¶
pause() の後に記録を再開します。同意を上書きしません。
setMotion¶
モーションセンサーをオフにする、または再びオンにします。Core Motion は init から dispose() まで、
取得の一時停止中も動き続けます。setMotion(false) はそれを止めます。モーションがオフの間、スコアリング
エンジンはモーションの読み取り値を受け取らず、タッチをモーション値ゼロでスコアリングするため、分類が
変わることがあります。motion はセンサーがオンかどうかを読み取ります。
captureEvent¶
| パラメータ | 型 | 説明 |
|---|---|---|
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¶
現在のセッションを終了し、新しいセッションを開始します。SDK がダウンロードしたモデルは引き続き使われ ます。セッションを参照してください。
sessionInfo¶
現在のセッション id、端末、SDK バージョン。
coreCounts¶
診断用。このセッションで SDK が処理した取得イベントの数です。samples はユーザーの操作に合わせて
増えます。取得が機能していることの確認に使ってください。
attest¶
端末キーを DEA に登録します。期限切れの直前までキャッシュされ、最初の呼び出しの後は自動で更新されます。
appKey が渡されていない場合は、要求なしで .unsupported を返します。
決して throw しません。ブロックします。 メインスレッド以外で呼び出してください。
アテステーションを参照してください。
renewAttestation¶
現在の結果が有効でも、今すぐ再登録します。失敗した場合は以前の有効な結果を保持します。ブロックします。
storedAttestation¶
このインストールがすでに保持している登録を、まだ有効であれば、ネットワーク要求なしで読み取ります。
attest() が再登録する必要がある場合は nil。キーチェーンを読み取るため、メインスレッド以外で呼び出して
ください。
forgetAttestation¶
このインストールの登録と、拒否された試行の後の待機を忘れるため、次の attest() は最初から登録します。
端末キーは保持します。自動更新は次の attest() まで停止します。
lastAttestation¶
最後のアテステーション結果。最初の attest() の前は nil。
nextAttestationRefresh¶
自動更新が次に実行される時刻。最初の 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¶
取得、モデル更新の確認、アテステーションの自動更新を停止し、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 == falsec.result == .insufficient十分でない間の c.value: 数値nilClassificationResultは 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 が破棄された |
Consent¶
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¶
SDK バージョン。sessionInfo.sdk.version と同じです。