Vungle 시작하기 - Windows SDK v.5.1 이상

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

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

목차

시작하기 전에

  • 이 설명서는 Vungle Windows SDK 5.1 이상 버전에 적용됩니다. 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 추가

  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의 문자열 배열입니다. 인스턴스을 받을 때 포함했던 광고위치 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를 확인하시기 바랍니다.

// 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

-

DEPRECATED

대시보드에서 광고위치 수준에서의 보상 구성을 설정할 수 있습니다. 광고위치 설정 및 보고를 참조하십시오.


참고:
대시보드에서 SoundEnabled와 동적 템플릿 및 플렉스 뷰 광고에 대한 인센티브화된 대화 상자의 옵션을 구성할 수 있습니다. 프로그래밍 방식 구성은 기존 광고에만 적용됩니다.

닫기 버튼 표시

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

이벤트 핸들러 구독

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

UI 스레드 노트

이벤트 리스너는 배경 스레드에서 실행되므로 이벤트 리스너에 의한 UI 상호 작용/업데이트는 실행 이전에 기본 UI 스레드로 전달되어야 합니다. 다음 방법으로 이를 수행할 수 있습니다.

await this.Dispatcher.RunAsync(CoreDispatcherPriority.Normal,
new DispatchedHandler(() =>
{ //이 블록은 UI 스레드에서 실행됩니다
} );

VungleAd 이벤트 핸들러

이벤트 핸들러

설명

OnInitCompleted

SDK의 초기화가 완료되면 즉시 호출됩니다. 이전 세션에서 다운로드된 광고가 있는지 확인하거나 광고위치에 광고를 로드할 수 있습니다.

OnAdPlayableChanged

광고위치의 광고 가용성 변경 사항을 알려줍니다. 광고위치에 광고를 로드한 후 광고를 사용할 수 있게 되면 이벤트 핸들러가 액션을 수행할 때까지 기다립니다.

OnAdStart

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

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 - 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가 진단 로그를 인쇄하려고 할 때 호출되는 이벤트 핸들러
private void SdkInstance_Diagnostic(object sender, DiagnosticLogEvent e)
{
  System.Diagnostics.Debug.WriteLine("Diagnostic - "
+ e.Level + " "
+ e.Type + " "
+ e.Exception + " "
+ e.Message); } // DEPRECATED - 대신 SdkInstance_OnAdEnd() 사용 private void SdkInstance_OnVideoView(object sender, AdViewEventArgs e) { }

Native Flex Ad 재생

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

Native Flex Ad 재생 요건

  • Windows SDK 5.1.0 이상
  • Windows 10 UWP

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

Native Flex Ad용 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 Ad 로드

Native Flex Ad위치는 전체 화면 광고와 동일한 방법으로 로드할 수 있습니다.

샘플 코드:

sdkInstance.LoadAd(“native_flex_id”); 

Native Flex Ad 재생

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

샘플 코드:

await vungleEmbedded.PlayAdAsync();

Native Flex Ad용 이벤트 핸들러

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

샘플 코드:

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

댓글