🛠️ 安装与集成

本指南将帮助您完成穿山甲内容SDK Flutter插件的安装和配置。

前置要求

在开始之前，请确保您的开发环境满足以下要求：

Flutter环境

Flutter SDK: 3.0.0 或更高版本
Dart SDK: 2.17.0 或更高版本

Android配置

最低API级别: Android 5.0 (API level 21)
目标API级别: Android 13 (API level 33) 或更高
Kotlin版本: 1.7.0 或更高

iOS配置

最低部署目标: iOS 11.0
Xcode版本: 13.0 或更高
Swift版本: 5.0 或更高

第一步：添加依赖

1.1 添加插件依赖

在项目根目录的 pubspec.yaml 文件中添加依赖：

dependencies:
  flutter:
    sdk: flutter
  pangrowth_content: ^1.0.0  # 请使用最新版本

1.2 安装依赖

在终端中运行以下命令：

flutter pub get

第二步：Android平台配置

2.1 配置Gradle

修改项目级build.gradle

在 android/build.gradle 文件中配置：

buildscript {
    ext.kotlin_version = '1.8.0'  // 确保Kotlin版本 >= 1.7.0

    repositories {
        google()
        mavenCentral()
    }

    dependencies {
        classpath 'com.android.tools.build:gradle:7.3.0'
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

allprojects {
    repositories {
        google()
        mavenCentral()
        // ⚠️ 必需：穿山甲广告SDK仓库（pangrowth依赖gromore_ads插件）
        maven { url 'https://artifact.bytedance.com/repository/pangle' }
        // ⚠️ 必需：穿山甲内容SDK仓库
        maven { url 'https://artifact.bytedance.com/repository/Volcengine' }
    }
}

修改应用级build.gradle

在 android/app/build.gradle 文件中配置：

android {
    compileSdkVersion 33  // 或更高版本

    defaultConfig {
        applicationId "com.example.yourapp"
        minSdkVersion 21      // 最低API 21
        targetSdkVersion 33   // 目标API 33或更高

        // 添加multiDex支持（如果需要）
        multiDexEnabled true
    }

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }

    kotlinOptions {
        jvmTarget = '1.8'
    }
}

dependencies {
    // 如果启用了multiDex
    implementation 'androidx.multidex:multidex:2.0.1'
}

2.2 配置AndroidManifest.xml

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

<manifest xmlns:android="http://schemas.android.com/apk/res/android">

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

    <!-- 读写存储权限（用于缓存）-->
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

    <application
        android:name=".MainApplication"
        android:label="@string/app_name"
        android:icon="@mipmap/ic_launcher"
        android:usesCleartextTraffic="true"
        android:requestLegacyExternalStorage="true">

        <!-- 您的Activity配置 -->

    </application>
</manifest>

2.3 配置混淆规则

如果您启用了代码混淆，在 android/app/proguard-rules.pro 中添加：

# 保留穿山甲SDK相关类
-keep class com.bytedance.sdk.** { *; }
-keep class com.pgl.sys.ces.* {*;}

# 保留Flutter插件桥接类
-keep class com.zhecent.pangrowth_content.** { *; }

第三步：iOS平台配置

3.1 配置Podfile

⚠️ 重要：添加 CocoaPods 源

由于 pangrowth_content 插件依赖穿山甲内容 SDK，需要在 Podfile 中添加 volcengine-specs 源。

在 ios/Podfile 文件中配置：

# ⚠️ 必需：添加穿山甲 SDK 的 CocoaPods 源
source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/volcengine/volcengine-specs.git'

platform :ios, '11.0'

target 'Runner' do
  use_frameworks!
  use_modular_headers!

  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))

  # 如果遇到编译问题，可以添加以下配置
  post_install do |installer|
    installer.pods_project.targets.each do |target|
      target.build_configurations.each do |config|
        config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '11.0'
      end
    end
  end
end

3.2 安装iOS依赖

在终端中执行：

cd ios
pod install
cd ..

3.3 配置Info.plist

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

<dict>
    <!-- 应用传输安全设置 -->
    <key>NSAppTransportSecurity</key>
    <dict>
        <key>NSAllowsArbitraryLoads</key>
        <true/>
    </dict>

    <!-- 相册访问权限（如果需要保存内容）-->
    <key>NSPhotoLibraryAddUsageDescription</key>
    <string>需要访问相册以保存内容</string>

    <!-- 相机权限（如果需要）-->
    <key>NSCameraUsageDescription</key>
    <string>需要访问相机</string>

    <!-- 麦克风权限（如果需要）-->
    <key>NSMicrophoneUsageDescription</key>
    <string>需要访问麦克风</string>

    <!-- 其他应用配置 -->
</dict>

第四步：准备配置文件

4.1 获取配置文件

从穿山甲平台获取您的SDK配置文件，文件名格式为 SDK_Setting_XXXXXXX.json（其中 XXXXXXX 是您的应用ID）。

4.2 Android：配置文件位置

Android 端支持两种放置方式：

Flutter assets（推荐）：将 SDK_Setting_XXXXXXX.json 放在项目根目录的 assets/ 目录，并在后续步骤中注册资源。
原生 assets（可选）：放到 android/app/src/main/assets/SDK_Setting_XXXXXXX.json，用于兼容已有项目或特殊构建流程。

your_project/
  ├── assets/
  │   └── SDK_Setting_XXXXXXX.json        ✅ Flutter assets（推荐）
  ├── android/app/src/main/assets/
  │   └── SDK_Setting_XXXXXXX.json        ✅ 原生 assets（可选）
  └── ios/Runner/
      └── SDK_Setting_XXXXXXX.json        ✅ iOS Bundle（下一节说明）

4.3 在pubspec.yaml中注册资源（Android）

flutter:
  assets:
    - assets/  # 注册整个assets目录（推荐）
    # 或者明确指定配置文件
    # - assets/SDK_Setting_XXXXXXX.json

配置路径规范：
✅ 推荐用法：在代码中直接使用文件名 SDK_Setting_XXXXXXX.json（插件会自动在 assets/ 目录查找）
⚠️ 兼容用法：也可以使用完整路径 assets/SDK_Setting_XXXXXXX.json（向后兼容旧代码）
Android 初始化时会依次查找：Flutter assets（assets/ 目录）→ 构建产物中的 flutter_assets/assets/ → android/app/src/main/assets/

4.4 iOS：加入应用 Bundle

将 SDK_Setting_XXXXXXX.json 放到 ios/Runner/ 目录，例如 ios/Runner/SDK_Setting_XXXXXXX.json。
打开 Xcode，选择 Runner Target → Build Phases → Copy Bundle Resources，手动添加该文件，确保其随应用打包。
iOS 运行时仅读取应用 Bundle 中的文件，不支持从 Flutter assets 目录加载。

配置文件请保持原样，不需手动修改内容。

第五步：验证安装

参考快速开始中的初始化示例，将示例中的 AppID 和 SDK_Setting_XXXXXXX.json 替换为您的实际配置。
执行 flutter run -d android 或 flutter run -d ios 进行真机/模拟器验证。
控制台输出 PangrowthContent.initialize 与 PangrowthContent.start 成功后，说明安装与依赖已全部就绪。

常见问题

Q1: Android编译失败，提示找不到SDK依赖？

A: 请检查以下几点：

⚠️ 确认 android/build.gradle 中添加了两个 Maven 仓库：

allprojects {
    repositories {
        google()
        mavenCentral()
        // 穿山甲广告SDK仓库（必需，因为 pangrowth_content 依赖 gromore_ads）
        maven { url 'https://artifact.bytedance.com/repository/pangle' }
        // 穿山甲内容SDK仓库（必需）
        maven { url 'https://artifact.bytedance.com/repository/Volcengine' }
    }
}

运行 flutter clean 后重新编译
检查网络连接是否正常
确认 Gradle 版本 >= 7.0

Q2: iOS编译失败，提示CocoaPods错误？

A: 尝试以下步骤：

cd ios
pod deintegrate
pod install
cd ..
flutter clean
flutter run

Q3: 初始化失败，提示配置文件找不到？

A: 这是最常见的问题，请按以下步骤排查：

步骤1：检查配置文件位置

# Flutter 资源目录（推荐，需在 pubspec.yaml 中注册）
✅ assets/SDK_Setting_XXXXXXX.json

# Android 原生 assets（可选备选方案）
✅ android/app/src/main/assets/SDK_Setting_XXXXXXX.json

# iOS Bundle（需加入 Copy Bundle Resources）
✅ ios/Runner/SDK_Setting_XXXXXXX.json

步骤2：检查文件名格式

文件名必须是 SDK_Setting_ 开头，后跟您的AppID
示例：SDK_Setting_5609594.json（不是 pangrowth_config.json）
确保文件扩展名是 .json

步骤3：检查pubspec.yaml注册

flutter:
  assets:
    - assets/  # 推荐：注册整个目录
    # 或者明确指定
    # - assets/SDK_Setting_5609594.json

步骤4：重新构建项目

flutter pub get          # 重新加载依赖
flutter clean            # 清理构建缓存
flutter run              # 重新运行

步骤5：验证配置路径参数

检查初始化代码中的路径参数：

// ✅ 推荐：直接使用文件名（Android 会依次查找 Flutter assets 与原生 assets）
PangrowthContent.initialize(
  configPath: 'SDK_Setting_5609594.json',
  ...
)

// ⚠️ 子目录：如果放在 assets 子目录，需要带上相对路径
PangrowthContent.initialize(
  configPath: 'configs/SDK_Setting_5609594.json', // 对应 assets/configs/SDK_Setting_5609594.json
  ...
)

⚠️ iOS：始终将配置文件放在 ios/Runner/，并在 Xcode 中加入 Copy Bundle Resources，configPath 仍然使用文件名或子目录写法。
⚠️ 绝对路径/临时文件：插件支持 file:// 或绝对路径，但仅用于特定调试场景，不建议在正式环境使用。
是否正确切换到了项目根目录执行命令
配置文件是否有读取权限（ls -la assets/）

Q4: Android运行时崩溃，提示MultiDex问题？

A: 在 android/app/build.gradle 中启用multiDex：

defaultConfig {
    multiDexEnabled true
}

dependencies {
    implementation 'androidx.multidex:multidex:2.0.1'
}

Q5: iOS运行时提示权限问题？

A: 确认在 Info.plist 中添加了所有必要的权限描述。

下一步

安装配置完成后，您可以：

📖 快速开始 - 学习基础用法
🏠 短剧聚合页 - 了解聚合页功能
🎬 短剧播放页 - 学习播放页集成

💡 提示: 如果遇到其他问题，请查看[故障排查指南]或联系技术支持。