Vungle - Windows SDK v.5 시작하기

이 설명서를 통해 SDK를 앱에 빠르게 통합하고 수익을 창출하십시오.

이 설명서에 사용된 코드 샘플은 C#이지만, GitHub 저장소에서 C#, C++, Visual Basic 및 DirectX+XAML 샘플 앱 파일이 제공됩니다.

목차

시작하기 전에

  • 이 설명서는 Vungle Windows SDK 5.3.2 이상을 대상으로 합니다. Vungle Windows SDK 버전 1.3.16 이하에 대한 통합 가이드는 Vungle - Windows SDK v 1.0 - v.1.3.16 시작하기를 참고하십시오.
  • 통합하려면 Vungle 계정이 필요하므로 계정이 없다면 Vungle 계정을 생성하십시오.
  • 아직 Vungle 계정을 만들지 않은 경우에는 대시보드로 이동하여 앱을 계정에 추가합니다. Vungle 대시보드에서 플레이스먼트를 설정하는 방법에 대해 알아보려면 플레이스먼트 설정 및 리포팅를 참고하십시오.
  • Windows 8.1 및 Windows Phone 8.1용으로 개발할 경우 Visual Studio 2015를 사용해야 합니다. Visual Studio 2017는 해당 버전을 지원하지 않습니다.
  • 모바일에서는 뒤로 버튼이 지원되지만 PC(키보드)에서는 지원되지 않습니다. 이로 인해 UWP 빌드의 동작 및 사용자 환경이 달라질 수 있습니다.
  • 테스트 모드에서 광고가 반환되지 않으면 어플리케이션을 활성 모드로 전환하십시오.

Vungle SDK 다운로드 및 프로젝트에 VungleSDK 추가

NuGet 사용 또는 수동 통합으로 Vungle을 Visual Studio 프로젝트에 추가할 수 있습니다.

옵션 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에는 Windows 10 또는 8.1 개발용 등 2개의 VungleSDK.windmd 파일이 있습니다. 압축을 푼 디렉토리인 Win10 또는 Win81에서 올바른 SDK를 사용하십시오.

InternetClient 기능

프로젝트에 package.appxmanifest 파일의 internetClient 기능이 있는지 확인합니다.

Visual Studio

  1. 솔루션 탐색기에서 appxmanifest 을(를) 두 번 클릭합니다.
  2. 기능 선택
  3. 인터넷(클라이언트) 옵션이 선택되어 있는지 확인하십시오.

수동 편집

package.appxmanifeset 파일을 열고 internetClient기능 섹션에 추가합니다.

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

VungleSDK 네임스페이스 가져 오기

using VungleSDK;

VungleAd 인스턴스 받기

VungleAd 인스턴스에 사용되는 매개 변수는 Vungle 앱 ID의 문자열과 플레이스먼트 ID의 문자열 배열입니다. 인스턴스을 받을 때 포함했던 플레이스먼트 ID만 사용할 수 있습니다. 자동 캐시된 플레이스먼트가 포함되어 있지 않으면 SDK에서 자동 캐시되지 않는 플레이스먼트 중 하나를 자동 캐시되도록 자동으로 할당합니다.

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 코드와 리포팅 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

"닫기"

 

스트링

보상형 광고를 건너뛰려고 할 때 표시되는 확인 대화 상자의 '취소' 버튼 텍스트를 설정합니다.

참고: 이 설정은 보상형 플레이스먼트에만 적용됩니다.

IncentivizedDialogContinueButton

"계속"

스트링

보상형 광고를 건너뛰려고 할 때 표시되는 확인 대화 상자의 'keep watching' 버튼 텍스트를 설정합니다.

참고: 이 설정은 보상형이 아닌 광고에는 적용되지 않습니다.

Incentivized

-

DEPRECATED

대시보드에서 플레이스먼트 수준에서의 보상형 구성을 설정할 수 있습니다. 플레이스먼트 설정 및 리포팅를 참조하십시오.


참고:
SoundEnabled 옵션 및 다이나믹 템플릿과 Flex View 광고에 대한 보상형 대화 상자를 대시보드에서 구성할 수 있습니다. 자동 구성은 기존 광고에만 적용됩니다.

닫기 버튼 표시

사용자에게 광고를 닫을 수 있는 옵션을 제공할지 결정하려면 Vungle 대시보드에서 앱의 고급 설정에 포함된 강제 보기 옵션을 사용합니다.

이벤트 핸들러 구독

Windows SDK에서는 프로그래밍 방식으로 처리할 수 있는 몇 가지 이벤트가 발생합니다. 이 이벤트 핸들러를 사용하여 배경 음악 일시 중지/다시 시작 등의 앱 기능을 제어할 수 있습니다.

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

광고를 재생하기 전에 호출됩니다. 배경 음악 일시 중지 등의 작업을 수행할 수 있습니다.

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) { }

Native Flex 광고 재생

Vungle Windows SDK 5.1.0 이상에서는 새로운 Native Flex 광고 기능이 지원됩니다. VungleAdControlAdConfig.AdContainer 속성을 통해 Vungle SDK에 사용자 정의 컨테이너를 전달하고 호스트 앱 Container.Content의 콘텐츠를 관리하여 동영상 광고를 네이티브 형식으로 구현합니다.

Native Flex 광고 재생 요건

  • Windows SDK 5.1.0 이상
  • Windows 10 UWP

Native Flex 광고 플레이스먼트를 구성하려면 계정 담당자에게 문의하거나 tech-support@vungle.com으로 연락하시기 바랍니다.

Native Flex 광고용 UI 설정 - XAML

앱에서 사용된 플레이스먼트 ID, 특정 Native Flex 보기용 플레이스먼트 ID, 피드 플레이스먼트는 반드시 Vungle 앱 ID로 VungleAdControl을 공표해야 합니다. 보상형 플레이스먼트에 사용된 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>

Native Flex 광고 로드

Native Flex 플레이스먼트는 전체 화면 광고와 동일한 방법으로 로드할 수 있습니다.

샘플 코드:

sdkInstance.LoadAd(“native_flex_id”); 

Native Flex 광고 재생

Native Flex 플레이스먼트를 사용한 광고 재생은 전체 화면 광고 재생과 비슷하지만, 광고를 시작할 때 소리를 비활성화하는 등의 사용자 정의 설정은 .xaml이나 대시보드에서 설정해야 합니다.

샘플 코드:

await vungleEmbedded.PlayAdAsync();

Native Flex 광고 닫기

Native Flex 광고의 특성상 사용자는 광고를 닫지 않고도 동영상 보기를 중단할 수 있습니다. 따라서 광고가 화면에 더 이상 표시되지 않는 경우 SDK가 광고를 종료하도록 지시해야 합니다. 이를 위해 다음과 같이 Native Flex 광고를 닫는 두 가지 방법이 제공됩니다.

  • CloseFlexViewAd(String placementId)을(를) 사용하여 지정된 플레이스먼트 ID의 광고를 즉시 닫습니다.

  • 지정된 시간(초)이 경과되면 SetFlexViewCloseTimeInSec(String placementId, int seconds)을(를) 사용하여 해당 플레이스먼트를 닫습니다.

Native Flex 광고용 이벤트 핸들러

별도의 이벤트 핸들러를 등록해서 전체 화면 광고와 네이티브 광고의 다양한 동작을 관리하면 보다 원활한 사용자 경험을 제공할 수 있습니다.

샘플 코드:

vungleEmbedded.OnAdStart += (sender, arg) => { ... } vungleEmbedded.OnAdEnd += (sender, arg) => { ... } await vungleEmbedded.PlayAdAsync(); 
또 다른 질문이 있으십니까? 문의 등록

댓글