适用于移动应用的 AFS (AFSMA) 实现（适用于 Android）

前提条件

本实现指南假定您熟悉以下内容：

• AFS 自定义搜索广告 (CSA) 实施 协议
• Android 应用开发
• 关联 Google 移动广告 适用于 Android 的 SDK （现已成为 Google Play 服务的一部分）与 Android Studio 项目相关联。 需要安装 9.0.0 版 Google Play 服务。

类

要在您的应用中投放 AFSMA 广告（也称为动态高度搜索广告），请按以下步骤操作： 实现以下类：

SearchAdView

• 此类继承自 Android ViewGroup 类 并展示 AFSMA 广告。 SearchAdView 发出包含 DynamicHeightSearchAdRequest 并呈现返回的广告。 应将 SearchAdView 添加到应用的任何现有视图组中。
• 必须使用上下文对 SearchAdView 进行实例化 SearchAdView 的运行位置，通常为 Activity。
• 实例化 SearchAdView 后，您必须调用 setAdSize() 方法 与AdSize.SEARCH请求 AFSMA 广告。 其他枚举值将请求与 AFS 移动应用不兼容的广告。
• 使用您的属性代码对此对象调用 setAdUnitId() 方法。

DynamicHeightSearchAdRequest.Builder

• 这个类用于封装广告请求参数。 这类似于在 JavaScript 广告请求对象中设置参数 （网页选项、广告单元选项）。
• 使用适当的 setter 方法（换言之， 调用 setQuery() 来设置查询参数）。

实现示例

以下示例演示了如何使用 Activity 创建 SearchAdView 以 ViewGroup 的子视图的形式呈现。为了正确请求 AFSMA 广告，SearchAdView 对象必须使用 AdSize.SEARCH 调用 setAdSize() 方法。

//  MainActivity.java implementation
//  (MainActivity is a subclass of Activity)

// Create the SearchAdView
final SearchAdView searchAdView = new SearchAdView(this);

// Set parameter to request for dynamic height search ads
searchAdView.setAdSize(AdSize.SEARCH); // Important!

// Replace with your pub ID (e.g. ms-app-pub-9616389000213823)
searchAdView.setAdUnitId("ms-app-pub-################");

// Add searchAdView to parent view group
...

在同一个 Activity 中，创建一个 DynamicHeightSearchAdRequest.Builder，用于 指定将在 SearchAdView 中呈现的广告的参数。 AFSMA 广告的配置方式与 AFS 自定义搜索广告相同； 请参阅 AFS 自定义搜索广告 参考文档 了解详情。

// Create the ad request
DynamicHeightSearchAdRequest.Builder builder =
        new DynamicHeightSearchAdRequest.Builder();
builder.setQuery("flowers");
builder.setNumber(2);

// Replace with the ID of a style from your custom search styles
builder.setAdvancedOptionValue("csa_styleId", "0000000001");

// Customization options (set using setters on
// DynamicHeightSearchAdRequest.Builder)
builder.setAdTest(true);

通过在 DynamicHeightSearchAdRequest.Builder 对象。

要发出广告请求，请调用 loadAd() 方法 SearchAdView 对象中的 DynamicHeightSearchAdRequest.Builder 对象：

searchAdView.loadAd(builder.build());

高级选项

大多数广告请求参数都可以通过 setter 方法进行设置 针对 DynamicHeightSearchAdRequest.Builder 对象的操作。 在 中没有任何 setter 方法的参数 DynamicHeightSearchAdRequest.Builder可使用具有 setAdvancedOptionValue() 方法。 查看 AFS 自定义搜索广告 参考文档 ，查看可通过 setAdvancedOptionValue() 方法。

键参数必须以“csa_”为前缀 才能正确设置该属性。

// Advanced customization options (set using key-value pair)

// Set a parameter (parameter_name) and its value (parameter_value)
// builder.setAdvancedOptionValue("csa_parameter_name", "parameter_value");

// Example: Show visible URL below description
// (domainLinkAboveDescription: false)
builder.setAdvancedOptionValue("csa_domainLinkAboveDescription", "false");

如果您使用参数的 setter 方法并使用 setAdvancedOptionValue 对其进行设置， 第二次调用将覆盖第一次调用的值。

调查错误

SearchAdView（此处为 searchAdView）包含 setAdListener() 方法 以帮助您调查错误。在同一 Activity 内：

searchAdView.setAdListener(new AdListener() {
    @Override
    public void onAdLoaded() {
        // Called when an ad is loaded
        super.onAdLoaded();
        Toast.makeText(MainActivity.this, "Ad Loaded",
                Toast.LENGTH_SHORT).show();
        Log.d(MainActivity.class.getSimpleName(), "Ad Loaded");
    }

    @Override
    public void onAdOpened() {
        // Called when an ad opens an overlay that covers the screen
        super.onAdOpened();
        Toast.makeText(MainActivity.this, "Ad Opened",
                Toast.LENGTH_SHORT).show();
        Log.d(MainActivity.class.getSimpleName(), "Ad Opened");
    }

    @Override
    public void onAdLeftApplication() {
        // Called when an ad leaves the application
        // (to go to the browser for example)
        super.onAdLeftApplication();
        Toast.makeText(MainActivity.this, "Ad Left Application",
                Toast.LENGTH_SHORT).show();
        Log.d(MainActivity.class.getSimpleName(), "Ad Left Application");
    }

    @Override
    public void onAdFailedToLoad(int errorCode) {
        // Called when an ad request failed
        super.onAdFailedToLoad(errorCode);
        Toast.makeText(MainActivity.this, "Ad Failed to Load: " + errorCode,
                Toast.LENGTH_SHORT).show();
        Log.e(MainActivity.class.getSimpleName(), "Ad Failed to Load: " +
                errorCode);
    }
});

onAdFailedToLoad() 回调方法中使用的常量 请参阅 API 参考文档。

为满足 Google Play 的数据披露要求做准备

2021 年 5 月，Google Play 宣布推出全新的“数据安全”部分，这是由开发者提供的关于应用的数据收集、共享和安全做法的披露声明。

本页面可帮助您满足与使用 AFS 原生 SDK（也适用于 AdSense 购物广告使用情况）相关的此类数据披露要求。在此页面上，您可以了解我们的 SDK 是否会处理最终用户数据以及如何处理这些数据。

我们的目标是尽可能透明地为您提供支持；不过，作为应用开发者，您应自行负责决定如何回答 Google Play 的“数据安全”部分与应用的最终用户数据收集、分享和安全做法有关的表单。

如何使用本页面中的信息

本页面仅列出了最新版本的 SDK 收集的最终用户数据。

如需完成数据披露，您可以使用 Android 的数据类型指南来确定哪些数据类型能最贴切地描述所收集的数据。在数据披露中，另请务必明确说明您的特定应用将如何共享和使用所收集的数据。

SDK 访问和收集的数据类型

软件包：

com.google.android.gms:play-services-afs-native

com.google.ads.afsn

自动收集的数据

AFS SDK 会自动收集以下数据。所有数据都将从设备传输至 Google 以用于投放广告，并且所有数据在传输过程中都会经过加密处理。绝不会收集用户的个人信息，除非您的应用在用户查询中发送这些信息。

数据	收集这些数据是为了以下目的...
IP 地址	<ph type="x-smartling-placeholder"></ph> 摘要： <ph type="x-smartling-placeholder"> </ph> 欺诈防范、安全和法规遵从 广告或营销 推导大致位置 。 <ph type="x-smartling-placeholder"></ph> 详细信息： IP 地址会用于监控欺诈和滥用行为，以及获取用户的大致位置。 然后，Google 会使用大致位置来确保投放的广告符合当地法规，以及提供与用户大致地理位置相关的广告。
应用活动记录 <ph type="x-smartling-placeholder"> </ph> 应用内页面浏览和点按操作 应用内搜索记录	<ph type="x-smartling-placeholder"></ph> 摘要： <ph type="x-smartling-placeholder"> </ph> 分析 欺诈防范、安全和法规遵从 广告或营销 个性化 。 <ph type="x-smartling-placeholder"></ph> 详细信息： 您的应用向我们提供用户的查询，以便我们返回与相应关键字相关的搜索广告。我们会衡量返回的广告的观看次数和互动（点按）。
诊断信息	<ph type="x-smartling-placeholder"></ph> 摘要： <ph type="x-smartling-placeholder"> </ph> 分析 。 <ph type="x-smartling-placeholder"></ph> 详细信息： SDK 会测量广告的呈现延迟时间，以便实施和衡量产品改进措施。我们还会发送崩溃/错误报告，并偶尔根据需要添加其他工具，以了解发布商如何使用这些功能。
设备或其他标识符	<ph type="x-smartling-placeholder"></ph> 摘要： <ph type="x-smartling-placeholder"> </ph> 欺诈防范、安全和法规遵从 广告或营销 。 <ph type="x-smartling-placeholder"></ph> 详细信息： 设备 ID 用于监控欺诈和滥用行为，以及衡量广告效果。