Pou's IT Life: UWP - Microsoft Universal Ad Client SDK

<Windows Phone - 調整新Advertising SDK的使用> 介紹過上一版本的使用方式，隨著 Dev Center 與 pubCenter 的整合，增加可同時加入不同 Ad Networks 的機制，讓開發者在自己的 App 裏面嵌入 Advertisement control 變得更加容易，更加上了 Video 廣告。

本篇將介紹怎麽使用新的 Microsoft Universal Ad Client SDK。

[開發準備]

1. 先安裝 Microsoft Advertising SDK (Ads in Apps)。
裏面包括：Microsoft Advertising 與 Ad mediation。

2. 擁有 Dev Center 或是 Pubcenter 的賬號，并且要設定好相關的付款方式（付款指的是 MS 匯錢給你）。

相關的設定可以參考<Windows Phone - 調整新Advertising SDK的使用>。
匯款使用的幣別不再全部使用美金，而是依照 DevCenter 或是 Pubcenter 設定的預設 Tax 國家。
如果您原本就有 Dev Center 與 Pubcenter 賬號在整合上遇到問題可以參考<pubCenter-Dev Center integration>。

3. 準備廣告使用的參數（AdUnitId, ApplicationId 與最新的 AdMediatorId）：
    a. 可以選擇到 Pubcenter 去建立 AdUnit 與 ApplicationId。(適用 Silverlight App 與 WP8.1 / Win8.1 App)
        請參考<開發免費版程式，就來加個廣告吧！- 2>或<Windows Phone - 調整新Advertising SDK的使用>。
    b. UWP, Universal App 或是已經上架在 Dev Center 的 App，可以直接在 Dev Center 中建立。
        步驟：參考<Monetize with ads>：
        a. 登入 Dev Center 并且進入 dashboard 選擇已經建立好的專案。
        b. 選擇 Monetization 下的 Monetize with ads，如下圖：

c. 依照 App 的畫面設計加入需要的 Adunit，例如：

在 Dev Center 建立的 Adunit 同樣被同步到 pubcenter 如下圖：

* Application ID：

* Ad Unit ID：

相關的整合可以另外參考：<pubCenter-Dev Center integration>的介紹。

4. 準備其他 Ad Networks 相關的帳號與廣告元件參數，例如：AdDuplex...等。

[注意]

Banner Ads 與 Interisital Ads 支援的國家或地區不完全一樣，詳細參考<Supported Markets for Microsoft Advertising>
Banner 跟 Video intersitial，在實作上使用的是不同的 class：

* Banner：使用 AdControl 或是 AdMediatorControl。(XAML Properties Example)
* Video interisitial：使用 InterstitialAd。(Interstitial Ad Sample Code in C# )

準備工作完成之後，往下開始説明如何在自己的 App 裏面加入廣告元件。

[加入廣告元件到 Apps]

加入廣告元件到 App 裏面有兩種元件：

AdControl 與 InterstitialAd (Microsoft.Advertising.WinRT.UI)
AdMediatorControl (Microsoft.AdMediator.Universal)
微軟新提供的 ad mediation 協助在 App 的廣告内容請求可以來自多個不同的 ad networks，達到廣告顯示的最佳化。
這裏提到的多個 ad networks，例如 Microsoft Advertising, AdDuplex, Smaato, ... 等，爲了讓顯示廣告不間斷地出現。

兩者差別：

AdControl 與 InterstitialAd 使用 AdUnitId 與 ApplicationId 代表僅有支援 Microsoft Advertising，
支援顯示類型包括：banner 與 interstitial ads。
AdMediatorControl 使用的是 MediatorId 可以同時支援多個已被設定在這個 Id 的 Ad Networks，
目前僅支援：banner。

更多詳細可參考<What is the difference: AdMediator or AdControl>。

往下接著分別介紹如何操作這些廣告元件。

先在專案裏面加入必要的參考元件，如下圖：

1. 利用 AdControl 加入廣告元件：
藉由 XAML 的方式會比較容易處理，如下：

<UI:AdControl Width="300" Height="250" 
              ApplicationId="d25517cb-12d4-4699-8bdc-52040c712cab" AdUnitId="10043121" 
              ErrorOccurred="AdControl_ErrorOccurred" />

   在使用 AdControl 時要特別處理它的 Event Handler，例如 ErrorOccurred，如果遇到沒有廣告或是錯誤要能處理，避免畫面空一塊。UI 標簽是加入 xmlns:UI="using:Microsoft.Advertising.WinRT.UI"。

   廣告要顯示的 size 有官方整理好的推薦，可參考<Supported Ad Sizes for Microsoft Advertising Banner Ads>，例如：Windows 10 Mobile 適用 300x50，Windows 10 適用 250x250，可以按照預計加入廣告的畫面使用對應的 size。

   如果要測試加入的廣告是否有正常，可以使用<Test Mode Values>裏面提供的值，但要記得上架前換成上述申請好的正式 Id。

2. 利用 InterstitialAd 加入廣告元件：
    參考<Interstitial Ads>的介紹，得知 InterstitialAd 跟 banner 不一樣，它是顯示全熒幕畫面的廣告内容，裏面可以顯示一些互動的内容，可能會是 Web，Video 或是其他類型，如下圖顯示的範例：

WhatIsAnInterstitial

IntersitialAd 目前不支援使用 XAML 的方式，需要寫程式碼去加入它。但是如果您有開發過自定義的 XAML Control，您可以將他好好包裝一下。

範例如下：

private InterstitialAd intersitialAdControl;

private void AddInterstitialAdControl()
{
 string adUnitId = "11389925";
 string applicationId = "d25517cb-12d4-4699-8bdc-52040c712cab";

 intersitialAdControl = new InterstitialAd();
 intersitialAdControl.AdReady += IntersitialAdControl_AdReady;
 intersitialAdControl.Cancelled += IntersitialAdControl_Cancelled;
 intersitialAdControl.Completed += IntersitialAdControl_Completed;
 intersitialAdControl.ErrorOccurred += IntersitialAdControl_ErrorOccurred;

 intersitialAdControl.RequestAd(AdType.Video, applicationId, adUnitId);
}

private void IntersitialAdControl_ErrorOccurred(object sender, AdErrorEventArgs e)
{
 // 需處理發生錯誤的狀況
 if (e.ErrorCode == Microsoft.Advertising.ErrorCode.NoAdAvailable)
 {
  // 這個是最常遇到的，這個時候就不要顯示廣告或是更換 InterstitialAd 的參數在做請求
 }
}

private void IntersitialAdControl_Completed(object sender, object e)
{
 // 當廣告影片播放完畢時被觸發
}

private void IntersitialAdControl_Cancelled(object sender, object e)
{
 // 當廣告播放到一半被取消時
 intersitialAdControl = null;
}

private void IntersitialAdControl_AdReady(object sender, object e)
{
 // 當 ready 的時候再顯示廣告内容
 if ((InterstitialAdState.Ready) == (intersitialAdControl.State))
 {
  intersitialAdControl.Show();
 }
}

3. 利用 AdMediatorControl 加入廣告元件：
AdMediatorControl 屬於 Microsoft.AdMediator.Universal 的元件，使用時會搭配 Ad Mediator 來設定要支援的 Ad Networks。
Ad Mediator 衹有支援 UWP (for Win10) 的專案才能使用這樣的功能。如下圖：

如果無法使用請參考<Install the Microsoft Universal Ad Client SDK>重新安裝 SDK。

往下説明怎麽使用它：

3-1. 先在 XAML 中加入 AdMediatorControl 元件，如下範例：

<Universal:AdMediatorControl x:Name="AdMediator_826892"
                             Id="AdMediator-Id-DD31B182-A545-46FF-AA64-C6A247649C15"
                             Width="300" Height="50" />

要記得加入 xmlns:Universal="using:Microsoft.AdMediator.Universal"，

這裏使用的是 Id 而不是 AdUnitId 與 ApplicationId，主要是 Ad Mediator 工具在設定多個 Ad Networks 之後會建立一個 Id。
由於 AdMediatorControl 目前衹能顯示 Banner，所以記得要參考<Adjust size and position>調整適合的呈現樣式。

3-2. 利用 Ad Mediator 設定支援的 Ad Networks：
加入好 AdMediatorControl 後，接著在 Visual Studio 中對專案加入 Connected Service，并且選擇 Ad Mediator。

如果看到衹有 Microsoft Advertisting 的話，可以按下 selecte ad networks 加入目前支援的 AdDuplex。

接著選擇要 Ad Network 后，按下 configure 設定必要的關鍵參數，如下圖：

AdDuplex

如果沒有 Ad 的必要資料，請先到 AdDuplex 建立賬號并且建立一個 App，如下圖：

并且建立 AdUnit，可以建立 Banner 或是 Interstitial Ad。
Microsoft Advertising

完成設定之後按下加入會看到專案中多了一個新的檔案：AdMediator.config。内容如下：

<?xml version="1.0" encoding="utf-8"?>
<AdMediatorConfiguration xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <BaseConfiguration>
    <AdAdapters>
      <AdAdapterInfo>
        <Metadata>
          <Property>
            <Key>WApplicationId</Key>
            <Value>d25517cb-12d4-4699-8bdc-52040c712cab</Value>
          </Property>
          <Property>
            <Key>MApplicationId</Key>
            <Value>3f83fe91-d6be-434d-a0ae-7351c5a997f1</Value>
          </Property>
        </Metadata>
        <Name>MicrosoftAdvertising</Name>
        <Weight>1</Weight>
      </AdAdapterInfo>
      <AdAdapterInfo>
        <Metadata>
          <Property>
            <Key>AppKey</Key>
            <Value>53f4d9ea-e88e-4986-9f06-5b4b594fd0e4</Value>
          </Property>
        </Metadata>
        <Name>AdDuplex</Name>
        <Weight>1</Weight>
      </AdAdapterInfo>
    </AdAdapters>
    <AdControlConfigurations>
      <AdControlConfiguration>
        <AdAdapters>
          <AdAdapterInfo>
            <Metadata>
              <Property>
                <Key>WAdUnitId</Key>
                <Value>10043121</Value>
              </Property>
              <Property>
                <Key>MAdUnitId</Key>
                <Value>10865270</Value>
              </Property>
            </Metadata>
            <Name>MicrosoftAdvertising</Name>
          </AdAdapterInfo>
          <AdAdapterInfo>
            <Metadata>
              <Property>
                <Key>AdUnitId</Key>
                <Value>185759</Value>
              </Property>
            </Metadata>
            <Name>AdDuplex</Name>
          </AdAdapterInfo>
        </AdAdapters>
        <Id>AdMediator-Id-DD31B182-A545-46FF-AA64-C6A247649C15</Id>
        <Name>AdMediator_826892</Name>
      </AdControlConfiguration>
    </AdControlConfigurations>
  </BaseConfiguration>
  <RefreshRate>30</RefreshRate>
  <SchemaVersion>2.0.1</SchemaVersion>
  <UpdatedDateTime>2016-02-17T16:29:56.6553327Z</UpdatedDateTime>
  <UseRoundRobin>true</UseRoundRobin>
</AdMediatorConfiguration>

可以看到 Id 則是 XAML中的那個 Id，這個設定檔案衹能加入一個 AdMediatorControl，代表 App 衹能設定一個 AdMediatorControl。
執行的結果如下圖：

瞭解加入與設定 Ad Medaitor 之後，接著説明如何在程式中調整已經被加入 Ad Network 的顯示與相關參數。

參考<Select and manage your ad networks>瞭解目前支援的類型：

除了要知道有哪些支援的類型之外，更重要的是要注意每一個 Ad Network 可以是被設定的參數。
這些參數非常重要，它們會影響廣告的顯示與投放的内容：
舉例 Microsoft Advertising 與 AdDuplex，如下圖：

并不是所有的參數都可以在 UWP 下使用，詳細請參考<Select and manage your ad networks>中的 Specific parameters and details for each network。

處理 AdMediatorControl 的事件：

// add this during initialization of your app

    AdMediator_Bottom.AdSdkError += AdMediator_Bottom_AdError;
    AdMediator_Bottom.AdMediatorFilled += AdMediator_Bottom_AdFilled;
    AdMediator_Bottom.AdMediatorError += AdMediator_Bottom_AdMediatorError;
    AdMediator_Bottom.AdSdkEvent += AdMediator_Bottom_AdSdkEvent;

// and then add these functions

void AdMediator_Bottom_AdSdkEvent(object sender, Microsoft.AdMediator.Core.Events.AdSdkEventArgs e)
{
    Debug.WriteLine("AdSdk event {0} by {1}", e.EventName, e.Name);}

void AdMediator_Bottom_AdMediatorError(object sender, Microsoft.AdMediator.Core.Events.AdMediatorFailedEventArgs e)
{
    Debug.WriteLine("AdMediatorError:" + e.Error + " " + e.ErrorCode );
    // if (e.ErrorCode == AdMediatorErrorCode.NoAdAvailable)
    // AdMediator will not show an ad for this mediation cycle
}

void AdMediator_Bottom_AdFilled(object sender, Microsoft.AdMediator.Core.Events.AdSdkEventArgs e)
{
    Debug.WriteLine("AdFilled:" + e.Name);
}

void AdMediator_Bottom_AdError(object sender, Microsoft.AdMediator.Core.Events.AdFailedEventArgs e)
{
    Debug.WriteLine("AdSdkError by {0} ErrorCode: {1} ErrorDescription: {2} Error: {3}", e.Name, e.ErrorCode, e.ErrorDescription, e.Error);
}

指定 Ad Network 請求的 timeout 時間：
可設定請求 timeout 時間在 2~60 秒之間，如果超過會自動換另一個 Ad Network 的請求。預設是 15 秒。
Pause, resume, and disable ad mediation：
針對 AdMediatorControl 的廣告如果想要暫停或繼續都有對應的 methods。

Handle unhandled exceptions from ad networks：
這個一定要特別處理，因爲那些 Ad networks 發生問題是不可預測的，所以一定要加入這個判斷。

public App()
{
 Microsoft.ApplicationInsights.WindowsAppInitializer.InitializeAsync(
  Microsoft.ApplicationInsights.WindowsCollectors.Metadata |
  Microsoft.ApplicationInsights.WindowsCollectors.Session);
 this.InitializeComponent();
 this.Suspending += OnSuspending;
 UnhandledException += App_UnhandledException;
}

private void App_UnhandledException(object sender, UnhandledExceptionEventArgs e)
{
 if (e != null)
 {
  Exception exception = e.Exception;
  if (exception is NullReferenceException && exception.ToString().ToUpper().Contains("SOMA"))
  {
   Debug.WriteLine("Handled Smaato null reference exception {0}", exception);
   e.Handled = true;
   return;
  }
 }
 // APP SPECIFIC HANDLING HERE
 if (Debugger.IsAttached)
 {
  // An unhandled exception has occurred; break into the debugger
  Debugger.Break();
 }

}

上面這個處理 UnhandledException 的代碼可以直接貼到專案的 App.xaml.cs 中，這個是節錄與<Add and use the ad mediator control>的内容，官方文件説明一定要處理這個問題。

[補充]

AdControl 需要處理的 Events，詳細參考<AdControl Events in C#>。
參考<Advertising performance report>瞭解廣告目前投遞狀況與用戶點擊的數量等相關的報告。
相關 AdMediatorControl 的操作可參考<Add and use the ad mediator control>。

[範例程式]

MediaAdvertisingSample

======
寫 App 除了自己工作需要之外，開發自己的 App 不想辦法加上一些廣告讓自己有收入，要怎麽有動力繼續開發與買新的設備呢？快爲自己的 App 加上廣告吧。希望大家荷包多少有補充到。謝謝。

References：
〉Monetize your apps with ads （安裝位置）
〉Microsoft Advertising SDK (Ads in Apps) (最完整的資料)
〉Microsoft Advertising SDK Libraries for XAML or JavaScript （重要）
〉Add and use the ad mediator control / Test Mode Values / Supported Ad Sizes for Microsoft Advertising Banner Ads （重要）
〉Add ads to apps with Microsoft Advertising
〉Monetize your app & Install the Universal Ad Client SDK
〉pubCenter-Dev Center integration
〉New advertising features and walkthrough of using Microsoft ads and mediation
〉Select and manage your ad networks (各家廣告比較表)
〉Guidelines and best practices for banner ads
〉Best practices for interstitial ads
〉Monetize and Promote your Universal Windows App with Ads [Channel 9]
〉測試您的廣告流量分配實作 & 新增和使用廣告流量分配者控制項
〉Troubleshoot ad mediation

Pou's IT Life

2015/12/31

UWP - Microsoft Universal Ad Client SDK

沒有留言:

張貼留言