Skip to content

Integration guide for Unity

Jump to bottom
pineglobal edited this page Jan 7, 2019 · 11 revisions

Unity 통합 가이드

개요

이 가이드에서는 Unity로 제작된 게임에서 Unity Ads를 구현하는 통합 방법을 소개합니다.

  • Objective-C를 사용하는 iOS 개발자 분들은 여기를 클릭하세요.
  • Java를 사용하는 Android 개발자 분들은 여기를 클릭하세요.

Unity의 수익화 플랫폼은 강력한 수익 툴을 제공합니다. 만약 게임에서 광고 외에 인앱 구매도 사용한다면, Unity의 머신러닝 데이터 모델이 콘텐츠 유형을 매끄럽게 혼합하여 수익화 전략을 최적화할 수 있습니다. Unity로 수익을 최적화하는 방법에 대한 자세한 내용은 개인화 플레이스먼트 참고 문서를 참조하세요.

이 가이드는 다음의 내용을 다룹니다.

기본 구현

프로젝트 구성

대상 빌드 설정

빌드 설정 창을 사용하여 프로젝트를 지원 플랫폼에 맞게 구성하십시오. 플랫폼을 iOS 또는 Android로 설정한 다음 Switch Platform(플랫폼 전환)을 클릭하십시오.

Unity Ads 설치

에셋 스토어에서 Unity Ads 최신 버전을 다운로드하여 사용하시기 바랍니다. Monetization API는 SDK 3.0 이상 버전이 필요합니다. 에셋 패키지 다운로드 및 설치에 관한 정보는 에셋 패키지 참고 문서를 참조하세요.

플레이스먼트 생성

플레이스먼트는 수익화 콘텐츠를 표시하는 게임 내 트리거 이벤트입니다. Developer Dashboard의 Operate 탭에서 프로젝트를 선택한 다음 왼쪽 내비게이션에서 Monetization(수익화) > Placements(플레이스먼트)를 선택하면 플레이스먼트를 관리할 수 있습니다.

ADD PLACEMENT(플레이스먼트 추가) 버튼을 클릭하면 플레이스먼트 생성 대화창이 나타납니다. 플레이스먼트 이름을 지정하고 유형을 선택하십시오.

  • 기본 삽입 광고 또는 홍보 콘텐츠를 표시하려면 Non-rewarded(비보상형)를 선택합니다. Non-rewarded(비보상형) 플레이스먼트의 경우에는 플레이어가 지정된 시간이 지나면 광고를 건너뛸 수 있습니다.
  • 플레이어가 광고 보기를 선택하고 보상을 받도록 하려면 Rewarded(보상형)를 선택합니다. Rewarded(보상형) 플레이스먼트의 경우에는 플레이어가 광고를 건너뛰지 못합니다.
  • 전용 배너 광고 플레이스먼트를 생성하려면 Banner(배너)를 클릭합니다.

Unity Ads가 활성화된 모든 프로젝트는 ‘video’(비보상형) 및 ‘rewardedVideo’(보상형) 플레이스먼트를 기본값으로 갖습니다. 필요에 따라 이 두 가지 중 하나를 첫 구현에 자유롭게 사용할 수 있으며, 아니면 직접 생성할 수도 있습니다.

SDK 초기화

SDK를 초기화하려면, 해당 플랫폼의 프로젝트에 있는 게임 ID를 참조해야 합니다. ID는 Developer Dashboard의 Operate 탭에서 프로젝트를 선택한 다음, 왼쪽 내비게이션에서 Monetization(수익화) > Platforms(플랫폼)를 선택하여 찾을 수 있습니다.

게임 스크립트 헤더에 UnityEngine.Monetization 네임스페이스를 포함시키십시오. Initialize 함수를 사용하여 게임 런타임 수명주기 초반에, 가능하다면 앱의 처음 시작시 SDK를 초기화하십시오. 예:

using UnityEngine.Monetization;

public class UnityAdsScript : MonoBehaviour { 

    string gameId = "1234567";
    bool testMode = true;

    void Start () {
        Monetization.Initialize (gameId, testMode);
    }
}

기본(비보상형) 광고 구현

PlacementContent는 수익화 콘텐츠를 나타내며 플레이스먼트에서 표시할 수 있는 오브젝트입니다. 자세한 내용은 콘텐츠 유형 및 개인화 플레이스먼트를 참조하세요. 표시할 준비가 된 콘텐츠를 GetPlacementContent 함수로 가져와 show 함수로 표시하십시오. 예:

using UnityEngine.Monetization;

public class UnityAdsPlacement : MonoBehaviour {

    public string placementId = "video";

    public void ShowAd () {
        StartCoroutine (ShowAdWhenReady ());
    }

    private IEnumerator ShowAdWhenReady () {
        while (!Monetization.IsReady (placementId)) {
            yield return new WaitForSeconds(0.25f);
        }

        ShowAdPlacementContent ad = null;
        ad = Monetization.GetPlacementContent (placementId) as ShowAdPlacementContent;

        if(ad != null) {
            ad.Show ();
        }
    }
}

이 예제에서 코루틴은 IsReady 함수를 사용해, 전달된 플레이스먼트 ID에서 이용 가능한 PlacementContent가 있는지 확인합니다. 이용 가능한 콘텐츠가 있는 경우 콘텐츠는 변수로 저장되고 Show 함수로 실행됩니다.

보상형 광고 구현

광고를 보는 플레이어를 보상하면 사용자 참여가 증가하고 더욱 높은 수익으로 이어질 수 있습니다. 예를 들어, 게임 내 화폐나 소모품, 추가 생명, 경험치 증가 등의 보상이 있습니다. 보상형 광고를 효과적으로 설계하는 방법에 관한 자세한 내용은 광고 베스트 프랙티스 참고 문서를 참조하세요.

광고를 보는 플레이어를 보상하려면, 기본 구현 섹션에 자세히 설명된 동일한 과정을 수행하십시오. 단, 광고 시청을 완료하는 플레이어를 위한 커스텀 로직으로 보상 콜백 메서드를 사용하여 광고를 표시해야 합니다.

플레이스먼트 선택

보상형 광고는 반드시 보상형 플레이스먼트를 통해서 표시해야 합니다. Unity Ads가 활성화된 모든 프로젝트는 ‘rewardedVideo’ 플레이스먼트를 기본값으로 갖습니다. 이것을 자유롭게 구현에 이용할 수 있으며, 아니면 직접 생성할 수도 있습니다. 단, 플레이스먼트를 반드시 보상형으로 구성해야 합니다.

스크립트에 콜백 메서드 추가

Show 함수는 SDK가 ShowResult enum을 반환하는 데 사용하는 콜백을 받습니다. 이 결과는 플레이어가 광고를 끝까지 시청했는지 아니면 건너뛰었는지를 나타냅니다. 이 정보를 이용하여 각 시나리오별로 핸들링 방법에 관해 커스텀 함수를 작성하십시오. 예:

using UnityEngine.Monetization;

public class RewardedAdsPlacement : MonoBehaviour {

    public string placementId = "rewardedVideo";

    public void ShowAd () {
        StartCoroutine (WaitForAd ());
    }

    IEnumerator WaitForAd () {
        while (!Monetization.IsReady (placementId)) {
            yield return null;
        }

        ShowAdPlacementContent ad = null;
        ad = Monetization.GetPlacementContent (placementId) as ShowAdPlacementContent;

        if (ad != null) {
            ad.Show (AdFinished);
        }
    }

    void AdFinished (ShowResult result) {
        if (result == ShowResult.Finished) {
            // Reward the player
        }
    }
}

보상형 광고 버튼 코드 예제

일반적으로 보상형 광고는 플레이어가 광고 보기를 선택하도록 유도하는 버튼을 이용합니다. 다음은 버튼을 눌렀을 때 콘텐츠가 이용 가능한 경우 광고를 표시하는 보상형 광고 버튼의 생성 방법을 설명합니다.

  1. Unity 에디터에서 Game Object(게임 오브젝트) > UI > Button(버튼)을 선택하여 씬에 버튼을 추가합니다.
  2. 버튼을 선택하고 인스펙터에서 Add Component(구성요소 추가) > New Script(새 스크립트)를 클릭하여 스크립트 컴포넌트를 버튼에 추가합니다. 클래스 이름과 일치하도록 스크립트 이름을 UnityAdsButton 으로 지정합니다.
  3. 스크립트를 열고 다음 예제 코드를 추가합니다.
using UnityEngine;
using UnityEngine.UI;
using UnityEngine.Monetization;

[RequireComponent (typeof (Button))]
public class UnityAdsButton : MonoBehaviour {

    public string placementId = "rewardedVideo";
    private Button adButton;

#if UNITY_IOS
   private string gameId = "1234567";
#elif UNITY_ANDROID
    private string gameId = "7654321";
#endif

    void Start () {
        adButton = GetComponent<Button> ();
        if (adButton) {
            adButton.onClick.AddListener (ShowAd);
        }

        if (Monetization.isSupported) {
            Monetization.Initialize (gameId, true);
        }
    }

    void Update () {
        if (adButton) {
            adButton.interactable = Monetization.IsReady (placementId);
        }
    }

    void ShowAd () {
        ShowAdCallbacks options = new ShowAdCallbacks ();
        options.finishCallback = HandleShowResult;
        ShowAdPlacementContent ad = Monetization.GetPlacementContent (placementId) as ShowAdPlacementContent;
        ad.Show (options);
    }

    void HandleShowResult (ShowResult result) {
        if (result == ShowResult.Finished) {
            // Reward the player
        } else if (result == ShowResult.Skipped) {
            Debug.LogWarning ("The player skipped the video - DO NOT REWARD!");
        } else if (result == ShowResult.Failed) {
            Debug.LogError ("Video failed to show");
        }
    }
}

참고: 이 예제는 게임 내 특정 지점에서 PlacementContent를 표시할 준비가 되었는지 점검하는 과정을 보여 줍니다. 또 다른 방법으로는, 콘텐츠를 이용할 수 있는 시점을 알리는 리스너를 구현할 수도 있습니다.

배너 광고 구현

플레이스먼트 구성

배너 광고는 특정 유형의 전용 배너 플레이스먼트가 필요합니다. 현재 배너는 화면 중앙 하단에 고정되어 표시됩니다.

스크립트 구현

플레이스먼트 스크립트 헤더에서 Banner 클래스를 포함하는 UnityEngine.Advertisement 네임스페이스를 선언합니다. 다음으로, SDK를 초기화하고 Advertisement.Banner.Show ()를 사용하여 배너 광고를 표시합니다. 예:

using System.Collections;
using UnityEngine;
using UnityEngine.Advertisements;

public class BannerAds : MonoBehaviour {

    public string bannerPlacement = "banner";
    public bool testMode = false;

#if UNITY_IOS
    public const string gameID = "1234567";
#elif UNITY_ANDROID
    public const string gameID = "1234568";
#elif UNITY_EDITOR
    public const string gameID = "1111111";
#endif

    void Start () {
        Advertisement.Initialize (gameID, testMode);
        StartCoroutine (ShowBannerWhenReady ());
    }

    IEnumerator ShowBannerWhenReady () {
        while (!Advertisement.IsReady ("banner")) {
            yield return new WaitForSeconds (0.5f);
        }
        Advertisement.Banner.Show (bannerPlacement);
    }
}

테스트

게임을 퍼블리시하기 전에 다음의 과정을 따라 테스트 모드를 활성화하십시오.

  1. 먼저 Developer Dashboard의 Operate 탭에서 프로젝트를 선택합니다.
  2. 왼쪽 내비게이션에서 Monetization > Platforms를 선택합니다.
  3. 원하는 플랫폼을 지정하고 SETTINGS(설정) 탭을 선택합니다.
  4. 아래로 스크롤하여 TEST MODE(테스트 모드) 섹션에서 오버라이드 클라이언트 테스트 모드로 선택한 다음 Force test mode ON(테스트 모드 강제 켜기) 라디오 버튼을 선택합니다.

Unity 에디터에서 플레이 버튼을 클릭하여 프로젝트를 실행하고 광고 구현을 테스트합니다.

참고: 광고가 잘 통합되었는지 테스트하기 전에 테스트 모드를 활성화해야만 fraud(부정행위)로 적발되는것을 방지할 수 있습니다.

수익 최적화

축하합니다. 이제 Unity Ads를 구현하셨습니다! 유니티의 목표는 사용자가 간편한 방법으로 수익을 최대화하는 것입니다. 이 점을 염두에 두고 다음 단계들을 살펴보십시오.

  • 혹시 게임에서 인앱 구매(IAP)를 사용하시나요?
    • 만약 그렇다면 IAP Promo를 구현하여 인앱 상품을 홍보하세요.
    • 그렇지 않다면 Unity IAP로 인앱 스토어를 생성하세요.
  • Ads와 IAP Promo가 준비되었다면 개인화 플레이스먼트를 사용하여 광고와 IAP 전략을 강화하고 전체 게임의 수익 상승을 노려 보세요.
  • 여기 베스트 프랙티스 가이드를 통해서 효율적인 광고를 설계하는 원리와 방법을 이해할 수 있습니다.

맨 위로

Unity API 레퍼런스

Monetization

Initialize

프로젝트를 위해 SDK를 초기화합니다.

public static void Initialize (string gameID, bool testMode)

gameId 파라미터는 Developer Dashboard에서 확인할 수 있는 프로젝트의 게임 ID입니다. testMode 파라미터는 게임이 테스트 모드 상태인지를 나타냅니다. testMode가 true이면, 테스트 광고만 볼 수 있습니다. testMode가 false이면, 라이브 광고를 볼 수 있습니다. 게임 출시 전까지는 테스트 모드를 사용하여 fraud(부정행위)로 적발되는것을 방지하는 것이 좋습니다.

IsReady

해당 플레이스먼트에 PlacementContent가 준비되었는지 확인합니다.

public static boolean IsReady (string placementId);

placementId 파라미터는 Developer Dashboard에서 구성된 플레이스먼트 ID입니다. 이 함수는 PlacementContent가 준비된 경우 true를, 그렇지 않으면 false를 반환합니다.

GetPlacementContent

해당 플레이스먼트에 대한 PlacementContent 오브젝트를 반환합니다.

public static PlacementContent GetPlacementContent (string placementId);

placementId 파라미터는 Developer Dashboard에서 구성된 플레이스먼트 ID입니다. 이용할 수 있는 경우 PlacementContent 오브젝트를, 그렇지 않은 경우 null을 반환합니다.

참고: PlacementContent를 변수로 설정할 때 올바른 유형으로 형변환(ShowAdPlacementContent 또는 PromoAdPlacementContent)해야 합니다. 자세한 내용은 콘텐츠 유형 참고 문서를 참조하세요.

IMonetizationListener

구현하여 SDK에 전달하는 인터페이스입니다.

public interface IMonetizationListener {   
    void OnPlacementContentReady (string placementId, PlacementContent placementContent);   
    void OnPlacementContentStateChange (string placementId, PlacementContent placementContent, Monetization.PlacementContentState previousState, Monetization.PlacementContentState newState);
}

OnPlacementContentReady

플레이스먼트 ID와 PlacementContent 오브젝트를 받아서 SDK가 표시 준비된 콘텐츠를 핸들링하는 방법을 지시합니다.

OnPlacementContentStateChange

SDK가 전달된 PlacementContent의 상태 변화를 기술하는 방법을 지시합니다.

SetListener

PlacementContent 이벤트의 리스너를 설정합니다. listener 파라미터는 이벤트 콜백의 리스너입니다.

public static void SetListener (IMonetizationListener listener);

GetListener

현재 수익화 리스너를 반환합니다. listener 오브젝트는 이벤트 콜백의 리스너입니다.

public static IMonetizationListener GetListener ();

PlacementContent

플레이스먼트가 표시할 수 있는 수익화 콘텐츠를 나타내는 오브젝트입니다.

RewardablePlacementContent

PlacementContent 클래스를 확장하여 보상형 콘텐츠를 확장합니다.

ShowAdPlacementContent

RewardablePlacementContent 클래스를 확장하여 동영상 광고 콘텐츠를 위한 기능을 제공합니다.

Show

PlacementContent가 ShowAdPlacementContent로 형변환될 때, Show 함수를 사용하여 표시합니다. 게임 내 보상 핸들링을 위해 콜백 메서드를 전달하여 광고를 끝까지 시청했는지, 건너뛰었는지, 아니면 표시가 되지 않았는지 나타낼 수 있습니다.

public void Show (ShowAdCallbacks showAdCallbacks)

public void Show (ShowAdFinishCallback finishCallback)

보상형 PlacementContent에 대해, 리스너를 사용하여 콘텐츠가 완료되었고 원하는 동작을 핸들링했는지 확인합니다.

ShowAdCallbacks

광고 실행 후 [[ShowOptions.resultCallback]]에 전달되는 ShowResult enum입니다.

값 설명
Finished 플레이어가 광고를 끝까지 시청한 경우를 나타냅니다.
Skipped 플레이어가 광고 시청을 끝까지 완료하지 않은 경우를 나타냅니다.
Failed 광고가 표시되는데 실패한 경우를 나타냅니다. 
public delegate void ShowAdFinishCallback (ShowResult finishState);

public delegate void ShowAdStartCallback ();

public struct ShowAdCallbacks {
    public ShowAdFinishCallback finishCallback;
    public ShowAdStartCallback startCallback;
}

PromoAdPlacementContent

ShowAdPlacementContent 클래스를 확장하여, IAP Promo 콘텐츠에 대한 기능을 제공합니다. 자세한 내용은 네이티브 Promo 참고 문서를 참조하십시오.

gamerSid

서버 간 보상 지급 콜백에서 사용되는 고유 서버 식별자입니다.

public string gamerSid

Banner

Load

배너 광고 콘텐츠를 로드하는 기본 메서드입니다. 필요에 따라 몇 가지 파라미터를 이용하여 이 함수를 조정할 수 있습니다.

메서드 설명
public static void Load () 기본 플레이스먼트 ID로 콜백 없이 배너 광고를 로드합니다.
public static void Load (BannerLoadOptions options) 기본 플레이스먼트 ID로 배너 광고를 로드하지만 로드 성공 시 loadCallback을 작동시키고 로드 실패 시 errorCallback 콜백을 작동시킵니다.
public static void Load (string placementID) 특정 플레이스먼트 ID로 콜백 없이 배너 광고를 로드합니다.
public static void Load (string placementID, BannerLoadOptions options) 특정 플레이스먼트 ID로 배너 광고를 로드하지만 로드 성공 시 loadCallback을 작동시키고 로드 실패 시 errorCallback 콜백을 작동시킵니다.
public static bool isLoaded () 콘텐츠를 성공적으로 로드했고 표시할 준비가 되었는지 확인합니다.
BannerLoadOptions

배너 로딩 시 SDK에 이벤트를 알릴 수 있도록 이 옵션을 SDK로 전달하여 돌려줍니다.

콜백 설명
public LoadCallback loadCallback { get; set; } 배너 광고가 로드되어 표시 가능할 때 작동합니다.
public ErrorCallback errorCallback { get; set; } 배너 광고 로드 프로세스 동안 오류가 발생할 때 이 콜백이 작동합니다. 이 콜백이 호출되면 배너가 로드되지 않은 것으로 추정할 수 있습니다. 나중에 다시 로드 호출을 시도할 수 있습니다.

Show

배너 광고 콘텐츠를 표시하는 기본 메서드입니다. 필요에 따라 몇 가지 파라미터를 이용하여 이 함수를 조정할 수 있습니다.

메서드 설명
public static void Show () 기본 플레이스먼트 ID로 콜백 없이 배너 광고를 표시합니다.
public static void Show (BannerOptions options) 기본값 플레이스먼트 ID로 배너 광고를 표시하지만 콘텐츠가 보일 때 showCallback을, 콘텐츠가 숨겨져 있을 때 hideCallback을 작동시킵니다.
public static void Show (string placementID) 특정 플레이스먼트 ID로 콜백 없이 배너 광고를 표시합니다.
public static void Show (string placementID, BannerLoadOptions options) 특정 플레이스먼트 ID로 배너 광고를 표시하지만 콘텐츠가 보일 때 showCallback을, 콘텐츠가 숨겨져 있을 때 hideCallback을 작동시킵니다.
BannerOptions

배너 내에서 SDK에 이벤트를 알릴 수 있도록 이 옵션을 SDK로 전달하여 돌려줍니다.

콜백 설명
public BannerCallback showCallback { get; set; } 이 콜백은 배너 광고가 플레이어에게 보일 때 작동합니다.
public BannerCallback hideCallback { get; set; } 이 콜백은 배너 광고가 플레이어에게 숨겨져 있을 때 작동합니다.

Hide

이 함수를 이용하면 배너 광고를 파기하지 않고 숨길 수 있습니다.

public static void Hide (bool destroy = false);

맨 위로

Clone this wiki locally