HTML 5 和 Javascript 中的 AdControl

  • 發行項

警告

自 2020 年 6 月 1 日起，Windows UWP 應用程式的 Microsoft 廣告收益平台將會關閉。 深入了解

本逐步解說示範如何使用 AdControl 類別，在適用於 Windows 10 和 Windows 11 的通用 Windows 平台 (UWP) JavaScript/HTML 應用程式中顯示橫幅廣告。

如需示範如何將橫幅廣告新增至 JavaScript/HTML 應用程式的完整範例專案，請參閱 GitHub 上的廣告範例。

必要條件

注意

如果您已安裝 Windows 10 SDK 10.0.14393 版 (年度更新版) 或更新版本的 Windows SDK，您也必須安裝 WinJS 程式庫。 此程式庫之前是包含在適用於 Windows 10 的舊版 Windows 10 SDK 中，但自 Windows 10 SDK 版本 10.0.14393 (年度更新版) 開始，必須個別安裝此程式庫。

將橫幅廣告整合到應用程式

  1. 在 Visual Studio 中，打開專案或建立新專案。

    注意

    如果您使用現有的專案，請在專案中開啟 Package.appxmanifest 檔案，並確定已選取 [網際網路 (用戶端)] 功能。 您的應用程式需要這項功能，才能接收測試廣告和即時廣告。

  2. 如果您的專案以 [任何 CPU] 為目標，請更新您的專案以使用架構特定的組建輸出 (例如 x86)。 如果您的專案以 [任何 CPU] 為目標，您將無法在下列步驟中成功新增 Microsoft Advertising 程式庫的參考。 如需詳細資訊，請參閱在專案中以任何 CPU 為目標所造成的參考錯誤。

  3. 在專案中新增 Microsoft Advertising SDK 的參考：

    1. 從 [方案總管] 視窗，以滑鼠右鍵按一下 [參考]，然後選取 [新增參考...]。
    2. 在 [參考管理員] 中，展開 [通用 Windows]，按一下 [延伸模組]，然後選取 [Microsoft Advertising SDK for JavaScript] (10.0 版) 旁的核取方塊。
    3. 在 [參考管理員] 中，按一下 [確定]。

  4. 開啟 index.html 檔案(或其他適用於您專案的 HTML 檔案)。

  5. 在 <head> 區段中，在專案的 javaScript 參考 default.css 和 main.js 之後，將參考新增至 ad.js。

    <!-- Advertising required references -->
<script src="//Microsoft.Advertising.JavaScript/ad.js"></script>

    注意

    在包含 main.js 之後，這一行必須放在 <前端> 區段中；否則，當您建置專案時會發生錯誤。

  6. 修改 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: '3f83fe91-d6be-434d-a0ae-7351c5a997f1', adUnitId: 'test'}">
</div>

  7. 編譯並執行應用程式，以查看附帶廣告的情況。

以下範例顯示了簡單應用程式的完整 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 中現有的具有識別碼為 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 值是測試模式值。 您必須先將這些值取代為合作夥伴中心的即時值 ，才能提交您的應用程式。

使用即時廣告發行您的應用程式

  1. 確定您遵循我們的橫幅廣告指導方針，在應用程式中使用橫幅廣告。

  2. 在合作夥伴中心中，前往 [應用程式內廣告] 頁面和 [建立廣告單元]。 針對廣告單元類型，指定 [橫幅]。 記下廣告單元識別碼和應用程式識別碼。

    注意

    測試廣告單元和即時 UWP 廣告單元的應用程式識別碼值格式不同。 測試應用程式識別碼值為 GUID。 當您在合作夥伴中心建立即時 UWP 廣告單元時，廣告單元的應用程式識別碼值一律符合您應用程式的 Store 標識碼（例如：Store 識別碼值看起來像 9NBLGGH4R315）。

  3. 您可以選擇啟用 AdControl 的廣告流量分配，方法是在 [應用程式內廣告] 頁面上的 [流量分配設定] 區段中配置設定。 廣告流量分配可讓您透過顯示來自多個廣告網路的廣告，充分提高您的廣告收益和應用程式推廣能力，這些廣告包括來自 Taboola 和 Smaato 等其他付費廣告網路的廣告，以及 Microsoft 應用程式宣傳行銷活動的廣告。

  4. 在您的程式碼中，將測試廣告單元值 (applicationId 和 adUnitId) 取代為您在合作夥伴中心產生的即時值。

  5. 使用合作夥伴中心將您的應用程式提交至市集。

  6. 在合作夥伴中心檢閱您的廣告績效報告。

管理應用程式中多個廣告控制項的廣告單元

您可以在單一應用程式中使用多個 AdControl 物件 (例如，應用程式中的每個頁面可能會裝載不同的 AdControl 物件)。 在此案例中，我們建議您為每個控制項指派不同的廣告單元。 如果每個控制項使用不同的廣告單元，您就能個別調整流量分配設定，並取得每個控制項的離散報告資料。 這也可讓我們的服務更妥善地將放送到您應用程式的廣告最佳化。

重要

每個廣告單元只能用於一個應用程式中。 如果您在多個應用程式中使用同一個廣告單元，該廣告單元將不會放送廣告。