README

这是一个 Drupal 扩展模块，为各种类型的广告实例（主要是广告）提供统一的集成。

为什么你可能想要统一广告管理

• 所有广告可以在需要时关闭，并且可以通过上下文字段进行目标定位。
• 只需点击几下即可用其他类型的广告替换现有的广告，而不会丢失任何上下文。
• 所有广告都使用 Theme Breakpoints JS 模块以相同的方式尊重你的主题断点。
• 配置基于同意的个性化：此模块提供了一种统一的方式来配置符合 GDPR 的广告，可选地与“同意”或“欧盟 Cookie 合规性”模块结合使用。

可用的提供商集成

• Doubleclick for Publishers (DFP)，包含在此模块中。
• AdTech Factory，包含在此模块中。
• 视频智能
• 智能广告服务器
• 对于高级用例，已包含的 ad_entity_generic 子模块提供了一个管理自定义和任意类型广告的骨架。

如果你基于 ad_entity 有进一步的集成并想在下面列出，请告诉我们！

要求

• 需要 Entity API 模块。
• 如果你想要设置尊重你的主题断点的广告，那么你需要 主题断点 JS 模块。

快速入门

• 安装此模块。
• 设置查看广告的权限。由于涉及两种不同的实体类型（ad_entity 和 ad_display），请确保你的角色已授予查看两种类型的访问权限，通过设置“查看广告实体”和“查看广告显示配置”。
• 你需要至少一个其他模块来定义广告类型。例如，ad_entity_dfp 模块允许你创建 Doubleclick for Publishers (DFP) 广告类型。此模块可在“modules”子文件夹中找到。
• 在 admin/structure/ad_entity/global-settings 中配置广告实体的全局设置。
• 在 admin/structure/ad_entity 中创建和管理你的广告实体。如果你的主题有多个断点，你可以为每个断点创建一个实体。
• 在 admin/structure/ad_entity/display 中创建和管理广告的显示配置。创建显示配置后，你可以在 admin/structure/block 中将其放置为块。

关于视图处理器

对于每种广告类型，通常有不同的视图处理器可供选择

• 默认 HTML 视图，这是在常规页面上查看广告的方式。
• iframe，可以用于源或在外部源发布。
• Facebook 即时文章（FIA），基本上也是一个 iframe。
• 加速移动页面（AMP），目前仅由 DFP 子模块提供。

关于广告上下文

给定的广告上下文能够扩展或修改在页面上显示的广告实体的信息和定义的行为。

广告上下文可以由内容（如节点和分类术语）定义。

为了使用户能够定义上下文，必须将“广告上下文”字段附加到实体类型。选择无限基数，让用户可以添加多个上下文。

该字段提供了不同的格式化工具用于广告上下文。在您的实体类型的“管理显示”部分，将上下文字段放入内容区域，以便在页面上传递用户定义的上下文。

传递广告上下文的字段格式化工具类型

可用的字段格式化工具在传递哪个上下文方面有所不同。如果您只想从给定实体传递用户定义的上下文，请选择“仅从实体传递上下文”。

如果您想包括任何通过引用实体引用的上下文，请选择“从具有引用的实体传递上下文”。

如果您想包括附加到属于节点的术语的上下文，请选择“从具有分类（无树）的节点传递上下文”。要包括分类树，您还可以在“树聚合”和“树覆盖”格式化工具变体之间进行选择。

使用树聚合意味着将包括一个术语的所有祖先的上下文。请注意，此类操作可能成本高昂。

使用树覆盖意味着在给定术语没有定义自己的上下文的情况下，将使用在分类树中找到的第一个上下文。将使用具有上下文的术语的第一个祖先（自下而上）。请注意，此操作也可能成本高昂。

对于分类术语，您也可以使用树聚合或树覆盖。

广告上下文的适用模式

在为传递广告上下文选择适当的字段格式化工具时，您还可以在前端应用和后端应用模式之间进行选择。前端应用模式将使用JavaScript应用传递的上下文，而后端应用模式将在服务器端完成这项工作。后端应用模式通常是推荐的模式（下一节将解释原因）。

前端应用模式曾经是节省服务器端资源的推荐模式。然而，已经证明，除非您的应用过程非常复杂，否则这不会成为现实。然而，大多数应用过程并不复杂，如果确实如此，您需要重新考虑整个过程，因为您不希望前端太慢。前端应用模式仍然存在，但可能被认为是下一个主要版本（2.x）的弃用。如果您想在iframe或feed上应用广告上下文，您需要在字段格式化工具上使用后端应用模式。

开发者提示

JavaScript事件

作为调整广告显示和行为的另一种方式，广告实现可能为您提供了事件。

以下事件通常提供

• 当从上下文中收集到广告实体的容器时：adEntity:collected，其中包含一个event.detail对象，包含collected, newcomers, context, settings。
• 在容器内初始化广告后：adEntity:initialized，其中包含一个event.detail对象，包含container。

AdTech实现提供了窗口事件atf:BeforeLoad，它在调用带有load_arguments数组的atf_lib.load_tags()之前触发。

DFP实现提供了窗口事件dfp:BeforeDisplay，它在插槽定义之后和显示指令之前触发，您可以对slot及其相应的targeting进行操作。

手动加载和渲染广告实体

当您编写用于嵌入广告实体的自定义代码时，您可能希望使用与某个特定（内容）实体相对应的上下文。对于此用例，您可以在服务器端重建上下文，例如在类似于这样的预处理器函数中

if (\Drupal::hasService('ad_entity.context_manager')) {
  $context_manager = \Drupal::service('ad_entity.context_manager');
  // $entity may be a node, term, user or any other entity.
  $context_manager->resetContextDataForEntity($entity);

  // .. Load and view your ad_entity instances.
  // .. $ad_view = $view_builder->view($ad_entity);

  // Reset to previous context data state (if any).
  $ad_view['#post_render'][] = '_ad_entity_reset_to_previous_context_data';
}

手动初始化广告

广告实体可以选择禁用自动初始化。当自动初始化被禁用时，在主题处理过程中，广告实体的容器会获得CSS类 initialization-disabled。

要手动初始化您的广告，您需要从容器中移除上述类，并调用 Drupal.ad_entity.restrictAndInitialize(containers, context, settings)。

避免可能出现问题的进一步提示

建议始终通过显示配置来显示您的广告实体。这样，您就能在整个网站上更改您的广告，并在可用的广告变体之间切换。

默认的树聚合和树覆盖可能是昂贵的操作。当使用大量术语来处理具有大型树的节点时，建议编写您自己的格式化程序，该程序直接加载您想要的上下文。