Advertisement — различия между версиями

Материал из wiki.appsalutecreator.com
Перейти к: навигация, поиск
(не показано 25 промежуточных версий 6 участников)
Строка 1: Строка 1:
[[Object|Объект]] '''ad''' позволяет отображать банеры банерных систем. Объект должен находиться на экране на котором необходимо показать банер, объект-провайдер рекламы может находиться на другом экране, но в области видимости объекта. Данный объект предназначен для соблюдения условий запуска рекламы. Огромный плюс, что большинство настроек, могут задавать удалённо маркетологи.
+
[[Object|Объект]] '''Advertisement''' позволяет отображать рекламу разных типов. Объект должен находиться на экране, на котором необходимо показать рекламу, либо на глобальном экране. Данный объект предназначен для соблюдения условий запуска рекламы. Огромный плюс, что большинство настроек, могут задавать удалённо маркетологи.
 +
 
  
 
==Параметры==
 
==Параметры==
  
'''все параметры являются параметрами по-умолчанию, и при получении файла настроек рекламы, будут использоваться настройки рекламы из файла'''
 
  
*'''тип экрана''' (''scrType'') - тип банера, more games или ad:
+
*'''синхронизация''' - не синхронизировать=0, синхронизировать=1;
::'''0''' - MoreGames, другие игры;
 
::'''1''' - Ad, реклама.
 
  
*'''дни''' (''days'') - Количество дней с первого запуска
+
*'''сохранение параметров''' - нет=0, только объект=1, объект с подобъектами=2, только подобъекты=3;
  
*'''запуски''' (''launches'') - Количество запусков
+
*'''placement''' - Идентификатор места показа рекламы в игре.
  
*'''время сессии''' (''sesTm'') - Время сессии (мс). '''''0''''' - показывать мгновенно, '''''-1''''' - не показывать по времени сессии.
 
  
*'''часы''' (''hours'') - Время между показами
+
==Добавляемые параметры==
  
*'''события''' (''events'') - Количество событий, после которого показывается реклама
 
  
*'''таймаут''' (''timeout'') - Время в мс. Если за указанное время не будет получен ответ от провайдера рекламы - появится сообщение об ошибке
+
[[Файл:+.png]] '''реклама готова к показу: изменить состояние объекта'''
  
*'''место в опциях''' - Имя группы параметров которой содержатся параметры объекта
+
*'''объект''' - Объект, состояние которого нужно изменить; '''!!! Объект должен находиться выше по дереву, чтобы успеть проинициализироваться до готовности рекламы !!!'''
  
*'''тестовый режим''' - значения параметров дни, время сессии, часы будут отсчитываться в минутах, то есть например вместо 10 дней - 10 минут
+
*'''состояние''' - Новое состояние объекта.
  
  
группа '''дополнительные данные'''
+
[[Файл:+.png]] '''реклама готова к показу: изменить свойство объекта'''
*'''тип рекламы''':
 
::'''0''' - fullscreen, полноэкранный;
 
::'''1''' - banner top, банер сверху;
 
::'''2''' - banner bottom, банер снизу.
 
*'''имя рекламы''' - ключ банера рекламы (ad), для playheaven:
 
::'''main_menu''' - показываем на главном экране (мейне), вызываем начиная с 2-й сессии;
 
::'''upsale''' - вызываем начиная с 2-й сессии, предлогаем скачать другую игру.
 
*'''имя more games''' - ключ банера more games, для playheaven:
 
::'''more_games''' - показываем другие игры по нажатию на кпопку.
 
  
 +
*'''объект''' - Объект, свойство которого нужно изменить; '''!!! Объект должен находиться выше по дереву, чтобы успеть проинициализироваться до готовности рекламы !!!'''
  
группа '''провайдер рекламы'''
+
*'''свойство''' - Свойство, которое нужно изменить.
*'''объект''' - Объект, обладающий рекламной функциональностью.
 
  
 +
*'''значение''' - Новое значение свойства.
  
Если добавлено несколько объектов обладающих рекламной функциональностью будет выбираться один из них равновероятностно.
 
  
Объект сам показывает рекламу если выполняются условия(текущее значение больше либо равно заданному). Условия '''дни''', '''запуски''', '''время сессии''', '''часы''' проверяются через логическое "и", то есть все 4 должны выполняться одновременно. '''события''' и временные условия проверяются через логическое "или". То есть банер покажется когда или выполняются временные условия, или когда количество событий совпадает с заданным значением или больше. После показа банера при совпадении количества событий - счётчик событий сбрасывается.
+
[[Файл:+.png]] '''реклама успешно показана: изменить состояние объекта'''
  
Показ рекламы можно включать и отключать через параметр ''ad'' в объекте типа [[Options]]
+
*'''объект''' - Объект, состояние которого нужно изменить;
  
===старые===
+
*'''состояние''' - Новое состояние объекта.
  
*'''тип'''''(adtype)'' - тип банерной системы(flurry, amazon, chartboost)
+
[[Файл:+.png]] '''нужен запрос gdpr''' [https://ru.wikipedia.org/wiki/%D0%9E%D0%B1%D1%89%D0%B8%D0%B9_%D1%80%D0%B5%D0%B3%D0%BB%D0%B0%D0%BC%D0%B5%D0%BD%D1%82_%D0%BF%D0%BE_%D0%B7%D0%B0%D1%89%D0%B8%D1%82%D0%B5_%D0%B4%D0%B0%D0%BD%D0%BD%D1%8B%D1%85]
  
*'''space'''''(adspace)'' - имя рекламной кампании для flurry. Это имя будет отображаться в списке рекламных кампаний на портале flurry.
+
*'''объект''' - Объект, состояние которого нужно изменить;
  
*'''size'''''(adsize)'' - размер и положение банера(top - 1, bottom - 2, fullscreen - 3)
+
*'''состояние''' - Новое состояние объекта.
  
==Состояния==
+
Этот параметр позволит нам использовать персональные данные игроков при выдаче рекламы.
  
*'''show''' - показать рекламу
+
'''Внимание''': для триггера команды '''"нужен запрос gdpr"''' нужно, чтобы выли выполнены следующие условия:
  
*'''hide''' - спрятать рекламу
+
* Приехал рекламный конфиг из Европы (в логе "type":"Europe");
  
*'''event''' - увеличить счётчик событий на 1
+
* нет информации о согласии игрока (в таком случае в опциях не будет значения gdpr) или мы вручную сбросили его согласие в игре (установив значение ниже -10).
  
Есть возможность использовать внешний конфигурационный файл. Для этого необходимо в [[app.icf]] указать:
+
Так как рекламный конфиг у нас приезжает неизвестно когда, мы не должны открывать окно через этот параметр. Вместо этого мы делаем небольшую машину, которая будет ставить флажок, сигнализируюющий о необходимости запросить у игрока его согласие на обработку персональных данных. А уже в самой логике игры мы можем вызывать окно на согласие о сборе персональной информации тогда, когда нам нужно, опираясь на этот флаг.
<pre>
 
[Advertisement]
 
ConfigUrl="http://url_to_file"
 
</pre>
 
  
=Настройки=
+
==Состояния==
  
==Google Mobile Ads (admob)==
+
*'''show''' - показать рекламу.
при добавлении в качестве провайдера в advertisiment необходимо указать рекламный id в добавляемое поле "имя"
 
  
Настройки для манифестов:
+
*'''startCache''' - запустить предварительное кеширование (для проектов с отложенным кешированием)
  
<pre>
+
*'''gdpr''' - при вызове этого состояния обьект '''advertisement''' запишет в параметр в опциях '''gdpr''' значение из '''param''' , которое мы передаем в сам обьект advertisement. Для стран, где действует GDPR, таргетированная реклама показывается, если мы установили значение параметра в 1, и нетаргетированная, если это значение установлено в 0.
<meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version" />
 
<!-- Activity required to show ad overlays. -->
 
<activity android:name="com.google.android.gms.ads.AdActivity" android:theme="@android:style/Theme.Translucent" android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|uiMode|screenSize|smallestScreenSize"/>
 
<activity android:name="com.facebook.ads.InterstitialAdActivity" android:configChanges="keyboardHidden|orientation|screenSize" />
 
<activity android:name="com.flurry.android.FlurryFullscreenTakeoverActivity" android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|uiMode|screenSize|smallestScreenSize" />
 
<activity android:name="com.jirbo.adcolony.AdColonyOverlay" android:configChanges="keyboardHidden|orientation|screenSize" android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen" />
 
<activity android:name="com.jirbo.adcolony.AdColonyFullscreen" android:configChanges="keyboardHidden|orientation|screenSize" android:theme="@android:style/Theme.Black.NoTitleBar.Fullscreen" />
 
<activity android:name="com.jirbo.adcolony.AdColonyBrowser" android:configChanges="keyboardHidden|orientation|screenSize" android:theme="@android:style/Theme.Black.NoTitleBar.Fullscreen" />
 
</pre>
 
  
 +
Это состояние мы не вызываем без ведома игрока! Оно должно вызываться, когда игрок принимает или отклоняет запрос о сборе персональных данных. Этот запрос мы представляем ему в виде окна с двумя кнопками и без возможности его закрыть. Также после принятия или отказа от сбора, игрок может изменить свое решение, например, через checkbox в настройках игры.
  
<pre>
+
==Коды ошибок==
<!-- Used to request banner and interstitial ads. -->
 
<uses-permission android:name="android.permission.INTERNET"/>
 
<!-- Used to avoid sending an ad request if there is no connectivity. -->
 
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
 
<uses-permission android:name="com.google.android.providers.gsf.permission.READ_GSERVICES" />
 
<uses-permission android:name="com.google.android.providers.gsf.permission.WRITE_GSERVICES" />
 
<uses-permission android:name="android.permission.VIBRATE" />
 
</pre>
 
  
настройки app.icf:
+
*'''0''' - ''AD_ERROR_NONE          = 0'' - все хорошо, ошибок нет;
 +
*'''1''' - ''AD_ERROR_SKIP          = 1'' - показывать нечего (нет ни одного активного провайдера рекламы, нужно спрятать кнопки показа, пользовательские окна при этой ошибке показывать не нужно!!!);
 +
*'''2''' - ''AD_ERROR_INTERNET      = 2'' - ошибка отсутствия интернета;
 +
*'''3''' - ''AD_ERROR_NOT_FOUND      = 3'' - запрос на показ рекламы был отправлен, но реклама по данному запросу отсутствует;
 +
*'''4''' - ''AD_ERROR_CANCELED      = 4'' - показ рекламы был отменен пользователем.
 +
*'''5''' - ''AD_ERROR_UNKNOWN      = 5'' - неизвестная ошибка.
  
[s3eAbsGoogleMobileAds]
+
Для обработки ошибок использовать [[Errormanager|ErrorManager]].
TestDevice0="device id" - id устройства. Можно получить с помощью приложения (https://play.google.com/store/apps/details?id=pe.go_com.admobdeviceidfinder )
 
VideoUnitID="unit id" - ключ из админки
 
  
==Playhaven==
+
==Симулятор==
  
[[Playhaven]]
+
Для работы симулятора рекламы на редакторном вьювере необходимо добавить в app.icf параметры:
  
==Chartboost==
+
  [Game]
 +
  bundle="%id_game"
 +
  [Game]
 +
  VersionMain=%m
 +
  VersionGraphic=%g
 +
  VersionLogic=%l
  
[[Chartboost]]
+
где:
 +
%id_game - бандл игры, соответствующий файлу конфигурации рекламы,
 +
%m, %g, %l - номер версии игры, соответствующий файлу конфигурации рекламы.
  
==Flurry==
+
При вызове состояния ''show'' объекту на экране появится черный прямоугольник с названием placement'а вызванной рекламы. Esc симулирует закрытие рекламы и вызов ''ошибки 4'' (показ рекламы отменен пользователем). Enter симулирует закрытие рекламы и вызов обработчика ''реклама успешно показана''.
  
[[Flurry]]
 
  
==Amazon==
+
[[Category:Options]]
 
+
[[Category:Реклама]]
Для работы рекламы от Amazon должен быть указан соответствующий тип рекламы, а также указаны следующие настройки в [[app.icf]]:
 
 
 
<pre>
 
 
 
[s3eAmazonAds]
 
app_key="sample-app-v1_pub-2"
 
logging=1
 
testing=1
 
 
 
</pre>
 
 
 
'''app_key''' - ключ для рекламы
 
  
'''logging''' - вести логи показа, полезно для отладки
+
==GDPR==
  
'''testing''' - режим тестирования
+
Некоторые провайдеры требуют согласия на сбор и обработку персональных данных в европейских странах. Для корректной работы необходимо в app.icf добавить параметр:
  
По умолчанию logging и testing равны 1, поэтому при релизе значение обоих параметров необходимо принудительно устанавливать в 0.
+
  [Parameters]
 +
  gdpr=-1
  
В итоговый ''AndroidManifest.xml'' должны быть добавлены следующие строки:
+
Если этот параметр есть в app.icf, то мы даем игре знать, что хотим собирать персональные данные игрока. Тогда будет работать добавляемый параметр '''нужен запрос gdpr'''.
  
<pre>
+
Значения, которые может принимать параметр: -1 - не известно, 0 - не согласен, 1 - согласен (Провайдер AppLovin воспринимает 0/1, Chartboost -1/0/1, AdMob - 0/1).
 +
Значение по-умолчанию, с которым собирать проект -1.
  
<activity android:name="com.amazon.device.ads.MraidBrowser" android:configChanges="keyboardHidden|orientation"/>
+
==Подробное описание работы обьекта==
<activity android:name="com.amazon.device.ads.VideoActionHandler" android:configChanges="keyboardHidden|orientation|screenSize"/>
 
  
</pre>
+
Продолжение здесь: http://jira1:8090/pages/viewpage.action?pageId=23822337
 
 
('''с вьювера версии от 10.07.2014 должны быть следующие строки''':
 
 
 
<pre>
 
<activity android:name="com.amazon.device.ads.AdActivity" android:configChanges="keyboardHidden|orientation|screenSize"/>
 
</pre>
 
 
 
)
 
 
 
Также должны быть следующие разрешения:
 
 
 
<pre>
 
 
 
<uses-permission android:name="android.permission.INTERNET" />
 
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
 
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
 
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
 
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
 
 
 
</pre>
 
 
 
более подробно про рекламу от amazon: https://developer.amazon.com/sdk/mobileads/quick-start.html
 
 
 
=Дополнительные сведения=
 
 
 
* ''AndroidManifest.xml'' находится обычно в каталоге ''%s3e_dir%\deploy\plugins\android''
 
 
 
* Также можно вместо ''AndroidManifest.xml'' вносить соответствующие настройки  в ''android-extra-application-manifest.xml'' и ''android-extra-manifest.xml'', которые находятся в каталоге
 
''%каталог_редактора%\system\marmalade\conf\%марект%(к примеру android)''
 
 
 
* Объект при загрузке экрана не переводится автоматически в состояние show, в это состояние его надо переводить машиной или другим объектом.
 
 
 
* Если выбран режим банера '''fullscreen''', то при показе банера все действия в приложении "ставятся на паузу", возврат в игру возможен только при закрытии банера, если выбран другой режим отображения - приложение во время показа "на паузу" не ставится, то есть все действия продолжают выполняться.
 
 
 
* <span style="background-color:yellow">Для работы Chartboost на ios необходима версия ос не ниже 6-й</span>
 
 
 
[[Category:Options]]
 
[[Category:Реклама]]
 

Версия 11:31, 29 мая 2019

Объект Advertisement позволяет отображать рекламу разных типов. Объект должен находиться на экране, на котором необходимо показать рекламу, либо на глобальном экране. Данный объект предназначен для соблюдения условий запуска рекламы. Огромный плюс, что большинство настроек, могут задавать удалённо маркетологи.


Параметры

  • синхронизация - не синхронизировать=0, синхронизировать=1;
  • сохранение параметров - нет=0, только объект=1, объект с подобъектами=2, только подобъекты=3;
  • placement - Идентификатор места показа рекламы в игре.


Добавляемые параметры

+.png реклама готова к показу: изменить состояние объекта

  • объект - Объект, состояние которого нужно изменить; !!! Объект должен находиться выше по дереву, чтобы успеть проинициализироваться до готовности рекламы !!!
  • состояние - Новое состояние объекта.


+.png реклама готова к показу: изменить свойство объекта

  • объект - Объект, свойство которого нужно изменить; !!! Объект должен находиться выше по дереву, чтобы успеть проинициализироваться до готовности рекламы !!!
  • свойство - Свойство, которое нужно изменить.
  • значение - Новое значение свойства.


+.png реклама успешно показана: изменить состояние объекта

  • объект - Объект, состояние которого нужно изменить;
  • состояние - Новое состояние объекта.

+.png нужен запрос gdpr [1]

  • объект - Объект, состояние которого нужно изменить;
  • состояние - Новое состояние объекта.

Этот параметр позволит нам использовать персональные данные игроков при выдаче рекламы.

Внимание: для триггера команды "нужен запрос gdpr" нужно, чтобы выли выполнены следующие условия:

  • Приехал рекламный конфиг из Европы (в логе "type":"Europe");
  • нет информации о согласии игрока (в таком случае в опциях не будет значения gdpr) или мы вручную сбросили его согласие в игре (установив значение ниже -10).

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

Состояния

  • show - показать рекламу.
  • startCache - запустить предварительное кеширование (для проектов с отложенным кешированием)
  • gdpr - при вызове этого состояния обьект advertisement запишет в параметр в опциях gdpr значение из param , которое мы передаем в сам обьект advertisement. Для стран, где действует GDPR, таргетированная реклама показывается, если мы установили значение параметра в 1, и нетаргетированная, если это значение установлено в 0.

Это состояние мы не вызываем без ведома игрока! Оно должно вызываться, когда игрок принимает или отклоняет запрос о сборе персональных данных. Этот запрос мы представляем ему в виде окна с двумя кнопками и без возможности его закрыть. Также после принятия или отказа от сбора, игрок может изменить свое решение, например, через checkbox в настройках игры.

Коды ошибок

  • 0 - AD_ERROR_NONE = 0 - все хорошо, ошибок нет;
  • 1 - AD_ERROR_SKIP = 1 - показывать нечего (нет ни одного активного провайдера рекламы, нужно спрятать кнопки показа, пользовательские окна при этой ошибке показывать не нужно!!!);
  • 2 - AD_ERROR_INTERNET = 2 - ошибка отсутствия интернета;
  • 3 - AD_ERROR_NOT_FOUND = 3 - запрос на показ рекламы был отправлен, но реклама по данному запросу отсутствует;
  • 4 - AD_ERROR_CANCELED = 4 - показ рекламы был отменен пользователем.
  • 5 - AD_ERROR_UNKNOWN = 5 - неизвестная ошибка.

Для обработки ошибок использовать ErrorManager.

Симулятор

Для работы симулятора рекламы на редакторном вьювере необходимо добавить в app.icf параметры:

 [Game]
 bundle="%id_game"
 [Game]
 VersionMain=%m
 VersionGraphic=%g
 VersionLogic=%l

где: %id_game - бандл игры, соответствующий файлу конфигурации рекламы, %m, %g, %l - номер версии игры, соответствующий файлу конфигурации рекламы.

При вызове состояния show объекту на экране появится черный прямоугольник с названием placement'а вызванной рекламы. Esc симулирует закрытие рекламы и вызов ошибки 4 (показ рекламы отменен пользователем). Enter симулирует закрытие рекламы и вызов обработчика реклама успешно показана.

GDPR

Некоторые провайдеры требуют согласия на сбор и обработку персональных данных в европейских странах. Для корректной работы необходимо в app.icf добавить параметр:

 [Parameters]
 gdpr=-1

Если этот параметр есть в app.icf, то мы даем игре знать, что хотим собирать персональные данные игрока. Тогда будет работать добавляемый параметр нужен запрос gdpr.

Значения, которые может принимать параметр: -1 - не известно, 0 - не согласен, 1 - согласен (Провайдер AppLovin воспринимает 0/1, Chartboost -1/0/1, AdMob - 0/1). Значение по-умолчанию, с которым собирать проект -1.

Подробное описание работы обьекта

Продолжение здесь: http://jira1:8090/pages/viewpage.action?pageId=23822337