SDK导入与初始化

💡Tips

• HyperBid Flutter SDK 同时支持 Android 和 iOS 平台
• 所有全局配置方法（如 setUserId、setChannel、隐私合规等）须在 McSdk.initialize() 之前调用
• 建议配置预置策略以提高首次启动的广告加载效果

1. 导入 Flutter SDK

1.1 手动导入

1. 下载 HyperBid Flutter SDK 压缩包，解压缩。
2. 将解压出的 mc_sdk 目录放置到您的工程目录中（与主工程平级或放入子目录均可）。
3. 在工程中找到 pubspec.yaml，添加本地依赖：

dependencies:
  mc_sdk:
    path: ../mc_sdk  # 相对路径，指向您放置的 mc_sdk 目录

1. 执行依赖安装：

flutter pub get

1. 在 Dart 代码中引入头文件：

import 'package:mc_sdk/mc_sdk.dart';

2. 导入 iOS 适配器

2.1 前提准备

• 最新版本的 Xcode
• 已安装 CocoaPods 最新版本
• iOS 最低部署目标为 13.0

2.2 找到正确的 mc_sdk.podspec 文件

mc_sdk.podspec 位于 Flutter SDK 的 ios/ 目录中。Flutter 的 Plugin 机制会自动引用该文件，您无需手动修改它。

• 若您手动导入了 Flutter SDK：目标文件位于 <mc_sdk 目录>/ios/mc_sdk.podspec
• 若要确认 podspec 路径：在 IDE 中，将鼠标放在 import 'package:mc_sdk/mc_sdk.dart'; 上，可定位到 SDK 所在目录

2.3 在 Podfile 中添加 iOS 适配器依赖

打开您主工程的 ios/Podfile，在 target 'Runner' do 块中添加 HyperBid 核心 SDK 及所需广告平台适配器：

您可以从HyperBid Tools SDK下载获取。

(1). 选择 SDK 版本

(2). 选择聚合平台

(3). 选择广告平台

(4). 点击生成接入代码

(5). 将生成的CocoaPods 引用代码拷贝到Podfile中

💡 Tips

• 版本号请以 SDK 下载中心 提供的最新版本为准
• 取消注释您需要接入的广告网络适配器即可
• 若使用 MAX 聚合，部分广告网络需额外添加 AppLovin Mediation Adapter（如 AppLovinMediationVungleAdapter）
• 若使用 AdMob 聚合，部分广告网络需额外添加 Google Mediation Adapter（如 GoogleMobileAdsMediationVungle）

2.4 安装 iOS 依赖

在编写完 Podfile 后，使用终端打开 iOS 目录，执行安装命令：

cd ios
pod install --repo-update

如非首次操作，可能需要先删除 Podfile.lock 后再执行上方命令。

3. 配置 iOS 工程

3.1 更新您的Info.plist

（1） 打开Info.plist

（2） 添加SKAdNetworkItems键

UnityAds的SKAdNetwork ID每个项目均不相同，若您选择了该广告平台，请以UnityAds后台生成为准，需要您前往UnityAds管理后台查看。

请您回到上文中打开的"SDK下载中心"网页，将"SKAdNetwork IDs代码"栏目中所列出的内容添加至您的Info.plist文件中，请参考下图:

（3） 添加LSApplicationQueriesSchemes键

请您再次回到上文中打开的"SDK下载中心"网页，或直接复制下方代码，将如下栏目中所列出的内容添加至您的Info.plist文件中，请参考下图:

（4） 添加NSUserTrackingUsageDescription键

• 从iOS14.5开始，只有在获得用户明确许可的前提下，应用才可以访问用户的IDFA数据并向用户投放定向广告。
• 在应用程序调用 App Tracking Transparency 框架向最终用户提出应用程序跟踪授权请求之前，IDFA将不可用。如果某个应用未提出此请求，则读取到的IDFA将返回全为0的字符串。

<key>NSUserTrackingUsageDescription</key>
<string>此处修改为您希望用户看到的权限请求描述，可本地化</string>

（5） 添加NSAppTransportSecurity键

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

（6） AdMob平台添加GADApplicationIdentifier键

因AdMob要求，若您勾选使用了该平台才添加该键。关于更多信息，请前往此处。

<key>GADApplicationIdentifier</key>
<string>Your GADApplicationIdentifier </string>
<!-- 上述值格式例如：ca-app-pub-9438501426181082~7319780494 -->

3.2 向用户请求应用程序跟踪权限以获取IDFA

您需要通过App Tracking Transparency来向用户申请获取应用程序跟踪权限。

• 在您使用下面的方法之前，您需要在Info.plist文件中设置NSUserTrackingUsageDescription键值。
• 如果您项目中需要适配GDPR或谷歌UMP，请前往这里进行配置。
  在iOS 15及以上版本时，只有在应用程序状态为UIApplicationStateActive时，调用此API才会提示授权。如果另一个权限请求正在等待用户确认，则不会显示授权提示。

#import <AppTrackingTransparency/AppTrackingTransparency.h>
#import <AdSupport/AdSupport.h>

//若使用AppDelegate
@implementation AppDelegate
 
- (void)applicationDidBecomeActive:(UIApplication *)application {
    if (@available(iOS 14, *)) {
        //iOS 14
        [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {

        }];
    } else {
        // 可以直接获取
        NSString * idfaStr = [ASIdentifierManager sharedManager].advertisingIdentifier.UUIDString;
    }
}

@end

4. 配置 Android 工程

4.1 导入 Android 适配器

在主工程的 android/app/build.gradle 中，引入 HyperBid 提供的 Gradle 引用代码：

从 SDK 下载中心 生成Gradle 引用代码后在 android/app/build.gradle 中添加所需的 Maven 仓库和依赖：

💡 Tips

• 版本号请以 SDK 下载中心 提供的最新版本为准
• 取消注释您需要接入的广告网络适配器
• 若使用 MAX 聚合，部分广告网络需额外添加 AppLovin Mediation Adapter（如 com.applovin.mediation:vungle-adapter）
• 若使用 AdMob 聚合，部分广告网络需额外添加 Google Ads Mediation Adapter（如 com.google.ads.mediation:vungle）

4.2 AndroidManifest 配置

如果使用了 AdMob，则必须在 AndroidManifest.xml 中添加以下配置：

<manifest>
    <application>
        <meta-data
            android:name="com.google.android.gms.ads.APPLICATION_ID"
            android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy" />
    </application>
</manifest>

详情可参考 AdMob 配置文档：更新您的 AndroidManifest.xml

4.3 SDK 混淆配置

在 proguard-rules.pro 中添加 Flutter SDK 混淆规则：

-keep class com.mcsdk.flutterbridge.** { *; }
-keepclassmembers class com.mcsdk.flutterbridge.** {
   public *;
}

5. SDK 初始化

在加载广告之前，需要先完成 SDK 初始化。建议在应用启动时（如 main() 或首页的 initState 中）尽早调用：

import 'package:mc_sdk/mc_sdk.dart';

Future<void> initializeSdk() async {
  // ==========================================
  // 全局配置（须在 initialize 之前调用）
  // ==========================================

  // 开启 Debug 日志（仅开发阶段使用，上线前请关闭）
  McSdk.setVerboseLogging(true);

  // ==========================================
  // 执行初始化
  // ==========================================

  McSdk.initialize("your app id", "your app key");
  
}

6. 全局 API 参考

6.1 全局配置方法

以下方法须在 McSdk.initialize() 之前调用：

6.2 初始化后可用方法

6.3 聚合平台 ID 常量

7. 预置策略

建议配置预置策略以提高应用首次启动时的广告加载效果。