插播式廣告

  • 發行項

警告

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

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

什麼是插播式廣告？

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

  • 使用「Paywall」廣告時，使用者必須在固定間隔觀看廣告。 例如，在遊戲關卡之間：

    whatisaninterstitial

  • 使用「獎勵型」廣告，使用者會明確尋求一些好處，例如提示或額外的時間來完成關卡，並透過應用程式的使用者介面初始化廣告。

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

注意

插播式廣告的 API 不會處理任何使用者介面，但播放影片時除外。 請參閱插播式最佳做法，取得在您考慮如何在應用程式中整合插播式廣告要做什麼和避免什麼的指導方針。

必要條件

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

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

XAML/.NET

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

  1. 在 Visual Studio 中，開啟您的專案。

    注意

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

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

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

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

  4. 在應用程式的適當程式碼檔案中 (例如，在 MainPage.xaml.cs 或某些其他頁面的程式碼檔案中)，新增下列命名空間參考。

    using Microsoft.Advertising.WinRT.UI;

  5. 在應用程式的適當位置 (例如，在 MainPage 或其他頁面中)，宣告 InterstitialAd 物件和數個 字串功能變數，代表插播式廣告的應用程式識別碼和廣告單元識別碼。 下列程式碼範例將 myAppId 和 myAdUnitId 功能變數指派給插播式廣告的測試值。

    注意

    每個 InterstitialAd 都有一個相對應的廣告單元，由我們的服務用來為控制項提供廣告，而每個廣告單元都包含廣告單元識別碼和應用程式識別碼。 在這些步驟中，您會將測試廣告單元識別碼和應用程式識別碼值指派給控制項。 這些測試值只能在應用程式的測試版本中使用。 將應用程式發佈至市集之前，您必須先將這些測試值取代為合作夥伴中心的即時值。

    InterstitialAd myInterstitialAd = null;
string myAppId = "d25517cb-12d4-4699-8bdc-52040c712cab";
string myAdUnitId = "test";

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

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

  7. 如果您想要顯示插播式影片廣告：需要廣告前約 30-60 秒，請使用 RequestAd 方法來預先擷取廣告。 這容許在顯示廣告前有足夠的時間要求並準備廣告。 請務必為廣告類型指定 AdType.Video。

    myInterstitialAd.RequestAd(AdType.Video, myAppId, myAdUnitId);

    如果您想要顯示插播式橫幅廣告：需要廣告前約 5-8 秒，請使用 RequestAd 方法來預先擷取廣告。 這容許在顯示廣告前有足夠的時間要求並準備廣告。 請務必為廣告類型指定 AdType.Display。

    myInterstitialAd.RequestAd(AdType.Display, myAppId, myAdUnitId);

  8. 在您的程式碼中想要顯示插播式影片或插播式橫幅廣告的點，確認 InterstitialAd 已準備好顯示，然後使用 Show 方法顯示它。

    if (InterstitialAdState.Ready == myInterstitialAd.State)
{
    myInterstitialAd.Show();
}

  9. 定義 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.
}

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

HTML/JavaScript

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

  1. 在 Visual Studio 中，開啟您的專案。

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

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

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

  4. 在專案中 HTML 檔案的 <head> 區段中，在專案的 JavaScript 參考 default.css 和 default.js 之後，將參考新增至 ad.js。

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

  5. 在專案中的 .js 檔案中，宣告 InterstitialAd 物件和數個功能變數，其中包含插播式廣告的應用程式識別碼和廣告單元識別碼。 下列程式碼範例將 applicationId 和 adUnitId 功能變數指派給插播式廣告的測試值。

    注意

    每個 InterstitialAd 都有一個相對應的廣告單元，由我們的服務用來為控制項提供廣告，而每個廣告單元都包含廣告單元識別碼和應用程式識別碼。 在這些步驟中，您會將測試廣告單元識別碼和應用程式識別碼值指派給控制項。 這些測試值只能在應用程式的測試版本中使用。 將應用程式發佈至市集之前，您必須先將這些測試值取代為合作夥伴中心的即時值。

    var interstitialAd = null;
var applicationId = "d25517cb-12d4-4699-8bdc-52040c712cab";
var adUnitId = "test";

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

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

  7. 如果您想要顯示插播式影片廣告：需要廣告前約 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);
}

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

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

  9. 定義 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.
}

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

C++ (DirectX Interop)

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

  1. 在 Visual Studio 中，開啟您的專案。

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

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

  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);

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

    注意

    每個 InterstitialAd 都有一個相對應的廣告單元，由我們的服務用來為控制項提供廣告，而每個廣告單元都包含廣告單元識別碼和應用程式識別碼。 在這些步驟中，您會將測試廣告單元識別碼和應用程式識別碼值指派給控制項。 這些測試值只能在應用程式的測試版本中使用。 將應用程式發佈至市集之前，您必須先將這些測試值取代為合作夥伴中心的即時值。

    Platform::String^ myAppId = L"d25517cb-12d4-4699-8bdc-52040c712cab";
Platform::String^ myAdUnitId = L"test";

  5. 在您想要新增程式碼以顯示插播式廣告的 .cpp 檔案中，新增下列命名空間參考。 下列範例假設您要將程式碼新增至應用程式中的 DirectXPage.xaml.cpp 檔案。

    using namespace Microsoft::Advertising::WinRT::UI;

  6. 在啟動時執行的程式碼中 (例如，在頁面的建構函式中)，具現化 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);

  7. 如果您想要顯示插播式影片廣告：需要插播式廣告前約 30-60 秒，請使用 RequestAd 方法來預先擷取廣告。 這容許在顯示廣告前有足夠的時間要求並準備廣告。 請務必為廣告類型指定 AdType:Video。

    m_interstitialAd->RequestAd(AdType::Video, myAppId, myAdUnitId);

    如果您想要顯示插播式橫幅廣告：需要廣告前約 5-8 秒，請使用 RequestAd 方法來預先擷取廣告。 這容許在顯示廣告前有足夠的時間要求並準備廣告。 請務必為廣告類型指定 AdType:Display。

    m_interstitialAd->RequestAd(AdType::Display, myAppId, myAdUnitId);

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

    if ((InterstitialAdState::Ready == m_interstitialAd->State))
{
    m_interstitialAd->Show();
}

  9. 定義 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.
}

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

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

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

  2. 在合作夥伴中心中，前往 [應用程式內廣告] 頁面和 [建立廣告單元]。 針對廣告單元類型，根據您顯示的插播式廣告類型，選擇 [影片插播式] 或 [橫幅插播式]。 記下廣告單元識別碼和應用程式識別碼。

    注意

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

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

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

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

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

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

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

重要

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