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

前提条件

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

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

如需在您的应用中投放 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);
    }
});

API 参考文档中介绍了 onAdFailedToLoad() 回调方法中使用的常量。

为满足 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 用于协助监控欺诈和滥用行为,以及衡量广告效果。