接入文档

能力与入参

左侧查看开放能力，右侧看接入时的数据流向。点击条目查看具体用法。

添加依赖

在 App 模块添加依赖，并配置下方的 GitHub Packages 仓库。

dependencies {
    implementation("com.remax:risk-control:0.1.4")
}

仓库凭据

在用户目录的 ~/.gradle/gradle.properties 配置拥有该仓库 / 包读取权限、包含 read:packages 的 GitHub 令牌；CI 可用同名用途的环境变量。以下均为占位符。

gpr.user=YOUR_GITHUB_USERNAME
gpr.key=YOUR_GITHUB_PACKAGES_TOKEN

Maven 仓库

合并到宿主现有的 dependencyResolutionManagement。仓库凭据只参与 Gradle 下载；SDK 的 appSecret 是另一项业务配置。

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        exclusiveContent {
            forRepository {
                maven {
                    url = uri("https://maven.pkg.github.com/toukaremax/risk-control")
                    credentials {
                        username = providers.gradleProperty("gpr.user")
                            .orElse(providers.environmentVariable("GITHUB_ACTOR")).orNull
                        password = providers.gradleProperty("gpr.key")
                            .orElse(providers.environmentVariable("GITHUB_TOKEN")).orNull
                    }
                }
            }
            filter { includeModule("com.remax", "risk-control") }
        }
    }
}

最简接入

只需提供 Application Context、接口域名、BundleId、应用密钥、稳定设备 ID 和国家。 在 Application 或业务单例中创建一次，后续复用。

import com.remax.riskcontrol.sdk.client.*
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob

val riskClient = RiskClient(
    context = applicationContext,
    config = RiskClientConfig(
        baseUrl = apiBaseUrl,
        bundleId = backendBundleId,
        appSecret = backendAppSecret,
    ),
    loginParameters = { scope ->
        // 本例用国家代码作为登录态分组，因此 country 取 scope。
        LoginParameters(deviceId = stableDeviceId, country = scope)
    },
)
val applicationScope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
val reports = ReportQueue(riskClient, applicationScope)

型号、系统版本、运营商、UA、应用版本和 RiskStat 由 SDK 默认采集；登录态和事件队列默认持久化。 gaid / adid / network 由业务按需提供，不传则省略。

0.1.2 已默认将 UNKNOWN 按未发现上报，无需额外兼容回调。 见 RiskStat 的版本说明。

// 登录态分组名，由业务必传；本例按国家分组，设备身份固定。
val identityScope = "USA"

// 在业务协程中获取登录态，有缓存时直接复用。
val session = riskClient.ensureSession(identityScope)
// session.userId / session.token 供业务接口使用；使用前检查 canLogin 和凭据。

// 在真实事件发生时调用；SDK 自动登录、持久化和重试，无需等待回执。
reports.report(identityScope, ReportEventType.CONTENT_START)
reports.report(identityScope, ReportEventType.OPEN_PAYOUT_PAGE)

按需覆盖：业务已有的设备或归因值可直接传入 LoginParameters； 日志、会话通知、风险策略和网络配置均为可选项，见 配置参考。

登录态分组：登录参数叫 scope，上报参数叫 identityScope，含义相同。 同组复用登录态，不同组隔离；分组名是 SDK 内部标识，不作为接口字段发送。 单一身份可固定传 "default"，此时 loginParameters 应独立提供真实的国家代码，不能把 default 当作 country。 按国家区分时可用 "USA" / "BRA" / "IDN"；多账号还需包含账号标识。 分组名必须稳定、非空，切换身份时换组，并让 loginParameters(scope) 能根据分组返回对应的设备 ID 和国家，包括积压事件的旧分组。

创建 RiskClient 本身不登录；队列恢复积压事件时可能触发登录。队列使用 Application 生命周期。

登录态与风控

ensureSession 表示确保有可复用结果；有缓存时不会重新请求登录。

先查找内存会话；未命中时尝试恢复磁盘缓存，仍未命中才请求登录。恢复缓存或取得新登录结果后，触发 onSession。

RiskSession 返回值

SDK 不调用广告库、不弹 Toast、不关闭应用，也不代替业务判断提现。是否上报以是否有完整凭据为准；等级 1 / 2 仍可上报。等级 3 无 Token 时失败结束，不循环登录。

业务接口如何无感刷新

SDK 自动处理自己的 report 会话失效。提现等宿主接口继续由现有拦截逻辑识别失效，并调用以下公共函数：

// failedSession 必须是这次失败请求实际使用的会话对象。
riskClient.invalidateSession(identityScope, failedSession)
val refreshed = riskClient.ensureSession(identityScope)
// 由业务决定是否使用 refreshed 重发该业务请求，并限制恢复次数。
// 不要将所有业务错误都当成 Token 失效。

SDK 的会话失效兼容条件为 Result=201 / 406 或 HTTP 401。单独 HTTP 406 不算；这是当前客户端兼容规则。

事件上报

普通业务全部使用 ReportQueue。SDK 负责登录、签名、持久化、串行发送和失败重试。

// scope 是应用级 CoroutineScope，store 通常省略。
val reports = ReportQueue(client = riskClient, scope = applicationScope)

val receipt: ReportReceipt = reports.report(
    identityScope = identityScope, // 必填：登录态分组，与 ensureSession 的 scope 一致
    type = ReportEventType.AD_COMPLETE,
    value = revenue, // Double；默认 0.0，必须非负且有限
)
// receipt.id 是本地事件 ID；不会作为幂等键发送给后端。
// 在协程中 receipt.await() 等待确认或失败；取消等待不取消事件。

当前不提供广告开始 AD_START / 3。开发工具可以直接调用相同公共队列，模拟内容开始、提现页打开等事件。

{
  "EventType": 5,
  "Value": 0,
  "Timestamp": 1793318400,
  "Retry": 0
}

Timestamp 是入队时记录的事件 UTC Unix 秒，重试保持原值。Retry 首次即传 0；同一事件重发递增。每次请求头 Timestamp / Nonce / Sign 会重新生成。仅登录阶段失败时，尚未发出 report，不增加该事件的 Retry。

riskClient.reportOnce(
    scope = identityScope,
    type = ReportEventType.CONTENT_START,
    value = 0.0,
    timestampSeconds = occurredAtUtcSeconds, // 可省略，默认当前 UTC 秒
)

队列与重试

同一队列按入队顺序发送。网络恢复由定时尝试发现，没有主动注册网络恢复监听。

1. 第一次重试：等待 30 秒。
2. 第二次重试：等待 2 分钟。
3. 第三次重试：等待 5 分钟。
4. 之后每 30 分钟重试一次。

前三档最多追加 20% 随机延迟；之后每 30 分钟一次。与服务端 Retry-After 取较长时间。网络失败与 HTTP 429 共用退避次数。

RiskStat

SDK 默认自动采集并拼接 RiskStat，业务无需实现检测或手动调用采集函数。 原始检测结果区分 DETECTED、NOT_DETECTED 和 UNKNOWN。

自定义策略可通过 deviceRisk 返回调整后的结果；明确状态会按业务值上报。 显式传 deviceRisk = null 或回调返回 null，则省略整个 RiskStat。

// 添加到 RiskClient(...) 参数中；awaitPlayResult 是业务函数。
// PlayInstall 仅为示例字段名，须与后端约定。
riskStatExtras = { scope ->
    val result = kotlinx.coroutines.withTimeoutOrNull(1_000) {
        awaitPlayResult(scope)
    }
    mapOf("PlayInstall" to result)
},

// Status 来自 com.remax.riskcontrol.sdk.Status。
// 添加到 RiskClient(...) 的参数中：
deviceRisk = {
    val observed = collectDeviceRisk(applicationContext)
    fun resolve(value: Status) =
        if (value == Status.UNKNOWN) Status.NOT_DETECTED else value
    observed.copy(
        root = resolve(observed.root), adb = resolve(observed.adb),
        emulator = resolve(observed.emulator), hook = resolve(observed.hook),
        accessibility = resolve(observed.accessibility), vpn = resolve(observed.vpn),
    )
}

collectDeviceRisk(context: Context): DeviceRisk 是挂起函数，内部切换 IO。DeviceRisk.toJson(): JSONObject 将 DETECTED 编码为 0、NOT_DETECTED 编码为 1；UNKNOWN 按上方版本说明处理。 采集只包含登录需要的设备项，不进行完整 APK 扫描，也不请求 Play Integrity Token。

需要独立检测时可用 RiskScanner.scan() 或直接检测函数，详见 设备检测与可选插件指南 ↗。这部分是 SDK 的独立能力。

调试日志

所有 login / report 请求及响应、RiskStat 明细和队列状态，统一使用 RiskClient 的 debug 配置。

从 0.1.4 起，RiskStat 和 EventType 的释义直接拼在请求日志的 JSON 值中， 不再另外输出释义段。字段名不变，原始 UNKNOWN 会注明“未知，按未发现上报”。 业务追加的 RiskStat 字段保留原样。

带释义的字符串仅用于 debug 日志；实际 HTTP 仍发送原协议值和类型，签名不变。例如日志中的 EventType 为“4（CONTENT_START，内容开始）”，实际发送的仍是数字 4。

RiskClientConfig(
    baseUrl = baseUrl,
    bundleId = bundleId,
    appSecret = appSecret,
    debug = RiskDebugConfig(enabled = BuildConfig.DEBUG, tag = "CoreModule"),
)
// 可选：传给 RiskClient 的 diagnostics 参数。
val diagnostics = RiskDiagnostics { tag, message ->
    android.util.Log.d(tag, "MultiCountryPayout: " + message)
}

request /user/login headers=
{ ... } body=
{
  "DeviceId": "example-device",
  "Country": "USA",
  "RiskStat": {
    "NetworkType": "wifi（网络类型）",
    "Timezone": "Asia/Shanghai（时区）",
    "Locale": "en-US（系统语言）",
    "Milan": "1（Root，未发现）",
    "Como": "0（ADB 调试，已检测到）",
    "Lazio": "1（模拟器，未发现）",
    "Roma": "1（Hook，未知，按未发现上报）",
    "Genoa": "1（无障碍服务，未发现）",
    "Verona": "0（VPN，已检测到）"
  }
}
request /user/report headers=
{ ... } body=
{
  "EventType": "4（CONTENT_START，内容开始）",
  "Value": 0,
  "Timestamp": 1793318400,
  "Retry": 0
}
response /user/report http=200 result=0 body=
{
  "Result": 0
}
report_queue ack type=CONTENT_START retry=0
report_queue retry type=CONTENT_START reason=network login_only=false delay_ms=32000

默认 enabled=false，不传 tag 时为 RiskControl。开启后完整打印请求头 / 正文 / 响应，包括 Token、DeviceId、UserId、Sign 等，不脱敏；RiskStat 和 EventType 的日志值附带释义。JSON 两空格缩进，长消息分段编号；不改变实际请求正文和签名。appSecret 本身不是请求字段，不单独输出。

配置参考

可选参数省略时使用默认实现；只覆盖业务已经维护的字段。

RiskClientConfig

RiskClient 构造参数

LoginParameters

Network 是业务归因渠道，RiskStat.NetworkType 是当前设备网络类型，两者含义不同。

辅助 API

标准接入省略 store 即可。仅兼容旧队列或有独立存储需求时覆盖。

ReportStore.preferences(...) 可指定持久化名称并迁移旧 scope； ReportStore(read, write, legacyScope) 可对接业务存储。 显式传入无参数的 ReportStore() 会使用纯内存，普通接入应省略 store。

普通 IOException、参数校验异常也可能返回给调用方；协程取消继续传播。SDK 没有对外提供手动 flush、成功历史查询、重试次数配置或队列清空函数。

更新记录

0.1.4 · 已发布

RiskStat 和 EventType 释义合并到请求日志 JSON 中，移除独立释义段。保留业务扩展字段、debug 开关和自定义 tag；实际 HTTP 请求、协议类型及签名不变。

0.1.3 · 已发布

新增 riskStatExtras 挂起回调，可在默认 RiskStat 中追加业务字段，由业务决定是否等待结果及超时策略；保留原构造函数。report 调试日志补充 EventType 中文释义。能力与入参增加接入示意图。

0.1.2 · 已发布

UNKNOWN 默认按未发现上报，保留原始检测状态和业务自定义能力；login 日志增加 RiskStat 字段释义。接入文档补充最简示例、能力导图和登录态分组说明。

0.1.1 · 已发布

• 统一 HTTP 日志：login / report 的请求、响应和 RiskStat 明细；JSON 格式化，长日志分段。
• 修复主线程发请求：开发工具由 Main 触发事件时，队列显式调度至 IO。
• 持久化网络重试：断网 / 超时保留事件，使用 30 秒 → 2 分钟 → 5 分钟 → 30 分钟退避。
• 恢复未确认事件：重启保留事件时间、Retry 和退避进度，继续尝试未确认的发送。