Windows 用 Vungle SDK を統合する

David Kim

2024年09月17日 17:35

このガイドでは、Vungle SDK をアプリに組み込み、マネタイズを始める簡単な方法を説明します。このガイドではコードのサンプルが C# で記述されていますが、GitHub レポジトリから C#、C++、Visual Basic、DirectX+XAML のサンプルアプリファイルを入手できます。

はじめに

要件

統合を行うには、Vungle アカウントが必要です。お持ちでない場合は、このページでアカウントを作成し、アカウントに新しいユニバーサル Windows アプリを作成します。Vungle ダッシュボードで広告配置を設定する方法については、パブリッシャーダッシュボードの使用に関する記事の「アプリと広告配置を追加する」セクションを参照してください。
Windows 8.1 向けの開発には Visual Studio 2015 を使用してください。Visual Studio 2017 では Windows 8.1 のサポートを終了しています。
[戻る] ボタンはモバイルデバイスでサポートされていますが、PC (キーボード) ではサポートされていません。このため、UWP ビルドでは動作やユーザーエクスペリエンスが異なる場合があります。
テスト モードで広告が返ってこない場合は、ダッシュボードでアプリケーションをアクティブ モードに切り替えてください。

SDK をダウンロードする

手動統合オプションを選択した場合は、Windows 用 Vungle SDK を https://publisher.vungle.com/sdk/sdks/windows からダウンロードできます。

参照: サンプルアプリ

統合の際には、以下で提供されているサンプルアプリを参照してください (https://github.com/Vungle/Windows-SDK/tree/master)。

手順 1. Vungle SDK をプロジェクトに統合する

Vungle を Visual Studio プロジェクトに追加するには、NuGet (推奨) 統合を使用する方法、または手動で統合を行う方法の 2 つがあります。

方法 1. NuGet 統合 (推奨)

Visual Studio のソリューションエクスプローラーでプロジェクトの名前を右クリックし、[NuGet パッケージの管理] を選択します。
[参照] をクリックして「Vungle」と入力し、[Vungle SDK] を選択します。
[インストール] をクリックします。

方法 2. 手動での統合

Vungle ダッシュボードから Vungle Windows SDK をダウンロードします。
アーカイブを展開します。
Visual Studio で、使用するアプリケーションとプログラミング言語に適したテンプレートを使用して、新しいユニバーサル Windows プロジェクトを作成します。
ダウンロードした Vungle Windows SDK ファイルにプロジェクトの参照を追加します。
Vungle SDK には、2 つの VungleSDK.windmd ファイルが付属しています。1 つは Windows 10 のデプロイメント環境用のファイルで、もう 1つは Windows 8.1 のデプロイメント環境用のファイルです。抽出したディレクトリ内の適切な SDK を、Win10 または Win81 で使用してください。
プロジェクトの package.appxmanifest ファイルで、internetClient 機能が設定されていることを確認してください。新しいプロジェクトを作成するとき、デフォルトでインターネット (クライアント) 機能がオンになります。Visual Studio または手動での編集でこの機能を確認できます。
- Visual Studio の internetClient 機能を確認する手順:
  1. Visual Studio のソリューションエクスプローラーで [appxmanifest] をダブルクリックします。
  2. [機能] を選択します。
  3. [インターネット (クライアント)] オプションが選択されていることを確認します。
- 手動での編集で internetClient 機能を有効にするには、package.appxmanifeset ファイルを開き、internetClient というコードを Capabilities セクションに追加します。
```
<Capabilities>
    ...
    <Capability Name="internetClient" />
    ...
</Capabilities>
```

手順 2. `VungleSDK` 名前空間をインポートする

次にように VungleSDK 名前空間をインポートします。

using VungleSDK;

手順 3. `VungleAd` インスタンスを取得する

Vungle SDK v6.3.0 以降、VungleAd インスタンスは 1 つのパラメータ (Vungle アプリ ID) のみを取ります。

VungleAd sdkInstance;
string appID = “app_id”;
sdkInstance = AdFactory.GetInstance(appID);

上記の例では、appId を Vungle アプリ ID で置き換えます。キャッシュの最適化を開始できるようにするため、アプリが重要なコンポーネントの読み込みを完了したらすぐにこれらの初期化手順を実行することをお勧めします。

Vungle SDK v6.2.0 以前のバージョンの場合、VungleAd インスタンスには、Vungle アプリ ID の文字列と広告配置 ID の文字配列の 2 つのパラメータがあります。インスタンスを取得するときに既に含んでいた広告配置 ID のみを使用できます。

sdkInstance = AdFactory.GetInstance(appID, placementList);

手順 4. コードを追加する

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

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

UI スレッドに関する注意

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

await this.Dispatcher.RunAsync(CoreDispatcherPriority.Normal,
  new DispatchedHandler(() =>
  {
    // This block will be executed in the UI thread
  }
);

診断

このイベントハンドラーは、SDK が診断ログを出力するときに呼び出されます。

サンプルコード:

//Register event handler
sdkInstance.Diagnostic          += SdkInstance_Diagnostic;

...

// Event handler called when SDK wants to print diagnostic logs
private void SdkInstance_Diagnostic(object sender, DiagnosticLogEvent e)
{
  System.Diagnostics.Debug.WriteLine("Diagnostic - "
    + e.Level + " " 
    + e.Type + " " 
    + e.Exception + " "
    + e.Message);
}

// DEPRECATED - Use SdkInstance_OnAdEnd() instead 
private void SdkInstance_OnVideoView(object sender, AdViewEventArgs e) { }

`OnAdPlayableChanged`

OnAdPlayableChanged イベントに対し、イベントハンドラーを作成します。このイベントハンドラーは、広告再生可能状態が変更されたときに呼び出されます。広告配置用に広告を読み込んだ後に広告が使用可能になった場合、このイベントハンドラーがアクションを実行するまで待ちます。どの広告配置がイベントをトリガーしたかは、e.Placement を確認することで特定できます。

// Event handler for OnAdPlayableChanged event
private async void SdkInstance_OnAdPlayableChanged(object sender, AdPlayableEventArgs e)
{
  if (e.AdPlayable == true)
  {
    // e.Placement - placement ID in string
    // Run asynchronously on the UI thread
    await CoreApplication.MainView.Dispatcher.RunAsync(CoreDispatcherPriority.Normal,
      new DispatchedHandler(() => methodToRun(e.Placement)));
  }
}

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

sdkInstance.OnAdPlayableChanged += SdkInstance_OnAdPlayableChanged;

`OnInitCompleted`

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

サンプルコード:

//Register event handler
sdkInstance.OnInitCompleted     += SdkInstance_OnInitCompleted;

...

// OnInitCompleted
//   e.Initialized - true if initialization succeeded, false if failed
//   e.ErrorMessage - reason for failure when e.Initialized is false
private async void SdkInstance_OnInitCompleted(object sender, ConfigEventArgs e)
{
  var placementsInfo = "OnInitCompleted: " + e.Initialized;
  // Initilization was success
  if (e.Initialized == true)
  {
    // Print out list of placements
    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)";
    }
  }
  // Initilization failed
  else
  {
    placementsInfo += "\n\t" + e.ErrorMessage;
  }
  System.Diagnostics.Debug.WriteLine(placementsInfo);
  await this.Dispatcher.RunAsync(CoreDispatcherPriority.Normal, new DispatchedHandler(() =>
    NotifyInitialization(e.Initialized)));
}

`OnAdStart`

このイベントハンドラーは、広告の再生前に呼び出されます。BGM の一時停止などのアクションを実行できます。

サンプルコード:

//Register event handler
sdkInstance.OnAdStart           += SdkInstance_OnAdStart;

...

// OnAdStart
//   e.Id - Vungle app ID in string
//   e.Placement - placement ID in string
private void SdkInstance_OnAdStart(object sender, AdEventArgs e)
{
  System.Diagnostics.Debug.WriteLine("OnAdStart(" + e.Id + "): " + e.Placement);
}

`OnAdEnd`

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

サンプルコード:

//Register event handlers
sdkInstance.OnAdEnd             += SdkInstance_OnAdEnd;

...

// OnAdEnd
//   e.Id - Vungle app ID in string
//   e.Placement - placement ID in string
//   e.IsCompletedView- true when 80% or more of the video was watched
//   e.CallToActionClicked - true when the user has clicked download button on end card
//   e.WatchedDuration - DEPRECATED
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 統合を完了します。各広告フォーマットについては、以下の説明を参照してください。

広告を詳細にカスタマイズする

詳細設定の記事に記載されている手順に従い、GDPR、CCPA の実装、その他の多くの設定など、追加の構成オプションとのアプリの統合を詳細に設定します。

はじめに

要件

SDK をダウンロードする

参照: サンプル アプリ

手順 1. Vungle SDK をプロジェクトに統合する

方法 1. NuGet 統合 (推奨)

方法 2. 手動での統合

手順 2. VungleSDK 名前空間 をインポートする

手順 3. VungleAd インスタンスを取得する

手順 4. コードを追加する

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

UI スレッドに関する注意

診断

OnAdPlayableChanged

OnInitCompleted

OnAdStart

OnAdEnd

広告フォーマットを統合する

広告を詳細にカスタマイズする

Questions?

参照: サンプルアプリ

手順 2. `VungleSDK` 名前空間をインポートする

手順 3. `VungleAd` インスタンスを取得する

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

`OnAdPlayableChanged`

`OnInitCompleted`

`OnAdStart`

`OnAdEnd`