Миграция с Vungle Android SDK v. 5 на v. 6

Добро пожаловать в руководство по миграции Vungle Android SDK v6! Новый SDK был полностью переписан для повышения надежности и снижения объема. Используйте этот документ для получения инструкций по обновлению SDK, так как в API и процессе интеграции произошли существенные изменения. Если это абсолютно новая интеграция, и вы не переходите с V5 SDK, воспользуйтесь руководством Интеграция Vungle Android SDK v6 вместо этого.

В этой статье:

GDPR: рекомендации по реализации

25 мая в Европейском союзе вступил в силу Общий регламент по защите данных (General Data Protection Regulation, GDPR). Разработчикам доступно два варианта соблюдения его требований.

  • Вариант 1 (рекомендуется): Издатель контролирует процесс согласия с GDPR на уровне пользователя, а затем сообщает о выборе пользователя Vungle. Для этого разработчики могут собирать данные о согласии пользователя, используя свой собственный механизм, а затем использовать API Vungle для обновления или запроса статуса согласия пользователя. Более подробная информация доступна в разделе «Рекомендованные инструкции по реализации GDPR».

  • Вариант 2: Разрешить Vungle обрабатывать требования. Vungle будет отображать диалоговое окно с запросом согласия перед воспроизведением рекламы для европейского пользователя и будет запоминать согласие или отказ пользователя для последующих показов.

Перед началом работы

Главное в выпуске

  • Скорость: инициализация и кэширование рекламы до 5 раз быстрее, чем в v5
  • Сниженный объем: сокращенное число методов
    • Основной SDK: 750 методов
    • Полная интеграция, включающая сторонние библиотеки: ~4000 методов
  • Соответствие требованиям GDPR: Vungle предоставляет два варианта получения согласия пользователя: этот процесс может контролироваться Vungle либо издателем. Добавлены новые вызовы API.

Требования

  • Android 4.0 (Ice Cream Sandwich — версия API 14) или более поздняя версия

Пример приложения

Шаг 1. Изменение Vungle SDK в проекте

В зависимости от настроек проекта используйте интеграцию AAR через 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

Скомпилируйте все файлы JAR из пакета SDK.

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

Раньше для инициализации нужно было сначала захватить экземпляр SDK Vungle и выдать init(). Этот метод принимал идентификатор приложения Vungle, массив строк, содержащий идентификаторы размещений, и 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) { }
});
}

Новый метод инициализации принимает другие параметры в другом порядке:

  • Список строк использованных идентификаторов размещения
  • Идентификатор приложения Vungle
  • Контекст приложения
  • InitCallback
    • onSuccess: уведомляет об успешной инициализации SDK
    • onError: уведомляет о сбое инициализации
      • выдает IllegalArgumentException, если InitCallback имеет значение null
      • выдает VungleException, если требуемые аргументы отсутствуют или являются недействительными
    • onAutoCacheAdAvailable: уведомляет, когда в размещении с автоматическим кэшированием есть доступная для воспроизведения реклама

onAutoCacheAdAvailablecallback доступно в рамках обратного вызова инициализации, так как SDK будет непрерывно пытаться кэшировать рекламу для размещения с автоматическим кэшированием всякий раз, когда реклама не была кэширована предварительно. Сюда входят случаи, когда SDK запускается в первый раз или когда была воспроизведена предварительно кэшированная реклама для размещения. Вышесказанное остается в силе до тех пор, пока процесс не завершится, или экземпляр Vungle не будет освобожден сборкой мусора. Для всех других размещений, которые не кэшируются автоматически, loadAd должны быть явно вызваны, как описано в разделе «Шаг 5. Загрузка рекламы».

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

Вы в любое время можете проверить инициализацию Vungle SDK, вызвав метод isInitialized:

public static boolean isInitialized() 

Шаг 4. Прослушиватель событий

Глобальный VungleAdEventListener в SDK v5 был заменен в SDK v6 двумя независимыми обратными вызовами для событий загрузки и воспроизведения. Удалите реализацию VungleAdEventListener для SDK v5 из вашего проекта:

// 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. Загрузка рекламы

Загрузка рекламы практически не отличается в обоих версиях, за исключением того, что в v6 допускается обратный вызов для каждой нагрузки, который не зависит от глобального параметра VungleAdEventListener, как в v5. LoadAdCallback будет уведомлен о состоянии загрузки для вызова, которому был назначен. SDK V6 только ссылается на этот обратный вызов и нигде его не сохраняет; ответственность за должное управление обратным вызовом лежит на вызывающем.

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

Вы всегда должны проверять доступность рекламы, вызывая метод canPlayAd перед вызовом метода playAd. Вы также должны убедиться, что дополнительный playAd не выполняется до того, как вы получите обратный вызов onAdEnd или onError от начального вызова playAd, так как реклама будет отображаться некорректно, если 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

принимает значение целого числа, которое больше или равно 0, которое указывает время в секундах, после которого реклама Flex-View закрывается автоматически

setImmersiveMode

true, если для устройств KitKat+ будет включен режим комфортного просмотра, иначе false

setAutoRotate

true, если видеореклама должна вращаться автоматически, false, чтобы следовать ориентации видеорекламы

setMuted

true, если видео должно запускаться с настройками звука, соответствующими настройкам вашего вложенного приложения, false, если оно должно запускаться без звука

setOrdinal

принимает значение целого числа порядкового счета для отслеживания количества рекламных объявлений, которые были воспроизведены за один сеанс

setTransitionAnimationEnabled

true, если анимация перехода видео должна быть включена, false, если она должна быть выключена

Настройка рекламы с вознаграждением

Вплывающее диалоговое окно для рекламы с вознаграждением можно было настроить с помощью объекта AdConfig в v5, но в 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 можно закрыть программно, вызвав метод closeFlexViewAd с идентификатором размещения, который в настоящее время воспроизводит рекламу Flex-View.

public static boolean closeFlexViewAd(@NonNull final String placementReferenceId) 

Список допустимых размещений

Вспомогательный метод, который возвращает коллекцию строк, содержащую все допустимые идентификаторы размещений для текущего сеанса.

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

Чтобы использовать API Vungle для обновления или запроса статуса согласия пользователя (как рекомендовано в Варианте 1 в разделе GDPR: рекомендации по реализации Vungle), используйте следующие функции:

  • // 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(); 
Была ли эта статья полезной?
Пользователи, считающие этот материал полезным: 0 из 0
Еще есть вопросы? Отправить запрос

Комментарии