Начало работы с сетью Vungle: Adobe Air

Руководство для расширения «Adobe Air»

Вводные сведения

  • Для работы расширения Vungle требуется Adobe AIR SDK 4.0 или более новой версии. Указания по обновлению AIR SDK в ПО «Flash Builder» и «Flash Professional» можно найти в конце этого руководства.
  • При работе с ОС «Android» расширение Vungle для платформы AIR требует наличия JDK 7 на машине разработчика.
  • Можно ознакомиться с документацией ко классу ActionScript 3.
  • Пример класса приложения приведен в файле «example/VungleExample.as». (Если у вас «Flash Professional» и вы не знаете, как использовать класс документа, в конце руководства рассматривается использование класса документа VungleExample для «Flash CS6».)
  1. Добавляем библиотеку расширений

Для начала создайте новый проект AIR для мобильных устройств и добавите «родное» расширение.

Если целевая платформа — «Android», может потребоваться добавить в проект службы «Google Play» и (или) библиотеку «Android Support v4». Во многих расширениях эти библиотеки уже включены, так что возможно, их добавлять не придется. Чтобы добавить расширения, следуйте указаниям ниже, но используйте «com.vungle.extensions.android.GooglePlayServices.ane» и (или) «com.vungle.extensions.android.AndroidSupportLib.ane» вместо «com.vungle.extensions.Vungle.ane».

«Flash Professional CS6» или более новая версия:

  1. Создайте новый проект AIR для ОС «Android» или «iOS».
  2. Выберите Файл > Настройки публикации...
  3. Выберите значок гаечного ключа рядом с пунктом «Скрипт» для «Настроек ActionScript».
  4. Выберите вкладку «Путь к библиотеке».
  5. Нажмите кнопку «Поиск файла Native Extension (ANE)» и выберите файл «com.vungle.extensions.Vungle.ane». Нажмите «ОК».
  6. Выберите значок гаечного ключа рядом с пунктом «Цель» для «Настроек проигрывателя».
  7. Если целевая платформа — «Android», Выберите вкладку «Разрешения» и включите «INTERNET», «WRITE_EXTERNAL_STORAGE» и «ACCESS_NETWORK_STATE».
  8. Поставьте флажок «Вручную управлять разрешениями и дополнениями к манифесту этого приложения».
  9. Нажмите «ОК».

«Flash Builder 4.6» или более новая версия:

  1. Перейдите в «Свойства проекта».
  2. Выберите «Родные расширения» в разделе «Путь сборки ActionScript
  3. Выберите «Добавить ANE...» и укажите файл «com.vungle.extensions.Vungle.ane».
  4. Выберите «Упаковка сборки ActionScript > Google Android
  5. Выберите вкладку «Родные расширения» и поставьте флажок «Упаковать» рядом с расширением.
  6. Если целевая платформа «iOS», повторите шаги 4 и 5, указывать «Цель» — «Apple iOS».

2. Обновляем дескриптор приложения

Для работы платформы Vungle необходимо внести изменения в XML-файл приложения. Измените созданный с помощью среды разработки XML-файл следующим образом (если используется «Flash Professional», необходимо выполнить соответствующие указания в разделе «Добавляем библиотеку расширений» для инструмента «Flash Professional CS6» или более новой версии: в противном случае ПО может отменить сделанные изменения):

  1. Задайте версию AIR SDK 4.0 (или более позднюю) в файле дескриптора приложения:

    <application xmlns="http://ns.adobe.com/air/application/4.0">
  2. Включите в дескриптор ссылку на расширение:

    <extensions>
    <extensionID>com.vungle.extensions.Vungle</extensionID>
    </extensions>
  3. Если целевая платформа — «Android», может потребоваться добавить расширения службы «Google Play» и (или) библиотеки «Android Support». В этом случае добавите соответствующие идентификаторы.

    <extensions>
    <extensionID>com.vungle.extensions.Vungle</extensionID>
    <extensionID>com.vungle.extensions.android.GooglePlayServices</extensionID>
    <extensionID>com.vungle.extensions.android.AndroidSupportLib</extensionID>
    </extensions>

Для приложений AIR с целевой платформой «Android»

Если целевая платформа — «Android», измените дополнения манифеста XML-элемента «android», и включите разрешения «INTERNET», «WRITE_EXTERNAL_STORAGE» и «ACCESS_NETWORK_STATE»; добавьте определение формы «FullScreenAdActivity»; добавьте службу «VungleService»; добавьте метатег версии «google-play-services»:

  1. <android> 
    <manifestAdditions><![CDATA[ 
    <manifest android:installLocation="auto"> 
    
      <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" /> 
    
      <application>
        <meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version"/>
    
        <activity
          android:name="com.vungle.publisher.FullScreenAdActivity"
          android:configChanges="keyboardHidden|orientation|screenSize"
          android:theme="@android:style/Theme.NoTitleBar.Fullscreen"
        />
    
        <service android:name="com.vungle.publisher.VungleService"
          android:exported="false"
        />
      </application> 
    </manifest> 
    ]]></manifestAdditions>
    </android>

3. Встраиваем Vungle API

Чтобы добавить интерфейс Vungle API, достаточно записать несколько строк ActionScript.

Инициализация расширения Vungle

Инициализируйте API при запуске приложения. (Если используется «чистый» ActionScript, это делается в конструкторе класса документа. Если у вас Flex, вызывайте событие initialize() основного класса. Если используется Flash и код со шкалой времени, это делается на 1-м кадре.)

  1. Импорт классов API:
import com.vungle.extensions.*; 
import com.vungle.extensions.events.*;
  1. Инициализируйте API: вызовите Vungle.create() и передайте массив, содержащий идентификатор приложения, полученный на панели управления Vungle. Если в одном проекте у вас и «iOS», и «Android» укажите в массиве оба идентификатора: сначала для платформы «iOS», затем — для платформы «Android».

Вызов метода Vungle.create() следует обернуть в «try — catch» поскольку во время создания Vungle может выдать ошибку (к примеру, расширение может выдавать ошибку при работе на настольном ПК):

try
{ 
  // инициализация с использованием идентификатора приложения 
  Vungle.create(["your_vungle_id"]); 

  // ИЛИ инициализация с идентификаторами для обеих ОС: «iOS» и «Android» — для многоплатформенных приложений 
  // Vungle.create(["Идентификатор Vungle для платформы «iOS»","Идентификатор Vungle для платформы «Android»"]); 
} catch (error:Error) {
  // расширение невозможно создать. Возможно, вы запускаете не платформе «iOS» («Android»).
}

Отображение рекламных вставок

Для отображения рекламных вставок вызывается метод «playAd()». Можно сначала проверить, доступна ли реклама, с помощью метода «isAdAvailable()»:

if (Vungle.vungle.isAdAvailable())
{
    Vungle.vungle.playAd();
}

Отображение стимулированной рекламы

Для отображения стимулированной рекламы вызывается метод «displayIncentivizedAd()». Можно сначала проверить, доступна ли реклама, с помощью метода «isAdAvailable()». Функция принимает два необязательных параметра, один из которых определяет, нужно ли отображать кнопку закрытия в рекламе, а второй задает необязательную строку-идентификатор пользователя (которая может быть использована в серверных веб-перехватах Vungle для вызова метода «HTTP GET», когда пользователь завершает просмотр):

if (Vungle.vungle.isAdAvailable())
{
    var config:VungleAdConfig = new VungleAdConfig();
    config.incentivized = true;
    Vungle.vungle.playAd(config);
}

Чтобы вознаградить игрока за завершение просмотра стимулированной рекламы, понадобится слушатель событий AD_VIEWED, который описывается ниже.

Добавление слушателей событий

Расширение Vungle отправляет пять событий: VungleEvent.AD_PLAYABLE, VungleEvent.AD_STARTED, VungleEvent.AD_FINISHED, VungleEvent.AD_VIEWED и VungleEvent.AD_LOG.

  1. Событие AD_PLAYABLE отправляется, когда реклама готова к проигрыванию:
Vungle.vungle.addEventListener(VungleEvent.AD_PLAYABLE, onAdPlayable);

function onAdPlayable(e:VungleEvent):void
{
    trace("реклама готова к проигрыванию");
}
  1. События AD_STARTED и AD_FINISHED отправляются, когда реклама начинает и заканчивает отображаться соответственно:
Vungle.vungle.addEventListener(VungleEvent.AD_STARTED, onAdStarted); 
Vungle.vungle.addEventListener(VungleEvent.AD_FINISHED, onAdFinished); 

function onAdStarted(e:VungleEvent):void 
{ 
  trace("реклама отображена"); 
} 

function onAdFinished(e:VungleEvent):void
{ 
  trace("реклама закрыта: " + e.wasCallToActionClicked);
}
  1. Событие AD_VIEWED срабатывает, когда пользователь больше не просматривает рекламу Vungle, но при этом просмотрел некоторую часть видео. Свойство «watched» — это продолжительность (в секундах) той части видео, которую просмотрел пользователь. Свойство «length» — общая продолжительность видео.

(В некоторых случаях это событие может не вызываться: например, когда в рекламе есть предваряющий ее HTML-ресурс, и пользователь отказался от рекламы до начала просмотра видео.)

В случае стимулированной рекламы система Vungle завершенным считает просмотр рекламы, в котором пользователь просмотрел более 80 % продолжительности видео:

Vungle.vungle.addEventListener(VungleEvent.AD_VIEWED, onAdViewed); 

function onAdStarted(e:VungleEvent):void 
{ 
  trace("просмотрено "+e.watched+" of "+e.length+" секунд видео."); 
  var percentComplete:Number=e.watched/e.length; 
  if(percentComplete>0.80) 
  { 
    trace("считается завершенным просмотром — засчитывается награда."); 
  } 
}
  1. Событие AD_LOG отправляется, когда Vungle SDK отправляет сообщение журнала, что можно использовать для отладки. Журналирование реализовано только в Vungle SDK для iOS, поэтому это событие работает только для одной платформы.

 

Vungle.vungle.setLoggingEnabled(true);
Vungle.vungle.addEventListener(VungleEvent.AD_LOG, onAdLog);

private function onAdLog(e:VungleEvent):void
{
    log("журнал рекламы: " + e.message);
}

Включение и выключение автоповорота

Чтобы указать, должно ли видео автоматически поворачиваться в соответствии с ориентацией устройства пользователя, используется метод «setAutoRotationEnabled()»:

Vungle.vungle.setAutoRotation(true);

Другие параметры

Как уже упоминалось ранее, при вызове метода «playAd()» можно передавать объект с параметрами конфигурации. В конфигурации «VungleAdConfig» можно задавать следующие свойства:

orientation

С помощью этого свойства можно указать ориентацию при отображении рекламы. Задаваемые флаги различны для платформ «Android» и «iOS»: подробнее см. в описании класса «VungleOrientation». Флаги можно объединять поразрядным оператором ИЛИ:

config.orientation = VungleOrientation.ANDROID_AUTOROTATE | VungleOrientation.IOS_PORTRAIT;

soundEnabled

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

backButtonImmediatelyEnabled

Используется только на платформе «Android». Если указано «true», пользователь может сразу выйти из показа рекламы с помощью кнопки «назад». Если указано «false», пользователь не может выйти из показа рекламы с помощью кнопки «назад», пока на экране не появится кнопка закрытия.

immersiveMode

Используется только на платформе «Android». Включает и отключает режим комфортного просмотра на устройствах с прошивкой «KitKat» и более новой версии.

incentivized

Устанавливает режим стимулированной рекламы. Если значение параметра — «true», при попытке пользователя пропустить рекламу откроется диалоговое окно подтверждения.

incentivizedUserId

Передаваемый в приложение уникальный идентификатор пользователя, который позволяет убедиться, что данный пользователь должен получить награду за просмотр стимулированной рекламы.

incentivizedCancelDialogTitle, incentivizedCancelDialogBodyText, incentivizedCancelDialogCloseButtonText, incentivizedCancelDialogKeepWatchingButtonText

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

extra1 … extra8

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

placement

Необязательное название показа рекламы, используемое в отчетах на панели управления.

largeButtons

Используется только на платформе «iOS». Если задано «true», кнопки, отображаемые на экране поверх видео, будут большего размера.

Глобальные значения по умолчанию

Установить значения параметров по умолчанию можно с помощью объекта глобальной конфигурации: 

// установка нужных параметров конфигурации
VungleAdConfig.globalConfig.orientation = VungleOrientation.ANDROID_MATCH_VIDEO;
VungleAdConfig.globalConfig.soundEnabled = false;

Теперь каждый создаваемый объект «VungleAdConfig» будет по умолчанию использовать указанные значения. Вызываемый без параметров метод «playAd()» также использует глобальную конфигурацию.

Устаревшие методы

Следующие методы считаются устаревшими, начиная с версии 2.4.0:

Vungle.vungle.displayAd(showCloseButton:Boolean, orientationHint:int):void;
Vungle.vungle.displayIncentivizedAd(name:String, showCloseButton:Boolean, orientationHint:int):void;
Vungle.vungle.setSoundEnabled(enabled:Boolean):void;
Vungle.vungle.setBackButtonEnabled(backEnabled:Boolean):void;
Vungle.vungle.setIncentivizedBackButtonEnabled(backEnabled:Boolean):void;

Поддержка указанных методов сохранена для обратной совместимости. Однако не рекомендуется использовать их в новых приложениях или вместе с вызовом метода «playAd()».

Устранение ошибок и часто задаваемые вопросы

Как использовать класс документа «VungleExample.as» в приложении «Flash Professional CS6»?

  1. Сначала создайте приложение и добавьте расширение (см. разделы 1–3 данного руководства).
  2. Скопируйте «VungleExample.as» в папку, содержащую файлы «.fla». Не копируйте содержимое файла на шкалу времени — так он работать не будет.
  3. Измените идентификаторы приложения (строка 51) на свои идентификаторы приложений Vungle.
  4. В свойствах Flash в «классе документа» запишите «VungleExample» (без кавычек) и нажмите «ОК».
  5. Соберите и установите приложение.

Как установить новую версию AIR SDK (4.0 и выше) в пакет «Flash Professional CS6»?

Скачайте актуальную версию AIR SDK. Если пакет AIR версии 4.0 или выше уже установлен, можете пропустить этот шаг. В противном случае следуйте инструкциям ниже:

  1. Распакуйте архив с пакетом AIR SDK версии 4.0 или более поздней в папку на жестком диске.
  2. Запустите «Flash Professional CS6».
  3. Выберите «Справка > Управление AIR SDK...»
  4. Нажмите кнопку „+“ (плюс) и перейдите в папку с распакованным пакетом AIR SDK.
  5. Нажмите «ОК».
  6. Выберите «Файл > Параметры публикации».
  7. В выпадающем меню «Цель» выберите последнюю версию AIR SDK для платформы iOS.

Как установить новую версию AIR SDK (4.0 и выше) в пакет «Flash Builder»?

Скачайте актуальную версию AIR SDK. Если пакет AIR версии 4.0 или выше уже установлен, можете пропустить этот шаг. Далее можно воспользоваться указаниями компании «Adobe» по обновлению AIR SDK для ПО «Flash Builder».

 

 

Была ли эта статья полезной?
Пользователи, считающие этот материал полезным: 0 из 0
Еще есть вопросы? Отправить запрос

Комментарии