HTML 5 和 JavaScript 中的 AdControl

项目
07/05/2024

警告

自 2020 年 6 月 1 日起，适用于 Windows UWP 应用的 Microsoft 广告盈利平台将关闭。了解详细信息

本演练演示如何使用 AdControl 类在适用于 Windows 10 和 Windows 11 的通用 Windows 平台（UWP） JavaScript/HTML 应用中显示横幅广告。

有关演示如何向 JavaScript/HTML 应用添加横幅广告的完整示例项目，请参阅 GitHub 上的广告示例。

先决条件

使用 Visual Studio 2015 或更高版本的 Visual Studio 安装Microsoft 广告 SDK。有关安装说明，请参阅本文。

注意

如果已安装 Windows 10 SDK 版本 10.0.14393（周年更新）或更高版本的 Windows SDK，那么还必须安装 WinJS 库。此库以前包含在 Windows SDK for Windows 10 的早期版本中，但从 Windows 10 SDK 版本 10.0.14393（周年更新）开始，必须单独安装此库。

在 Visual Studio 中，打开项目或创建新项目。

注意

如果使用的是现有项目，请在项目中打开 Package.appxmanifest 文件，并确保 已选择 Internet（客户端） 功能。你的应用需要此功能才能接收测试广告和实时广告。
如果你的项目面向任何 CPU，请更新你的项目以使用特定于体系结构的生成输出（例如，x86）。如果你的项目面向任何 CPU，你将无法在以下步骤中成功添加对 Microsoft Advertising 库的引用。有关详细信息，请参阅项目中由面向任何 CPU 引起的引用错误。
在项目中添加对Microsoft 广告 SDK的引用：
1. 在解决方案资源管理器窗口中，右键单击引用，然后选择添加引用...
2. 在引用管理器中，展开通用 Windows、单击扩展，然后选中适用于 JavaScript 的 Microsoft 广告 SDK（版本 10.0）旁边的复选框。
3. 在引用管理器中，单击“确定”。
打开 index.html 文件（或其他适用于你项目的 html 文件）。
在 <头> 部分中，在项目的 JavaScript 引用default.css和main.js之后，添加对ad.js的引用。
```

<script src="//Microsoft.Advertising.JavaScript/ad.js"></script>
```
注意

在包含了 main.js 之后，此行必须放置在 <head> 部分；否则，在生成项目时会遇到错误。
修改 default.html 文件（或其他适用于你项目的 html 文件）的 <body> 部分，以便包含 AdControl 的 div。将 AdControl 的 applicationId 和 adUnitId 属性分配给测试广告单元值。同时调整高度和宽度，以便控件是横幅广告支持的广告大小之一。

注意

每个 AdControl 都有一个相应的 广告单元，服务使用该单元 向控件提供广告，每个广告单元都包含 广告单元 ID 和 应用程序 ID。在这些步骤中，你将测试广告单元 ID 和应用程序 ID 值分配给控件。这些测试值只能在应用的测试版本中使用。在将应用发布到 Microsoft Store 之前，必须在合作伙伴中心将这些测试值替换为实时值。
```
<div id="myAd" style="position: absolute; top: 50px; left: 0px; width: 300px; height: 250px; z-index: 1"
    data-win-control="MicrosoftNSJS.Advertising.AdControl"
    data-win-options="{applicationId: '3f83fe91-d6be-434d-a0ae-7351c5a997f1', adUnitId: 'test'}">
</div>
```
编译并运行应用，以使用广告查看它。

以下示例演示简单应用的完整index.html。

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>AdControlExampleApp</title>
    <!-- WinJS references -->
    <link href="lib/winjs-4.0.1/css/ui-light.css" rel="stylesheet" />
    <script src="lib/winjs-4.0.1/js/base.js"></script>
    <script src="lib/winjs-4.0.1/js/ui.js"></script>
    <!-- AdControlExampleApp references -->
    <link href="css/default.css" rel="stylesheet" />
    <script src="js/main.js"></script>
    <!-- Required reference for AdControl -->
    <script src="//Microsoft.Advertising.JavaScript/ad.js"></script>
</head>
<body>
    <div id="myAd" style="position: absolute; top: 50px; left: 0px; width: 300px; height: 250px; z-index: 1"
      data-win-control="MicrosoftNSJS.Advertising.AdControl"
      data-win-options="{applicationId: '3f83fe91-d6be-434d-a0ae-7351c5a997f1', adUnitId: 'test'}">
    </div>
    <p>Content goes here</p>
</body>
</html>

在 JavaScript 中以编程方式创建 AdControl

前面的步骤演示如何在 HTML 标记中声明 AdControl 。或者，可以使用 JavaScript 以编程方式创建 AdControl 。此示例假定你在 HTML 中使用 ID myAd 中的现有 div。

var adDiv = document.getElementById("myAd");
var myAdControl = new MicrosoftNSJS.Advertising.AdControl(adDiv,
{
    applicationId: "3f83fe91-d6be-434d-a0ae-7351c5a997f1",
    adUnitId: "test",
});

myAdControl.isAutoRefreshEnabled = false;
myAdControl.onErrorOccurred = myAdError;
myAdControl.onAdRefreshed = myAdRefreshed;
myAdControl.onEngagedChanged = myAdEngagedChanged;

此示例假定你已经声明了名为 myAdError、 myAdRefreshed 和 myAdEngagedChanged 的事件处理程序方法。

如果使用此代码并且看不到广告，则可以尝试在包含 AdControl 的 div 中插入 position：relative 属性。这将替代 IFrame 的默认设置。广告将正确显示，除非由于此属性的值而未显示广告。请注意，新广告单元最多可能不可用 30 分钟。

注意

此示例中显示的 applicationId 和 adUnitId 值是测试模式值。在提交应用之前，必须通过合作伙伴中心将测试值替换为实时值。

使用实时广告发布应用

确保在你的应用中使用横幅广告遵循我们的横幅广告指南。
在合作伙伴中心中，转到应用内广告页，然后创建广告单元。对于广告单元类型，请指定横幅。记下广告单元 ID 和应用程序 ID。

注意

测试广告单元和实时 UWP 广告单元的应用程序 ID 值采用不同的格式。测试应用程序 ID 值为 GUID。在合作伙伴中心中创建实时 UWP 广告单元时，该广告单元的应用程序 ID 值始终与应用的 Store ID（例如 Store ID 值类似于 9NBLGGH4R315）匹配。
可以选择通过在应用内广告页上的中介设置部分配置设置，为 AdControl 启用广告中介。通过广告中介，你可以通过显示来自多个广告网络的广告（包括来自其他付费广告网络（如 Taboola 和 Smaato）的广告以及用于Microsoft应用促销活动的广告来最大化广告收入和应用推广功能。
在你的代码中，将测试广告单元值（ApplicationId 和 AdUnitId）替换为你在合作伙伴中心生成的实时值。
使用合作伙伴中心提交应用至 Microsoft Store。
在合作伙伴中心中查看广告性能报告。

在应用中管理多个广告控件的广告单元

可以在单个应用中使用多个 AdControl 对象（例如，应用中的每个页面可能托管不同的 AdControl 对象）。在此情况下，我们建议你为每个控件分配不同的广告单元。对每个控件使用不同的广告单元使你可以分别配置中介设置并获取每个控件的独立报告数据。这还使我们的服务能够更好地优化我们为应用提供的广告。

重要

每个广告单元都只能在一个应用中使用。如果在多个应用中使用某个广告单元，将不为该广告单元提供广告。

通过

HTML 5 和 JavaScript 中的 AdControl

先决条件

将横幅广告集成到应用中

在 JavaScript 中以编程方式创建 AdControl

使用实时广告发布应用

在应用中管理多个广告控件的广告单元

反馈

其他资源

通过

HTML 5 和 JavaScript 中的 AdControl

先决条件

将横幅广告集成到应用中

在 JavaScript 中以编程方式创建 AdControl

使用实时广告发布应用

在应用中管理多个广告控件的广告单元

相关主题

反馈

其他资源