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

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

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

目次

EU 一般データ保護規則 (GDPR) に準拠するための推奨事項

5 月 25 日より、欧州連合で一般データ保護規則 (GDPR) が施行されました。開発者は、以下に示すいずれかの方法で GDPR に準拠する必要があります。

  • 方法 1 (推奨): パブリッシャーが、ユーザー レベルで GDPR 同意プロセスを管理し、ユーザーによる選択内容を Vungle に伝える。これを行うには、開発者が独自のメカニズムを使用してユーザーから同意を取得し、Vungle API を使用して、ユーザーの同意状況の更新や照会を実行します。詳しくは、「GDPR に準拠するための推奨手順」を参照してください。

  • 方法 2: 広告を表示するための要件の処理を Vungle に委任する。この方法の場合、欧州のユーザーに広告を表示する前に、同意ダイアログが表示されます。それ以降は、ユーザーが広告の表示に同意したか拒否したかがシステムに記憶されることになります。

はじめに

  • これは、バージョン 5.3.2 以降の Vungle Windows SDK 用のガイドです。バージョン 1.3.16 以前の Vungle Windows SDK の統合ガイドについては、「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 をプロジェクトに追加する

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

方法 1. NuGet 統合

  1. Visual Studio で [プロジェクト] を右クリックし、[NuGet パッケージの管理] を選択します。
  2. [参照] をクリックして「Vungle」と入力し、[Vungle SDK] を選択して [インストール] をクリックします。

方法 2. 手動での統合

  1. Vungle ダッシュボードから Vungle Windows SDK をダウンロードします。
  2. アーカイブを展開します。
  3. Visual Studio で、使用するアプリケーションとプログラミング言語に適したテンプレートを使用して、新しいプロジェクトを作成します。
  4. ダウンロードした Vungle Windows SDK ファイルに、プログラム用の参照を追加します。

Vungle SDK には、2 つの VungleSDK.windmd ファイルが付属しています。1 つは Windows 10 のデプロイメント環境用のファイルで、もう 1つは Windows 8.1 のデプロイメント環境用のファイルです。抽出したディレクトリ内の適切な SDK を、Win10 または Win81 で使用してください。

internetClient 機能

プロジェクトの package.appxmanifest ファイルで、internetClient 機能が設定されていることを確認してください。

Visual Studio

  1. ソリューション エクスプローラーで [appxmanifest ] をダブルクリックします。
  2. [機能] を選択します。
  3. [インターネット (クライアント)] オプションが選択されていることを確認します。

手動での編集

package.appxmanifeset ファイルを開き、internetClient というコードを Capabilities セクションに追加します。

<Capabilities>
...
<Capability Name="internetClient" />
...
</Capabilities>

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 を確認することで特定できます。

// Event handler for OnAdPlayableChanged event private async void SdkInstance_OnAdPlayableChanged(object sender, AdPlayableEventArgs e) { // 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; 

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

自動キャッシュされる広告配置以外の広告配置では、最初に 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 オブジェクト インスタンスで利用できるプロパティは以下のとおりです。

注意: 報酬対象の広告は、インセンティブ広告として参照されることがあります。どちらの場合も、同等な広告のことを示しています。SDK のコードと Reporting API では、「インセンティブ」を使用します。

オプション

デフォルト値/
タイプ

説明

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

-

非推奨

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


注:
SoundEnabled のオプションと、Dynamic Template 広告と Flex View 広告用のインセンティブ ダイアログは、ダッシュボード上で設定することができます。プログラム経由での設定は、以前の広告にのみ適用されます。

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

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

EU 一般データ保護規則 (GDPR) に準拠するための推奨手順

// To set the user’s consent status as opted in: sdkInstance.UpdateConsentStatus(VungleConsentStatus.VungleConsentAccepted); // To set the user’s consent status as opted out: sdkInstance.UpdateConsentStatus(VungleConsentStatus.VungleConsentDenied); // To find out what the user’s current consent status is: // This will return null if the GDPR Consent status has not been set // Otherwise, it will return VungleConsentStatus.VungleConsentAccepted or // VungleConsentStatus.VungleConsentDenied UpdateConsentStatus? currentStatus = sdkInstance.GetCurrentConsentStatus(); 

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

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

UI スレッドに関する注意

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

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

VungleAd イベント ハンドラー

イベント ハンドラー

説明

OnInitCompleted

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

OnAdPlayableChanged

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

OnAdStart

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

OnAdEnd

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

Diagnostic

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

サンプル コード:

//Register event handlers sdkInstance.OnInitCompleted += SdkInstance_OnInitCompleted; sdkInstance.OnAdPlayableChanged += SdkInstance_OnAdPlayableChanged; sdkInstance.OnAdStart += SdkInstance_OnAdStart; sdkInstance.OnAdEnd += SdkInstance_OnAdEnd; sdkInstance.Diagnostic += SdkInstance_Diagnostic; ... // 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))); } // OnAdPlayableAdPlayable // e.AdPlayable - true if an ad is available to play, false otherwise // e.Placement - placement ID in string 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 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 // 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); } // 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) { }

ネイティブ Flex 広告の再生

Vungle Windows SDK 5.1.0+ は新しいネイティブ Flex 広告機能をサポートします。VungleAdControl は、AdConfig.AdContainer プロパティを介してカスタム コンテナを Vungle SDK に渡し、ホスト アプリケーションの Container.Content のコンテンツを管理することによって、動画広告をネイティブ フォーマットで実現します。

ネイティブ Flex 広告の要件

  • Windows SDK 5.1.0+
  • Windows 10 UWP

アカウント マネージャーに相談するか、tech-support@vungle.com に連絡してネイティブ Flex 広告配置を設定してください。

ネイティブ Flex 広告の UI の設定 - XAML

VungleAdControl は、Vungle アプリ ID、アプリ内で使用されるすべての広告配置 ID、特定のネイティブ Flex ビューまたはフィード広告配置の広告配置 ID で宣言しなければなりません。報酬型広告配置で使用される UserIdもここで設定できます。

サンプル コード:

<Grid
<UI:VungleAdControl x:Name="vungleEmbedded"
Height="200"
Width="300"
AppID="vungle_app_id"
Placements="placement_id_1,placement_id_2,native_flex_id"
Placement = "native_flex_id"
UserId="vungle_test_user">
<TextBlock x:Name="Vungle Native Flex Ad"/>
</UI:VungleAdControl>
</Grid>

ネイティブ Flex 広告を読み込む

ネイイティブ Flex 広告配置を使用して広告を読み込むのは、フルスクリーン広告を読み込むのとまったく同じです。

サンプル コード:

sdkInstance.LoadAd(“native_flex_id”); 

ネイティブ Flex 広告を再生

ネイティブ Flex 広告配置を使用して広告を再生するのは、フルスクリーン広告の再生と同様ですが、サウンドを無効にして広告を開始するなど、カスタマイズがある場合には .xaml またはダッシュボード上で設定する必要があります。

サンプル コード:

await vungleEmbedded.PlayAdAsync();

ネイティブ Flex 広告を閉じる

ユーザーは、ネイティブ Flex 広告を閉じることなく、動画の再生を停止することができます。これは、ネイティブ Flex 広告の特性です。そのため、動画が画面に表示されなくなったら、広告を破棄するように SDK に指示する必要があります。これを行うため、ネイティブ Flex 広告を終了する 2 つのメソッドが導入されました。

  • 指定された広告配置 ID を使用して広告を即時に終了する場合は、CloseFlexViewAd(String placementId) メソッドを使用します。

  • 指定された時間 (秒単位) が経過してから対象の配置広告を終了する場合は、SetFlexViewCloseTimeInSec(String placementId, int seconds) メソッドを使用します。

ネイティブ Flex 広告のイベント ハンドラー

よりスムーズなユーザー エクスペリエンスのために、フルスクリーン広告とネイティブ広告の異なる動作を管理するために、独立したイベント ハンドラーを登録することを考慮してください。

サンプル コード:

vungleEmbedded.OnAdStart += (sender, arg) => { ... } vungleEmbedded.OnAdEnd += (sender, arg) => { ... } await vungleEmbedded.PlayAdAsync(); 
他にご質問がございましたら、リクエストを送信してください

コメント