Vungle Android SDK를 v.5에서 v.6으로 마이그레이션

Vungle Android SDK v6의 마이그레이션 설명서를 시작합니다. 최신 SDK는 가벼우면서 강력한 기능으로 완전히 새롭게 개선되었습니다. API와 통합 세부 사항 모두에서 중요한 변경 사항이 있으므로 본 문서를 통해 SDK 업그레이드에 대해 살펴보시기 바랍니다. 본 통합이 처음이며, v5 SDK에서 마이그레이션하지 않는 경우 Vungle Android SDK v6 통합 설명서를 대신 사용하십시오.

이 문서의 내용:

GDPR: 권장 구현

5월 25일부터 GDPR(General Data Protection Regulation, 일반데이터보호규정)이 유럽 연합에서 시행됩니다. 개발자에게는 GDPR 준수를 위한 2가지 옵션이 있습니다.

  • 옵션 1(권장): 퍼블리셔는 사용자 수준에서 GDPR 동의 과정을 제어한 후 Vungle에 사용자의 선택을 전달합니다. 이를 위해 개발자는 자체 메커니즘을 사용하여 사용자의 동의를 수집한 다음 Vungle API를 사용하여 사용자의 동의 상태를 업데이트하거나 쿼리할 수​있습니다. 자세한 내용은 GDPR 권장 구현 지침 섹션을 참조하십시오.

  • 옵션 2: Vungle이 요구사항을 처리하도록 허용합니다. Vungle은 유럽 사용자를 위해 광고를 재생하기 전에 동의 대화 상자를 표시하고 이후 광고에 대한 해당 사용자의 동의 여부를 기억합니다.

시작하기 전에

릴리스 주요 사항

  • 빠른 속도: 초기화 및 광고 캐시 성능이 v5보다 최대5배까지 빨라졌습니다.
  • 경량: 메서드 수 감소됨
    • 핵심 SDK: 750개 메서드
    • 타사 라이브러리를 포함한 완벽한 통합: 4000개 메서드까지
  • GDPR 준수: Vungle은 사용자 동의를 얻기 위한 2가지 옵션을 제공합니다. Vungle 또는 퍼블리셔는 이 프로세스를 제어할 수 있습니다, 새 API 호출이 추가되었습니다.

요구사항

  • Android 4.0(Ice Cream Sandwich - API 버전 14) 이상

샘플 앱

1단계. 프로젝트에서 Vungle SDK 변경

프로젝트 설정에 따라 수동 통합에 Maven 또는 JAR을 사용합니다.

옵션 1. Gradle 통합

dependencies {
compile 'com.github.vungle:vungle-android-sdk:6.2.3'
compile 'com.google.android.gms:play-services-basement:11.0.1' // Required
compile 'com.google.android.gms:play-services-location:11.0.1' // Recommended
}

"2단계. Vungle SDK 가져오기"로 건너 뜁니다.

옵션 2. JAR 통합

Vungle SDK v6를 다운로드하고 이전 Vungle SDK와 타사 종속성 JAR 파일을 새 SDK와 라이브러리로 변경합니다. 버전 업데이트와 필수 라이브러리의 추가 및 제거에 주의하십시오.

v5 라이브러리 v6 라이브러리
image3.png image2.png

SDK 패키지 다운로드에서 모든 JAR 파일을 컴파일합니다.

dependencies { // Vungle SDK compile files('libs/vungle-android-sdk-6.2.5.jar') // Required Third-party Dependencies compile files('libs/android-job-1.2.0.jar') compile files('libs/cat-1.0.5.jar') compile files('libs/converter-gson-2.2.0.jar') compile files('libs/fetch-1.1.5.jar') compile files('libs/gson-2.7.jar') compile files('libs/logging-interceptor-3.7.0.jar') compile files('libs/okhttp-3.7.0.jar') compile files('libs/okio-1.12.0.jar') compile files('libs/retrofit-2.2.0.jar') compile files('libs/VNG-moat-mobile-app-kit-2.2.0.jar') // Google Play Services compile 'com.google.android.gms:play-services-gcm:11.0.4' // Required compile 'com.google.android.gms:play-services-basement:11.0.4' // Optional compile 'com.google.android.gms:play-services-location:11.0.4' // Optional }

AndroidManifest.xml. 을 수정합니다.

<!--Required Permissions-->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="18" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<uses-permission android:name="android.permission.WAKE_LOCK" /> <!--Optional Permissions-->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> <application
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:roundIcon="@mipmap/ic_launcher_round"
android:supportsRtl="true"
android:theme="@style/AppTheme"
android:networkSecurityConfig="@xml/network_security_config" > <activity android:name=".MainActivity">
<intent-filter>
<action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity> <!-- Google Play Services -->
<meta-data android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version" /> <!-- Vungle -->
<activity
android:name="com.vungle.warren.ui.VungleActivity"
android:configChanges="keyboardHidden|orientation|screenSize|screenLayout|smallestScreenSize"
android:launchMode="singleTop"
android:theme="@android:style/Theme.Translucent.NoTitleBar" /> <!-- android-job -->
<service
android:name="com.evernote.android.job.v21.PlatformJobService"
android:exported="false"
android:permission="android.permission.BIND_JOB_SERVICE" />
<service
android:name="com.evernote.android.job.v14.PlatformAlarmService"
android:exported="false"
android:permission="android.permission.BIND_JOB_SERVICE" />
<service
android:name="com.evernote.android.job.v14.PlatformAlarmServiceExact"
android:exported="false" />
<receiver
android:name="com.evernote.android.job.v14.PlatformAlarmReceiver"
android:exported="false" >
<intent-filter>
<!-- Keep the filter for legacy intents -->
<action android:name="com.evernote.android.job.v14.RUN_JOB" />
<action android:name="net.vrallev.android.job.v14.RUN_JOB" />
</intent-filter>
</receiver>
<receiver
android:name="com.evernote.android.job.JobBootReceiver"
android:exported="false" >
<intent-filter>
<action android:name="android.intent.action.BOOT_COMPLETED" />
<action android:name="android.intent.action.QUICKBOOT_POWERON" />
<action android:name="com.htc.intent.action.QUICKBOOT_POWERON" />
<action android:name="android.intent.action.MY_PACKAGE_REPLACED" />
</intent-filter>
</receiver>
<service
android:name="com.evernote.android.job.gcm.PlatformGcmService"
android:enabled="false"
android:exported="true"
android:permission="com.google.android.gms.permission.BIND_NETWORK_TASK_SERVICE" >
<intent-filter>
<action android:name="com.google.android.gms.gcm.ACTION_TASK_READY" />
</intent-filter>
</service>
<service
android:name="com.evernote.android.job.JobRescheduleService"
android:exported="false"
android:permission="android.permission.BIND_JOB_SERVICE" /> </application>

2단계. Vungle SDK 가져오기

// v5 Import SDK
import com.vungle.publisher.*;

// v6 Import SDK
import com.vungle.warren.*;

3단계. Vungle SDK 초기화

이전에는 초기화하려면 먼저 Vungle SDK 인스턴스를 가져오고 init()를 발행해야 했습니다. 이 방법은 다음과 같은 방식으로 Vungle 어플리케이션 ID, 플레이스먼트 참조 ID를 포함하는 문자열 배열 및 VungleInitListener를 가져왔습니다.

// v5 Initialization
private final VunglePub vunglePub = VunglePub.getInstance();
private final String[] placement_array = {"PLACEMENT_1", "PLACEMENT_2", "PLACEMENT_3"};
...
vunglePub.init(this, app_id, placement_array, new VungleInitListener() {
@Override
public void onSuccess() { }

@Override
public void onFailure(Throwable e) { }
});
}

새 초기화 방법은 다른 매개변수를 다른 순서로 가져옵니다.

  • 사용된 플레이스먼트 참조 ID의 문자열 목록
  • Vungle 어플리케이션 ID
  • 어플리케이션 컨텍스트
  • InitCallback
    • onSuccess: SDK 초기화가 완료되면 알림
    • onError: SDK 초기화가 실패하면 알림
      • InitCallback이 null인 경우 IllegalArgumentException 발생
      • 필수 인수가 누락되었거나 잘못된 경우 VungleException 발생
    • onAutoCacheAdAvailable: 자동 캐시된 플레이스먼트에 재생 가능한 광고가 있으면 알림

광고가 사전 캐시되지 않을 때마다 SDK가 자동 캐시된 플레이스먼트에 대해 광고 캐시를 시도하므로 onAutoCacheAdAvailablecallback을 초기화 콜백의 일부로 사용할 수 있습니다. SDK가 처음 시작되거나 플레이스먼트에 대해 사전 캐시된 광고가 재생되는 경우가 여기에 포함됩니다. 이는 프로세스가 중단되거나 Vungle 인스턴스가 가비지 수집에 의해 회수될 때까지 true로 유지됩니다. 자동 캐시된 플레이스먼트가 아닌 다른 모든 플레이스먼트의 경우 반드시 “5단계. 광고 로드”의 설명에 따라 loadAd를 발행해야 합니다.

// v6 Initialization
private final List<String> placement_collection = Arrays.asList("PLACEMENT_1", "PLACEMENT_2", "PLACEMENT_3");

Vungle.init(placement_collection, app_id, this.getApplicationContext(), new InitCallback() {
@Override
public void onSuccess() {
// Initialization has succeeded and SDK is ready to load an ad or play one if there
// is one pre-cached already
}

@Override
public void onError(Throwable throwable) {
// Initialization error occurred - throwable.getMessage() contains error message
}

@Override
public void onAutoCacheAdAvailable(String placementId) {
// Callback to notify when an ad becomes available for the auto-cached placement
//
// NOTE: This callback works only for the auto-cached placement. Please use
// LoadAdCallback interface for other placements
}
};

isInitialized 메서드를 호출하여 Vungle SDK 초기화 여부를 언제든지 확인할 수 있습니다.

public static boolean isInitialized() 

4단계. 이벤트 리스너

v5 SDK의 글로벌 VungleAdEventListener가 SDK v6에서 로드 및 재생 이벤트에 대해 2개의 독립적인 콜백으로 변경되었습니다. 프로젝트에서 SDK v5에 대한 VungleAdEventListener 구현을 제거하십시오.

// Remove v5 Event Listener
public class FirstActivity extends android.app.Activity {

private final VungleAdEventListener vungleListener = new VungleAdEventListener(){

@Override
public void onAdEnd(String placementReferenceId, boolean wasSuccessfulView, boolean wasCallToActionClicked) { }

@Override
public void onAdStart(String placementReferenceId) { }

@Override
public void onUnableToPlayAd(String placementReferenceId, String reason) { }

@Override
public void onAdAvailabilityUpdate(String placementReferenceId, boolean isAdAvailable) { }
};

@Override
public void onDestroy() {
vunglePub.clearEventListeners();
super.onDestroy();
};
}

모든 이벤트에 일반 콜백을 사용하려는 경우 이제 광고 로드 이벤트용 LoadAdCallback 및 광고 재생 이벤트용 PlayAdCallback을 구현합니다. 그렇지 않은 경우 “5단계. 광고 로드”로 건너뛰어 인라인 콜백을 구현합니다.

// Implement v6 LoadAdCallback
private final LoadAdCallback vungleLoadAdCallback = new LoadAdCallback() {
@Override
public void onAdLoad(String placementReferenceId) {
// Placement reference ID for the placement to load ad assets
}

@Override
public void onError(String placementReferenceId, Throwable throwable) {
// Placement reference ID for the placement that failed to download ad assets
// Throwable contains error message
}
};

 

// Implement v6 PlayAdCallback
private final PlayAdCallback vunglePlayAdCallback = new PlayAdCallback() {
@Override
public void onAdStart(String placementReferenceId) {
// Placement reference ID for the placement to be played
}

@Override
public void onAdEnd (String placementReferenceId, boolean completed, boolean isCTAClicked) {
// Placement reference ID for the placement that has completed ad experience
// completed has value of true or false to notify whether video was
// watched for 80% or more
// isCTAClkcked has value of true or false to indicate whether download button
// of an ad has been clicked by the user
}

@Override
public void onError(String placementReferenceId, Throwable throwable) {
// Placement reference ID for the placement that failed to play an ad
// Throwable contains error message
}
};

5단계. 광고 로드

광고 로드는 v5의 글로벌 VungleAdEventListener에 따라 로드당 콜백이 대신 허용되는 v6의 주요 특징을 제외하면 두 버전 모두에서 본질적으로 동일합니다. LoadAdCallback는 할당된 호출의 로드 상태에 대한 알림을 받습니다. v6 SDK는 이 콜백을 참조만 하며 저장하지 않습니다. 콜백을 적절하게 관리하는 것은 호출자의 책임입니다.

// v5 loadAd
public void loadAd(@NonNull String placementReferenceId)

// v6 loadAd
public static void loadAd(@NonNull final String id, @Nullable LoadAdCallback callback)

SDK는 자동 캐시된 플레이스먼트에 대한 광고 자산 다운로드를 관리하므로 자동 캐시된 플레이스먼트에 대해 이 메서드를 호출할 필요가 없습니다. 기타 모든 플레이스먼트의 경우 loadAd 메서드가 반드시 호출되고 성공적으로 완료되어야 SDK가 해당 플레이스먼트에 대해 광고를 재생할 수 있습니다. 이런 경우 onAdLoad 콜백이 트리거됩니다.

// v6 Load Ad Implementation
if (Vungle.isInitialized()) {
Vungle.loadAd("PLACEMENT_ID", new LoadAdCallback() {
@Override
public void onAdLoad(String placementReferenceId) { }

@Override
public void onError(String placementReferenceId, Throwable throwable) { }
};
}

6단계. 광고 가용성 확인

가용성 확인은 v5에서와 본질적으로 동일하게 유지되며, 유일한 차이점은 해당 메서드가 이제 인스턴스 메서드가 아닌 정적 메서드라는 점입니다.

 // v5 isAdPlayable
public boolean isAdPlayable(@NonNull final String placementReferenceId)

// v6 canPlayAd
public static boolean canPlayAd(@NonNull String id)

7단계. 광고 재생

광고 로드의 변경 사항과 유사하게 광고 재생 시 v5에서와 동일한 정보가 필요하며, PlayAdCallback을 메서드에 전달할 수 있는 옵션을 사용하면 광고가 재생되는 동안 성공 또는 오류에 대한 알림이 전송됩니다.

// v5 playAd
public void playAd(@NonNull String placementReferenceId, @Nullable AdConfig adConfig)

// v6 playAd
public static void playAd(@NonNull final String id, final AdConfig settings, @Nullable final PlayAdCallback listener)

playAd 메서드를 호출하기 전에 canPlayAd 메서드를 호출하여 광고 가용성을 항상 확인해야 합니다. 또한 playAd가 반복적으로 잇달아 호출되는 경우 광고가 적절하게 렌더링되지 않으므로 초기 playAd 호출의 onAdEnd 또는 onError 콜백을 수신하기 전에 추가 playAd가 발행되지 않는지 확인해야 합니다.

// v6 Play Ad Implementation
if (Vungle.canPlayAd("PLACEMENT_ID")) {
Vungle.playAd("PLACEMENT_ID", new AdConfig, new PlayAdCallback() {
@Override
public void onAdStart(String placementReferenceId) { }

@Override
public void onAdEnd(String placementReferenceId, boolean completed, boolean isCTAClicked) { }

@Override
public void onError(String placementReferenceId, Throwable throwable) { }
});
}

8단계. 구성 옵션

광고 재생 옵션

다음 표는 사용 가능한 모든 AdConfig 옵션을 보여줍니다.

옵션

설명

setBackButtonImmediatelyEnabled

광고 종료 버튼이 표시되기 전에 뒤로 버튼이 활성화되어야 하는 경우 true, 그렇지 않은 경우 false

setFlexViewCloseTime

Flex-View 광고가 자동으로 닫힐 때까지의 시간(초)을 지정하는 0보다 크거나 같은 정수 값을 사용

setImmersiveMode

몰입형 모드가 KitKat+ 장치에 대해 활성화되는 경우 true, 그렇지 않은 경우 false

setAutoRotate

동영상 광고가 자동 회전하도록 되어 있는 경우 true, 동영상 광고 방향을 따르도록 되어 있는 경우 false

setMuted

동영상이 주변의 어플리케이션의 설정 중 일치하는 오디오 설정으로 시작되어야 하는 경우 true, 음소거로 시작되어야 하는 경우 false

setOrdinal

동일한 세션에서 재생되는 광고의 수를 추적하려면 서수의 정수 값을 사용합니다.

setTransitionAnimationEnabled

동영상 전환 애니메이션이 활성화되어야 하는 경우 true, 비활성화되어야 하는 경우 false

보상형 광고 사용자 정의

보상형 광고에 대한 팝업 메시지 대화 상자는 v5의 AdConfig 개체로 구성 가능하지만 v6은 새 메서드인 setIncentivizedFields를 대신 제공합니다.

public static void setIncentivizedFields(@Nullable String userID, @Nullable String title, @Nullable String body, @Nullable String keepWatching, @Nullable String close) 

Flex-View 광고 닫기

현재 Flex-View 광고를 재생 중인 플레이스먼트 참조 ID를 사용해 closeFlexViewAd 메서드를 발행하여 Flex-View를 프로그래밍 방식으로 닫을 수 있습니다.

public static boolean closeFlexViewAd(@NonNull final String placementReferenceId) 

올바른 플레이스먼트 목록

현재 세션에 대해 올바른 플레이스먼트 참조 ID를 모두 포함하는 문자열 집합을 반환하는 도우미 메서드

public static Collection<String> getValidPlacements() 

ProGuard 규칙

# Vungle -keep class com.vungle.warren.** { *; } # Evernote -dontwarn com.evernote.android.job.gcm.** -dontwarn com.evernote.android.job.GcmAvailableHelper -dontwarn com.google.android.gms.ads.identifier.** -keep public class com.evernote.android.job.v21.PlatformJobService -keep public class com.evernote.android.job.v14.PlatformAlarmService -keep public class com.evernote.android.job.v14.PlatformAlarmReceiver -keep public class com.evernote.android.job.JobBootReceiver -keep public class com.evernote.android.job.JobRescheduleService -dontwarn org.codehaus.mojo.animal_sniffer.IgnoreJRERequirement -keep class com.google.android.gms.internal.** { *; } # Moat SDK -keep class com.moat.** { *; } -dontwarn com.moat.**

GDPR 권장 구현 지침

Vungle API를 사용하여 업데이트하거나 사용자 동의 상태를 쿼리하려면(GDPR: 권장 구현의 옵션 1 참조) 다음 함수를 사용하십시오.

  • // To set the user's consent status to opted in: Vungle.updateConsentStatus(Vungle.Consent.OPTED_IN); // To set the user's consent status to opted out: Vungle.updateConsentStatus(Vungle.Consent.OPTED_OUT); // 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 Vungle.Consent.OPTED_IN or Vungle.Consent.OPTED_OUT UpdateConsentStatus? currentStatus = sdkInstance.GetCurrentConsentStatus(); Vungle.Consent currentStatus = Vungle.getConsentStatus(); 
또 다른 질문이 있으십니까? 문의 등록

댓글