HTML 5 和 JavaScript 中的 AdControl
警告
自 2020 年 6 月 1 日起,Windows UWP 應用程式的 Microsoft 廣告收益平台將會關閉。 深入了解
本逐步解說示範如何使用 AdControl 類別,在適用於 Windows 10 和 Windows 11 的通用 Windows 平台 (UWP) JavaScript/HTML 應用程式中顯示橫幅廣告。
如需示範如何將橫幅廣告新增至 JavaScript/HTML 應用程式的完整範例專案,請參閱 GitHub 上的廣告範例。
必要條件
- 搭配 Visual Studio 2015 或更新版本的 Visual Studio 安裝 Microsoft Advertising SDK。 如需安裝指示,請參閱本文。
注意
如果您已安裝 Windows 10 SDK 10.0.14393 版 (年度更新版) 或更新版本的 Windows SDK,您也必須安裝 WinJS 程式庫。 此程式庫之前是包含在適用於 Windows 10 的舊版 Windows 10 SDK 中,但自 Windows 10 SDK 版本 10.0.14393 (年度更新版) 開始,必須個別安裝此程式庫。
將橫幅廣告整合到應用程式
在 Visual Studio 中,打開專案或建立新專案。
注意
如果您使用現有的專案,請在專案中開啟 Package.appxmanifest 檔案,並確定已選取 [網際網路 (用戶端)] 功能。 您的應用程式需要這項功能,才能接收測試廣告和即時廣告。
如果您的專案以 [任何 CPU] 為目標,請更新您的專案以使用架構特定的組建輸出 (例如 x86)。 如果您的專案以 [任何 CPU] 為目標,您將無法在下列步驟中成功新增 Microsoft Advertising 程式庫的參考。 如需詳細資訊,請參閱在專案中以任何 CPU 為目標所造成的參考錯誤。
在專案中新增 Microsoft Advertising SDK 的參考:
- 從 [方案總管] 視窗,以滑鼠右鍵按一下 [參考],然後選取 [新增參考...]。
- 在 [參考管理員] 中,展開 [通用 Windows],按一下 [延伸模組],然後選取 [Microsoft Advertising SDK for JavaScript] (10.0 版) 旁的核取方塊。
- 在 [參考管理員] 中,按一下 [確定]。
開啟 index.html 檔案(或其他適用於您專案的 HTML 檔案)。
在 <head> 區段中,在專案的 javaScript 參考 default.css 和 main.js 之後,將參考新增至 ad.js。
<!-- Advertising required references --> <script src="//Microsoft.Advertising.JavaScript/ad.js"></script>
注意
在包含 main.js 之後,這一行必須放在 <前端> 區段中;否則,當您建置專案時會發生錯誤。
修改 default.html 檔案中的 <body> 區段 (或其他適用於您專案的 html 檔案),以包含 AdControl 的 div。 將 AdControl 的 applicationId 和 adUnitId 屬性指派給測試廣告單元值。 請將控制項的高度和寬度調整為支援的橫幅廣告尺寸。
注意
每個 AdControl 都有 一個相對應的廣告單元,由我們的服務用來為控制項提供廣告,而每個廣告單元都包含廣告單元識別碼和應用程式識別碼。 在這些步驟中,您會將測試廣告單元識別碼和應用程式識別碼值指派給控制項。 這些測試值只能在應用程式的測試版本中使用。 將應用程式發佈至市集之前,您必須先將這些測試值取代為合作夥伴中心的即時值。
<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: '00001111-aaaa-2222-bbbb-3333cccc4444', 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: '00001111-aaaa-2222-bbbb-3333cccc4444', adUnitId: 'test'}">
</div>
<p>Content goes here</p>
</body>
</html>
以程序設計方式在 JavaScript 中建立 AdControl
先前的步驟示範如何在 HTML 標記中宣告 AdControl。 或者,您可以使用 JavaScript 以程式設計方式建立 AdControl。 這個範例假設您正在使用 HTML 中現有的具有識別碼為 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 值是測試模式值。 您必須先將這些值取代為合作夥伴中心的即時值 ,才能提交您的應用程式。
使用即時廣告發行您的應用程式
確定您遵循我們的橫幅廣告指導方針,在應用程式中使用橫幅廣告。
在合作夥伴中心中,前往 [應用程式內廣告] 頁面和 [建立廣告單元]。 針對廣告單元類型,指定 [橫幅]。 記下廣告單元識別碼和應用程式識別碼。
注意
測試廣告單元和即時 UWP 廣告單元的應用程式識別碼值格式不同。 測試應用程式識別碼值為 GUID。 當您在合作夥伴中心建立即時 UWP 廣告單元時,廣告單元的應用程式識別碼值一律符合您應用程式的 Store 標識碼(例如:Store 識別碼值看起來像 9NBLGGH4R315)。
您可以選擇啟用 AdControl 的廣告流量分配,方法是在 [應用程式內廣告] 頁面上的 [流量分配設定] 區段中配置設定。 廣告流量分配可讓您透過顯示來自多個廣告網路的廣告,充分提高您的廣告收益和應用程式推廣能力,這些廣告包括來自 Taboola 和 Smaato 等其他付費廣告網路的廣告,以及 Microsoft 應用程式宣傳行銷活動的廣告。
在您的程式碼中,將測試廣告單元值 (applicationId 和 adUnitId) 取代為您在合作夥伴中心產生的即時值。
使用合作夥伴中心將您的應用程式提交至市集。
在合作夥伴中心檢閱您的廣告績效報告。
管理應用程式中多個廣告控制項的廣告單元
您可以在單一應用程式中使用多個 AdControl 物件 (例如,應用程式中的每個頁面可能會裝載不同的 AdControl 物件)。 在此案例中,我們建議您為每個控制項指派不同的廣告單元。 如果每個控制項使用不同的廣告單元,您就能個別調整流量分配設定,並取得每個控制項的離散報告資料。 這也可讓我們的服務更妥善地將放送到您應用程式的廣告最佳化。
重要
每個廣告單元只能用於一個應用程式中。 如果您在多個應用程式中使用同一個廣告單元,該廣告單元將不會放送廣告。