API リファレンス¶
DeaSdk.init(context, config) で SDK を起動し、以降は DeaSdk.instance でどこからでもアクセスします。
付随ライブラリ由来の型(Consent、SessionInfo、CaptureEvent など)は ai.dea.base パッケージに、
アテステーションの型は ai.dea.sdk.attest に、証明の型は ai.dea.sdk.proof に、モデルの型は ai.dea.sdk.model
にあります。
DeaSdk¶
init¶
fun init(
context: Context,
config: DeaConfig = DeaConfig(),
targets: TargetReader = ViewTargetReader(),
): DeaSdk
SDK と取得を開始します。すでに実行中のインスタンスがあればそれを返します。例外を投げません。メインスレッドで
呼び出し、Application を渡してください。SDK は与えられた Context を保持します。
オプションを参照してください。
instance¶
実行中のインスタンス。init の前と dispose() の後は null です。
ready¶
SDK がスコアリングできるかどうか。false のとき、取得は続きますが getClassification() は INSUFFICIENT を
返し、coreFault がその理由を示します。
coreFault¶
SDK がスコアリングできない理由。できる場合は null。
getClassification¶
セッションが人物、ボット、またはまだどちらでもないと読めるかを、その根拠となるスコアとモデルのしきい値とともに 返します。1 つのスナップショットであり、これまでのすべての操作を対象とし、フィールドは常に互いに整合しています。 同期的で、メインスレッドで安全です。ヒューマンスコアリングを参照してください。
例外: 読み込まれたモデルがbot しきい値を設定していない場合は ThresholdMissing。SDK がスコアリングできない
(ready が false)場合は例外を投げず、value が null の INSUFFICIENT を返します。
consent¶
ユーザーの現在の同意の回答。ユーザー同意を参照してください。
setConsent¶
| パラメーター | 型 | 説明 |
|---|---|---|
granted |
Boolean |
ユーザーが同意したかどうか |
remember |
Boolean |
false ではこの起動の間だけ回答を保持し、何も保存しません |
即座に有効になります。撤回すると、取得済みでまだ処理されていないものは破棄されます。いずれの場合もセッションは 維持されます。
pause¶
記録を停止します。セッションは維持されます。機密性の高い画面を 参照してください。
resume¶
pause() の後に記録を再開します。同意を上書きしません。
captureEvent¶
| パラメーター | 型 | 説明 |
|---|---|---|
name |
String |
1〜64 文字。それ以外ではイベントは破棄されます |
data |
Map<String, Any?>? |
省略可。JSON として最大 1024 バイト。超えるとイベントは破棄されます |
戻り値: Boolean — イベントが記録されたとき true。
カスタムイベントを参照してください。
captureKey¶
fun captureKey(
keyClass: KeyClass,
pressed: Boolean = true,
mods: Int = 0,
repeat: Boolean = false,
field: String? = null,
)
| パラメーター | 型 | 説明 |
|---|---|---|
keyClass |
KeyClass |
キーの種類。KeyClass.of(character) は入力された文字を種類に変換します |
pressed |
Boolean |
false は解放を報告します。ソフトキーボードには報告すべき解放がないため、押下だけを送ります |
mods |
Int |
押されている修飾キー。KeyMod のビット。ソフトキーボードでは 0 |
repeat |
Boolean |
押下がキーリピートかどうか |
field |
String? |
入力先のテキストフィールドの名前。ビューのターゲット名と同様 |
アプリが検知した 1 回のキー押下を報告します。SDK は自身ではキーイベントを見ないため、キー押下はアプリが報告した
場合にのみ記録され、記録されるのはその種類だけで、文字は決して記録されません。
events に CaptureEvent.KEY_DOWN(解放には CaptureEvent.KEY_UP)が
含まれていなければ何も記録せず、取得の一時停止中や同意前にも何も記録しません。パスワードフィールドでは決して
呼び出さないでください。
setMotion¶
実行中のアプリについて、モーションセンサーをオフにするか、再びオンにします。オフの間、SDK はモーションデータを
読まず、sessionInfo.device.sensorRate は 0 になります。タッチの取得とセッションは続きます。motion は
センサーがオンかどうかを示します。
reset¶
現在のセッションを終了し、新しいセッションを開始します。セッションを 参照してください。
sessionInfo¶
現在のセッション id、端末、SDK バージョン。
modelInfo¶
どのモデルがスコアリングしているか。その version(組み込みモデルでは 0)と source(EMBEDDED、
CACHE(以前の起動でダウンロード)、NETWORK(この実行中にダウンロード))。
モデルオプションを参照してください。
checkForModel¶
前回の確認から 1 日が経過していれば、今すぐ DEA のモデルホストを確認します。force = true では常に確認します。
SDK は起動ごとと、フォアグラウンドに戻ったときにすでに確認しているため、ほとんどのアプリはこれを呼び出しません。
例外を投げません。ブロックします。メインスレッド以外で呼び出してください。モデル更新がオフのときは
ModelCheckOutcome.CANCELLED を返します。
addModelListener¶
この実行中に新しいモデルがスコアリングを始めるたびに、バックグラウンドスレッドで listener を呼び出します。
購読解除関数を返します。
attest¶
端末キーを DEA に登録し、自動更新を有効にします。期限が近づくまでキャッシュされます。例外を投げません。
ブロックします。メインスレッド以外で呼び出してください。appKey が指定されていない場合は要求を行わずに
UNSUPPORTED を返します。アテステーションを参照してください。
renewAttestation¶
今すぐ再登録します。失敗してもすでに保持している登録はそのまま残ります。ブロックします。
lastAttestation¶
最後のアテステーション結果。最初の attest() の前は null。
storedAttestation¶
このインストールがすでに保持している登録。まだ有効であれば、要求を行わずにストレージから読みます。そうでなければ
null。有効な登録があれば自動更新を有効にします。
forgetAttestation¶
保存された登録と、拒否された試行の後の待機を忘れ、自動更新を停止します。端末キーは維持されます。
nextAttestationRefresh¶
次に登録が自動更新される時刻(エポック秒)。
onAttestationEvent¶
自動更新の判断ごとに呼び出されます: Scheduled(afterSeconds)、Fired(verdict)、Idle。最初の attest() の前に
設定してください。
広告¶
Android には広告セッションオブジェクトがありません。次の 3 つの呼び出しはそれぞれ 1 つの広告イベントに署名し
(セッションの現在のスコアを端末キーで署名)、送信するか返します。DEA が証明を受け付けるには、
appKey を渡し、attest() で端末キーを登録してください。広告を
参照してください。
sendProof¶
fun sendProof(
event: ProofEvent,
sessionId: String? = null,
attestation: Attestation? = null,
adUnit: String? = null,
appScopedUid: String? = null,
extra: Map<String, Any?> = emptyMap(),
update: Boolean = false,
): RecordOutcome
| パラメーター | 型 | 説明 |
|---|---|---|
event |
ProofEvent |
広告イベント |
sessionId |
String? |
証明に署名して含める広告セッションの id。インプレッションでは "" とし、DEA がセッションを開いてその id を返します。クリックと終了ではその id を使います。null は取得セッションの id(sessionInfo.session)に署名しますが、これは広告セッションの id ではありません |
attestation |
Attestation? |
tier クレームのみを設定します。Play Integrity トークンを伴い期限切れでない PASSED の登録では B、それ以外は C。null では SDK が attest() から保持している登録を使います |
adUnit |
String? |
広告ユニット。証明に署名して含めます。1 つの広告の 3 つのイベントには同じものを渡します |
appScopedUid |
String? |
app_scoped_uid として証明に署名して含めます。null では省略されます |
extra |
Map<String, Any?> |
証明と並べて要求本文で送る未署名のフィールド。証明や SDK バージョンを置き換えることはありません |
update |
Boolean |
true では、POST /api/sessions ではなく、sessionId が指す広告セッションの更新 PUT /api/sessions/{sessionId} として証明を送信します。AD_ENDED に使います |
DEA からチャレンジを取得し、イベントに署名し、証明を送信します。証明には、スコアリングエンジンが保持する
スコア、その証拠の終了時刻、根拠となる操作の数、モデルバージョンが含まれます。これらをアプリが設定することは
できません。証明は appId を含みません。DEA は端末キーからアプリを取得します。チャレンジが失敗した場合、証明は DEA のノンスなしで署名・送信されます。
DEA に到達できない、または 5xx が返った場合、証明は 2 秒後に再送され、間隔は 30 秒まで倍増し、さらに最大
1 秒が加わります。送信は合計で最大 5 回、署名から 90 秒後の証明の期限切れ以降は行いません。4xx は最終的な
ものです。再試行の間もブロックします。メインスレッド以外で呼び出してください。
appKey が指定されていない場合は要求を行わずに拒否されます。端末にキーがない、スコアリングエンジンが動作して
いない、またはセッションがまだ十分でない(getClassification().result が INSUFFICIENT)場合は何も署名しません。
そのときに宣言されたインプレッションは記録されません。クリックはユーザーのタッチと照合されません。
戻り値: RecordOutcome — DEA が証明を受け付けたかどうか、証明、DEA または SDK の回答。
広告: 証明が受け付けられなかった理由を調べるを
参照してください。
record¶
fun record(
event: ProofEvent,
sessionId: String? = null,
attestation: Attestation? = null,
adUnit: String? = null,
appScopedUid: String? = null,
extra: Map<String, Any?> = emptyMap(),
update: Boolean = false,
): Boolean
sendProof と同じ送信を、同じパラメーターで行います。ブロックします。
戻り値: Boolean — DEA が証明を受け付けたとき true。インプレッションの後に DEA のセッション id を読むには
sendProof を使ってください。
getProof¶
fun getProof(
event: ProofEvent,
sessionId: String? = null,
attestation: Attestation? = null,
adUnit: String? = null,
appScopedUid: String? = null,
): SignedProof?
sendProof と同様に 1 つのイベントに署名し、送信せずに証明を返します。証明を自分で配信するアプリ向けです。
パラメーターは sendProof と同じです。ブロックします。チャレンジを取得するためです。appKey がなくても
拒否されません。
戻り値: SignedProof? — 証明。何も署名されなかった場合(端末キーがない、スコアリングエンジンが動作して
いない、証拠がまだ足りない)は null。理由は示されません。sendProof の said が理由を示します。
dispose¶
取得を停止し、まだ処理されていないものを破棄し、SDK を解放します。
DeaConsentDialog¶
show¶
fun show(
activity: Activity,
sdk: DeaSdk? = DeaSdk.instance,
copy: ConsentCopy = ConsentCopy(),
remember: Boolean = true,
ask: Boolean = true,
onResult: (Boolean) -> Unit = {},
)
| パラメーター | 型 | 説明 |
|---|---|---|
activity |
Activity |
ダイアログを添付する、表示中のアクティビティ |
sdk |
DeaSdk? |
回答を記録する SDK |
copy |
ConsentCopy |
ダイアログの文言 |
remember |
Boolean |
false では保存された回答を消去し、呼び出しごとに尋ね、各回答をこの起動の間だけ保持します |
ask |
Boolean |
false では何も表示せずに保存された回答を読みます |
onResult |
(Boolean) -> Unit |
回答とともにメインスレッドで呼び出されます |
回答が保存されていなければ同意ダイアログを表示し、回答を記録します。メインスレッドで呼び出してください。 ユーザー同意を参照してください。
関数¶
View.deaTarget¶
ビューが何であるかを宣言します: その名前と、どの種類のコントロールか。SDK が推定する内容を上書きします。
オプション: targetsを参照してください。
型¶
DeaConfig¶
オプションを参照してください。
registryAppId は 0.20.8 以降非推奨で、無視されます。証明は
appId を含みません。
Classification¶
| フィールド | 型 | 説明 |
|---|---|---|
result |
ClassificationResult |
結果 |
value |
Double? |
セッションのスコア(0〜1)。result が INSUFFICIENT のときに限り null |
actions |
Int |
value の根拠となる操作の数。読み込まれたモデルが求める数(組み込みモデルでは 8)に達するまで、結果は INSUFFICIENT のまま |
botThreshold |
Double? |
これ未満なら、十分なセッションはボット。読み込まれたモデルの値。SDK がスコアリングできないときは null |
humanThreshold |
Double? |
これ以上なら、十分なセッションは人物。読み込まれたモデルの値。モデルが設定していないときは null |
modelVersion |
Int? |
しきい値の元となるモデル。組み込みモデルでは 0。SDK がスコアリングできないときは null |
しきい値は読み込まれたモデルからのみ得られます。アカウント設定や組み込みの定数がそれを変えることはありません。
ClassificationResult¶
次の順序で判定されます。
| 値 | 条件 |
|---|---|
INSUFFICIENT |
スコアリングエンジンがない、または読み込まれたモデルが求める数よりアクションが少ない。value は null |
HUMAN |
value が humanThreshold 以上 |
BOT |
value が botThreshold 未満 |
HUMAN |
humanThreshold がなく、value が botThreshold 以上 |
UNDETERMINED |
value が 2 つのしきい値の間 |
このリリースへの移行:
Classification.sufficientはなくなり、ClassificationResultに 4 つ目の値が 追加されました。
以前 このリリース c.sufficient == falsec.result == ClassificationResult.INSUFFICIENT不十分なときの c.value: 数値nullClassificationResultは 3 値4 値: すべての網羅的な whenでINSUFFICIENTを扱うhumanThresholdがなく、valueがbotThreshold以上:UNDETERMINEDHUMAN
ThresholdMissing¶
読み込まれたモデルがbot しきい値を設定していない(しきい値より古いモデルファイル)ときに getClassification()
が投げます。modelVersion がそのモデルを示します。フォールバックのしきい値はありません。キャッチして
セッションを未判定として扱ってください。
Consent¶
| メンバー | 型 | 説明 |
|---|---|---|
decision |
ConsentDecision |
UNKNOWN、GRANTED、DENIED のいずれか |
isAnswered |
Boolean |
ユーザーが回答したかどうか |
isGranted |
Boolean |
ユーザーが同意したかどうか |
forget() |
Unit |
保存された回答を消去し、ユーザーに再度尋ねるようにします |
onChange(listener) |
() -> Unit |
判定が変わったときに新しい判定で listener を呼び出します。購読解除関数を返します |
Consent() |
コンストラクタ | この起動の間だけ保持される回答 |
Consent(store) |
コンストラクタ | 独自の ConsentStore に保持される回答 |
Consent.granted() |
Consent |
すでに「はい」である回答 |
ConsentStore¶
Consent が回答を保持する場所。write(ConsentDecision.UNKNOWN) は回答が忘れられたことを意味します。
ConsentCopy¶
同意ダイアログの文言: title、body、recorded、notRecorded、recordedLabel、notRecordedLabel、closing、
accept、decline。すべてのフィールドに英語のデフォルトがあります。
ユーザー同意を参照してください。
CaptureEvent¶
POINTER、SCROLL、MOTION、LIFECYCLE、CUSTOM、KEY_DOWN、KEY_UP。デフォルトの CAPTURE_EVENTS は
最初の 5 つです。オプション: eventsを参照してください。
KeyClass¶
LETTER、DIGIT、SPACE、DELETE、NAVIGATION、MODIFIER、OTHER(句読点、Enter、その他すべて)。
KeyClass.of(char: String) は入力された文字を LETTER、DIGIT、SPACE、OTHER のいずれかに分類します。
TargetBucket¶
UNKNOWN、BUTTON、LINK、INPUT、SCROLLER、CANVAS、BACKGROUND。
SessionInfo¶
| フィールド | 型 | 説明 |
|---|---|---|
session |
String |
現在のセッション id(UUID) |
device |
DeviceRecord |
現在の端末情報 |
sdk.version |
String |
SDK バージョン |
sdk.core |
String |
動作中のスコアリングエンジンのビルド。SDK がスコアリングできないときは none |
startedAt |
Long |
セッションの開始時刻(Unix ミリ秒) |
DeviceRecord¶
| フィールド | 型 | 説明 |
|---|---|---|
surface |
Surface |
画面サイズ(dp、width と height) |
pixelRatio |
Double |
dp あたりの物理ピクセル数 |
rotation |
Int |
画面の回転: 0、90、180、270 |
maxTouchPoints |
Int |
画面が同時に追跡できると宣言しているタッチの数 |
sensorRate |
Int |
モーションデータが届いた後の、要求したモーションレート(Hz)。それ以前とモーションがオフの間は 0 |
os |
Int |
オペレーティングシステムのコード |
runtime |
Int |
SDK ランタイムのコード |
ModelInfo¶
| フィールド | 型 | 説明 |
|---|---|---|
version |
Int |
モデルのバージョン。組み込みモデルでは 0 |
source |
ModelSource |
EMBEDDED、CACHE、NETWORK のいずれか |
ModelCheck¶
| フィールド | 型 | 説明 |
|---|---|---|
outcome |
ModelCheckOutcome |
NOT_DUE、UNCHANGED、NOT_PUBLISHED、NOT_SUPPORTED、LOADED、REFUSED、FAILED、CANCELLED のいずれか |
detail |
String? |
問題があった場合、その内容 |
Attestation¶
| フィールド | 型 | 説明 |
|---|---|---|
supported |
Boolean |
SDK が登録できたかどうか。キーを作成できなかった場合、または appKey が指定されていない場合は false |
verdict |
Verdict |
PASSED、FAILED、UNSUPPORTED のいずれか |
platformAttested |
Boolean |
受け付けられた登録に Play Integrity トークンが添付されていたかどうか |
platformTokenSpent |
Boolean |
DEA の回答にかかわらず、この試行で Play Integrity トークンを取得したかどうか |
integrity |
String? |
DEA が返した場合の、端末の完全性についての DEA の判定 |
expiresAt |
Long? |
有効期限(エポック秒) |
kid |
String? |
キーの識別子 |
tier |
String? |
DEA が割り当てた信頼ティア |
backing |
String? |
キーの保管場所: strongbox、tee、software のいずれか |
detail |
String? |
SDK が登録しなかった理由、または失敗時に DEA やネットワークが返した内容 |
ProofEvent¶
| 値 | wire |
イベント |
|---|---|---|
AD_IMPRESSION |
ad.impression |
広告が画面に表示されている |
AD_CLICK |
ad.click |
広告がクリックされた |
AD_ENDED |
ad.ended |
広告が消えた |
wire は証明に署名して含まれる event_type です。他の値はありません。
RecordOutcome¶
| フィールド | 型 | 説明 |
|---|---|---|
accepted |
Boolean |
DEA が証明を受け付けたかどうか |
signed |
SignedProof? |
署名された証明。何も署名されなかった場合は null |
isSigned |
Boolean |
signed が null でないかどうか |
said |
String? |
DEA の回答そのまま、または DEA に到達できなかった・受け付けなかった理由 |
sessionId |
String? |
DEA の回答の session_id。指定されなかった場合は null。インプレッションの後は広告セッションの id で、クリックと終了に渡します |
SignedProof¶
| メンバー | 型 | 説明 |
|---|---|---|
proof |
String |
コンパクト JWS(header.payload.signature)。端末キーで署名(ES256) |
score |
Double |
証明に署名して含まれるスコア(0〜1) |
evidenceAt |
Long |
score の根拠となる証拠の終了時刻(エポック秒) |
windows |
Int |
score の根拠となるスコアリングされた操作の数 |
sessionId |
String |
証明に署名して含まれる session_id |
event |
ProofEvent |
証明に署名して含まれるイベント |
modelVersion |
Int? |
score を生成したモデルのバージョン。組み込みモデルでは 0。証明に含まれない場合は null |
composedBy |
ProofSource |
署名対象を構成した主体。DeaSdk が署名するすべての証明では CORE(スコアリングエンジン) |
composedBytes |
Int? |
署名されたバイト数 |
header |
JSONObject? |
デコードされた署名ヘッダー: alg、typ、kid |
claims |
JSONObject? |
デコードされた署名クレーム |
signature |
String? |
署名セグメント(base64url) |
score、evidenceAt、windows、modelVersion は署名されたクレームから読み戻されます。