插播式廣告

2025-03-29

警告

自 2020 年 6 月 1 日起，Windows UWP app 的Microsoft廣告獲利平臺將會關閉。深入瞭解

本逐步解說示範如何在適用於 Windows 10 和 Windows 11 的通用 Windows 平臺（UWP） app 和遊戲中包含插播式廣告。如需示範如何使用 C C++# 將插播式廣告新增至 JavaScript/HTML 應用程式和 XAML 應用程式的完整範例專案，請參閱 GitHub 上的廣告範例。

什麼是插播式廣告？

不同於標準橫幅廣告，這些廣告僅限於應用程式或遊戲中 UI 的一部分，插播式廣告會顯示在整個畫面上。遊戲經常使用兩種基本形式。

透過 Paywall 廣告，用戶必須定期觀看廣告。例如，遊戲層級之間的範例：
透過 以 Rewards 為主的 廣告，用戶會明確尋求一些好處，例如提示或額外的時間來完成關卡，並透過應用程式的使用者介面啟動廣告。

我們提供兩種類型的插播式廣告，以用於您的應用程式和遊戲：插播式影片廣告 和 插播式橫幅廣告。

注意

插播式廣告的 API 不會處理任何使用者介面，但視訊播放時除外。請參考插播式廣告最佳實踐，獲取有關應用程式中如何整合插播式廣告的建議，以及應避免的做法。

先決條件

使用 Visual Studio 2015 或更新版本安裝 Microsoft Advertising SDK。如需安裝指示，請參閱本文。

將插播式廣告整合到您的應用程式

若要在您的應用程式中顯示插播式廣告，請遵循項目類型的指示：

XAML/.NET
HTML/JavaScript
C++ （DirectX Interop）

XAML/.NET

本節提供 C# 範例，但 XAML/.NET 專案也支援 Visual Basic 和 C++。如需完整的 C# 程式代碼範例，請參閱 C# 中的插播式廣告範例程式代碼。

在 Visual Studio 中開啟您的專案。

注意

如果您使用現有的專案，請在專案中開啟 Package.appxmanifest 檔案，並確定已選取 因特網（用戶端） 功能。您的應用程式需要這項功能，才能接收測試廣告和實時廣告。
如果您的專案目標設定為 Any CPU，請將專案更新為使用特定架構的組建輸出（例如，x86）。如果您的專案以 任何 CPU為目標，您將無法在下列步驟中成功新增 Microsoft 廣告程式庫的參考。如需詳細資訊，請參閱以專案中的任何 CPU 為目標所導致的參考錯誤。
在專案中新增Microsoft Advertising SDK 的參考：
1. 從 [方案總管] 視窗中，右鍵點選 [參考]，然後選取 [新增參考...]
2. 在 參考管理員中，展開 [通用 Windows ]，按兩下 [延伸模組]，然後選取 [Microsoft XAML [10.0 版] 廣告 SDK 旁的複選框。
3. 在 [參考管理員]中，按兩下 [確定]。
在應用程式的適當程式代碼檔案中（例如，在 MainPage.xaml.cs 或某些其他頁面的程式代碼檔案中），新增下列命名空間參考。
```
using Microsoft.Advertising.WinRT.UI;
```
在應用程式的適當位置（例如，在 MainPage 或其他頁面），宣告 InterstitialAd 物件，以及數個字元串字段，代表插播式廣告的應用程式標識符和廣告單元標識符。下列程式碼範例將 myAppId 和 myAdUnitId 欄位指派給測試值，以用於插播式廣告。

注意

每個 InterstitialAd 都有一個對應的 廣告單元，我們的服務使用這些單元向控制項展示廣告。每個廣告單元包含一個 廣告單元標識符 和 應用程式標識符。在這些步驟中，您會將測試廣告單元標識碼和應用程式識別碼值指派給控件。這些測試值只能在應用程式的測試版本中使用。將應用程式發佈至市集之前，您必須先將這些測試值取代為合作夥伴中心的即時值。
```
InterstitialAd myInterstitialAd = null;
string myAppId = "d25517cb-12d4-4699-8bdc-52040c712cab";
string myAdUnitId = "test";
```

在啟動時執行的程式代碼中（例如，在頁面的建構函式中），實例化 InterstitialAd 物件，並綁定物件的事件處理程式。

myInterstitialAd = new InterstitialAd();
myInterstitialAd.AdReady += MyInterstitialAd_AdReady;
myInterstitialAd.ErrorOccurred += MyInterstitialAd_ErrorOccurred;
myInterstitialAd.Completed += MyInterstitialAd_Completed;
myInterstitialAd.Cancelled += MyInterstitialAd_Cancelled;

如果您想要顯示 插播式影片 廣告：在您需要廣告前大約 30 到 60 秒，請使用 RequestAd 方法來預先擷取廣告。這樣可以在廣告展示前有足夠的時間來申請和準備廣告。請務必為廣告類型指定 AdType.Video。
```
myInterstitialAd.RequestAd(AdType.Video, myAppId, myAdUnitId);
```
如果您想要在廣告顯示插播式橫幅：大約需要廣告 5-8 秒，請使用 RequestAd 方法來預先擷取廣告。這樣可以有足夠的時間來申請和準備廣告，然後再顯示。請務必為廣告類型指定 AdType.Display。
```
myInterstitialAd.RequestAd(AdType.Display, myAppId, myAdUnitId);
```
當您的程式代碼中您想要顯示插播式視訊或插播式橫幅廣告時，請確認 InterstitialAd 已準備好顯示，然後使用 Show 方法加以顯示。
```
if (InterstitialAdState.Ready == myInterstitialAd.State)
{
    myInterstitialAd.Show();
}
```

定義 InterstitialAd 物件的事件處理程式。

void MyInterstitialAd_AdReady(object sender, object e)
{
    // Your code goes here.
}

void MyInterstitialAd_ErrorOccurred(object sender, AdErrorEventArgs e)
{
    // Your code goes here.
}

void MyInterstitialAd_Completed(object sender, object e)
{
    // Your code goes here.
}

void MyInterstitialAd_Cancelled(object sender, object e)
{
    // Your code goes here.
}

建置並測試您的應用程式，以確認它正在顯示測試廣告。

HTML/JavaScript

下列指示假設您已在 Visual Studio 中建立適用於 JavaScript 的通用 Windows 專案，並且以特定 CPU 為目標。如需完整的程式代碼範例，請參閱 javaScript 中的插播式廣告範例程序代碼。

在 Visual Studio 中開啟您的專案。
如果您的專案設定為 任何 CPU，請將專案更新為使用特定架構的建置輸出（例如，x86）。如果您的專案以 任何 CPU為目標，您將無法在下列步驟中成功新增 Microsoft 廣告庫的參考。如需詳細資訊，請參閱以專案中的任何 CPU 為目標所導致的參考錯誤。
在專案中新增Microsoft Advertising SDK 的參考：
1. 從 [方案總管] 視窗中，以滑鼠右鍵點選 [參考]，然後選取 [新增參考...]
2. 在 參考管理員中，展開 通用 Windows，點擊 Extensions，然後選取 Microsoft Advertising SDK for JavaScript（10.0 版）旁的複選框。
3. 在 [參考管理員]中，按兩下 [確定]。
在專案中的 HTML 檔案的 <head> 區段中，在專案參考的 JavaScript 的 default.css 和 default.js之後，新增對 ad.js的參考。
```
<script src="//Microsoft.Advertising.JavaScript/ad.js"></script>
```
在專案中的 .js 檔案中，宣告 InterstitialAd 物件，以及數個字段，其中包含插播式廣告的應用程式標識碼和廣告單元標識符。下列程式碼範例會將欄位 applicationId 和 adUnitId 指派給用於插播式廣告的測試值和。

注意

每個 InterstitialAd 都有一個對應的 廣告單元，我們的服務用來提供廣告給控件，而每個廣告單元都包含一個 廣告單元標識符 和 應用程式標識符。在這些步驟中，您會將測試廣告單元標識碼和應用程式識別碼值指派給控件。這些測試值只能在應用程式的測試版本中使用。將應用程式發佈至市集之前，您必須先將這些測試值取代為合作夥伴中心的即時值。
```
var interstitialAd = null;
var applicationId = "d25517cb-12d4-4699-8bdc-52040c712cab";
var adUnitId = "test";
```

在啟動時執行的程式代碼中（例如，在頁面的建構函式中），具現化 InterstitialAd 物件，並連接物件的事件處理程式。

interstitialAd = new MicrosoftNSJS.Advertising.InterstitialAd();
interstitialAd.onErrorOccurred = errorOccurredHandler;
interstitialAd.onAdReady = adReadyHandler;
interstitialAd.onCancelled = cancelledHandler;
interstitialAd.onCompleted = completedHandler;

如果您想要顯示 插播式影片 廣告：請在您需要廣告的 30-60 秒之前，使用 RequestAd 方法來預先擷取廣告。這樣可以有足夠的時間來請求和準備廣告，在廣告顯示之前。請務必為廣告類型指定 InterstitialAdType.video。
```
if (interstitialAd) {
    interstitialAd.requestAd(MicrosoftNSJS.Advertising.InterstitialAdType.video, applicationId, adUnitId);
}
```
如果您想顯示 插播式橫幅廣告：請在需要廣告的前大約 5-8 秒，使用 RequestAd 方法來預先擷取廣告。這允許有足夠的時間來申請和準備廣告，以便在顯示之前準備就緒。請務必為廣告類型指定 InterstitialAdType.display。
```
if (interstitialAd) {
    interstitialAd.requestAd(MicrosoftNSJS.Advertising.InterstitialAdType.display, applicationId, adUnitId);
}
```

在您想要顯示廣告的程式代碼中，確認 InterstitialAd 已準備好顯示，然後使用 Show 方法顯示廣告。

if (interstitialAd && interstitialAd.state === MicrosoftNSJS.Advertising.InterstitialAdState.ready) {
    interstitialAd.show();
}

定義 InterstitialAd 物件的事件處理程式。

function adReadyHandler(sender) {
  // Your code goes here.
}

function errorOccurredHandler(sender, args) {
  // Your code goes here.
}

function completedHandler(sender) {
  // Your code goes here.
}

function cancelledHandler(sender) {
  // Your code goes here.
}

建置並測試您的應用程式，以確認它正在顯示測試廣告。

C++ （DirectX Interop）

此範例假設您已在 Visual Studio 中建立 C++ DirectX 和 XAML 應用程式（通用 Windows） 專案，並以特定的 CPU 架構為目標。

在 Visual Studio 中開啟您的專案。
在專案中新增Microsoft Advertising SDK 的參考：
1. 從 [方案總管] 視窗中，以滑鼠右鍵按兩下 [參考]，然後選取 [[新增參考...]
2. 在 參考管理員中，展開 [通用 Windows]，按一下 [擴充功能]，然後選取 [Microsoft Advertising SDK for XAML (10.0 版)] 旁的複選框。
3. 在 [參考管理員]中，按兩下 [確定]。

在應用程式的適當頭檔中（例如 DirectXPage.xaml.h），宣告 InterstitialAd 對象和相關事件處理程式方法。

Microsoft::Advertising::WinRT::UI::InterstitialAd^ m_interstitialAd;
void OnAdReady(Object^ sender, Object^ args);
void OnAdCompleted(Object^ sender, Object^ args);
void OnAdCancelled(Object^ sender, Object^ args);
void OnAdError(Object^ sender, Microsoft::Advertising::WinRT::UI::AdErrorEventArgs^ args);

在相同的頭檔中，宣告數個字串字段，代表插播式廣告的應用程式標識碼和廣告單位標識碼。下列程式代碼範例會將 myAppId 和 myAdUnitId 欄位指派給用於插播式廣告的測試值。

注意

每個 InterstitialAd 都有一個對應的 廣告單元，我們的服務用來提供廣告給控件，而每個廣告單元都包含一個 廣告單元標識符 和 應用程式標識符。在這些步驟中，您會將測試廣告單元標識碼和應用程式識別碼值指派給控件。這些測試值只能在應用程式的測試版本中使用。將應用程式發佈至市集之前，您必須先將這些測試值替換為來自合作夥伴中心的實時值。
```
Platform::String^ myAppId = L"d25517cb-12d4-4699-8bdc-52040c712cab";
Platform::String^ myAdUnitId = L"test";
```
在您想要新增程式代碼以顯示插播式廣告的.cpp檔案中，新增下列命名空間參考。下列範例假設您要將程式代碼新增至應用程式中DirectXPage.xaml.cpp檔案。
```
using namespace Microsoft::Advertising::WinRT::UI;
```

在啟動時執行的程式代碼中（例如，在頁面的建構函式中），實例化 InterstitialAd 物件，並連接物件的事件處理程式。在下列範例中，InterstitialAdSamplesCpp 是您專案的命名空間;視您的程式代碼需要變更此名稱。

m_interstitialAd = ref new InterstitialAd();         
m_interstitialAd->AdReady += ref new Windows::Foundation::EventHandler<Platform::Object ^>
    (this, &InterstitialAdSamplesCpp::DirectXPage::OnAdReady);
m_interstitialAd->Completed += ref new Windows::Foundation::EventHandler<Platform::Object ^>
    (this, &InterstitialAdSamplesCpp::DirectXPage::OnAdCompleted);
m_interstitialAd->Cancelled += ref new Windows::Foundation::EventHandler<Platform::Object ^>
    (this, &InterstitialAdSamplesCpp::DirectXPage::OnAdCancelled);
m_interstitialAd->ErrorOccurred += ref new
    Windows::Foundation::EventHandler<Microsoft::Advertising::WinRT::UI::AdErrorEventArgs ^>
    (this, &InterstitialAdSamplesCpp::DirectXPage::OnAdError);

如果您想要顯示 插播式影片 廣告：在需要插播式廣告之前大約 30-60 秒，請使用 RequestAd 方法來預先擷取廣告。這使我們有足夠的時間來請求和準備廣告，然後再顯示它。請務必為廣告類型指定 AdType：：Video。
```
m_interstitialAd->RequestAd(AdType::Video, myAppId, myAdUnitId);
```
如果您想顯示 插播式橫幅 廣告：在您需要廣告之前的約 5-8 秒，請使用 RequestAd 方法來預先擷取廣告。這樣就有足夠的時間來要求並準備廣告，然後再顯示廣告。請務必為廣告類型指定 AdType::Display。
```
m_interstitialAd->RequestAd(AdType::Display, myAppId, myAdUnitId);
```
在您想要顯示廣告的程式代碼中，確認 InterstitialAd 已準備好顯示，然後使用 Show 方法顯示廣告。
```
if ((InterstitialAdState::Ready == m_interstitialAd->State))
{
    m_interstitialAd->Show();
}
```

定義 InterstitialAd 物件的事件處理程式。

void DirectXPage::OnAdReady(Object^ sender, Object^ args)
{
    // Your code goes here.
}


void DirectXPage::OnAdCompleted(Object^ sender, Object^ args)
{
    // Your code goes here.
}

void DirectXPage::OnAdCancelled(Object^ sender, Object^ args)
{
    // Your code goes here.
}

void DirectXPage::OnAdError(Object^ sender, Microsoft::Advertising::WinRT::UI::AdErrorEventArgs^ args)
{
    // Your code goes here.
}

建置並測試您的應用程式，以確認它正在顯示測試廣告。

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

請確定您在應用程序中使用插頁式廣告時遵循我們的插頁式廣告指導方針，。
在合作夥伴中心，移至應用程式內廣告頁面，建立廣告單元。針對廣告單元類型，選擇 視訊插播式 或 橫幅插播式，視您顯示的插播式廣告類型而定。記下廣告單元標識碼和應用程式標識碼。

注意

測試廣告單元和即時UWP廣告單元的應用程式識別碼值具有不同的格式。測試應用程式識別碼值為 GUID。當您在合作夥伴中心建立即時 UWP 廣告單元時，廣告單元的應用程式識別碼值一律符合您 app 的市集標識碼（例如市集標識符值看起來像 9NBLGGH4R315）。
您可以選擇性地在應用程式內廣告頁面的中介設定區塊中，為 插頁式廣告 啟用廣告調解。廣告流量分配可讓您透過顯示來自多個廣告網路的廣告，包括來自其他付費廣告網路的廣告，例如 Taboola 和 Smaato 的廣告，以及Microsoft應用程式促銷活動的廣告，來最大化您的廣告收入和應用程式促銷功能。
在您的程式代碼中，將測試廣告單元值取代為您在合作夥伴中心產生的即時值。
使用合作夥伴中心將您的應用程式提交至市集。
在合作夥伴中心檢閱您的廣告績效報告。

管理應用程式中多個插播式廣告控件的廣告單位

您可以在單一應用程式中使用多個 InterstitialAd 控件。在此案例中，我們建議您將不同的廣告單元指派給每個控件。針對每個控件使用不同的廣告單位，可讓您個別設定流量分配設定，並取得每個控件的離散報告數據。這也可讓我們的服務更妥善地優化我們服務給您的應用程式的廣告。

重要

您只能在一個應用程式中使用每個廣告單元。如果您在多個應用程式中使用廣告單元，廣告將不會針對該廣告單元提供服務。

插播式廣告的指導方針
C# 中的插播式廣告範例程式碼
在 JavaScript 中的插播式廣告範例程式代碼
GitHub 上的 Advertising 範例
為您的應用程式設定廣告單元

共用方式為

插播式廣告

什麼是插播式廣告？

先決條件

將插播式廣告整合到您的應用程式

XAML/.NET

HTML/JavaScript

C++ （DirectX Interop）

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

管理應用程式中多個插播式廣告控件的廣告單位

相關主題

意見反應

其他資源