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

1. 集成要求

• MAX 作为 AppLovin 的聚合广告平台，要求开发者在应用运行期间，不能同时使用其他聚合，否则中间可能会产生各种冲突和潜在问题，属于违规操作，可能导致的问题包括但不限于账户使用受限以及结算受限，具体内容请参考 AppLovin Policy。
• 接入时，请务必和 Sofish SDK 使用的版本保持一致，避免出现兼容性问题。AppLovin SDK 版本更新日志可参考文档 Changelog 的内容。

2. 接入前准备

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

• AppLovin Ad Review Key：广告审核密钥
• AppLovin Ad Unit ID：广告单元 ID
• 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-max'
}

3.1.2 手动集成

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

dependencies {
    // AppLovin MAX
    implementation 'com.applovin:applovin-sdk:13.6.2'

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

3.2 添加应用配置

在游戏工程的 应用级模块 的 Gradle 文件（通常是<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 控制台中找到)

[!WARNING|labelVisibility:hidden|iconVisibility:hidden] 注意：如果AndroidManifest.xml文件中包含applovin.sdk.key条目，请务必删除！！！

3.3 启用广告审核

• 要启用 MAX Ad Review 服务，需要在游戏工程的 根目录下 的 Gradle 文件 (通常是<project>/build.gradle) 中，将 Google 服务和 Crashlytics 插件添加为构建脚本依赖项：

  buildscript {
    repositories {
        ...
        maven { url 'https://artifacts.applovin.com/android' }
    }
  
    dependencies {
        ...
        // Add the dependency for the AppLovin Quality Service Gradle plugin
        classpath "com.applovin.quality:AppLovinQualityServiceGradlePlugin:5.10.2"
    }
  }
  

• 在游戏工程的 应用级模块 的 Gradle 文件（通常是<project>/<app-module>/build.gradle）中，添加以下配置：

  apply plugin: 'applovin-quality-service'
  applovin {
    apiKey "AppLovin_AD_REVIEW_KEY"
  }
  

  参数说明：

  • AppLovin_AD_REVIEW_KEY：Applovin 广告审核密钥

3.4 添加中介适配器

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

建议通过 Gradle 依赖方式集成适配器。AppLovin 适配器的 POM 文件自动集成中介网络的 SDK 及其依赖项。AppLovin 提供了 AdColony、Amazon、BidMachine、Chartboost、Criteo、DT Exchange、Google Ad Manager、Google bidding and Google AdMob、HyprMX、InMobi、lronSource、LINE、Meta Audience Network、Pangle、Unity Ads 等多家广告中介适配器，在 Preparing Mediated Networks 页面勾选想要集成的中介广告网络，如下图所示：

勾选需要集成的中介广告网络后，页面下方将显示集成这些中介网络的脚本，然后将下面的 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 {
    // MAX Mediation adapters
    implementation 'com.applovin.mediation:bigoads-adapter:5.10.1.0'
    implementation 'com.applovin.mediation:fyber-adapter:8.4.6.0'
    implementation 'com.applovin.mediation:google-adapter:25.4.0.0'
    implementation 'com.applovin.mediation:inmobi-adapter:11.3.0.1'
    implementation 'com.squareup.picasso:picasso:2.8'
    implementation 'androidx.recyclerview:recyclerview:1.4.0'
    implementation 'com.applovin.mediation:verve-adapter:3.9.0.0'
    implementation 'com.applovin.mediation:bidmachine-adapter:3.7.1.0'
    implementation 'com.applovin.mediation:facebook-adapter:6.21.0.0'
    implementation 'com.applovin.mediation:mintegral-adapter:17.1.61.0'
    implementation 'com.applovin.mediation:moloco-adapter:4.9.0.0'
    implementation 'com.applovin.mediation:bytedance-adapter:8.1.0.4.0'
    implementation 'com.applovin.mediation:unityads-adapter:4.19.0.0'
    implementation 'com.applovin.mediation:vungle-adapter:7.7.5.0'
    implementation 'com.adsurge.sdk:adapter-for-max:1.9.0.0'

}

然后需要将添加的中介网络的依赖项指定为最新版本，请参考 Adapter Network Information 。

3.5 添加自定义适配器

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

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

3.6 初始化 SDK

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

SFAdManager.getInstance().initializeSdk(context, listener);

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

AppLovinSettings settings = new AppLovinSettings.Builder()
        .setMuted(false)                                 // 设置是否为静音状态
        .setVerboseLoggingEnabled(true)                  // 设置是否启用详细日志
        .setMediationDebuggerEnabled(false)              // 设置是否启用中介调试器
        .setCreativeDebuggerEnabled(true)                // 设置是否启用创意调试器
        .build();
SFAdManager.getInstance().initializeSdk(context, settings, listener);

3.7 设置用户 ID

AppLovin SDK 从 10.3.0 版本开始，可以在客户端访问展示级别的用户收入数据，应该在用户登录成功时完成此设置。

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

[!TIP|labelVisibility:hidden|iconVisibility:hidden] 注意：userId请设置为 Sofish SDK 登录成功返回的uid。

3.8 Google UMP

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

3.8.1 AdMob 配置

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

3.8.2 通过MAX SDK集成

AppLovin MAX SDK v12.0.0 及以上版本可自动集成 Google UMP，因此无需在游戏中手动集成 Google UMP，该功能可选择性加入的。下面是流程的直观表示：

如果需要通过MAX SDK集成Google UMP，请在初始化 SDK 之前完成同意流程设置，代码示例如下所示：

AppLovinSettings.ConsentFlowSettings consentFlowSettings = new AppLovinSettings.ConsentFlowSettings.Builder()
        .setEnabled(true)                                   // 启用CMP流程
        .setMaxCmpEnabled(true)                             // 启用MAX集成的CMP
        .setPrivacyPolicyUri(privacyPolicyUri)              // 设置隐私政策URL
        .setTermsOfServiceUri(termsOfServiceUri)            // 设置服务条款URL(可选)
        .setShowTermsAndPrivacyPolicyAlertInGdpr(show)      // 设置是否在Google UMP流之前在GDPR区域中显示条款和隐私政策提醒(可选)
        .build();
AppLovinSettings settings = new AppLovinSettings.Builder()
        .setConsentFlowSettings(consentFlowSettings)
        .build();
SFAdManager.getInstance().initializeSdk(getApplication(), settings, listener);

AppLovin 建议允许 GDPR 区域中的现有用户重新进入 GDPR 流程。通常，用户可以在应用程序的“设置”部分中通过 Manage Existing Privacy Settings 选项来执行此操作。为了确定用户是否位于 GDPR 区域内，以便可以有条件地显示该设置选项，可以使用 SDK API AppLovinConfiguration.getConsentFlowUserGeography()(当用户位于 GDPR 区域时返回 ConsentFlowUserGeography.GDPR)。当用户单击 Manage Existing Privacy Settings（或其等效项）时，调用 showCmpForExistingUser() 方法，该操作这会重置用户现有的同意信息。

SFAdManager.getInstance().showCmpForExistingUser(this, new SFResultListener<SFCmpError>() {
    @Override
    public void onResult(SFCmpError error) {
        if (error == null) {
            // The CMP alert was shown successfully.
        }
    }
});

3.8.3 通过Sofish SDK集成

Sofish 广告 SDK v1.6.3 及以上版本可自动集成 Google UMP，因此无需在游戏中手动集成 Google UMP，该功能可选择性加入的。与MAX SDK集成方式相比，没有服务条款和隐私政策弹窗，游戏可自行设计UI。

如果需要通过Sofish SDK集成Google UMP，请在初始化 SDK 之前完成同意流程设置，代码示例如下所示：

AppLovinSettings.ConsentFlowSettings consentFlowSettings = new AppLovinSettings.ConsentFlowSettings.Builder()
        .setEnabled(true)
        .setMaxCmpEnabled(false)                            // 禁用MAX集成的CMP
        .setWaitForGameTriggerShow(true)                    // 设置是否等待游戏触发显示(默认为false，禁用MAX集成的CMP时生效)
        .build();
AppLovinSettings settings = new AppLovinSettings.Builder()
        .setConsentFlowSettings(consentFlowSettings)
        .build();
SFAdManager.getInstance().initializeSdk(getApplication(), settings, listener);

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

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

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

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

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

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

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

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

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

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

[!TIP|labelVisibility:hidden|iconVisibility:hidden] 如果游戏需要控制同意表单的显示时机，建议尽早初始化广告SDK可以预加载同意表单，反之则建议在获得用户同意之后再初始化广告SDK，避免服务条款和隐私政策弹窗和同意表单同时显示。

3.8.4 测试

如果想在 GDPR 区域之外测试 Google CMP，可以通过设置调试用户地理位置来实现，代码示例如下所示：

AppLovinSettings.ConsentFlowSettings consentFlowSettings = new AppLovinSettings.ConsentFlowSettings.Builder()
        .setEnabled(true)
        .setConsentFlowUserGeography(AppLovinConfiguration.ConsentFlowUserGeography.GDPR)       // 设置调试用户地理位置(上线时请去掉该设置)
        .build();

[!TIP|labelVisibility:hidden|iconVisibility:hidden] 在初始化 SDK 时，SDK 会呈现同意流程。当用户完成同意流程时，SDK 会调用初始化完成回调。

3.9 隐私设置

在使用 AppLovin SDK 时，AppLovin 要求正确设置标志，用以指示用户是否位于某些地理区域，包括欧盟、欧洲经济区、英国、瑞士（统称为“欧洲国家” ）和巴西，已同意收集和使用个人数据用于基于兴趣的广告。AppLovin 还要求设置标志，用以指示用户是否属于有年龄限制的类别，或者来自某些州的用户是否选择不共享其信息。

3.9.1 用户同意标志

如果用户同意基于兴趣的广告，请将用户同意标志设置为 true，如果用户不同意基于兴趣的广告，请将用户同意标志设置为 false。

SFAdManager.getInstance().setHasUserConsent(true);

将同意值设置为 false 后，AppLovin 将在应用程序的整个生命周期内继续尊重该价值，或者直到用户同意基于兴趣的广告为止。

3.9.2 基于兴趣的广告标志

美国的州法律可能要求显示“请勿出售或分享我的个人信息”链接，或向这些州的用户提供其他选项以选择退出基于兴趣的广告。必须设置一个标志，用以指示相关州的用户是否选择退出基于兴趣的广告或共享基于兴趣的广告的个人信息。如果用户不通过这些方式选择退出，请将“不共享”标志设置为 false，如果用户确实以这些方式选择退出，请将“不共享”标志设置为 true。

SFAdManager.getInstance().setDoNotSell(true);

3.9.3 年龄限制类别

Android/iOS AppLovin SDK 从版本 13.0.0 开始，setIsAgeRestrictedUser方法不再受支持，因为如果用户符合“儿童”的条件，则 SDK 可能无法初始化或以任何方式使用。开发者不能在专为儿童设计或专门针对儿童的应用中使用 AppLovin 服务。例如，“儿童”类别中的 iOS 应用和针对儿童且必须遵守家庭广告和盈利政策要求的 Google Play 应用不得使用 AppLovin 服务。AppLovin 不会故意收集儿童的个人信息或向儿童投放广告。

[!TIP|labelVisibility:hidden|iconVisibility:hidden] 如果更新SDK V4.1.6及更高版本后出现setIsAgeRestrictedUser方法找不到的错误，可以删除setIsAgeRestrictedUser方法调用，其他功能不受影响。

3.10 高级设置

3.10.1 静音

可以在初始化 SDK 时通过 AppLovinSettings 设置，或者通过以下方法设置是否静音：

SFAdManager.getInstance().setMuted(muted);

[!TIP|labelVisibility:hidden|iconVisibility:hidden] 请在加载广告之前设置静音状态。某些网络（例如 Google Bidding 和 Google AdMob）会返回静音或未静音的视频，具体取决于广告加载之前的静音状态。

3.10.2 启用详细日志记录

可以在初始化 SDK 时通过 AppLovinSettings 设置，或者通过以下方法设置是否启用详细日志记录：

SFAdManager.getInstance().setVerboseLogging(enabled);

3.10.3 自动广告加载

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

SFAdManager.getInstance().setAdAutoLoad(enabled);

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

3.11 获取首次广告价值

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

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

4. 加载广告

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

4.1 设置监听

4.1.1 广告加载监听

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

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

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

    @Override
    public void onAdLoadFailed(String adUnitId, 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 onAdHidden(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.1.3 广告素材 ID 生成监听

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

SFAdManager.getInstance().setAdReviewListener(new SFAdReviewListener() {
    @Override
    public void onCreativeIdGenerated(String creativeId, SFAd ad) {
        // SDK在成功生成广告素材ID时，将调用此方法
    }
});

4.2 广告格式

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

4.2.1 开屏广告

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

SFAdWrapper appOpenAd = SFAdManager.getInstance().createAppOpenAd(activity, adUnitId);

开屏广告请确保接入渠道 Adapter 版本满足版本要求。参考 Supported Adapter Versions

4.2.2 插页式广告

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

SFAdWrapper interstitialAd = SFAdManager.getInstance().createInterstitialAd(activity, adUnitId);

4.2.3 激励视频广告

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

SFAdWrapper rewardedAd = SFAdManager.getInstance().createRewardedAd(activity, adUnitId);

4.2.4 Banner 广告

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

SFAdWrapper bannerAd = SFAdManager.getInstance().createBannerAd(activity, adUnitId, adContainer);

如果需要修改Banner广告的位置，可以通过以下代码设置：

ViewGroup adContainer = findViewById(android.R.id.content);
// 创建Banner广告
SFAdWrapper adWrapper = SFAdManager.getInstance().createBannerAd(activity, adUnitId, adContainer);
if (adWrapper.isAdViewAd()) {
    View bannerAd = (View) adWrapper.getMaxAd();
    FrameLayout.LayoutParams layoutParams = (FrameLayout.LayoutParams) bannerAd.getLayoutParams();
    layoutParams.gravity = Gravity.CENTER_HORIZONTAL | Gravity.BOTTOM;
    bannerAd.setLayoutParams(layoutParams);
}

如果需要修改Banner广告的可见性，可以通过以下代码设置：

// 显示Banner
public void showBannerAd() {
    if (adWrapper.isAdViewAd()) {
        ((View) adWrapper.getMaxAd()).setVisibility(View.VISIBLE);
        adWrapper.startAutoRefresh();
    }
}

// 隐藏Banner
public void hideBannerAd() {
    if (adWrapper.isAdViewAd()) {
        adWrapper.stopAutoRefresh();
        ((View) adWrapper.getMaxAd()).setVisibility(View.GONE);
    }
}

4.2.5 MREC 广告

MREC 广告是一种控件视图广告，请通过以下代码初始 MREC 广告：

SFAdWrapper mrecAd = SFAdManager.getInstance().createMRECAd(activity, adUnitId, adContainer);

4.2.6 Native 广告

Native 广告可以设计与应用程序的外观和风格一致的广告布局，可以将自定义 UI 组件绑定到 MAX SDK，并将原生广告资源渲染到这些组件中：

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="https://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="wrap_content">

    <ImageView
        android:id="@+id/icon_image_view"
    … />
    <LinearLayout
        android:id="@+id/ad_options_view"
    … />
    <TextView
        android:id="@+id/title_text_view"
    … />
    <FrameLayout
        android:id="@+id/star_rating_view"
    … />
    <TextView
        android:id="@+id/advertiser_textView"
    … />
    <TextView
        android:id="@+id/body_text_view"
    … />
    <FrameLayout
        android:id="@+id/media_view_container"
    … />
    <Button
        android:id="@+id/cta_button"
    … />
</androidx.constraintlayout.widget.ConstraintLayout>

根据 AppLovin 的政策，广告必须包含隐私信息图标。该图标链接到重要的隐私声明，可以通过 SFNativeAdViewBinder.Builder#setOptionsContentViewGroupId(id) 方法进行绑定。请通过以下代码创建 Native 广告：

SFNativeAdViewBinder binder = new SFNativeAdViewBinder.Builder(R.layout.native_custom_ad_view)
        .setTitleTextViewId(R.id.title_text_view)
        .setBodyTextViewId(R.id.body_text_view)
        .setIconImageViewId(R.id.icon_image_view)
        .setAdvertiserTextViewId(R.id.advertiser_textView)
        .setMediaContentViewGroupId(R.id.media_view_container)
        .setOptionsContentViewGroupId(R.id.options_view)
        .setStarRatingContentViewGroupId(R.id.star_rating_view)
        .setCallToActionButtonId(R.id.cta_button)
        .build();
SFAdWrapper nativeAd = SFAdManager.getInstance().createNativeAd(activity, adUnitId, adContainer, binder);

Native 广告请确保接入渠道 Adapter 版本满足版本要求。参考 Supported Adapter Versions

4.3 方法说明

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

4.3.1 获取广告单元 ID

String getAdUnitId();

4.3.2 获取广告格式

String getAdFormat();

4.3.3 判断是否为全屏广告

boolean isFullscreenAd();

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

4.3.4 判断是否为视图广告

boolean isAdViewAd();

Banner 广告和 MREC 广告都属于视图广告。Native 广告不属于视图广告。

4.3.5 判断广告是否加载完成

boolean isReady();

4.3.6 加载广告

void loadAd();

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

4.3.7 设置广告展示位置

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

void setPlacement(String placement);

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

4.3.8 显示广告

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

void showAd(String placement, Activity activity);

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

4.3.9 销毁广告

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

void destroy();

4.3.10 停止自动刷新

当隐藏 Banner/MREC 广告或想要手动刷新时，可以通过以下代码停止 Banner/MREC 广告的自动刷新：

void stopAutoRefresh();

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

4.3.11 启动自动刷新

当想要启动 Banner/MREC 广告的自动刷新时，可以通过以下代码启动 Banner/MREC 广告的自动刷新：

void startAutoRefresh();

4.3.12 设置广告参数

当需要对广告设置参数时，可以通过以下代码设置：

void setExtraParameter(String key, String value);

• 内容 URL 传递 AppLovin 允许在发出广告请求时传递应用内容 URL。应用程序内容 URL 在出价请求中传递，以供买方情境化或审核，并且某些 DSP 买家的支出可能需要该 URL。可以通过以下代码传递应用内容 URL：

  sfAdWrapper.setExtraParameter("content_url", "VALUE");
  

• 统一标识符 MAX Publishers 可以将 UID2 令牌作为附加数据点传递给买家，以用于对应用程序库存进行定位和准确出价。可以通过以下代码设置统一标识符：

  sfAdWrapper.setExtraParameter("uid2_token", "VALUE");
  

• 自定义 Banner/MREC 广告刷新间隔 AppLovin 允许的最小和最大刷新间隔分别为 10 秒和 120 秒，超出这些限制的值将被忽略。可以通过以下代码自定义 Banner/MREC 广告刷新间隔：

  sfAdWrapper.setExtraParameter("ad_refresh_seconds", <ad refresh rate> );
  

4.3.13 设置广告加载监听

void setAdListener(SFAdListener listener);

4.3.14 设置广告收入监听

void setAdRevenueListener(SFAdRevenueListener listener);

4.3.15 广告素材 ID 生成监听

void setAdReviewListener(SFAdReviewListener listener);

5. 测试网络

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

5.1 创意调试器

借助 AppLovin MAX SDK，可以在 MAX 介导的应用程序中公开全面的广告信息。当完成特殊手势时，创意调试器会在应用程序中的任意位置显示一个按钮五秒钟。如果随后按下出现的按钮，将可以看到一个新屏幕，其中包含最近显示的广告列表。如果从此列表中选择一个广告，则会显示有关该广告的信息（例如其中介网络和广告素材 ID），并且可以报告该广告的广告素材问题。此手势适用于 SDK 11.6.0 或更高版本的所有广告。

在 AppLovin SDK 版本 11.6.0 及更高版本中，可以通过进行以下方法来显示创意调试器：

SFAdManager.getInstance().showCreativeDebugger();

[!TIP|labelVisibility:hidden|iconVisibility:hidden] 创意调试器默认为启用状态，如果需要禁用创意调试器，请在SDK初始化时设置。

5.2 中介调试器

Mediation Debugger 是一套测试工具。这些工具可帮助开发者更快地与 MAX 集成并启动。可以使用它们来确认网络集成的有效性，这样可确保可以成功加载和展示广告等。

[!TIP|labelVisibility:hidden|iconVisibility:hidden] Mediation Debugger 不支持自定义 SDK 网络。

中介调试器中有四个部分：

• 集成状态：使用此状态确认您已成功完成网络集成。
• 使用测试广告进行测试：使用每个网络的测试模式加载和显示来自网络的广告。
• 使用实时广告进行测试：使用此功能可以通过瀑布配置加载并显示来自网络的广告。
• 共享中介调试器：使用它来生成集成清单的副本，您可以在启动之前将其发送给审阅者。

如果需要显示中介调试器，请在 SDK 初始化时设置，或者也可以通过进行以下方法来显示中介调试器：

SFAdManager.getInstance().showMediationDebugger();

5.2.1 整合状态

中介调试器显示应用程序中找到的 MAX 中介网络适配器和 SDK 的集成状态。它标记与每个网络相关的集成问题（例如网络 SDK 和适配器版本之间不匹配，或缺少 SKAdNetwork ID）。它分三个部分显示中介网络的集成状态：Completed SDK Integrations、Incomplete SDK Integrations 和 Missing SDK Integrations。

• Completed SDK Integrations：已成功将这些广告网络集成到您的应用程序中。
• Incomplete SDK Integrations：这些广告网络存在一个或多个问题，需要先解决这些问题，然后才能将它们成功集成到应用程序中。点击单元格以获取更多信息。可以在本文档的准备中介网络部分找到集成说明。
• Missing SDK Integrations：尚未将这些广告网络集成到您的应用程序中。

5.2.2 使用测试广告进行测试

成功集成中介网络后，AppLovin 建议通过加载并展示这些网络的测试广告来验证集成。

[!WARNING] 某些中介网络可能有一些要求，必须满足这些要求才能加载广告。例如，SDK 可能需要足够的时间来完全初始化（例如，对于 AdColony 和 Liftoff Monetize 来说就是如此）。如果没有留出足够的时间，这可能会导致无填充错误。AppLovin 建议在初始化 SDK 后 2-5 秒的窗口期间加载广告。

要使用测试广告功能，需要以下步骤：

• 在Completed SDK Integrations部分下选择已成功集成的中介网络。
• 点击Select Test Mode Network右侧的的Enable。
• 重新启动应用程序，以便中介 SDK 使用测试广告凭据进行初始化。
• 再次选择中介网络以进入测试广告视图，如下所示：

5.2.3 使用正式广告进行测试

中介调试器允许使用广告单元的瀑布配置查看和测试广告。请求正式广告需要当前设备不处于测试模式中(未在 AppLovin 后台配置测试设备、未通过 Mediation Debugger 启用测试模式)

[!WARNING] 如果使用正式广告进行测试，某些网络可能会将其标记为欺诈活动。由于瀑布配置或网络的定位参数，可能还会遇到填充问题。强烈建议在验证集成时使用正式广告进行测试。当查看和测试正式广告单元时，国家/地区和 LAT（限制广告流量）定位规则适用于您的设备。

5.2.4 共享中介调试器

在应用程序上线之前，质量审核人员可能会要求开发人员共享中介调试器输出的副本。这可确保集成正确并准备好上线。要共享您的 Mediation Debugger 输出，请单击 Mediation Debugger 主屏幕右上角的 SHARE 按钮，然后选择一种方法完成操作。

5.2.5 app-ads.txt

互动广告局 (IAB) 创建了 app-ads.txt ，作为应用发布商向广告商证明他们拥有发起广告请求的应用的一种方式。这可以防止恶意行为者发出欺诈性广告请求。

从 AppLovin SDK 版本 11.6.0 开始，可以通过中介调试器检查 app-ads.txt 文件包含 AppLovin 格式正确的条目。如果在 Google Play 商店或 Apple App Store 上列出的开发者网站的根域下成功找到包含 AppLovin 所有条目的文件，中介调试器会在 MAX 部分下显示 app-ads.txt 的行并带有 ✅ 标记。

app-ads.txt 有什么好处？

• 减少广告欺诈。app-ads.txt 会阻止开发者试图冒充合法应用程序并误导品牌购买虚假库存。
• 降低被列入黑名单的风险。现在，越来越多的广告商依靠采用 app-ads.txt 来确保他们购买授权广告资源。采用 app-ads.txt 可以帮助开发者避免被列入黑名单。
• 提高收入。随着欺诈事件的减少，经过身份验证的开发者可以从真正针对其应用程序的广告资源中保留更多的广告收入。

如何将 AppLovin 添加到应用发布商的 app-ads.txt 中，请参考如何为您的应用实施 app-ads.txt

5.3 启用测试模式

使用测试模式功能验证是否已成功集成 MAX 中介的特定广告网络。如果定义测试设备并在 MAX 帐户的测试模式部分选择网络，则当该设备发出 MAX 广告请求时，MAX 将从选择的网络请求广告，并启用该网络的测试模式。设备还将收到详细的设备日志。

[!TIP|labelVisibility:hidden|iconVisibility:hidden] 启用测试模式时，MAX SDK 会将详细设备日志记录输出到 Android Logcat 或 iOS 控制台。

要启用测试模式，请选择 MAX > Mediation > Manage > Test Mode，然后单击 + Add Test Device。

输入设备名称和相关设备 ID：Android 为Google Advertising ID(GAID)，iOS 为广告商标识符(IDFA)。

选择您想要查看广告的测试网络，然后单击 ✔ Save。保存完成后，与您的帐户关联的所有 MAX 应用都将开始从所选网络接收测试广告。

5.4 广告测试包

游戏完成广告 SDK 接入后，需要在广告 SDK 初始化成功后，通过以下方法来显示中介调试器：

SFAdManager.getInstance().showMediationDebugger();

[!WARNING] 中介调试器仅用于广告测试，上架前请删除该代码，如果是在初始化时通过AppLovinSettings的setMediationDebuggerEnabled方法开启的中介调试器，请将该方法设置为false。

6. 常见问题

6.1 为什么 Mediation Debugger 里边显示的是 View Ad Units (0) ？

说明初始化时，没有获取到当前包名相关的 ad unit 信息，请确认以下内容：

• 后台已经创建完用于当前包名的 Ad Unit ；
• 后台创建的 Ad Unit 包名和当前工程的包名完全一致；
• 工程中配置了正确的 SDK key；
• 是否是刚创建的 Ad Unit ，需要等待生效 (约 30-60 分钟)；
• 后台创建的 Ad Unit 中选择的平台与当前测试的平台一致。注意 fire os 与 Android 为两个不同的平台，如果创建的 Ad Unit 为 Android 平台，则该在 fire os 设备上测试该包时 会显示 Ad Unit 为 0 个。

6.2 如何判断渠道是否完成了初始化？

Mediation debugger 选择指定渠道进入下一级界面，可以看到 Initialization Status。

6.3 为什么某个渠道没有初始化？如何能初始化某个渠道？

正式模式下， SDK 只会初始化该包名对应的 Ad Unit 中启用的渠道。需要确定 Ad Unit 中启用并正确配置渠道的参数，MAX 才能完成对该渠道的初始化。若 Ad Unit 只在部分地区启 用，需要确保当前请求的网络环境 IP 属于启用的地区。

6.4 为什么 Mediation Debugger 的 View Ad Unit 里某个 ad unit 展示的瀑布流与后台配置的不同？

后台配置需要一段时间生效，请等待生效后再查看；

界面中显示的瀑布流为当前地区的瀑布流配置情况。例：若瀑布流只配置在 US 地区， 请在 US 地区的 IP 下打开 Mediation Debugger 查看。

6.5 为什么 Select Live Network 或 Select Test Mode Network 指定渠道后，看到的不是该渠道的广告？

若在选择前应用已经发出过广告请求，播放的可能是已经缓存到的广告。播放完缓存的 广告后，后续就会播放指定渠道的广告了。

6.6 为什么没有在 Integration 中看到添加的 Custom Network？

目前 Mediation Debugger 及测试模式不支持 Custom Network。

6.7 为什么请求不到测试广告？

测试模式也不一定 100% 填充，不同渠道会有不同测试条件的限制，甚至频次控制。测试 时至少要满足 Mediation Debugger 上提示的要求，例如， Pangle 需要挂日本 VPN。

测试过程中，若测试广告或正式广告中任一可以拉取到，通常说明代码接入没有问题。

6.8 为什么请求不到正式广告？

正式广告的请求是否填充取决于渠道的填充意愿，不能确保每次请求都有填充。若测试 广告可以拉取到，通常说明代码接入没有问题。

若某个渠道正式广告持续请求失败 ，应先确认后台 Ad Unit 该渠道配置正确。此外，建议查看 load fail 回调返回的错误码和错误信息，尤其需要关注渠道 SDK 返回的 NetworkErrorCode 和错误信息，参考错误码文档定位原因。

7. 官方技术支持

在完成以上自测流程之后，如果还有未解决的问题。请联系您的 AppLovin 客户经理。并提供以下信息：

• Mediation Debugger 的完整截图
• 各个广告位置的出现场景和逻辑
• 提供正式包（非 demo）如果是实际线上用户观看广告有一定限制，请给我们提供快速测试到广告的方法（预留至少 2-3 天的时间给我们测包/查看问题，请不要直接上线有问题的包）
• 对于接入问题，请简要描述问题并说明：
  • 使用的 Max SDK 的版本和有问题的 Network SDK, adapter 版本
  • 具体问题以及复现的方法。（复现的几率）
  • 复现场景的录屏或者截图
  • 复现过程完整的文字版（非截图）日志，抓取日志前请务必确保通过文档方法启用 verbose log
    • 注意：只有完整 verbose log 才会显示详细请求日志，否则，非 verbose log 通常不包含需要的信息，我们无法做进一步分析，对于开发者来说也浪费了时间。
• 对于问题素材：
  • 如果是开发者本地能够复现的问题，请通过 Creative Debugger（Android | iOS） 获取完整 ad info 截图。若为 AppLovin 渠道的素材，请通过点击 report 获取 ad_response.json 文件；如果是其他广告渠道的问题，开发者需要将信息反馈给相应渠道，需要他们处理或者屏蔽。
  • 如果应用接入了 Ad Review 插件，可以先尝试在 MAX 后台 Ad Review 报告中搜索，看看是否能定位到具体广告素材，找好的话把信息反馈给相应的渠道。
  • 如果是线上用户反馈的素材问题，或者开发者复现过但恰好没有保存以上的信息，麻烦提供以下信息，我们只能尝试定位问题素材的来源（但不保证能精准找到具体的广告）：
    • 出现问题广告设备的 IDFA 或者 GAID
    • AppLovin 账号邮箱
    • 出现问题广告的应用包名和操作系统
    • 出现问题素材的截图或者录屏信息
    • 出现问题素材的时间，最好能缩小到小时范围
• 若反馈 Crash/ANR，请提供如下完整信息：
  • 完整日志（包括主线程和其他线程的完整调用）
  • 出现时间（是否有规律或值得注意的点、是否本地可复现）
  • 出现次数、受影响的用户占总用户数比例
  • 出现的设备和系统版本
  • AppLovin Account 和 App 包名
  • MAX/AppLovin sdk 版本（请说明是否使用 Max 聚合或者其他聚合方式）
  • 渠道 SDK/Adapter 版本（如果是其他广告渠道有关问题）