原生廣告

  • 發行項

警告

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

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

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

注意

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

必要條件

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

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

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

    注意

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

  2. 如果您的專案以 [任何 CPU] 為目標，請更新您的專案以使用架構特定的組建輸出 (例如 x86)。 如果您的專案以 [任何 CPU] 為目標，您將無法在下列步驟中成功新增 Microsoft Advertising SDK 的參考。 如需詳細資訊，請參閱在專案中以任何 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;
using Windows.UI.Xaml.Media.Imaging;

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

    注意

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

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

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

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

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

    myNativeAdsManager.RequestAd();

  8. 當原生廣告可供您的應用程式使用時，會呼叫 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);
}

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

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

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

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

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

  1. 請確定您的原生廣告實作遵循我們的 原生廣告指導方針。

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

    注意

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

  3. 您可以選擇啟用原生廣告的廣告流量分配，方法是在 [應用程式內廣告] 頁面上的 [流量分配設定] 區段中配置設定。 廣告流量分配可讓您透過顯示來自多個廣告網路的廣告，將廣告收入和應用程式促銷功能最大化。

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

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

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

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

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

重要

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