Vungle スタート ガイド - Windows SDK v.2.0+

このガイドでは、Vungle の SDK をアプリに組み込み、マネタイズを始める簡単な方法を説明します。

このガイドではコードのサンプルが C# で記述されていますが、GitHub レポジトリから C#、C++、Visual Basic、DirectX+XAML のサンプル アプリ ファイルを入手できます。

コンテンツ

始める前に

  • このガイドは Vungle Windows SDK 2.0 以降用です。Vungle Windows SDK バージョン 1.3.16 以下の組み込みガイドはこちらでご覧になれます。Vungle スタート ガイド - Windows SDK v. 1.0 - v.1.3.16
  • 組み込みには Vungle のアカウントが必要です。お持ちでない場合は、こちらのページから Vungle のアカウントを作成してください。
  • アプリをアカウントにまだ追加していない場合は、Vungle のダッシュボードにアクセスしてアプリをアカウントに追加します。「広告配置の設定とレポート作成」を参照してください。
  • Windows 8.1、Windows Phone 8.1 向けの開発には Visual Studio 2015 を使用してください。Visual Studio 2017 ではこれらのバージョンのサポートを終了しています。
  • [戻る] ボタンはモバイルでサポートされていますが、PC (キーボード) ではサポートされていません。このため、UWP ビルドでは動作やユーザー エクスペリエンスが異なる場合があります。
  • テスト モードで広告が返ってこない場合は、アプリケーションをアクティブ モードに切り替えてください。

SDK をダウンロードして VungleSDK をプロジェクトに追加する

  1. Vungle ダッシュボードから Vungle Windows SDK をダウンロードします。
  2. アーカイブを展開します。
  3. Visual Studio で、お使いのアプリケーションとプログラミング言語に適切なテンプレートを使って、新しいプロジェクトを作成します。
  4. ダウンロードした Vungle Windows SDK ファイルに、プロジェクトへの参照を追加します。
  5. 以下のように、プロジェクトの package.appxmanifest に「internetClient」機能があることを確認します。
    <Capabilities>
    ...
    <Capability Name="internetClient" />
    ...
    </Capabilities>
  6. VungleSDK 名前空間をインポートします。
    using VungleSDK;
    

VungleAd インスタンスを取得する

VungleAd インスタンスには、Vungle アプリ ID の文字列と広告配置 ID の文字列の配列の 2 つのパラメータがあります。インスタンスを取得するときに既に含んでいた広告配置 ID のみを使用できます。自動キャッシュされた広告配置が 1 つも含まれていない場合には、自動キャッシュでない広告配置の 1 つが自動キャッシュ対象として自動的に割り当てられます。

VungleAd sdkInstance;

string appID = “app_id”;
string[] placementArray = new string[]
{
  “placement_id_1”,
  “placement_id_2”,
  “placement_id_3”
};
sdkInstance = AdFactory.GetInstance(appID, placementArray);

上記の例では、app_id を Vungle アプリ ID で、placement_id_# をプロジェクトで使用する広告配置 ID で置き換えます。自動キャッシングを早めに開始できるよう、アプリが重要なコンポーネントの読み込みを完了するとすぐにこれらの初期化手順を実行することをおすすめします。

イベント ハンドラーを作成、登録する

OnAdPlayableChanged イベントに対し、イベント ハンドラーを作成します。このイベント ハンドラーは、広告再生可能状態が変更されたときに呼び出されます。どの広告配置がイベントをトリガーしたかは、e.Placement を確認することで特定できます。

// OnAdPlayableChanged イベントのイベント ハンドラー
private async void SdkInstance_OnAdPlayableChanged(object sender, AdPlayableEventArgs e)
{
  // e.Placement - 文字列の広告配置 ID
  // UI スレッドで非同期的に実行
  await CoreApplication.MainView.Dispatcher.RunAsync(CoreDispatcherPriority.Normal,
    new DispatchedHandler(() => methodToRun(e.Placement)));
}

このイベント ハンドラーを OnAdPlayableChanged イベントに登録します。

sdkInstance.OnAdPlayableChanged += SdkInstance_OnAdPlayableChanged;

広告配置用の広告を読み込む

自動キャッシュされる広告配置以外の広告配置では、最初に LoadAd を呼び出し、広告アセットをダウンロードするための十分な時間をおいてから、OnAdPlayableChanged が呼び出されるまで待つ必要があります。

sdkInstance.LoadAd(“placement_id”);

注意: 自動キャッシュされた広告配置は、PlayAdAsync が呼び出された後すぐに新しい広告アセットをダウンロードしようとします。このため、LoadAd を呼び出す必要はありません。

サンプル コード:

private void OnLevelStart(Object sender, RoutedEventArgs e)
{
  sdkInstance.LoadAd(“placement_id”);
}

広告を再生する

初期設定で広告を再生する:

sdkInstance.PlayAdAsync(new AdConfig(), “placement_id”);

サンプル コード:

private async void OnLevelComplete(Object sender, RoutedEventArgs e)
{
  await sdkInstance.PlayAdAsync(new AdConfig(), “placement_id”);
}

AdConfig オブジェクトを渡すと、再生する広告を任意でカスタマイズできます。

サンプル コード:

private async void PlayCustomizedAd(Object sender, RoutedEventArgs e)
{
  AdConfig adConfig = new AdConfig();

  adConfig.Orientation = DisplayOrientations.Portrait;
  adConfig.SoundEnabled = false;
  
  await sdkInstance.PlayAdAsync(adConfig, placement2);
}

カスタマイズ オプション

AdConfig オブジェクト インスタンスで利用できるプロパティは以下のとおりです。

オプション

デフォルト値
または型

説明

Orientation

AutoRotate

DisplayOrientations

Orientation.AutoRotate (デフォルト) は、デバイスの向きに合わせて広告を自動的に回転させます。

Orientation.Portrait は、広告を縦向きでのみ再生します。

Orientation.Landscape は、広告を横向きでのみ再生します。

注意: このオプションはモバイル アプリケーションにのみ適用されます。

SoundEnabled

true

bool

広告開始時のサウンドの状態を設定します。

true (デフォルト) の場合、音声はデバイスの音量とサウンド設定に従います。

false の場合、動画はミュートされた状態で始まりますが、ユーザーはサウンドの状態を変更できます。

BackButtonImmediatelyEnabled

false

bool

true の場合、ユーザーは [戻る] ボタンを使用して広告をすぐに終了することができます。

false (デフォルト) の場合、画面に [閉じる] ボタンが表示されるまで、ユーザーは [戻る] ボタンを使用して広告を終了することができません。

注意: このオプションはモバイル アプリケーションにのみ適用されます。

UserId

null

文字列

一意のユーザー ID をアプリケーションに渡し、このユーザーがインセンティブ広告の視聴による報酬の対象となることを確認します。

注意: この設定は報酬型広告配置にのみ適用されます。

IncentivizedDialogTitle

「この広告を閉じますか?」

文字列

インセンティブ広告をスキップするときに表示される確認メッセージのタイトルを設定します。

注意: この設定は報酬型広告配置にのみ適用されます。

IncentivizedDialogBody

「この広告をスキップしてもよろしいですか。報酬を受け取るには最後まで視聴する必要があります。」

文字列

インセンティブ広告をスキップするときに表示される確認メッセージの本文を設定します。

注意: この設定は報酬型広告配置にのみ適用されます。

IncentivizedDialogCloseButton

「閉じる」

 

文字列

インセンティブ広告をスキップするときに表示される確認メッセージの 'cancel' ボタンのテキストを設定します。

注意: この設定は報酬型広告配置にのみ適用されます。

IncentivizedDialogContinueButton

「続行」

文字列

インセンティブ広告をスキップするときに表示される確認メッセージの 'keep watching' ボタンのテキストを設定します。

注意: インセンティブ広告でない場合、この設定は適用されません。

Incentivized

-

非推奨

報酬対象構成は、ダッシュボードから広告配置レベルで設定することができます。「広告配置の設定とレポート作成」を参照してください。


注意:
Dynamic Template および Flex View 広告の SoundEnabledおよびインセンティブ ダイアログのオプションはダッシュボードで設定できます。プログラマティック構成は旧来の広告にのみ適用されます。

[閉じる] ボタンを表示する

広告を閉じるオプションをユーザーに表示するかどうかを管理するには、Vungle ダッシュボードにあるアプリケーションの詳細設定で、強制表示オプションを使用します。

イベント ハンドラーへのサブスクライブ

Windows SDK は、プログラムで処理できるイベントをいくつか発生させます。</p>これらのイベント ハンドラーを使用して、BGM の一時停止や再開などのアプリの機能を制御できます。

UI スレッドに関する注意

イベント リスナーはバックグラウンド スレッドで実行されるため、実行前に、イベント リスナーの結果発生した UI での操作や更新をメインの UI スレッドに渡す必要があります。次に挙げるのはその方法の例です。

await this.Dispatcher.RunAsync(CoreDispatcherPriority.Normal,
new DispatchedHandler(() =>
{ // このブロックは UI スレッドで実行されます
} );

VungleAd イベント ハンドラー

イベント ハンドラー

説明

OnInitCompleted

SDK の初期化が完了した直後に呼び出されます。前のセッションからダウンロードされた広告があるか確認する、または広告配置用の広告を読み込むことができます。

OnAdPlayableChanged

配置する広告の使用可能状況の変更について通知します。広告配置用に広告を読み込んだ後に広告が使用可能になった場合、このイベント ハンドラーがアクションを実行するまで待ちます。

OnAdStart

広告の再生前に呼び出されます。BGM の一時停止などのアクションを実行できます。

OnAdEnd

ユーザーがエンドカードを閉じ、アプリケーションに制御が戻ったときに呼び出されます。IsCompletedView または CallToActionClicked のいずれかが true である場合、ユーザーは広告を視聴したか、広告の中のダウンロード ボタンをクリックしています。この場合、報酬対象の広告の場合はユーザーが報酬を受け取ることになります。アプリの機能の再開などのアクションを実行できます。

Diagnostic

SDK が診断ログを出力するときに呼び出されます。

サンプル コード:

//イベント ハンドラーを登録する
sdkInstance.OnInitCompleted     += SdkInstance_OnInitCompleted;
sdkInstance.OnAdPlayableChanged += SdkInstance_OnAdPlayableChanged;
sdkInstance.OnAdStart           += SdkInstance_OnAdStart;
sdkInstance.OnAdEnd             += SdkInstance_OnAdEnd;
sdkInstance.Diagnostic          += SdkInstance_Diagnostic;

...

// OnInitCompleted
//   e.Initialized - 初期化が正常に完了した場合は true、失敗した場合は false
//   e.ErrorMessage - e.Initialized が false の場合の失敗の理由
private async void SdkInstance_OnInitCompleted(object sender, ConfigEventArgs e)
{
  var placementsInfo = "OnInitCompleted: " + e.Initialized;
  // 初期化が正常に完了しました
  if (e.Initialized == true)
  {
    // 広告配置のリストを出力します
    for (var i = 0; i < e.Placements.Length; i++)
    {
      placementsInfo += "\n\tPlacement" + (i + 1) + ": " + e.Placements[i].ReferenceId;
      if (e.Placements[i].IsAutoCached == true)
        placementsInfo += " (Auto-Cached)";
    }
  }
  // 初期化に失敗しました
  else
  {
    placementsInfo += "\n\t" + e.ErrorMessage;
  }
  System.Diagnostics.Debug.WriteLine(placementsInfo);
  await this.Dispatcher.RunAsync(CoreDispatcherPriority.Normal, new DispatchedHandler(() =>
    NotifyInitialization(e.Initialized)));
}

// OnAdPlayableAdPlayable
//   e.AdPlayable - 広告が再生可能な場合は true、そうでない場合は false
//   e.Placement  - 文字列の広告配置 ID
private async void SdkInstance_OnAdPlayableChanged(object sender, AdPlayableEventArgs e)
{
  System.Diagnostics.Debug.WriteLine("OnAdPlayable(" + e.Placement + ") - " + e.AdPlayable);
  await this.Dispatcher.RunAsync(CoreDispatcherPriority.Normal, new DispatchedHandler(() =>
    NotifyWatcher(e.AdPlayable, e.Placement)));
}

// OnAdStart
//   e.Id - 文字列の Vungle アプリ ID
//   e.Placement  - 文字列の広告配置 ID
private void SdkInstance_OnAdStart(object sender, AdEventArgs e)
{
  System.Diagnostics.Debug.WriteLine("OnAdStart(" + e.Id + "): " + e.Placement);
}

// OnAdEnd
//   e.Id - 文字列の Vungle アプリ ID
//   e.Placement  - 文字列の広告配置 ID
//   e.IsCompletedView- 動画が 80% 以上視聴された場合は true
//   e.CallToActionClicked - ユーザーがエンドカードのダウンロード ボタンをクリックした場合は true
//   e.WatchedDuration - 非推奨
private void SdkInstance_OnAdEnd(object sender, AdEndEventArgs e)
{
  System.Diagnostics.Debug.WriteLine("OnVideoEnd(" + e.Id + "): "
    + "\n\tPlacement: " + e.Placement
    + "\n\tIsCompletedView: " + e.IsCompletedView
    + "\n\tCallToActionClicked: " + e.CallToActionClicked
    + "\n\tWatchedDuration: " + e.WatchedDuration);
}

// SDK が診断ログを出力するときに呼び出されるイベント ハンドラー
private void SdkInstance_Diagnostic(object sender, DiagnosticLogEvent e)
{
  System.Diagnostics.Debug.WriteLine("Diagnostic - "
+ e.Level + " "
+ e.Type + " "
+ e.Exception + " "
+ e.Message); } // 非推奨 - SdkInstance_OnAdEnd() を代わりに使用してください private void SdkInstance_OnVideoView(object sender, AdViewEventArgs e) { }
他にご質問がございましたら、リクエストを送信してください

コメント