API リファレンス¶
import { init, DeaSdk } from '@dea/sdk';
// or '@dea/sdk/desktop', '@dea/sdk/mobile' — same API, no device detection
init は SDK インスタンスを返します。他の場所では DeaSdk.current がそれを返します。
注: パッケージには以下のすべての TypeScript 宣言が含まれています。エディターに
@dea/sdkの 完全な型が表示されます。
関数¶
init¶
SDK と取得を開始します。実行中のインスタンスがあればそれを返し、その後の呼び出しのオプションは無視します。 オプションを参照してください。
例外: ブラウザーが crypto.randomUUID() を提供しない場合に TypeError を投げます。セキュア
コンテキストでないページ(HTTPS でも localhost でもない)や、最低バージョン
より古いブラウザーが該当します。スコアリングエンジンを読み込めない場合、init は例外を投げず、error
に問題を報告します。
DeaSdk¶
DeaSdk.current¶
実行中のインスタンス。init の前と dispose() の後は null です。
ready¶
SDK の読み込みが成功・失敗を問わず完了した時点で解決します。決して reject しません。他のメソッドを呼ぶ
前に待つ必要はありません。requireConsent: true の場合は setConsent(true) の後にのみ解決します。
ユーザー同意を参照してください。
error¶
スコアリングエンジンを読み込めなかった理由、または null。設定されている場合、取得は続きますがスコアは
なく、分類は 'insufficient' のままです。読み込みの失敗は CoreLoadError で、その reason は
'core_not_loaded'、'core_abi_mismatch'、'core_wrong_profile' のいずれかです。
トラブルシューティングを参照してください。
appId¶
SDK が動作しているアカウント。
appKey¶
SDK が DEA に送るアプリキー。本番の appId にキーが渡されなかった場合は null で、その場合 attest()
は失敗し、広告の証明は要求を送らずに署名されません。
profile¶
使用中の取得プロファイル(自動判定または固定)。profile.id は 'web-desktop' または 'web-mobile' です。
getClassification¶
唯一のスコア読み取りです。スコア、その根拠となる証拠、読み込まれたモデルのしきい値を、'human'、'bot'、
'undetermined'、'insufficient' のいずれかに分類した 1 つのスナップショットとして返します。同期的で、
ユーザーの最新の入力を含みます。しきい値は読み込まれたモデルのみから来ます。
ヒューマンスコアリングを参照してください。
例外: 読み込まれたモデルにボットのしきい値がない場合、ThresholdMissing(modelVersion 付き)を
投げます。
sufficiency¶
これまでに収集された証拠。スコアリングエンジンが動作していない間(読み込み中、読み込み失敗、同意待ち)
は null です。
model¶
使用中のスコアリングモデル: { version, source }。version はパッケージに組み込まれたモデルでは 0
です。source は 'embedded'、'cache'(以前の訪問でダウンロード)、'network'(このセッションで
ダウンロード)のいずれかです。modelUpdates を参照してください。
checkForModel¶
ready() を待ち、SDK が毎回の init で実行するモデル確認に合流し(まだ実行されていなければ実行し)、
確認が終わった時点で使用中のモデルで解決します。{ force: true } の場合は DEA に再度問い合わせますが、その時点で確認が進行中なら二重に問い合わせず、その確認に合流します。
modelUpdates: false の場合は何も問い合わせません。
pause¶
記録を停止します。セッションは保持されます。機密性の高い画面 を参照してください。
resume¶
pause() の後に記録を再開します。同意ゲートは開きません。
consent¶
ユーザーの回答: decision('unknown'、'granted'、'denied')、isAnswered、isGranted。init 時に
ブラウザーから復元されます。
setConsent¶
回答を記録します。requireConsent: true の場合、true で記録が始まり、false で止まります。
{ remember: false } は回答をこのページの間だけ保持します。
ユーザー同意を参照してください。
captureEvent¶
| パラメーター | 型 | 説明 |
|---|---|---|
name |
string |
1〜64 文字 |
data |
Record<string, unknown> |
省略可。JSON で最大 1024 バイト |
戻り値: 記録されたとき true。一時停止中、同意待ち、破棄後、または名前が不正な場合は false。
カスタムイベントを参照してください。
reset¶
現在のセッションを終了し、新しいセッションを開始します。セッション を参照してください。
getSessionInfo¶
現在のセッション ID、端末、モーションセンサーへのアクセス、SDK バージョン。
attest¶
ブラウザーのキーを DEA に登録します。期限の 60 秒前までキャッシュされます。決して例外を投げません。 SDK が自ら呼ぶことはありません。アテステーションを参照してください。
ads¶
広告検証モジュール。広告を参照してください。
dispose¶
取得を停止し、まだ処理または送信されていないものを破棄し、SDK を解放します。
AdModule¶
session_opened¶
広告が画面に表示されました。インプレッションに署名して送信し、DEA のサービスが開いた広告セッションで
解決します。開けなかった場合は null で、分類が 'insufficient' の間は常にそうなります。その場合
インプレッションは記録されません。surface は広告が描画される要素、またはそのビューポートピクセルでの
矩形を返す関数です。
広告セッションが開かなかった理由を調べるを
参照してください。
counts¶
証明の signed、refused、notScored(分類がまだ 'insufficient' だった)、unwitnessed なクリック、
および delivery(sent、dropped、pending)。
AdSession¶
| メンバー | 型 | 説明 |
|---|---|---|
id |
string |
DEA のサービスが作成した広告セッションの ID |
click() |
() => boolean |
広告がクリックされた。監視中の要素に一度も触れていない場合、最初のクリックの後、または end() の後は拒否される |
end() |
() => void |
広告が消えた。広告セッションの終了を送信する |
型¶
SessionInfo¶
| フィールド | 型 | 説明 |
|---|---|---|
session |
string |
現在のセッション ID |
device |
DeviceRecord |
現在の端末情報: ビューポートサイズ(surface)、pixel_ratio、rotation、max_touch_points、sensor_rate など |
identity |
DeviceIdentity |
ブラウザーが User-Agent Client Hints で報告する場合の os_version と model。それ以外は null |
motion |
'off' \| 'unsupported' \| 'pending' \| 'denied' \| 'granted' |
モーションセンサーへのアクセス |
sdk.version |
string |
SDK バージョン |
sdk.core |
string |
スコアリングエンジンのビルド |
Classification¶
| フィールド | 型 | 説明 |
|---|---|---|
result |
ClassificationResult |
答え |
value |
number \| null |
0 から 1 のヒューマンスコア。result が 'insufficient' のときに限り null |
actions |
number |
value の根拠となるスコアリングされたアクションの数。最大 64。「あと N アクション」の表示に使う |
botThreshold |
number \| null |
モデルのbot しきい値。モデルが読み込まれる前は null |
humanThreshold |
number \| null |
モデルのhuman しきい値。モデルが設定しない場合は null |
modelVersion |
number \| null |
しきい値の元となるモデル。組み込みのものは 0。モデルが読み込まれる前は null |
ClassificationResult¶
| 値 | 条件 |
|---|---|
'insufficient' |
スコアリングエンジンがまだ動作していない、またはアクションが少なすぎる: デスクトップでは 20 未満か入力の種類(ポインター、ホイール、キーボード)が 1 つだけ、スマートフォンでは 8 未満。value は null で、証明は署名されない |
'human' |
value が humanThreshold 以上。humanThreshold が null のとき: value が botThreshold 以上 |
'bot' |
value が botThreshold 未満 |
'undetermined' |
value が 2 つのしきい値の間 |
行はこの順序で判定され、'insufficient' が最初です。スコアは十分なアクションに裏付けられて初めて
意味を持ちます。
Sufficiency¶
| フィールド | 型 | 説明 |
|---|---|---|
durationMs |
number |
これまでのセッション時間 |
actions |
number |
収集された操作の数 |
pointer |
number |
ポインター操作 |
wheel |
number |
ホイール操作 |
key |
number |
キーボード操作 |
sufficient |
boolean |
セッションを分類するのに十分なアクションがあるかどうか。証拠を参照 |
Attestation¶
| フィールド | 型 | 説明 |
|---|---|---|
supported |
boolean |
キーを作成できたかどうか |
verdict |
'passed' \| 'failed' \| 'unsupported' |
結果 |
expiresAt |
number \| null |
有効期限(エポック秒) |
kid |
string \| null |
キーの識別子 |
tier |
string \| null |
DEA が割り当てた信頼ティア |
AdCounts¶
| フィールド | 型 | 説明 |
|---|---|---|
signed |
number |
署名された証明 |
refused |
number |
署名されなかった証明: appKey がない、ブラウザーのキーがない、またはスコアリングエンジンが動作していないか拒否した |
notScored |
number |
分類がまだ 'insufficient' だったため署名されなかった証明 |
unwitnessed |
number |
監視中の要素に何も触れなかったため拒否されたクリック |
delivery |
{ sent: number; dropped: number; pending: number } |
DEA が受理した証明、断念した証明、送信中の証明 |
ModelState¶
| フィールド | 型 | 説明 |
|---|---|---|
version |
number |
モデルのバージョン。パッケージに組み込まれたものは 0 |
source |
'embedded' \| 'cache' \| 'network' |
取得元 |
ThresholdMissing¶
読み込まれたモデルにボットのしきい値がない場合に getClassification() が投げる Error。modelVersion
がモデルを示します。
CoreLoadError¶
スコアリングエンジンを読み込めなかったときの dea.error の Error。reason は 'core_not_loaded'、
'core_abi_mismatch'、'core_wrong_profile' のいずれかです。