[!WARNING] AdMob广告集成文档适用于需要接入AdMob聚合广告的项目研发人员。已经自行接入AdMob的可以忽略该文档，广告SDK只需要选择一种接入即可，具体情况请和发行方联系。

1. 接入准备

发行方运营申请 AdMob 接入需要用到的参数提供给游戏研发：

• AdMob App ID：AdMob 的 App ID

3. 集成步骤

3.1 集成SDK

3.1.1 自动集成(推荐)

在游戏工程的模块级的 build.gradle 文件中添加 SDK 的依赖项：

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.aar', '*.jar'])
    ...
    // Import the BoM for the Sofish platform
    implementation platform('com.sofish.game:game-bom:1.7.5')
    implementation 'com.sofish.game:game-ad-admob'
}

3.1.2 手动集成

将 sf-sdk-admob-x.x.x.aar 文件添加到模块的 libs 目录中，并在游戏工程的模块级的 build.gradle 文件中，添加以下依赖：

dependencies {
    // ConstraintLayout
    implementation 'androidx.constraintlayout:constraintlayout:2.1.4'

    // Firebase
    implementation(platform("com.google.firebase:firebase-bom:34.7.0"))
    implementation("com.google.firebase:firebase-analytics")
    implementation("com.google.firebase:firebase-config")

    // Google AdMob Next-Gen
    implementation 'com.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk:1.2.1'

    // Google UMP
    implementation 'com.google.android.ump:user-messaging-platform:4.0.0'
}

3.1.3 注意事项

如果项目在编译时出现了com.google.android.gms.ads.**相关的依赖冲突/类重复(Duplicate Class)，可以通过在项目根目录的 build.gradle 文件中添加以下配置强制排除(Exclude)重复的模块解决这个问题，代码示例如下：

allprojects {
    configurations.configureEach {
        exclude group: 'com.google.android.gms', module: 'play-services-ads'
    }
}

3.2 集成AdMob

3.2.1 添加中介适配器

[!TIP|labelVisibility:hidden|iconVisibility:hidden] 注意：具体需要接入哪些中介广告网络请和游戏发行方运营联系。

建议通过 Gradle 依赖方式集成适配器。AppLovin 适配器的 POM 文件自动集成中介网络的 SDK 及其依赖项。AdMob 提供了 AppLovin、Chartboost、DT Exchange、i-mobile、InMobi、ironSource、Liftoff Monetize、LINE Ads Network、maio、Meta、Mintegral、Moloco、Pangle、PubMatic OpenWrap、Unity Ads 等多家广告中介适配器，在 Choose networks 页面勾选想要集成的中介广告网络，如下图所示：

勾选需要集成的中介广告网络后，点击下方的Show mediation setup按钮页面下方将显示集成这些中介网络的脚本，然后将下面的 Gradle 脚本添加到模块级的 build.gradle 文件中，以下为示例代码：

repositories {
    google()
    mavenCentral()
    maven { url "https://dl-maven-android.mintegral.com/repository/mbridge_android_sdk_oversea" }
    maven { url "https://artifact.bytedance.com/repository/pangle" }
}

dependencies {
    // AdMob Mediation adapters
    implementation 'com.google.ads.mediation:applovin:13.6.3.0'
    implementation 'com.google.ads.mediation:bigo:5.9.0.1'
    implementation 'com.google.ads.mediation:fyber:8.4.5.1'
    implementation 'com.google.ads.mediation:moloco:4.10.1.0'
    implementation 'com.google.ads.mediation:inmobi:11.3.0.1'
    implementation 'com.google.ads.mediation:facebook:6.21.0.3'
    implementation 'com.google.ads.mediation:mintegral:17.1.61.1'
    implementation 'com.google.ads.mediation:pangle:8.1.0.4.0'
    implementation 'com.google.ads.mediation:unity:4.19.0.0'
    implementation 'com.google.ads.mediation:verve:3.9.0.0'
    implementation 'com.google.ads.mediation:bidmachine:3.7.1.1'
    implementation 'com.google.ads.mediation:vungle:7.7.4.2'
}

然后需要将添加的中介网络的依赖项指定为最新版本，请参考 Open source and versioned adapters 。

3.2.2 添加自定义适配器

目前 AdMob 支持的自定义适配器有 AdSurge，集成时需要将以下 Gradle 脚本添加到模块级的 build.gradle 文件中：

dependencies {
    implementation 'com.adsurge.sdk:adapter-for-admob:1.9.0.0'
}

3.3 添加配置

3.3.1 添加应用配置

在游戏工程的 应用级模块 的资源文件（通常是<project>/<app-module>/src/main/res/values/strings.xml）中，添加以下配置：

<string name="admob_app_id">AdMob_APP_ID</string>

参数说明：

• AdMob_APP_ID：Google AdMob 应用 ID (可在AdMob 控制台中找到)

3.3.2 添加默认配置

广告配置分为本地配置和远程配置，本地配置为默认配置，远程配置通过Firebase Remote Config实现，未在Firebase Remote Config配置的属性将使用默认值。在应用发布时，可以从 Firebase 控制台下载一个包含所有默认值的XML文件，并添加到应用级模块的资源目录（通常是<project>/<app-module>/src/main/res/xml）中，请保持文件名为remote_config_defaults.xml，为了保证默认配置生效，请不要随意修改文件名。

3.4 初始化 SDK

广告SDK的初始化建议在游戏启动并且首屏渲染完毕后调用，尽量避开冷启动高峰，如果游戏包含热更新功能并且不需要加载开屏广告的，则建议在不需要热更新时/完成热更新之后调用：

SFAdManager.getInstance().initializeSdk();

如果需要添加其他设置，可以使用下面的方法进行初始化：

SFAdSettings settings = new SFAdSettings.Builder()
        .setAdMobAdSettings(                                        // AdMob广告设置(可选)
                new SFAdMobAdSettings.Builder()
                        .setMuted(false)                            // 设置是否静音
                        .setVolume(1.0f)                            // 设置视频广告音量
                        .setAdInspectorEnabled(false)               // 设置是否启用广告检查器
                        .setAdUnitsConfig(
                            new SFAdUnitsConfig.Builder()
                                .setAppOpenAdUnitId("ca-app-pub-3940256099942544/9257395921")
                                .setInterstitialAdUnitId("ca-app-pub-3940256099942544/1033173712")
                                .setRewardedAdUnitId("ca-app-pub-3940256099942544/5224354917")
                                .setBannerAdUnitId("ca-app-pub-3940256099942544/6300978111")
                                .setNativeAdUnitId("ca-app-pub-3940256099942544/2247696110")
                                .build()
                        )                                           // 设置默认的广告单元配置
                        .build()
        )
        .setConsentFlowSettings(                                    // CMP流程设置
                new SFConsentDebugSettings.Builder()
                        .setEnabled(true)                           // 启用CMP流程
                        .build()
        )
        .setUserIdentifier(userId)                                  // 设置用户唯一标识(可选)
        .build();
SFAdManager.getInstance().initializeSdk(settings, listener);

3.5 设置用户 ID

设置用户 ID 可以在客户端访问展示级别的用户收入数据，应该在用户登录成功时完成此设置。

SFAdManager.getInstance().setUserIdentifier(userId); // 设置Sofish SDK登录成功返回的uid

[!TIP|labelVisibility:hidden|iconVisibility:hidden] 注意：userId请设置为 Sofish SDK 登录成功返回的uid。SDK 内部已经集成了该功能。

3.6 Google UMP

根据 Google 欧盟地区用户意见征求政策，必须向位于欧洲经济区 (EEA) 和英国境内的用户披露相关信息，在法律有相应要求的情况下，必须就 Cookie 或其他本地存储方式的使用征得他们的同意，并使用个人数据（例如 AdID）来投放广告。此政策反映了欧盟《电子隐私指令》和《一般数据保护条例》(GDPR) 的要求。为了帮助发布商履行此政策规定的职责，Google 提供了 User Messaging Platform (UMP) SDK，UMP SDK 支持最新的 IAB 标准。

SDK 内部已自动集成 Google UMP，因此无需在 SDK 之外手动集成 Google UMP。

3.6.1 AdMob 配置

要让 SDK 同意流程显示 Google GDPR 表单，首先必须在 AdMob 仪表板上创建并发布 Google GDPR 消息，然后要自定义在 GDPR 消息中显示哪些广告合作伙伴。

3.6.2 启用 Google UMP

请在初始化 SDK 时启用 Google UMP，需要调试时可以设置调试信息，代码示例如下所示：

SFAdSettings settings = new SFAdSettings.Builder()
        .setConsentFlowSettings(                                    // CMP流程设置
                new SFConsentDebugSettings.Builder()
                        .setEnabled(true)                           // 启用CMP流程
                        .setWaitForGameTriggerShow(true)            // 设置是否等待游戏触发显示(默认为false)
                        .build()
        )
        .build();
SFAdManager.getInstance().initializeSdk(settings, listener);

如果游戏需要控制同意表单的显示时机，可以通过setWaitForGameTriggerShow(true)设置，在需要显示同意表单的时候调用以下方法显示同意表单以完成同意流程：

SFAdManager.getInstance().getCmpService().showConsentForm(activity);

[!TIP|labelVisibility:hidden|iconVisibility:hidden] 在初始化 SDK 时，SDK 会呈现同意流程。当用户完成流程时，SDK 会调用初始化完成回调。该功能可选择性加入。

3.6.3 隐私设置选项

根据合规要求，请在游戏中添加一个可见且可交互的UI元素(如按钮或菜单项)，用于触发显示隐私选项表单。如果不需要提供入口，请将相应的UI元素设置为不可见且不可交互。可以通过以下方法检查是否需要隐私选项入口：

SFAdManager.getInstance().getCmpService().isPrivacyOptionsRequired();

当用户与游戏元素互动，需要显示隐私选项表单时，可以通过以下方法实现：

SFAdManager.getInstance().getCmpService().showPrivacyOptionsForm(activity, listener);

3.6.4 设置监听

当游戏中需要监听同意表单是否加载完成时，可以通过以下方法实现：

SFAdManager.getInstance().getCmpService().setCmpLoadedListener(listener);

当游戏中需要监听用户是否操作完成时，可以通过以下方法实现：

SFAdManager.getInstance().getCmpService().setCmpCompletedListener(listener);

3.6.5 测试 Google UMP

如果需要测试 Google UMP，可以通过设置调试用户地理位置来实现，代码示例如下所示：

SFAdSettings settings = new SFAdSettings.Builder()
        .setConsentFlowSettings(                                    // CMP流程设置
                new SFConsentDebugSettings.Builder()
                        .setEnabled(true)                           // 启用CMP流程
                        .setDebugGeography(SFDebugGeography.GDPR)   // 仅用于调试，发布时请删除
                        .build()
        )
        .build();
SFAdManager.getInstance().initializeSdk(settings, listener);

[!WARNING|labelVisibility:hidden|iconVisibility:hidden] 注意：setDebugGeography() 方法仅用于测试目的，不可以在生产代码中调用该方法，发布时请删除！！！。

3.6.6 重置用户同意情况

通过 UMP SDK 测试应用时，如果需要模拟用户的首次安装体验，可以通过reset()方法重置 UMP 的状态，代码示例如下所示：

SFAdManager.getInstance().getCmpService().reset();

[!WARNING|labelVisibility:hidden|iconVisibility:hidden] 注意：reset() 方法仅用于测试目的，不可以在生产代码中调用该方法，发布时请删除！！！。

3.7 自动广告加载

SDK 内部处理了在广告关闭或广告加载失败情况下自动加载下一条广告的逻辑，如果需要使用此功能，请通过以下方式启用自动广告加载功能。

SFAdManager.getInstance().setAdAutoLoad(enabled);

[!WARNING|labelVisibility:hidden|iconVisibility:hidden] 注意：如果不需要使用此功能，请自行处理各种情况下(初始化、加载失败、显示失败、广告消失)的广告加载逻辑。

3.8 获取首次广告价值

SDK 内部记录了每个广告位首次广告的价值信息，如果需要获取广告位的首次广告价值信息，可以通过以下方法获取：

SFAdRevenue adRevenue = SFAdManager.getInstance().getFirstAdRevenue(waterfallType); // 如果没有成功展示过广告可能返回null

4. 加载广告

[!TIP|labelVisibility:hidden|iconVisibility:hidden] 注意：不需要加载开屏广告的，建议在游戏热更新结束或者用户进入游戏之后再进行广告加载，尽量避免广告资源的加载影响游戏热更新操作和游戏资源的加载。

4.1 设置监听

4.1.1 广告加载监听

可以在广告加载之前通过此方法设置广告监听，所有类型的广告回调都通过此监听通知游戏：

SFAdManager.getInstance().setAdListener(new SFAdListener() {
    @Override
    public void onAdRequest(String adUnitId, String adFormat) {
        // SDK在发送广告请求时，将调用此方法
    }

    @Override
    public void onAdLoaded(SFAd ad) {
        // SDK成功加载广告后，将调用此方法
    }

    @Override
    public void onAdLoadFailed(String adUnitId, String adFormat, SFAdError error) {
        // SDK在广告加载失败时，将调用此方法
    }

    @Override
    public void onAdDisplayed(SFAd ad) {
        // SDK成功展示广告时，将调用此方法
    }

    @Override
    public void onAdDisplayFailed(SFAd ad, SFAdError error) {
        // SDK在全屏广告展示失败时，将调用此方法
    }

    @Override
    public void onAdClicked(SFAd ad) {
        // SDK在用户点击广告时会，将调用此方法
    }

    @Override
    public void onAdDismissed(SFAd ad) {
        // SDK在完成广告展示后会，将调用此方法
    }

    @Override
    public void onUserRewarded(SFAd ad, SFAdReward reward) {
        // SDK在用户应该获得奖励时，将调用此方法
    }

    @Override
    public void onAdExpanded(SFAd ad) {
        // SDK在广告控件展开全屏时，将调用此方法
    }

    @Override
    public void onAdCollapsed(SFAd ad) {
        // SDK在广告控件折叠回其原始大小时，将调用此方法
    }
});

4.1.2 广告收入监听

可以在广告加载之前通过此方法设置广告收入监听，所有类型的广告收入回调都通过此监听通知游戏：

SFAdManager.getInstance().setAdRevenueListener(new SFAdRevenueListener() {
    @Override
    public void onAdRevenuePaid(@NonNull SFAd ad) {
        // SDK在检测到广告收入事件时，将调用此方法
    }
});

[!WARNING|labelVisibility:hidden|iconVisibility:hidden] SDK内部已经添加了广告收入数据统计，请不要重复记录Firebase的 ad_impression 事件。

4.2 广告格式

SDK 支持 开屏广告、插页式广告、激励视频广告 和 Banner广告，请在广告SDK初始化完成之后再创建并加载广告，所有方法调用请在UI线程中完成。

4.2.1 开屏广告

开屏广告是一种全屏广告，与插页式广告类似，但在用户冷启动或软启动应用程序时显示，请通过以下代码创建开屏广告：

SFAdWrapper appOpenAd = SFAdManager.getInstance().createAppOpenAd();

4.2.2 插页式广告

插页式广告是一种全屏广告，请通过以下代码创建插页式广告：

SFAdWrapper interstitialAd = SFAdManager.getInstance().createInterstitialAd();

4.2.3 激励视频广告

激励视频广告是一种全屏广告，主要用于为用户提供某种价值(比如用户可以观看奖励视频广告并接收更多金币或解锁优质内容)，请通过以下代码创建激励视频广告：

SFAdWrapper rewardedAd = SFAdManager.getInstance().createRewardedAd();

4.2.4 Banner 广告

Banner 广告是一种控件视图广告，可以通过以下代码创建 Banner 广告：

SFAdRequest request = new SFAdRequest.Builder()
        .setAdSize(SFAdSize.BANNER)                 // 广告尺寸
        .setAdContainer(bannerAdContainer)          // 广告容器
        .setGravity(gravity)                        // 广告位置(默认底部居中)
        .build();
SFAdWrapper bannerAd = SFAdManager.getInstance().createBannerAd(request);

[!TIP|labelVisibility:hidden|iconVisibility:hidden] 广告容器请优先使用FrameLayout或LinearLayout，其他类型的的容器不支持设置gravity。如果没有指定容器，默认容器为activity.findViewById(android.R.id.content)。

4.2.5 Native 广告

Native 广告是一种自定义视图的广告，可以通过以下代码创建 Native 广告：

SFAdWrapper nativeAd = SFAdManager.getInstance().createNativeAd();

4.3 方法说明

SFAdWrapper 是 SDK 对各种格式广告的一种包装，下面主要介绍 SFAdWrapper 提供的方法。

4.3.1 获取广告格式

String getAdFormat();

4.3.2 获取广告单元ID

String getAdUnitId();

4.3.3 获取广告信息

SFAd getAd();

4.3.4 判断是否为全屏广告

boolean isFullscreenAd();

开屏广告、插页式广告和激励视频广告都属于全屏广告。

4.3.5 判断是否为视图广告

boolean isAdViewAd();

Banner 广告属于视图广告。

4.3.6 判断广告是否正在加载中

boolean isLoading();

4.3.7 判断广告是否加载完成

boolean isReady();

4.3.8 加载广告

void loadAd();

[!TIP|labelVisibility:hidden|iconVisibility:hidden] 如果没有开启自动广告加载功能，请在创建广告后，主动调用loadAd()方法加载广告。

4.3.9 显示广告

该方法主要用于展示 开屏广告、插页式广告 和 激励视频广告 等全屏广告，展示广告之前请确认广告已准备好，显示广告时请传入广告展示位置。

void showAd(String placement);

4.3.10 展示 Native 广告

该方法主要用于展示 Native广告，展示广告之前请确认广告已准备好并且已成功添加广告容器，显示广告时请传入广告展示位置。

void showNativeAd(String placement, SFNativeAdTemplate template);

请将原生广告布局资源文件中的控件设置一个非0的ID并绑定到模版中，布局方式请参考AdMob Native Ad，代码示例如下：

SFNativeAdTemplate nativeAdTemplate = new SFNativeAdTemplate.Builder(adContainer, layoutResId)
    .setIconImageViewId(iconImageViewId)                // 广告图标
    .setTitleTextViewId(titleTextViewId)                // 广告标题
    .setBodyTextViewId(bodyTextViewId)                  // 广告内容(可选)
    .setAdvertiserTextViewId(advertiserTextViewId)      // 广告主(可选)
    .setStarRatingViewId(starRatingViewId)              // 商店评分(可选)
    .setCallToActionViewId(callToActionViewId)          // 广告点击按钮
    .setMediaContentViewId(mediaContentViewId)          // 广告媒体内容(可选)
    .setNativeAdCloseViewId(nativeAdCloseViewId)        // 广告关闭按钮(可选，可以游戏自行处理关闭事件)
    .build();
wrapper.showNativeAd(placement, nativeAdTemplate);

[!TIP|labelVisibility:hidden|iconVisibility:hidden] Native 广告展示之前需要先在当前游戏页面中创建一个广告容器并将其添加到视图树中，请在游戏端完成广告容器的大小和位置设置，SDK 只负责渲染原生广告并将广告添加到广告容器中。对于原生视频广告，主素材资源 MediaView 的尺寸不得小于 120x120dp (Android)。在展示原生广告时，必须展示广告标示，以指明该视图是广告，具体请参考政策指南。

4.3.11 关闭 Native 广告

该方法主要用于关闭 Native广告，关闭广告时请确保广告正在展示。

void dismissNativeAd();

4.3.12 设置广告展示位置

该方法主要用于为 Banner广告设置广告展示位置，请在广告创建后立即设置。

void setPlacement(String placement);

[!TIP|labelVisibility:hidden|iconVisibility:hidden] 为了更好的统计数据，广告展示位置必须传入，请使用字母、数字和下划线的组合。

4.3.13 销毁广告

当页面关闭或者销毁游戏场景的时候，请销毁创建的广告对象，释放资源。

void destroy();

4.3.14 设置Banner是否可见

当游戏内场景切换时需要改变Banner的可见状态，可以通过以下代码设置Banner是否可见：

void setBannerVisibility(boolean visible);

4.3.15 设置Banner是否自动刷新

当游戏页面的可见性改变或者需要手动刷新时，可以通过以下代码设置Banner是否自动刷新：

void setBannerAutoRefresh(boolean enabled);

[!WARNING|labelVisibility:hidden|iconVisibility:hidden] 当Banner广告或MREC广告消失在屏幕上时， 务必调用setBannerAutoRefresh(false)方法停止自动刷新，否则因此会造成的后果包括但不限于：展示率低、填充下降、收入下跌、账户使用受限。

4.3.16 设置广告加载监听

void setAdListener(SFAdListener listener);

4.3.17 设置广告收入监听

void setAdRevenueListener(SFAdRevenueListener listener);

5. 测试广告网络

[!TIP|labelVisibility:hidden|iconVisibility:hidden] 广告测试大部分渠道推荐使用 VPN 节点且测试设备需包含 Google Service。

AdMob Ad Inspector是一款应用内叠加工具，可以直接在移动应用内对测试广告请求进行实时分析。

广告检查器中可以执行以下操作：

• 验证适配器集成：查看与应用中配置的广告来源相关联的所有适配器的列表。
• 测试广告单元：在广告检查器中请求测试广告。
• 排查广告单元问题：在 Ad Units（广告单元）标签页中，点按某个广告单元即可查看其 SDK 请求日志。
• 排查隐私设置问题：通过隐私权标签页，广告检查器可提供有关意见征求管理平台 (CMP) 的信息。

如果需要显示AdMob的广告检查器，请在 SDK 初始化时设置：

SFAdSettings settings = new SFAdSettings.Builder()
        .setAdMobAdSettings(
                new SFAdMobAdSettings.Builder()
                        .setAdInspectorEnabled(true)               // 设置是否启用广告检查器
                        .build()
        )
        .build();

6. 数据结构说明

6.1 SFAdSettings

SFAdSettings 是用于初始化广告SDK的设置信息，数据结构如下：

6.2 SFAdMobAdSettings

SFAdMobAdSettings 是用于初始化AdMob广告聚合平台的设置信息，数据结构如下：

6.3 SFAdBufferSize

SFAdBufferSize 是用于预加载时广告缓冲区大小的配置信息，数据结构如下：

6.3 SFAdUnitsConfig

SFAdUnitsConfig 是用于添加默认的广告单元配置信息，数据结构如下：

6.5 SFConsentFlowSettings

SFConsentFlowSettings 是用于Cmp流程的设置信息，数据结构如下：

6.6 SFNativeAdTemplate

SFNativeAdTemplate 是用于绑定原生广告控件信息，数据结构如下：