原生廣告

發行項
04/01/2024

警告

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

原生廣告是以元件為基礎的廣告格式，其中每一項廣告創意 (例如標題、影像、描述和喚起行動文字) 都會當做個別元素傳送到您的應用程式。您可以使用自己的字型、色彩、動畫和其他 UI 元件，將這些元素整合到您的應用程式中，結合搭配成適合您應用程式外觀和風格的低干擾度使用者體驗，同時從廣告中賺取高收益。

對於廣告客戶來說，原生廣告提供高效能的放置位置，因為廣告體驗已緊密整合到應用程式中，因此使用者傾向於更常與這些類型的廣告互動。

注意

原生廣告目前僅支援 Windows 10 和 Windows 11 的 XAML 型 UWP 應用程式。已規劃在未來的 Microsoft Advertising SDK 版本支援使用 HTML 和 JavaScript 撰寫的 UWP 應用程式。

必要條件

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

將原生廣告整合到應用程式

請遵循這些指示，將原生廣告整合到您的應用程式，並確認您的原生廣告實作可顯示測試廣告。

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

注意

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

注意

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

在啟動時執行的程式碼中 (例如，在頁面的建構函式中)，具現化 NativeAdsManagerV2 物件，並將物件的 AdReady 事件處理程式和 ErrorOccurred 事件連接。

myNativeAdsManager = new NativeAdsManagerV2(myAppId, myAdUnitId);
myNativeAdsManager.AdReady += MyNativeAd_AdReady;
myNativeAdsManager.ErrorOccurred += MyNativeAdsManager_ErrorOccurred;

當您準備好要顯示原生廣告時，請呼叫 RequestAd 方法來擷取廣告。
```
myNativeAdsManager.RequestAd();
```

當原生廣告可供您的應用程式使用時，會呼叫 AdReady 事件處理程式，代表原生廣告的 NativeAdV2 物件會傳遞至 e 參數。使用 NativeAdV2 屬性來取得原生廣告的每個元素，並在您的頁面上顯示這些元素。請務必也呼叫 RegisterAdContainer 方法來註冊作為原生廣告容器的 UI 元素，這是正確追蹤廣告曝光和點擊次數的必要條件。

注意

原生廣告的某些元素是必要的，而且必須一律顯示在您的應用程式中。如需詳細資訊，請參閱原生廣告的指導方針。

例如，假設您的應用程式包含 MainPage (或其他頁面) 搭配下列 StackPanel。此 StackPanel 包含一系列控制項，可顯示原生廣告的不同元素，包括標題、描述、影像、贊助商文字，以及會顯示行動呼籲文字的按鈕。

<StackPanel x:Name="NativeAdContainer" Background="#555555" Width="Auto" Height="Auto"
            Orientation="Vertical">
    <Image x:Name="AdIconImage" HorizontalAlignment="Left" VerticalAlignment="Center"
           Margin="20,20,20,20"/>
    <TextBlock x:Name="TitleTextBlock" HorizontalAlignment="Left" VerticalAlignment="Center"
           Text="The ad title will go here" FontSize="24" Foreground="White" Margin="20,0,0,10"/>
    <TextBlock x:Name="DescriptionTextBlock" HorizontalAlignment="Left" VerticalAlignment="Center"
               Foreground="White" TextWrapping="Wrap" Text="The ad description will go here"
               Margin="20,0,0,0" Visibility="Collapsed"/>
    <Image x:Name="MainImageImage" HorizontalAlignment="Left"
           VerticalAlignment="Center" Margin="20,20,20,20" Visibility="Collapsed"/>
    <Button x:Name="CallToActionButton" Background="Gray" Foreground="White"
            HorizontalAlignment="Left" VerticalAlignment="Center" Width="Auto" Height="Auto"
            Content="The call to action text will go here" Margin="20,20,20,20"
            Visibility="Collapsed"/>
    <StackPanel x:Name="SponsoredByStackPanel" Orientation="Horizontal" Margin="20,20,20,20">
        <TextBlock x:Name="SponsoredByTextBlock" Text="The ad sponsored by text will go here"
                   FontSize="24" Foreground="White" Margin="20,0,0,0" HorizontalAlignment="Left"
                   VerticalAlignment="Center" Visibility="Collapsed"/>
        <Image x:Name="IconImageImage" Margin="40,20,20,20" HorizontalAlignment="Left"
               VerticalAlignment="Center" Visibility="Collapsed"/>
    </StackPanel>
</StackPanel>

下列程式碼範例示範 AdReady 事件處理程式，其顯示 StackPanel 中控制項的原生廣告每個元素，然後呼叫 RegisterAdContainer 方法註冊 StackPanel。此程式碼假設它是從包含 StackPanel 頁面的程式碼後置檔案執行。

void MyNativeAd_AdReady(object sender, NativeAdReadyEventArgs e)
{
    NativeAdV2 nativeAd = e.NativeAd;

    // Show the ad icon.
    if (nativeAd.AdIcon != null)
    {
        AdIconImage.Source = nativeAd.AdIcon.Source;

        // Adjust the Image control to the height and width of the 
        // provided ad icon.
        AdIconImage.Height = nativeAd.AdIcon.Height;
        AdIconImage.Width = nativeAd.AdIcon.Width;
    }

    // Show the ad title.
    TitleTextBlock.Text = nativeAd.Title;

    // Show the ad description.
    if (!string.IsNullOrEmpty(nativeAd.Description))
    {
        DescriptionTextBlock.Text = nativeAd.Description;
        DescriptionTextBlock.Visibility = Visibility.Visible;
    }

    // Display the first main image for the ad. Note that the service
    // might provide multiple main images. 
    if (nativeAd.MainImages.Count > 0)
    {
        NativeImage mainImage = nativeAd.MainImages[0];
        BitmapImage bitmapImage = new BitmapImage();
        bitmapImage.UriSource = new Uri(mainImage.Url);
        MainImageImage.Source = bitmapImage;

        // Adjust the Image control to the height and width of the 
        // main image.
        MainImageImage.Height = mainImage.Height;
        MainImageImage.Width = mainImage.Width;
        MainImageImage.Visibility = Visibility.Visible;
    }

    // Add the call to action string to the button.
    if (!string.IsNullOrEmpty(nativeAd.CallToActionText))
    {
        CallToActionButton.Content = nativeAd.CallToActionText;
        CallToActionButton.Visibility = Visibility.Visible;
    }

    // Show the ad sponsored by value.
    if (!string.IsNullOrEmpty(nativeAd.SponsoredBy))
    {
        SponsoredByTextBlock.Text = nativeAd.SponsoredBy;
        SponsoredByTextBlock.Visibility = Visibility.Visible;
    }

    // Show the icon image for the ad.
    if (nativeAd.IconImage != null)
    {
        BitmapImage bitmapImage = new BitmapImage();
        bitmapImage.UriSource = new Uri(nativeAd.IconImage.Url);
        IconImageImage.Source = bitmapImage;

        // Adjust the Image control to the height and width of the 
        // icon image.
        IconImageImage.Height = nativeAd.IconImage.Height;
        IconImageImage.Width = nativeAd.IconImage.Width;
        IconImageImage.Visibility = Visibility.Visible;
    }

    // Register the container of the controls that display
    // the native ad elements for clicks/impressions.
    nativeAd.RegisterAdContainer(NativeAdContainer);
}

定義 ErrorOccurred 事件的事件處理程式，以處理與原生廣告相關的錯誤。下列範例會在測試期間將錯誤資訊寫入 Visual Studio [輸出] 視窗。

private void MyNativeAdsManager_ErrorOccurred(object sender, NativeAdErrorEventArgs e)
{
    System.Diagnostics.Debug.WriteLine("NativeAd error " + e.ErrorMessage +
        " ErrorCode: " + e.ErrorCode.ToString());
}

編譯並執行應用程式，以使用測試廣告來查看它。

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

確認原生廣告實作成功可顯示測試廣告之後，請遵循這些指示來設定您的應用程式以顯示真實廣告，並將更新的應用程式提交至 Store。

請確定您的原生廣告實作遵循我們的原生廣告指導方針。
在合作夥伴中心中，前往 [應用程式內廣告] 頁面和 [建立廣告單元]。針對廣告單元類型，指定 Native。記下廣告單元識別碼和應用程式識別碼。

注意

測試廣告單元和即時 UWP 廣告單元的應用程式識別碼值格式不同。測試應用程式識別碼值為 GUID。當您在合作夥伴中心建立即時 UWP 廣告單元時，廣告單元的應用程式識別碼值一律符合您應用程式的 Store ID (例如：Store ID 值看起來像 9NBLGGH4R315)。
您可以選擇啟用原生廣告的廣告流量分配，方法是在 [應用程式內廣告] 頁面上的 [流量分配設定] 區段中配置設定。廣告流量分配可讓您透過顯示來自多個廣告網路的廣告，將廣告收入和應用程式促銷功能最大化。
在您的程式碼中，將測試廣告單元值 (即 NativeAdsManagerV2 建構函式的 applicationId 和 adUnitId 參數) 取代為在合作夥伴中心產生的即時值。
使用合作夥伴中心將您的應用程式提交至市集。
在合作夥伴中心檢閱您的廣告績效報告。

管理應用程式中多個原生廣告的廣告單位

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

重要

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

共用方式為

原生廣告

必要條件

將原生廣告整合到應用程式

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

管理應用程式中多個原生廣告的廣告單位

意見反應

其他資源

共用方式為

原生廣告

必要條件

將原生廣告整合到應用程式

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

管理應用程式中多個原生廣告的廣告單位

相關主題

意見反應

其他資源