接入文档

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

gpr.user=YOUR_GITHUB_USERNAME
gpr.key=YOUR_GITHUB_PACKAGES_TOKEN

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") }
        }
    }
}

import android.content.Context
import com.remax.riskcontrol.sdk.Status
import com.remax.riskcontrol.sdk.client.*
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob

class AppRisk(
    context: Context,
    baseUrl: String,
    bundleId: String,
    appSecret: String,
    debugEnabled: Boolean,
    parameters: suspend (String) -> LoginParameters,
    onSession: (RiskSession) -> Unit = {},
) {
    private val appContext = context.applicationContext
    private val applicationScope = CoroutineScope(SupervisorJob() + Dispatchers.IO)

    val client = RiskClient(
        context = appContext,
        config = RiskClientConfig(
            baseUrl = baseUrl,
            bundleId = bundleId,
            appSecret = appSecret,
            debug = RiskDebugConfig(enabled = debugEnabled, tag = "CoreModule"),
            persistSession = true,
        ),
        loginParameters = parameters,
        deviceRisk = { collectDeviceRisk(appContext).withShortDramaUnknownPolicy() },
        onSession = onSession,
    )
    // 默认持久化；创建后自动恢复旧事件。
    val reports = ReportQueue(client, applicationScope)
}

// 这是业务策略，不是 SDK 默认行为。
private fun DeviceRisk.withShortDramaUnknownPolicy(): DeviceRisk {
    fun Status.resolved() = if (this == Status.UNKNOWN) Status.NOT_DETECTED else this
    return copy(
        root = root.resolved(), adb = adb.resolved(), emulator = emulator.resolved(),
        hook = hook.resolved(), accessibility = accessibility.resolved(), vpn = vpn.resolved(),
    )
}

// parameters 参数示例。countryByScope / stableDeviceId / attributionNetwork
// 来自宿主现有的身份与归因数据；不要每次生成新的 DeviceId。
val loginParameters: suspend (String) -> LoginParameters = { identityScope ->
    LoginParameters(
        deviceId = stableDeviceId,
        country = countryByScope.getValue(identityScope),
        network = attributionNetwork, // 可选：归因渠道
        userAgent = existingUserAgent, // 可选：覆盖 Android 默认值
        // deviceType / deviceVersion / isp / version 不传则使用 Android 默认值
        // gaid / adid 不传则省略
    )
}

// 在宿主协程中获取登录态：内存 → 加密磁盘缓存 → /user/login。
val session = appRisk.client.ensureSession(identityScope)
// session.userId / session.token 提供给业务接口；使用前检查权限和凭据。

// 在真实事件发生时调用，无需先手动登录，也无需自己实现重试。
appRisk.reports.report(identityScope, ReportEventType.CONTENT_START)
appRisk.reports.report(identityScope, ReportEventType.OPEN_PAYOUT_PAGE)

// 开发工具可在协程内等待本次事件结果；普通页面无需等待。
val receipt = appRisk.reports.report(identityScope, ReportEventType.CONTENT_COMPLETE)
receipt.await()

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

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

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

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

// 1. 省略 deviceRisk：默认 collectDeviceRisk(applicationContext)。
//    若检测结果包含 UNKNOWN，直接序列化会失败，需要业务明确处理策略。

// 2. 自定义采集 / 映射（短剧例子见快速接入）。
// deviceRisk = { collectDeviceRisk(applicationContext).withShortDramaUnknownPolicy() }

// 3. 明确不发送 RiskStat。
// deviceRisk = null
// 或 deviceRisk = { null }

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/report headers=
{ ... } body=
{
  "EventType": 4,
  "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

// 显式纯内存：进程结束即丢失，不是默认行为。
val memoryOnly = ReportStore()

// 指定持久化名称；不同环境应使用不同名称。
val persistent = ReportStore.preferences(
    context = applicationContext,
    name = "my_app_risk_events",
    legacyScope = { oldLanguageTag -> scopeByOldLanguageTag[oldLanguageTag] },
)
val reports = ReportQueue(riskClient, applicationScope, store = persistent)

// 自定义串行 JSON 数组读写：read / write 在队列 IO 中执行。
// 不要将无关 JSON 或业务对象作为队列数据写入。
val custom = ReportStore(
    read = { readStoredEventsJson() },
    write = { json -> persistEventsJson(json) },
    legacyScope = { oldLanguageTag -> scopeByOldLanguageTag[oldLanguageTag] },
)