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

前提条件

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

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

类

如需在您的应用中投放 AFSMA 广告（也称为动态高度搜索广告），请实现以下类：

SearchAdView

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

DynamicHeightSearchAdRequest.Builder

  • 此类封装了广告请求参数。 这类似于在 AFS 桌面和移动网站的 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 对象上设置其他属性可以实现其他自定义选项。

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

searchAdView.loadAd(builder.build());

高级选项

大多数广告请求参数都可以通过 DynamicHeightSearchAdRequest.Builder 对象上的 setter 方法设置。DynamicHeightSearchAdRequest.Builder 中任何没有 setter 方法的参数都可以通过 setAdvancedOptionValue() 方法使用键值对进行设置。有关可以使用 setAdvancedOptionValue() 方法进行设置的完整设置列表，请参阅 AFS 自定义搜索广告参考文档。

键参数必须以“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 地址 摘要：
  • 欺诈防范、安全和法规遵从
  • 广告或营销
  • 推导大致位置
详细信息：
IP 地址用于欺诈和滥用行为监控，以及获取大概用户位置。

然后，Google 会利用大致位置信息确保所投放的广告符合当地法规，以及提供与用户粗略的地理位置相关的广告。

应用活动
  • 应用内页面浏览和点按操作
  • 应用内搜索记录
 摘要：
  • 数据分析
  • 欺诈防范、安全和法规遵从
  • 广告或营销
  • 个性化
详细信息：
您的应用会向我们提供用户的查询，以便我们返回与该关键字相关的搜索广告。我们会衡量观看情况以及与所返回广告的互动情况（点按）。
诊断 摘要：
  • 数据分析
详细信息：
SDK 会衡量广告的呈现延迟时间，以便您能够实施和衡量产品改进。我们还会发送崩溃报告/错误报告，并且偶尔会根据需要添加其他插桩，以了解发布商如何使用相应功能。
设备或其他标识符 摘要：
  • 欺诈防范、安全和法规遵从
  • 广告或营销
详细信息：
设备 ID 用于协助防范欺诈和滥用行为，以及衡量广告效果。