📦 集成安装

本文档介绍如何在 Flutter 项目中集成 GroMore 广告插件。

1. 添加依赖

在你的 pubspec.yaml 文件中添加插件依赖：

dependencies:
  gromore_ads:
    path: ../path/to/gromore_ads  # 或者从pub.dev添加

2. 安装依赖

flutter pub get

3. Android 配置

3.1 Gradle 配置

3.1.1 配置项目级 build.gradle

在 android/build.gradle 中添加穿山甲 Maven 仓库：

allprojects {
    repositories {
        google()
        mavenCentral()
        // ⚠️ 必需：穿山甲融合SDK仓库
        maven { url 'https://artifact.bytedance.com/repository/pangle' }
    }
}

重要提示: 如果不添加此 Maven 仓库，编译时会报错 Could not find com.pangle.cn:mediation-sdk:x.x.x.x

3.1.2 配置应用级 build.gradle

在 android/app/build.gradle 中添加必要的配置：

android {
    compileSdkVersion 33
    defaultConfig {
        minSdkVersion 24  // GroMore SDK 要求最低 Android 7.0 (API 24)
        targetSdkVersion 33
    }
}

dependencies {
    // GroMore广告SDK依赖会自动添加
}

3.2 权限配置

在 android/app/src/main/AndroidManifest.xml 中添加权限：

<!-- 必需权限 -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- 建议权限（用于提升广告效果和防作弊） -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<!-- Android 特有权限 -->
<permission
    android:name="${applicationId}.openadsdk.permission.TT_PANGOLIN"
    android:protectionLevel="signature" />
<uses-permission android:name="${applicationId}.openadsdk.permission.TT_PANGOLIN" />

4. iOS 配置

4.1 配置 Podfile

⚠️ 重要：添加 CocoaPods 源

在 ios/Podfile 文件中添加官方 CocoaPods 源（如果项目中未配置）：

# ⚠️ 必需：添加 CocoaPods 官方源
source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '10.0'

target 'Runner' do
  use_frameworks!
  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
end

4.2 配置 Info.plist

在 ios/Runner/Info.plist 中添加必要的权限描述：

<dict>
    <!-- 广告标识符权限描述（iOS 14+ 必需） -->
    <key>NSUserTrackingUsageDescription</key>
    <string>该标识符将用于向您推送个性化广告</string>
    
    <!-- SKAdNetwork 配置（用于广告归因） -->
    <key>SKAdNetworkItems</key>
    <array>
        <dict>
            <key>SKAdNetworkIdentifier</key>
            <string>238da6jt44.skadnetwork</string>
        </dict>
        <dict>
            <key>SKAdNetworkIdentifier</key>
            <string>x2jnk7ly8j.skadnetwork</string>
        </dict>
    </array>
    
    <!-- 网络权限 -->
    <key>NSAppTransportSecurity</key>
    <dict>
        <key>NSAllowsArbitraryLoads</key>
        <true/>
    </dict>
</dict>

5. 环境要求

确保您的开发环境满足以下要求：

Flutter: >=3.3.0
Dart: ^3.9.0
Android: minSdkVersion 24
iOS: iOS 10.0+

6. 验证安装

安装完成后，您可以在代码中导入插件来验证安装是否成功：

import 'package:gromore_ads/gromore_ads.dart';

如果导入没有报错，说明插件安装成功。

下一步

⚡ 快速开始 - 学习如何初始化 SDK 和基本使用方法
📊 事件处理 - 了解如何处理广告事件

💡 提示: 如果在安装过程中遇到问题，请查看最佳实践文档。