# ADS_DEMO

**Repository Path**: jooan-android/ads_-demo

## Basic Information

- **Project Name**: ADS_DEMO
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-15
- **Last Updated**: 2026-04-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Android喵眼ADX SDK  演示项目

本项目是Android喵眼ADX SDK V1.0.2的集成演示应用，展示了如何集成和使用喵眼ADX SDK进行广告展示。

## 项目简介

喵眼ADX SDK V1.0.2是一个聚合广告SDK，支持多种广告形式，包括开屏广告、插屏广告和信息流广告。本演示项目展示了SDK的完整集成流程和使用方法。

**注意**: 详细的SDK接口文档请参考项目根目录下的 `Android喵眼ADX SDK_V1.0.2接口文档.docx`。

## 技术栈

- **开发语言**: Kotlin
- **最低支持版本**: Android 5.0 (API 21)
- **目标版本**: Android 14 (API 34)
- **编译版本**: Android 14 (API 34)
- **构建工具**: Gradle 7.3.1
- **Kotlin版本**: 1.9.0

## 项目结构

```
ads_-demo/
├── app/
│   ├── libs/                          # 第三方SDK库文件
│   │   ├── Baidu_MobAds_SDK.aar      # 百度广告SDK
│   │   ├── GDTSDK.aar                # 广点通SDK
│   │   ├── kssdk-ad.aar              # 快手广告SDK
│   │   ├── myads-release.aar         # 喵眼ADX SDK核心库
│   │   ├── jad_yun_sdk.aar           # 广告适配器
│   │   └── base_core.aar             # 基础核心库
│   ├── src/main/
│   │   ├── java/com/jooan/sdkdemo/
│   │   │   ├── DemoApplication.kt    # Application，SDK初始化入口
│   │   │   ├── LaunchActivity.kt     # 启动页，展示冷启动广告
│   │   │   ├── MainActivity.kt       # 主界面，展示插屏和信息流广告
│   │   │   └── HotStartActivity.kt   # 热启动广告页
│   │   ├── res/                      # 资源文件
│   │   └── AndroidManifest.xml
│   └── build.gradle
├── build.gradle
├── settings.gradle
└── gradle.properties
```

## 快速开始

### 1. 环境要求

- Android Studio Hedgehog 或更高版本
- JDK 8 或更高版本
- Android SDK (API 21+)
- Gradle 7.3.1+

### 2. 导入项目

1. 使用Android Studio打开项目
2. 等待Gradle同步完成
3. 确保所有依赖库已正确下载

### 3. 配置SDK参数

在 `DemoApplication.kt` 中配置SDK参数：

```kotlin
private var appId = "145592117684179156"              // App ID，由乔安提供
private var positionId = "145592423043592208"         // 广告位ID
private var feedAdId = "231871280234655750"           // 信息流广告ID
private var interstitialAdId = "231871215810146458"   // 插屏广告ID
private var userId = "795baa058a6932f5b3ee39a0472dfca2" // 用户ID
```

### 4. 运行项目

连接Android设备或启动模拟器，运行项目即可看到广告演示效果。

## SDK集成指南

### 1. SDK初始化

在 `Application` 的 `onCreate()` 方法中进行SDK初始化：

```kotlin
override fun onCreate() {
    super.onCreate()
    
    // 配置参数（可选）
    MyAdConfig.getInstance()
        .setUserId(userId)                    // 设置用户ID
        .setPackageName(packageName)          // 设置包名
            .setVersionName("1.0.2")              // 设置版本号
        .setAppId(appId)                      // 设置App ID
        .setExt(mapOf("key" to "value"))      // 可选额外参数
        .setMillisInFuture(5000)               // 广告倒计时时间（毫秒），默认5000
        .setGlobalAdsWaitTime(5000)           // 全局广告等待时间（毫秒），默认5000
        .setLogOpen(true)                     // 是否开启日志，默认false
        .setTestEnv(false)                    // 是否测试环境，默认false
    
    // 初始化广告服务
    // 注意：必须在用户同意隐私协议后再初始化
    MYAdsManager.getInstance().init(
        this, 
        appId, 
        positionId, 
        userId, 
        feedAdId, 
        interstitialAdId
    )
}
```

### 2. 广告类型

SDK V1.0.2支持三种广告类型：

- **开屏广告 (SPLASH)**: `MyAdsConstant.AD_TYPE_SPLASH` - 应用启动时展示的全屏广告
- **插屏广告 (INTERSTITIAL)**: `MyAdsConstant.AD_TYPE_INTERSTITIAL` - 在应用内容之间展示的全屏广告
- **信息流广告 (FEED)**: `MyAdsConstant.AD_TYPE_FEED` - 在信息流中展示的原生广告

### 3. 启动和加载广告

#### 3.1 启动广告服务

```kotlin
MYAdsManager.getInstance().startWithAdType(
    this,                                    // Activity上下文
    object : MyAdStartListener {
        override fun adStartSuccess() {
            // 启动成功，开始加载广告
            MYAdsManager.getInstance().loadAd()
        }
        
        override fun adStartFail(error: String) {
            // 启动失败处理
            println("启动失败: $error")
        }
    },
    adActionCallback,                        // 广告事件回调
    MyAdsConstant.AD_TYPE_SPLASH,           // 广告类型
    null                                     // 广告尺寸（可选，可为null）
)
```

**参数说明：**
- `activity`: Activity上下文，必须传入
- `startListener`: 启动监听器，用于监听启动成功或失败
- `adListener`: 广告事件监听器，用于监听广告的完整生命周期
- `adType`: 广告类型，使用`MyAdsConstant`常量
- `adSize`: 广告尺寸，可选参数，可为`null`。如需指定尺寸，使用`AdSize(width, height)`

#### 3.2 广告事件监听

实现 `MyAdsAdListener` 接口监听广告事件：

```kotlin
val adActionCallback = object : MyAdsAdListener {
    override fun onStartLoadAd() {
        // 开始加载广告
    }

    override fun onLoadAdFailed(result: MyAdResult) {
        // 加载失败
        // result.code: 错误码
        // result.msg: 错误信息
    }

    override fun onLoadAdSuccess(adType: Int) {
        // 加载成功
    }

    override fun onRenderAdSuccess(adType: Int) {
        // 渲染成功，展示广告
        when (adType) {
            MyAdsConstant.AD_TYPE_SPLASH -> {
                // 展示开屏广告
                val bottomView = LayoutInflater.from(this)
                    .inflate(R.layout.layout_bottom_view, null) as ViewGroup
                MYAdsManager.getInstance().showSplashAd(flAd, bottomView)
            }
            MyAdsConstant.AD_TYPE_INTERSTITIAL -> {
                // 展示插屏广告
                MYAdsManager.getInstance().showInterstitialAd()
            }
            MyAdsConstant.AD_TYPE_FEED -> {
                // 展示信息流广告
                MYAdsManager.getInstance().showFeedAd(feedFrame)
            }
        }
    }

    override fun onAdExposed() {
        // 广告曝光
    }

    override fun onAdClick() {
        // 广告点击
    }

    override fun onAdSkip() {
        // 广告跳过
    }

    override fun onAdFinished(closeType: Int) {
        // 广告关闭
        // closeType 关闭类型：
        // - MyAdsConstant.AD_CLOSE_TYPE_USER_SKIP(1): 用户点击跳过关闭
        // - MyAdsConstant.AD_CLOSE_TYPE_AD_PROVIDER(2): 广告商主动关闭
        // - MyAdsConstant.AD_CLOSE_TYPE_TIMEOUT(3): 广告超时关闭（倒计时结束）
        when (closeType) {
            MyAdsConstant.AD_CLOSE_TYPE_USER_SKIP -> {
                // 用户跳过
            }
            MyAdsConstant.AD_CLOSE_TYPE_AD_PROVIDER -> {
                // 广告商关闭
            }
            MyAdsConstant.AD_CLOSE_TYPE_TIMEOUT -> {
                // 超时关闭
            }
        }
    }

    override fun unKnownError(msg: String) {
        // 未知错误
    }
}
```

### 4. 开屏广告集成

#### 4.1 冷启动广告

在 `LaunchActivity` 中实现冷启动广告：

```kotlin
class LaunchActivity : AppCompatActivity() {
    private var flAd: FrameLayout? = null
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_launch)
        flAd = findViewById(R.id.fl_ad)
        
        // 启动广告服务
        MYAdsManager.getInstance().startWithAdType(
            this,
            object : MyAdStartListener {
                override fun adStartSuccess() {
                    // 启动成功，开始加载广告
                    MYAdsManager.getInstance().loadAd()
                }
                
                override fun adStartFail(error: String) {
                    // 启动失败，直接跳转主界面
                    MyAdsLogUtil.e("LaunchActivity", "启动失败: $error")
                    toMainActivity()
                }
            },
            adActionCallback,
            MyAdsConstant.AD_TYPE_SPLASH,
            null  // 开屏广告通常使用全屏，尺寸参数可为null
        )
    }
    
    // 处理触摸事件（用于点击统计）
    // 开屏广告需要记录用户的触摸事件，用于统计点击行为
    override fun onTouchEvent(event: MotionEvent?): Boolean {
        try {
            when (event?.action) {
                MotionEvent.ACTION_DOWN -> {
                    // 记录按下事件
                    MYAdsManager.getInstance().setDownMillis(System.currentTimeMillis())
                    MYAdsManager.getInstance().setDownX(event.x)
                    MYAdsManager.getInstance().setDownY(event.y)
                }
                MotionEvent.ACTION_UP -> {
                    // 记录抬起事件
                    MYAdsManager.getInstance().setUpX(event.x)
                    MYAdsManager.getInstance().setUpY(event.y)
                    MYAdsManager.getInstance().setUpMillis(System.currentTimeMillis())
                }
            }
        } catch (ignored: Exception) {
            // 异常处理
        }
        return super.onTouchEvent(event)
    }
    
    private fun toMainActivity() {
        startActivity(Intent(this, MainActivity::class.java))
        finish()
    }
}
```

#### 4.2 热启动广告

在 `HotStartActivity` 中实现热启动广告，使用方式与冷启动广告一致。热启动广告的频率由开发者自行控制，SDK内部不做限制。

在 `Application` 中监听应用前后台切换：

```kotlin
class DemoApplication : Application(), Application.ActivityLifecycleCallbacks {
    
    private var countActivity = 0
    private var appInForeground = true // 是否在前台
    
    override fun onCreate() {
        super.onCreate()
        registerActivityLifecycleCallbacks(this)
        // ... SDK初始化代码 ...
    }
    
    override fun onActivityStarted(activity: Activity) {
        countActivity++
        if (countActivity == 1) {
            MyAdsLogUtil.i(TAG, "进入前台")
            if (!appInForeground) {
                // 应用从后台回到前台，展示热启动广告
                // 注意：需要确保用户已同意隐私协议
                activity.startActivity(Intent(activity, HotStartActivity::class.java))
            }
            appInForeground = true
        }
    }
    
    override fun onActivityStopped(activity: Activity) {
        countActivity--
        if (countActivity <= 0) {
            appInForeground = false
            MyAdsLogUtil.i(TAG, "进入后台")
        }
    }
}
```

### 5. 插屏广告集成

插屏广告是全屏展示的广告，通常在用户完成某个操作后展示。

**完整示例：**

```kotlin
findViewById<CardView>(R.id.ad_interstitial).setOnClickListener {
    // 开始启动广告服务
    MYAdsManager.getInstance().startWithAdType(
        this,
        object : MyAdStartListener {
            override fun adStartSuccess() {
                // 启动成功，开始加载广告
                MYAdsManager.getInstance().loadAd()
            }
            
            override fun adStartFail(error: String) {
                // 启动失败处理
                MyAdsLogUtil.e("MainActivity", "启动失败: $error")
            }
        },
        adActionCallback,
        MyAdsConstant.AD_TYPE_INTERSTITIAL,
        null  // 插屏广告全屏展示，尺寸参数可为null
    )
}

// 在onRenderAdSuccess回调中展示广告
override fun onRenderAdSuccess(adType: Int) {
    if (adType == MyAdsConstant.AD_TYPE_INTERSTITIAL) {
        // 展示插屏广告
        MYAdsManager.getInstance().showInterstitialAd()
    }
}
```

### 6. 信息流广告集成

信息流广告需要提供一个容器View来展示广告内容。

**完整示例：**

```kotlin
private var feedFrame: FrameLayout? = null

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)
    
    feedFrame = findViewById(R.id.feed_layout)
    
    findViewById<CardView>(R.id.ad_feed).setOnClickListener {
        // 开始启动广告服务
        MYAdsManager.getInstance().startWithAdType(
            this,
            object : MyAdStartListener {
                override fun adStartSuccess() {
                    // 启动成功，开始加载广告
                    MYAdsManager.getInstance().loadAd()
                }
                
                override fun adStartFail(error: String) {
                    // 启动失败处理
                    MyAdsLogUtil.e("MainActivity", "启动失败: $error")
                }
            },
            adActionCallback,
            MyAdsConstant.AD_TYPE_FEED,
            null  // 信息流广告尺寸参数可为null，或使用AdSize(width, height)指定
        )
    }
}

// 在onRenderAdSuccess回调中展示广告
override fun onRenderAdSuccess(adType: Int) {
    if (adType == MyAdsConstant.AD_TYPE_FEED) {
        // feedFrame 是广告展示的容器，必须传入
        MYAdsManager.getInstance().showFeedAd(feedFrame)
    }
}
```

### 7. SDK销毁

在 `Application` 的 `onTerminate()` 中销毁SDK：

```kotlin
override fun onTerminate() {
    super.onTerminate()
    MYAdsManager.getInstance().destroy()
}
```

## 配置说明

### MyAdConfig 配置项

| 方法 | 说明 | 默认值 | 必填 |
|------|------|--------|------|
| `setUserId(userId)` | 设置用户ID | - | 是 |
| `setPackageName(packageName)` | 设置包名 | - | 是 |
| `setVersionName(versionName)` | 设置版本号 | - | 否 |
| `setAppId(appId)` | 设置App ID | - | 是 |
| `setExt(ext)` | 设置额外参数 | - | 否 |
| `setMillisInFuture(millis)` | 广告倒计时时间（毫秒） | 5000 | 否 |
| `setGlobalAdsWaitTime(millis)` | 全局广告等待时间（毫秒） | 5000 | 否 |
| `setLogOpen(open)` | 是否开启日志 | false | 否 |
| `setTestEnv(testEnv)` | 是否测试环境 | false | 否 |

### 广告尺寸

使用 `AdSize(width, height)` 设置广告尺寸，单位为dp。该参数在`startWithAdType()`方法中为可选参数，可为`null`：

```kotlin
// 方式1：不指定尺寸（推荐）
MYAdsManager.getInstance().startWithAdType(
    this, startListener, adListener, adType, null
)

// 方式2：指定尺寸
MYAdsManager.getInstance().startWithAdType(
    this, startListener, adListener, adType, AdSize(320, 50)
)
```

**常用广告尺寸：**
- 横幅广告：`AdSize(320, 50)` - 标准横幅尺寸
- 开屏广告：通常使用全屏，尺寸参数可为`null`（推荐）
- 插屏广告：全屏展示，尺寸参数可为`null`（推荐）
- 信息流广告：根据实际需求设置，如`AdSize(320, 250)`，或使用`null`由SDK自动适配（推荐）

## 注意事项

### V1.0.2版本重要提示

1. **隐私协议**: 必须在用户同意隐私协议后再初始化SDK，这是合规要求
2. **初始化时机**: SDK初始化应在 `Application.onCreate()` 中进行，且只初始化一次
3. **生命周期管理**: 在 `Application.onTerminate()` 中调用 `destroy()` 销毁SDK，释放资源
4. **开屏广告底部视图**: 开屏广告可以自定义底部视图（bottomView），用于展示APP名称、广告说明等信息，建议设置合理高度（如100dp）
5. **热启动广告频率**: 热启动广告的频率由开发者自行控制，SDK内部不做限制，建议根据业务需求合理控制展示频率
6. **触摸事件记录**: 开屏广告需要记录触摸事件（`onTouchEvent`），用于统计点击行为，必须实现
7. **广告尺寸参数**: `startWithAdType()`方法的`adSize`参数为可选，可为`null`。开屏和插屏广告通常使用全屏，无需指定尺寸
8. **错误处理**: 所有回调方法都应实现，特别是错误处理（`onLoadAdFailed`、`unKnownError`），避免应用崩溃
9. **网络权限**: 确保在 `AndroidManifest.xml` 中配置了网络权限（`INTERNET`、`ACCESS_NETWORK_STATE`）
10. **日志调试**: 开发调试时建议开启日志（`setLogOpen(true)`），生产环境建议关闭（`setLogOpen(false)`）
11. **混淆配置**: Release版本建议启用ProGuard，相关规则在 `proguard-rules.pro` 中配置
12. **全局广告等待时间**: `setGlobalAdsWaitTime()` 设置全局广告等待时间，若服务器也下发了全局超时时间，则此项不生效
13. **测试环境**: 开发阶段可使用 `setTestEnv(true)` 开启测试环境，生产环境务必设置为 `false`
14. **广告容器**: 信息流广告必须提供有效的容器View（FrameLayout），且建议全屏展示
15. **回调顺序**: 广告加载流程为：`onStartLoadAd()` → `onLoadAdSuccess()` → `onRenderAdSuccess()` → `onAdExposed()`

## 依赖库

### 核心依赖

- AndroidX AppCompat: 1.4.1
- Kotlin Coroutines: 1.6.0
- Material Design: 1.9.0

### 网络库

- OkHttp: 3.14.9
- Retrofit: 2.9.0
- RxJava2: 2.0.1

### 其他依赖

- Glide: 4.11.0 (图片加载)
- 腾讯云CLS SDK: 1.0.13 (日志服务)
- OAID SDK: 4.2.16 (设备标识)
- 穿山甲融合SDK: 5.8.0.7

完整依赖列表请查看 `app/build.gradle` 文件。

## 构建说明

### Debug构建

```bash
./gradlew assembleDebug
```

生成的APK位于：`app/build/outputs/apk/debug/SDKDemo.apk`

### Release构建

```bash
./gradlew assembleRelease
```

生成的APK位于：`app/build/outputs/apk/release/SDKDemo.apk`

## 常见问题

### Q: 广告加载失败怎么办？

A: 检查以下几点：
- 网络连接是否正常
- App ID、广告位ID是否正确配置
- SDK初始化是否成功
- 查看日志输出获取详细错误信息（开启日志：`setLogOpen(true)`）

### Q: 如何开启测试环境？

A: 在初始化时设置：
```kotlin
MyAdConfig.getInstance().setTestEnv(true)
```

### Q: 如何自定义广告倒计时时间？

A: 在初始化时设置：
```kotlin
MyAdConfig.getInstance().setMillisInFuture(3000) // 3秒
```

### Q: 热启动广告什么时候展示？

A: 当应用从后台回到前台时会触发热启动广告，具体时机在 `Application.onActivityStarted()` 中控制。

## 代码示例参考

完整的代码示例请参考项目中的以下文件：

- **`DemoApplication.kt`** - SDK初始化和生命周期管理，热启动广告触发逻辑
- **`LaunchActivity.kt`** - 冷启动广告完整实现，包含触摸事件处理
- **`HotStartActivity.kt`** - 热启动广告完整实现
- **`MainActivity.kt`** - 插屏广告和信息流广告完整实现

## 接口文档

详细的SDK接口文档请参考：

- **`Android喵眼ADX SDK_V1.0.2接口文档.docx`** - 官方SDK V1.0.2接口文档

## 技术支持

如有问题或建议，请联系乔安技术支持团队。

## 许可证

本项目仅供学习和演示使用。

---

## 版本信息

- **SDK版本**: V1.0.2
- **文档版本**: V1.0.2
- **最后更新**: 2026-01-28

**注意**: 本演示项目展示了喵眼ADX SDK V1.0.2的基本使用方法，实际使用时请根据业务需求进行调整，并参考最新的SDK接口文档（`Android喵眼ADX SDK_V1.0.2接口文档.docx`）。所有代码示例均基于项目实际代码，可直接参考使用。