コンテンツにスキップ

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

function init(config?: DeaConfig): DeaSdk

SDK と取得を開始します。実行中のインスタンスがあればそれを返し、その後の呼び出しのオプションは無視します。 オプションを参照してください。

例外: ブラウザーが crypto.randomUUID() を提供しない場合に TypeError を投げます。セキュア コンテキストでないページ(HTTPS でも localhost でもない)や、最低バージョン より古いブラウザーが該当します。スコアリングエンジンを読み込めない場合、init は例外を投げず、error に問題を報告します。

DeaSdk

DeaSdk.current

static get current(): DeaSdk | null

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

ready

ready(): Promise<void>

SDK の読み込みが成功・失敗を問わず完了した時点で解決します。決して reject しません。他のメソッドを呼ぶ 前に待つ必要はありません。requireConsent: true の場合は setConsent(true) の後にのみ解決します。 ユーザー同意を参照してください。

error

get error(): Error | null

スコアリングエンジンを読み込めなかった理由、または null。設定されている場合、取得は続きますがスコアは なく、分類は 'insufficient' のままです。読み込みの失敗は CoreLoadError で、その reason は 'core_not_loaded'、'core_abi_mismatch'、'core_wrong_profile' のいずれかです。 トラブルシューティングを参照してください。

appId

get appId(): string

SDK が動作しているアカウント。

appKey

get appKey(): string | null

SDK が DEA に送るアプリキー。本番の appId にキーが渡されなかった場合は null で、その場合 attest() は失敗し、広告の証明は要求を送らずに署名されません。

profile

get profile(): CaptureProfile

使用中の取得プロファイル(自動判定または固定)。profile.id は 'web-desktop' または 'web-mobile' です。

getClassification

getClassification(): Classification

唯一のスコア読み取りです。スコア、その根拠となる証拠、読み込まれたモデルのしきい値を、'human'、'bot'、 'undetermined'、'insufficient' のいずれかに分類した 1 つのスナップショットとして返します。同期的で、 ユーザーの最新の入力を含みます。しきい値は読み込まれたモデルのみから来ます。 ヒューマンスコアリングを参照してください。

例外: 読み込まれたモデルにボットのしきい値がない場合、ThresholdMissing(modelVersion 付き)を 投げます。

sufficiency

sufficiency(): Sufficiency | null

これまでに収集された証拠。スコアリングエンジンが動作していない間(読み込み中、読み込み失敗、同意待ち) は null です。

model

model(): ModelState

使用中のスコアリングモデル: { version, source }。version はパッケージに組み込まれたモデルでは 0 です。source は 'embedded'、'cache'(以前の訪問でダウンロード)、'network'(このセッションで ダウンロード)のいずれかです。modelUpdates を参照してください。

checkForModel

checkForModel(options?: { force?: boolean }): Promise<ModelState>

ready() を待ち、SDK が毎回の init で実行するモデル確認に合流し(まだ実行されていなければ実行し)、 確認が終わった時点で使用中のモデルで解決します。{ force: true } の場合は DEA に再度問い合わせますが、その時点で確認が進行中なら二重に問い合わせず、その確認に合流します。 modelUpdates: false の場合は何も問い合わせません。

pause

pause(): void

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

resume

resume(): void

pause() の後に記録を再開します。同意ゲートは開きません。

get consent(): Consent

ユーザーの回答: decision('unknown'、'granted'、'denied')、isAnswered、isGranted。init 時に ブラウザーから復元されます。

setConsent

setConsent(granted: boolean, options?: { remember?: boolean }): void

回答を記録します。requireConsent: true の場合、true で記録が始まり、false で止まります。 { remember: false } は回答をこのページの間だけ保持します。 ユーザー同意を参照してください。

captureEvent

captureEvent(name: string, data?: Readonly<Record<string, unknown>>): boolean
パラメーター 型 説明
name string 1〜64 文字
data Record<string, unknown> 省略可。JSON で最大 1024 バイト

戻り値: 記録されたとき true。一時停止中、同意待ち、破棄後、または名前が不正な場合は false。 カスタムイベントを参照してください。

reset

reset(): void

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

getSessionInfo

getSessionInfo(): SessionInfo

現在のセッション ID、端末、モーションセンサーへのアクセス、SDK バージョン。

attest

attest(): Promise<Attestation>

ブラウザーのキーを DEA に登録します。期限の 60 秒前までキャッシュされます。決して例外を投げません。 SDK が自ら呼ぶことはありません。アテステーションを参照してください。

ads

get ads(): AdModule

広告検証モジュール。広告を参照してください。

dispose

dispose(): void

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

AdModule

session_opened

session_opened(surface?: Element | (() => Rect | null), adUnit?: string): Promise<AdSession | null>

広告が画面に表示されました。インプレッションに署名して送信し、DEA のサービスが開いた広告セッションで 解決します。開けなかった場合は null で、分類が 'insufficient' の間は常にそうなります。その場合 インプレッションは記録されません。surface は広告が描画される要素、またはそのビューポートピクセルでの 矩形を返す関数です。 広告セッションが開かなかった理由を調べるを 参照してください。

counts

readonly counts: AdCounts

証明の 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' のいずれかです。