コンテンツにスキップ

API リファレンス

import 'package:dea_sdk/dea_sdk.dart';

DeaSdk

init

static DeaSdk init(
  DeaOptions options, {
  int? playIntegrityProject,
  String? appKey,
  String? registryAppId,
  Directory? modelDirectory,
  bool modelUpdates = true,
  Duration modelTimeout = const Duration(seconds: 30),
})

SDK と取得を開始します。すでに実行中のインスタンスがあればそれを返します。決して例外を投げません。 オプションを参照してください。

registryAppId は 0.20.8 以降非推奨で、無視されます。証明は appId を含みません。 オプションを参照してください。

instance

static DeaSdk? get instance

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

error

Object? get error

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

isScoring

bool get isScoring

SDK がスコアリングできるかどうか。false のとき、getClassification() は null の値とともに insufficient を返し、error にその理由が入ります。

getClassification

Classification getClassification()

スコアの読み取りはこれひとつです。スコア、その根拠となる証拠、読み込まれたモデルのしきい値を、ひとつの スナップショットで human、bot、undetermined、または insufficient に分類します。同期的で、 ネットワークは使いません。直前のジェスチャーも含まれます。しきい値は読み込まれたモデルからのみ 来ます。ヒューマンスコアリングを参照してください。

読み込まれたモデルに bot しきい値がない場合、ThresholdMissing(modelVersion 付き)を投げます。SDK が スコアリングできない場合には決して例外を投げません。

Consent get consent

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

setConsent

Future<void> setConsent(bool granted, {bool remember = true})
パラメーター 型 説明
granted bool ユーザーが同意したかどうか
remember bool 回答を端末に保存する。false はこの実行の間だけ保持する

すぐに効果を持ちます。撤回すると、取得済みでまだ処理されていないものは破棄されます。

pause

void pause()

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

resume

void resume()

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

setMotion

void setMotion(bool on)

この実行の間、モーションセンサーをオフ(false)またはオン(true)に切り替えます。オフの間は モーションデータは記録されず、getSessionInfo().device.sensorRate は 0 を返します。タッチの取得と セッションは継続します。その場合、分類が使える証拠は少なくなります。

motion

bool get motion

モーションセンサーがオンかどうか。setMotion(false) が呼ばれていなければ true。

captureEvent

void captureEvent(String name, [Map<String, Object?>? data])
パラメーター 型 説明
name String 最大 64 文字。長い名前は切り詰められる
data Map<String, Object?>? 任意。JSON として最大 1024 バイト。超えるとイベントは破棄される

カスタムイベントを参照してください。

captureKey

void captureKey(
  KeyClass keyClass, {
  bool pressed = true,
  int mods = 0,
  bool repeat = false,
  String? field,
})

アプリが検知したキーストローク 1 件を報告します。events に EventKind.keyDown(押下)または EventKind.keyUp(解放)が含まれていなければ何もしません。

パラメーター 型 説明
keyClass KeyClass キーの種類。文字そのものではない。KeyClass.of(char) が文字を分類する
pressed bool false は解放を報告する
mods int 押されている修飾キー(KeyMod フラグ)。ソフトキーボードでは 0
repeat bool 押下がキーボードのオートリピートかどうか
field String? フィールドの安定した名前。デフォルトはフォーカスされているウィジェットのセマンティクス識別子

パスワードフィールドでは決して呼び出さないでください。 キー入力を報告するを参照してください。

capturePointer

void capturePointer({
  required EventKind kind,
  required int pointerId,
  required double x,
  required double y,
  required int atEpochMs,
  Tool tool = Tool.touch,
  Force? force,
  Contact? contact,
  Target? target,
})

Web ビューなど、Flutter がルーティングしないサーフェスからのポインターイベント 1 件を報告します。 一時停止中、同意前、dispose() 後、および kind が events に 含まれていない場合は破棄されます。

パラメーター 型 説明
kind EventKind down、move、up、cancel、scroll、または hover
pointerId int 1 本の指またはポインターをそのイベント群の間で識別する
x, y double 論理ピクセル単位の位置。アプリウィンドウ全体に対する座標
atEpochMs int イベントが起きた時刻(Unix ミリ秒)
tool Tool 何が生成したか。デフォルトはタッチ
force Force? 端末の min..max の範囲内の value としての圧力(分かる場合)
contact Contact? 接触サイズ(分かる場合)
target Target? タッチが着地した対象。down のときだけ読み取られる

Web ビュー内のタッチを報告するを参照してください。

reset

void reset()

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

getSessionInfo

SessionInfo getSessionInfo()

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

attest

Future<Attestation> attest()

端末キーを DEA に登録します。passed の結果は有効期限間近まで再利用されます。決して例外を投げません。 アテステーションを参照してください。

最初の呼び出しは自動更新も開始します。SDK は登録の有効期限の 1 分前に同じキーを再登録し、アプリが フォアグラウンドに戻るたびに再確認します。失敗した更新は 30 秒後、次に 1、2、5、15 分後、その後は 15 分ごとに再試行されます。kid は変わりません。アプリ側で独自の更新タイマーを持つ必要はありません。

attestation

Attestation? get attestation

この実行中の最後の attest() の結果(拒否を含む)。最初の呼び出しの前は null。

storedAttestation

Future<Attestation?> storedAttestation()

端末に保持されている登録(まだ有効な場合)を、ネットワーク要求なしで読み取ります。attest() が再登録 しなければならない場合は null。

ここで見つかった登録も、attest() と同様に自動更新を開始します。

forgetAttestation

Future<void> forgetAttestation()

このインストールの登録をメモリ上と端末上から忘れ、自動更新を停止します。次の attest() は、同じ端末 キーと kid で再登録します。たとえば、別のアカウントがサインインしたときに使います。

nextAttestationRefresh

int? get nextAttestationRefresh

次の自動更新の予定時刻(Unix 秒)。最初の attest() の前、およびキーを保持できない端末では null。

onAttestationEvent

void Function(RefreshEvent event)? onAttestationEvent

更新の判断ごとに呼び出されます: RefreshScheduled(after)、RefreshFired(verdict)、または RefreshIdle()。最初のスケジュールを見るには、最初の attest() の前に設定してください。

モデルの更新

modelDirectory が init に渡されている場合のみ有効です。 オプションを参照してください。

model

ModelInfo get model

使用中のモデル: version(組み込みモデルでは 0)と source(ModelSource.embedded、cache、 または network)。

modelChanges

Stream<ModelInfo> get modelChanges

この実行中に新しいモデルがスコアリングを開始するたびに発行します。更新がオフの場合は空です。

checkForModel

Future<ModelCheck> checkForModel({bool force = false})

前回のチェックから 1 日が経過していれば、今すぐ新しいモデルを確認します。force: true は経過時間に かかわらず確認します。人が押すボタンに使い、スケジュール実行には決して使わないでください。決して 例外を投げません。

結果の outcome は ModelCheckOutcome で、さらに伝えることがある場合は detail に記されます:

結果 意味
notDue 前回のチェックから 1 日未満。何も問い合わせていない
unchanged 新しいモデルは公開されていない
notPublished このプラットフォーム向けのモデルは公開されていない
notSupported 新しいモデルは公開されているが、新しい SDK リリースが必要
loaded 新しいモデルがダウンロードされ、現在スコアリングしている
refused モデルはダウンロードされたが、スコアリングエンジンが拒否した。使用中のモデルが維持される
failed 使える応答がない: オフライン、タイムアウト、または検証に通らなかったダウンロード
cancelled モデルの更新が動作していない(modelDirectory がない、modelUpdates: false、または SDK がスコアリングできない)、または SDK が破棄された

lastModelCheck

({ModelCheck check, DateTime at})? get lastModelCheck

最後のチェックがどのように、いつ終わったか。まだ実行されていない場合は null。

広告

Flutter には広告セッションオブジェクトがなく、ユーザーが広告に触れたかどうかもチェックしません。以下の 3 つの呼び出しは、広告イベント 1 件の証明に端末キーで署名します。sendProof と record はそれを DEA にも送信します。広告を参照してください。

各呼び出しはまず DEA に署名に含める単回使用のノンスを求め、DEA が返さない場合はノンスなしで署名します。 スコアの主張はスコアリングエンジンが構成するため、分類が insufficient の間は何も署名されません。 これらの呼び出しは appKey やアテステーションをチェックしません。

パラメーター 型 説明
sessionId String 広告のセッション ID。session_id として署名される。adImpression では '' とし、DEA に ID を作らせる。adClick と adEnded では DEA が返した ID。取得セッションの ID ではない
event ProofEvent 広告イベント。event_type として署名される
attestation Attestation? 証明が主張するティアを決める: verdict が passed で platformAttested が true なら B、それ以外は C。デフォルトは最後の attest() の結果である attestation
adUnit String? 広告が読み込まれた広告ユニット。ad_unit として署名される。null のときは省略される
appScopedUid String? アプリ内でのユーザーの擬似匿名 ID。app_scoped_uid として署名される。null のときは省略される
extra Map<String, Object?> sendProof と record のみ。証明と並べて要求本文に追加される署名されないフィールド。h_proof や sdk_version を置き換えることはない
update bool sendProof と record のみ。true にすると、証明を POST /api/sessions ではなく PUT /api/sessions/{sessionId} として送る。adEnded で渡す

sendProof

Future<RecordOutcome> sendProof({
  required String sessionId,
  required ProofEvent event,
  Attestation? attestation,
  String? adUnit,
  String? appScopedUid,
  Map<String, Object?> extra = const {},
  bool update = false,
})

証明 1 件に署名し、DEA に送信します。RecordOutcome は、DEA が受け入れたかどうか、DEA が返した セッション ID、受け入れられなかった場合はその理由を示します。

DEA に到達できない、または 5xx ステータスが返った場合、同じ証明を 2、4、8、16 秒後(それぞれ最大 1 秒を加算)に再送し、合計で最大 5 回送信します。署名後 90 秒の証明の有効期限を過ぎてからは送信しません。 4xx の応答は最終です。Future は最後の送信の後に完了します。端末には何も保持されません。

record

Future<bool> record({
  required String sessionId,
  required ProofEvent event,
  Attestation? attestation,
  String? adUnit,
  String? appScopedUid,
  Map<String, Object?> extra = const {},
  bool update = false,
})

sendProof と同じですが、DEA が証明を受け入れたかどうかだけを返します。インプレッションに対して DEA が 返すセッション ID は返しません。インプレッションは sendProof で送ってください。

getProof

Future<SignedProof?> getProof({
  required String sessionId,
  required ProofEvent event,
  Attestation? attestation,
  String? adUnit,
  String? appScopedUid,
})

証明 1 件に送信せずに署名します。何も署名されなかった場合は null: 端末キーがない、スコアリング エンジンがない、分類がまだ insufficient、または端末キーが署名しなかった。証明は署名後 90 秒間 有効です。

dispose

void dispose()

取得を停止し、まだ処理されていないものを破棄し、SDK を解放します。

関数

showDeaConsentDialog

Future<bool> showDeaConsentDialog(
  BuildContext context, {
  DeaSdk? sdk,
  ConsentCopy copy = const ConsentCopy(),
  ConsentDialogStyle style = ConsentDialogStyle.adaptive,
  bool remember = true,
  bool ask = true,
})

ユーザーがまだ回答していなければ同意ダイアログを表示し、回答を記録して返します。SDK が初期化されて いない場合は、何も表示せずに false を返します。

パラメーター 説明
sdk SDK インスタンス。デフォルトは DeaSdk.instance
copy ダイアログのテキスト
style adaptive(アプリのテーマのプラットフォームに従う)、material、または cupertino
remember 回答を保存する。false は保存済みの回答を消去し、呼び出しごとに尋ねる
ask false は何も表示せずに保存された回答を返す

ウィジェット

DeaConsentDialog

const DeaConsentDialog({Key? key, ConsentCopy copy = const ConsentCopy(), ConsentDialogStyle style = ConsentDialogStyle.adaptive})

ダイアログそのもの。独自のフローの中に配置するためのものです。true(承諾)または false(拒否)で 自身のルートをポップします。回答は setConsent で記録してください。

型

DeaOptions

オプションを参照してください。

EventKind

down、move、up、cancel、scroll、hover、keyDown、keyUp。定数 pointerKinds は最初の 6 つを列挙し、これが DeaOptions.events のデフォルトです。

KeyClass

letter、digit、space、delete、navigation、modifier、other。

KeyClass.of(String char) は 1 文字のクラスを返します: 任意の文字体系の文字には letter、0 から 9 には digit、空白には space、それ以外には other。

KeyMod

captureKey の mods 用のフラグ: KeyMod.ctrl、KeyMod.alt、KeyMod.shift、KeyMod.meta。| で 組み合わせます。

Tool

unknown、touch、mouse、pen、trackpad、penInverted。

Force

フィールド 型 説明
value double 圧力の読み取り値
min double 端末が報告する最小値
max double 端末が報告する最大値

プラットフォームの数値をそのまま転送してください。min と max が等しい端末には圧力センサーが ありません。

Contact

フィールド 型 説明
x, y double? 画面軸に沿った接触の半径
major, minor double? 接触楕円の半軸
orientation double? 長軸の方向(ラジアン)

プラットフォームが計測しないフィールドは null のままにしてください。null と 0.0 は異なる意味を 持ちます。

Target

フィールド 型 説明
bucket TargetBucket unknown、button、link、input、scroller、canvas、または background
id int 要素の安定した 16 ビット ID。不明なら 0

Classification

フィールド 型 説明
result ClassificationResult 答え
value double? 0 から 1 の human スコア。result が insufficient のときに限り null
actions int value の根拠となるスコアリングされたアクションの数。「あと N アクション」の表示用
botThreshold double? モデルの bot しきい値。SDK がスコアリングできないとき null
humanThreshold double? モデルの human しきい値。モデルが設定していないとき、または SDK がスコアリングできないとき null
modelVersion int? しきい値の元となるモデル。組み込みモデルでは 0。SDK がスコアリングできないとき null

ClassificationResult

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

値 条件
insufficient SDK がスコアリングできない、またはセッションのアクションがモデルの求める数(組み込みモデルでは 8)に達していない。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 値: すべての switch で insufficient を扱う
humanThreshold なし、value が botThreshold 以上: undetermined human

ThresholdMissing

読み込まれたモデルに bot しきい値がない場合に getClassification() が投げます。

フィールド 型 説明
modelVersion int しきい値を持たないモデルのバージョン
メンバー 型 説明
decision ConsentDecision unknown、granted、または denied
isAnswered bool ユーザーが回答したかどうか
isGranted bool ユーザーが同意したかどうか
forget() Future<void> 保存された回答を消去し、ユーザーに再度尋ねるようにする
addListener(listener) void 判断が変わったときに新しい判断で listener を呼ぶ
removeListener(listener) void listener の呼び出しを止める

ConsentCopy

フィールド 型 説明
title String ダイアログのタイトル
body String 説明文
recorded List<String> 記録されるもの。空ならセクションを非表示
notRecorded List<String> 決して記録されないもの。空ならセクションを非表示
recordedLabel String recorded の見出し
notRecordedLabel String notRecorded の見出し
closing String 結びの文
accept String 承諾ボタン
decline String 拒否ボタン

SessionInfo

フィールド 型 説明
session String 現在のセッション ID
device Device 現在の端末情報
startedAt int 現在のセッションが開始した時刻(Unix ミリ秒)
sdk.version String SDK バージョン
sdk.core String スコアリングエンジンのビルド。読み込まれなかった場合は none

Device

フィールド 型 説明
runtime Runtime Runtime.flutter
os Os オペレーティングシステム
surface Surface 論理ピクセル単位の画面サイズ
pixelRatio double 論理ピクセルあたりの物理ピクセル数
rotation int 画面の回転: 0、90、180、または 270
maxTouchPoints int 0: Flutter はこれを報告しない
sensorRate int モーションデータが届いた後の要求モーションレート(Hz)。それ以前、およびモーションがオフの間は 0

注: Flutter では、rotation はすべての端末で 0 を返します。SDK はプラットフォームから画面の回転を 読み取りません。

Attestation

フィールド 型 説明
supported bool キーを作成できたかどうか。appKey が渡されなかった場合も false
verdict Verdict passed、failed、または unsupported
platformAttested bool Play Integrity(Android)または App Attest(iOS)のトークンがキーとともに DEA に送られたかどうか
expiresAt int? 有効期限(エポック秒)
kid String? キー識別子
tier String? DEA が割り当てた信頼ティア
backing String? キーが保持されている場所
integrity String? DEA のサービス側で決定される、端末の整合性の読み取り。DEA が送らない場合は null
detail String? アテステーションが失敗した、または未サポートである理由

注: DEA のサービスは現時点では integrity の読み取りを送信しないため、integrity は null です。

Verdict

値 条件
passed DEA が端末キーを受け入れた
failed DEA が登録を拒否した、または到達できなかった、プラットフォームがトークンの発行を拒否した、または拒否された試行の後でアテステーションが一時停止している。detail がどれかを示す
unsupported この端末でキーを作成できない、SDK のネイティブプラグインが登録されていない、または appKey が渡されていない

ProofEvent

証明が記録する広告イベント。wire は署名される event_type クレームです。

値 wire 送信方法
adImpression ad.impression sessionId ''、POST /api/sessions として。DEA は広告のセッション ID を返す
adClick ad.click DEA のセッション ID、POST /api/sessions として
adEnded ad.ended DEA のセッション ID と update: true、PUT /api/sessions/{sessionId} として

RecordOutcome

sendProof が返すもの。

フィールド 型 説明
accepted bool DEA が証明を受け入れたかどうか(2xx ステータス)
sessionId String? DEA の応答に含まれる session_id。含まれなかった場合は null。インプレッションでは、クリックと終了を送るための ID
signed SignedProof? 署名された証明。何も署名されなかった場合は null
isSigned bool DEA が受け入れたかどうかにかかわらず、証明が署名されたかどうか
said String? DEA が証明を受け入れた場合はその応答。それ以外は、何も署名されなかった理由、または配信されなかった理由。人が読むためのもの。広告を参照

SignedProof

getProof が返すもの、および RecordOutcome.signed。

フィールド 型 説明
proof String コンパクト JWS(header.claims.signature)。h_proof として DEA に送られるもの
header Map<String, Object?>? デコードされた署名済みヘッダー: alg、typ、kid
claims Map<String, Object?>? デコードされた署名済みクレーム
signature String? 署名セグメント(base64url)
score double 署名に含まれたスコア(h_score)。0 から 1
evidenceAt int score の根拠となる証拠が集められた時刻(Unix 秒、h_ts)
windows int score の根拠となるスコアリングされたアクションの数(h_wc)
modelVersion int? スコアリングしたモデル(h_mv)。組み込みモデルでは 0。証明に含まれない場合は null
sessionId String 署名に含まれた session_id
event ProofEvent 署名に含まれたイベント