コンテンツにスキップ

API リファレンス

import ai.dea.sdk.ClassificationResult
import ai.dea.sdk.DeaConfig
import ai.dea.sdk.DeaSdk

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

val instance: DeaSdk?

実行中のインスタンス。init の前と dispose() の後は null です。

ready

val ready: Boolean

SDK がスコアリングできるかどうか。false のとき、取得は続きますが getClassification() は INSUFFICIENT を 返し、coreFault がその理由を示します。

coreFault

val coreFault: String?

SDK がスコアリングできない理由。できる場合は null。

getClassification

fun getClassification(): Classification

セッションが人物、ボット、またはまだどちらでもないと読めるかを、その根拠となるスコアとモデルのしきい値とともに 返します。1 つのスナップショットであり、これまでのすべての操作を対象とし、フィールドは常に互いに整合しています。 同期的で、メインスレッドで安全です。ヒューマンスコアリングを参照してください。

例外: 読み込まれたモデルがbot しきい値を設定していない場合は ThresholdMissing。SDK がスコアリングできない (ready が false)場合は例外を投げず、value が null の INSUFFICIENT を返します。

val consent: Consent

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

setConsent

fun setConsent(granted: Boolean, remember: Boolean = true)
パラメーター 型 説明
granted Boolean ユーザーが同意したかどうか
remember Boolean false ではこの起動の間だけ回答を保持し、何も保存しません

即座に有効になります。撤回すると、取得済みでまだ処理されていないものは破棄されます。いずれの場合もセッションは 維持されます。

pause

fun pause()

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

resume

fun resume()

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

captureEvent

fun captureEvent(name: String, data: Map<String, Any?>? = null): Boolean
パラメーター 型 説明
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

fun setMotion(on: Boolean)
val motion: Boolean

実行中のアプリについて、モーションセンサーをオフにするか、再びオンにします。オフの間、SDK はモーションデータを 読まず、sessionInfo.device.sensorRate は 0 になります。タッチの取得とセッションは続きます。motion は センサーがオンかどうかを示します。

reset

fun reset()

現在のセッションを終了し、新しいセッションを開始します。セッションを 参照してください。

sessionInfo

val sessionInfo: SessionInfo

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

modelInfo

val modelInfo: ModelInfo

どのモデルがスコアリングしているか。その version(組み込みモデルでは 0)と source(EMBEDDED、 CACHE(以前の起動でダウンロード)、NETWORK(この実行中にダウンロード))。 モデルオプションを参照してください。

checkForModel

fun checkForModel(force: Boolean = false): ModelCheck

前回の確認から 1 日が経過していれば、今すぐ DEA のモデルホストを確認します。force = true では常に確認します。 SDK は起動ごとと、フォアグラウンドに戻ったときにすでに確認しているため、ほとんどのアプリはこれを呼び出しません。 例外を投げません。ブロックします。メインスレッド以外で呼び出してください。モデル更新がオフのときは ModelCheckOutcome.CANCELLED を返します。

addModelListener

fun addModelListener(listener: (ModelInfo) -> Unit): () -> Unit

この実行中に新しいモデルがスコアリングを始めるたびに、バックグラウンドスレッドで listener を呼び出します。 購読解除関数を返します。

attest

fun attest(): Attestation

端末キーを DEA に登録し、自動更新を有効にします。期限が近づくまでキャッシュされます。例外を投げません。 ブロックします。メインスレッド以外で呼び出してください。appKey が指定されていない場合は要求を行わずに UNSUPPORTED を返します。アテステーションを参照してください。

renewAttestation

fun renewAttestation(): Attestation

今すぐ再登録します。失敗してもすでに保持している登録はそのまま残ります。ブロックします。

lastAttestation

val lastAttestation: Attestation?

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

storedAttestation

fun storedAttestation(): Attestation?

このインストールがすでに保持している登録。まだ有効であれば、要求を行わずにストレージから読みます。そうでなければ null。有効な登録があれば自動更新を有効にします。

forgetAttestation

fun forgetAttestation()

保存された登録と、拒否された試行の後の待機を忘れ、自動更新を停止します。端末キーは維持されます。

nextAttestationRefresh

val nextAttestationRefresh: Long?

次に登録が自動更新される時刻(エポック秒)。

onAttestationEvent

var onAttestationEvent: ((AttestRefresher.Event) -> Unit)?

自動更新の判断ごとに呼び出されます: 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

fun 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

fun View.deaTarget(name: String? = null, bucket: TargetBucket? = null)

ビューが何であるかを宣言します: その名前と、どの種類のコントロールか。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 == false c.result == ClassificationResult.INSUFFICIENT
不十分なときの c.value: 数値 null
ClassificationResult は 3 値 4 値: すべての網羅的な when で INSUFFICIENT を扱う
humanThreshold がなく、value が botThreshold 以上: UNDETERMINED HUMAN

ThresholdMissing

class ThresholdMissing(val modelVersion: Int) : Exception

読み込まれたモデルがbot しきい値を設定していない(しきい値より古いモデルファイル)ときに getClassification() が投げます。modelVersion がそのモデルを示します。フォールバックのしきい値はありません。キャッチして セッションを未判定として扱ってください。

メンバー 型 説明
decision ConsentDecision UNKNOWN、GRANTED、DENIED のいずれか
isAnswered Boolean ユーザーが回答したかどうか
isGranted Boolean ユーザーが同意したかどうか
forget() Unit 保存された回答を消去し、ユーザーに再度尋ねるようにします
onChange(listener) () -> Unit 判定が変わったときに新しい判定で listener を呼び出します。購読解除関数を返します
Consent() コンストラクタ この起動の間だけ保持される回答
Consent(store) コンストラクタ 独自の ConsentStore に保持される回答
Consent.granted() Consent すでに「はい」である回答

ConsentStore

interface ConsentStore {
    fun read(): ConsentDecision
    fun write(decision: ConsentDecision)
}

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 は署名されたクレームから読み戻されます。