# DeviceSdk

**Repository Path**: niumenglin/device-sdk

## Basic Information

- **Project Name**: DeviceSdk
- **Description**: 设备标识获取 SDK，基于友盟统计实现 OAID 获取，提供合规稳定的设备唯一标识解决方案。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-27
- **Last Updated**: 2026-04-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DeviceSdk

设备标识获取 SDK，基于友盟统计实现 OAID 获取，提供合规稳定的设备唯一标识解决方案。

## 特性

- **OAID 优先**：优先获取移动安全联盟提供的 OAID（不获取 IMEI 等敏感权限）
- **合规稳定**：OAID 不可用时自动降级为基于 AndroidID 生成的稳定 ID
- **卸载重装不变**：稳定 ID 通过 SP 持久化，卸载重装后保持一致
- **线程安全**：采用 AtomicReference 保证并发安全
- **初始化友好**：同步获取设备 ID，不阻塞调用线程

## 集成步骤

### 1. 添加 Maven 仓库

确保 `settings.gradle.kts` 包含必要仓库：

```kotlin
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}
```

### 2. 添加依赖

在模块的 `build.gradle.kts` 中添加：

```kotlin
dependencies {
    implementation("com.niu.device:device-sdk:1.0.0")
}
```

或使用 version catalog（推荐）：

```kotlin
dependencies {
    implementation(libs.deviceSdk)
}
```

### 3. 配置 AndroidManifest

获取 OAID **无需声明任何权限**（友盟 ASMS SDK 已内置权限处理）。

### 4. 初始化 SDK

在 `Application` 子类的 `onCreate()` 中初始化：

```kotlin
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        DeviceSdk.init(this, "友盟AppKey", "渠道名称")
    }
}
```

并在 `AndroidManifest.xml` 中注册：

```xml
<application
    android:name=".MyApplication"
    ...>
</application>
```

## 使用示例

### Kotlin

```kotlin
// 获取设备唯一标识
val deviceId = DeviceSdk.getDeviceId()

// 获取 OAID（可能为空）
val oaid = DeviceSdk.getOaid()

// 检查是否已初始化
val isReady = DeviceSdk.isInitialized

// 异步获取（适合 UI 线程）
DeviceSdk.getDeviceIdAsync { deviceId ->
    Log.d("Device", "设备ID: $deviceId")
}
```

### Java

```java
String deviceId = DeviceSdk.INSTANCE.getDeviceId();
String oaid = DeviceSdk.INSTANCE.getOaid();
boolean isReady = DeviceSdk.INSTANCE.isInitialized();
```

## API 文档

### init()

```
fun init(context: Context, umengAppKey: String, channel: String = "default")
```

全局初始化，推荐在 Application.onCreate() 中调用。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| context | Context | 是 | 应用上下文，会自动转换为 applicationContext |
| umengAppKey | String | 是 | 友盟 AppKey |
| channel | String | 否 | 渠道标识，默认为 "default" |

### getDeviceId()

```
fun getDeviceId(): String
```

获取设备唯一标识。优先返回 OAID，不可 用时返回稳定 ID。

**注意**：调用前必须先调用 `init()`。

### getOaid()

```
fun getOaid(): String?
```

获取 OAID。可能返回 null（设备不支持或获取失败）。

### isInitialized

```
val isInitialized: Boolean
```

检查 SDK 是否已初始化。

### getDeviceIdAsync()

```
fun getDeviceIdAsync(callback: (String) -> Unit)
```

异步获取设备标识，推荐在 UI 线程中使用。

## 设备标识策略

```
                    ┌──────────────────────┐
                    │   获取设备唯一标识     │
                    └──────────┬───────────┘
                               ▼
                    ┌──────────────────────┐
                    │      尝试获取 OAID     │
                    └──────────┬───────────┘
                               ▼
                    ┌──────────────────────┐
                    │      OAID 可用？       │
                    └──┬───────────────┬────┘
                       ▼               ▼
                   ┌──────┐    ┌──────────────┐
                   │ 返回  │    │ AndroidID有效?│
                   │ OAID │    └──┬─────────┬───┘
                   └──────┘        ▼         ▼
                             ┌────────┐  ┌───────┐
                             │ 生成   │  │ 随机   │
                             │ UUID   │  │ UUID  │
                             └───┬────┘  └───┬───┘
                                 ▼           ▼
                         ┌──────────────────────┐
                         │    SP 持久化存储      │
                         └──────────┬───────────┘
                                    ▼
                         ┌──────────────────────┐
                         │      返回设备 ID      │
                         └──────────────────────┘
```

## 注意事项

### 1. 初始化时机

`init()` 必须在其他方法之前调用，建议在 Application.onCreate() 中执行。

### 2. 友盟 AppKey

必须配置有效的友盟 AppKey，否则 OAID 获取会失败。

### 3. OAID 获取

- OAID 依赖设备厂商支持，不保证所有设备都能获取
- 首次获取可能需要 1-2 秒
- 获取失败会自动降级到稳定 ID

### 4. 权限说明

**无需声明任何权限**，SDK 不申请敏感权限，符合合规要求。

### 5. 混淆配置

如需混淆，请添加以下规则：

```proguard
# 友盟 SDK
-keep class com.umeng.** { *; }
-keep class com.uc.** { *; }
```

## 依赖说明

- `com.umeng.umsdk:common` - 友盟公共库
- `com.umeng.umsdk:asms` - 设备标识获取库

## 版本说明

### v1.0.0
- 初始版本
- 支持 OAID 获取
- 支持稳定 ID 降级
- 线程安全实现

## License

```
Copyright 2024

Licensed under the Apache License, Version 2.0
```