Начало работы с пакетом Vungle SDK 1.0–1.4 — Adobe Air

В этом руководстве показано, как интегрировать подключаемый модуль Adobe Air для Vungle в обычное приложение. Приведенный здесь исходный код доступен в нашем публичном репозитории на GitHub.

Содержание

Перед началом работы
1. Добавление библиотеки расширений
2. Обновление дескриптора приложения
3. Интеграция Vungle API
Устранение неполадок и ответы на часто задаваемые вопросы

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

  • Расширению Vungle требуется пакет Adobe AIR SDK 4.0 или более поздней версии. Инструкции по обновлению пакета AIR SDK в программе Flash Builder или Flash Professional см. в разделе «Как обновить пакет AIR SDK?» в конце этого руководства.

  • При работе с платформой Android для расширения Vungle AIR требуется наличие JDK 6 или JDK 7 (в зависимости от используемой версии Flash) в системе разработки. Для работы приложения требуется Android 3.0 (Honeycomb — API версии 11) или более поздней версии.

  • Вы можете ознакомиться с документаций по классу ActionScript 3.

  • Пример класса приложения приведен в файле example/VungleExample.as. (Если у вас Flash Professional и вы не знаете, как использовать класс документа, см. раздел «Как использовать класс документа VungleExample в Flash CS6?» в конце этого руководства.)

1. Добавление библиотеки расширений

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

При разработке для платформы Android может потребоваться также добавить в проект библиотеку сервисов Google Play. Эта библиотека уже добавлена во многие другие расширения, так что возможно, добавлять ее не придется. Чтобы добавить расширение, выполните описанные ниже действия, но используйте com.vungle.extensions.android.GooglePlayServices.ane вместо com.vungle.extensions.Vungle.ane.

Flash Professional CS6 или более поздней версии:

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

Flash Builder 4.6 или более поздней версии:

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

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

Для работы Vungle необходимо внести изменения в XML-файл приложения. Измените XML-файл, созданный с помощью среды IDE, следующим образом (если у вас 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. В этом случае добавьте также ее идентификатор расширения.
    <extensions>
    <extensionID>com.vungle.extensions.Vungle</extensionID>
    <extensionID>com.vungle.extensions.android.GooglePlayServices</extensionID>
    </extensions>

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

Если целевая платформа — Android, измените дополнения манифеста в XML-элементе android следующим образом:

  • включите разрешения INTERNET, WRITE_EXTERNAL_STORAGE и ACCESS_NETWORK_STATE;
  • добавьте определения действий VideoFullScreenAdActivity и MraidFullScreenAdActivity;
  • добавьте тег метаданных версии google-play-services.
<android> 
<manifestAdditions><![CDATA[
<manifest android:installLocation="auto">

 <uses-permission android:name="android.permission.INTERNET"/>
 <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
 <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.VideoFullScreenAdActivity"
     android:configChanges="keyboardHidden|orientation|screenSize"
     android:theme="@android:style/Theme.NoTitleBar.Fullscreen"/>
   <activity android:name="com.vungle.publisher.MraidFullScreenAdActivity"
     android:configChanges="keyboardHidden|orientation|screenSize"
     android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen"/>
 </application>
</manifest>
]]></manifestAdditions>
</android>

Приложения AIR с целевой платформой iOS

Если целевая платформа — iOS, рекомендуем отключить App Transport Security (ATS). Для этого добавьте в XML-дескриптор приложения следующие строки при сборке с использованием Adobe AIR 21+:

<iPhone>
    <InfoAdditions>
        <![CDATA[
            <key>NSAppTransportSecurity</key>
            <dict>
                <key>NSAllowsArbitraryLoads</key>
                <true />
            </dict>
        ]]>
    </InfoAdditions>
</iPhone>

Подробнее об App Transport Security см. в статье Подготовка приложений для iOS 9 (Preparing Your Apps for iOS 9).

3. Интеграция Vungle API

Для добавления Vungle API в приложение нужно добавить всего несколько строк в ActionScript.

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

Инициализируйте API при запуске приложения.

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

    Заключите вызов метода Vungle.create() между операторами try и catch, поскольку в процессе создания Vungle может выдать ошибку (например, расширение выдает ошибку при работе на настольном компьютере).
    try
    {
     // инициализация с идентификатором приложения
     Vungle.create(["your_vungle_id"]);

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

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

Для отображения рекламных вставок вызовите метод playAd(). Лучше сначала проверить, доступна ли реклама, с помощью метода AdAvailable().

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

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

Для отображения стимулированной рекламы вызовите метод playAd() с объектом конфигурации и укажите для параметра incentivized значение true. Лучше сначала проверить, доступна ли реклама, с помощью метода isAdAvailable().

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

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

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

Расширение Vungle формирует четыре события: VungleEvent.AD_PLAYABLE, VungleEvent.AD_STARTED, VungleEvent.AD_FINISHED, и VungleEvent.AD_LOG.

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

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

    function onAdStarted(e:VungleEvent):void
    {
     trace("ad displayed");
    }

    function onAdFinished(e:VungleEvent):void
    {
     trace("ad dismissed, CTA = " + e.wasCallToActionClicked);
     if (e.wasSuccessfulView)
     {
       trace("counts a completed view - present reward.");
     }
    }
  3. Событие 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("ad log: " + e.message);
    }

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

Как уже было сказано, при вызове метода 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

ПОЯВИТСЯ ВСКОРЕ. Необязательное имя размещения рекламы для расширенной классификации при запросе данных через Vungle API отчетности.

largeButtons

Этот параметр действует только в iOS. Если значение true, кнопки, отображаемые на экране поверх видео, будут большего размера.

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

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


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

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

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

Следующие методы считаются устаревшими, начиная с v2.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().

ПРИМЕЧАНИЕ. Когда приложение находится в режиме тестирования, скачивать рекламируемые приложения нельзя. Кроме того, на панели управления невозможно будет просмотреть количество показов. Это связано с тем, что тестовая реклама предназначена только для проверки правильности интеграции SDK. Эти функциональные возможности станут доступны после запуска приложения в активном режиме.

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

Как использовать класс документа 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 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.

Появляется ошибка Adobe Animate Invalid Input. Что делать?

Если появляется сообщение об ошибке, показанное на иллюстрации ниже, см. эту статью.error_message_at_publish.png

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

Комментарии