Скрипт базовой витрины — различия между версиями
Admin (обсуждение | вклад) м (Защищена страница «Скрипт базовой витрины» ([edit=sysop] (бессрочно) [move=sysop] (бессрочно))) |
Admin (обсуждение | вклад) |
||
Строка 182: | Строка 182: | ||
<br> | <br> | ||
+ | |||
+ | |||
Пример объекта: | Пример объекта: |
Текущая версия на 13:15, 3 апреля 2019
Работа с экземпляром партнерских витрин
Данный документ содержит информацию по развертыванию партнерских XML-витрин на сервере партнера, а также по их дальнейшей работе. Документ предназначен для программистов, разрабатывающих партнерские XML-витрины, а также для партнеров, желающих разворачивать витрины на своем сервере самостоятельно.
Содержание
- Определения, используемые в данном документе
- Введение: что это такое, для чего нужно, как это работает, примеры готовых витрин, FAQ
- Интеграция шаблона витрины
- Развертывание готовой XML-витрины на сервере партнера
- Приложение 1. Описание форматов данных
- Описание формата данных игр
- Описание формата данных жанров
- Приложение 2. Дополнительная информация по эксплуатации витрины
- Описание основных значений конфигурации витрины
- Параметры кеширования данных на витрине
Определения
Игра – продукт компании Alawar Entertainment, Inc., представляющий собой компьютерную игру. Игра содержит текстовое описание, дату выхода, ссылки на графические материалы, дистрибутив игры, ссылку на регистрацию игры.
Партнерская программа Alawar – набор услуг Alawar Entertainment, Inc. по предоставлению развлекательного игрового контента любым веб-ресурсам.
Витрина – сайт или раздел сайта участника Партнерской программы, предоставляющий информацию о продуктах компании Alawar Entertainment, Inc.
Шаблон витрины – неделимый набор файлов, включающий в себя графические материалы, стили и php-файлы, отображающие контент витрины. (Ссылка на архив с шаблоном витрины).
Скрипт витрины (ядро витрины, движок витрины) – программный скрипт, реализующий работу витрины на сервере партнера. Распространяется через Партнерскую программу Alawar.
XML-витрина – разновидность скрипта витрины компании Alawar Entertainment, Inc. Данные об играх на витрину загружаются из XML-файла. Далее по тексту «Витрина».
Рекламные блоки – это блоки небольшого размера, с описанием небольшого количества новых, хитовых или других игр. Эти блоки вставляются в другие разделы партнерского сайта и являются входными точками на партнерскую витрину. Примеры (http://www.klerk.ru/humour/)
Административная зона витрины – это раздел витрины, где можно указать или изменить основные параметры витрины. В этот раздел можно попасть по адресу http://[aдрес-витрины]/admin/index.php, где [адрес-витрины] – URI Витрины на сервере Партнера. Пример: Если витрина расположена по адресу http://alawar-vitrina-example, то в административную зону можно попасть по следующей ссылке: http://alawar-vitrina-example/admin/index.php.
Введение
Партнерская программа Alawar – система партнерских витрин для распространения игрового контента. Партнерская витрина включает в себя все игры, представленные в портфолио Alawar Entertainment и предполагает размещение казуальных скачиваемых мини-игр и онлайновых флеш-игр. Примеры витрин можно увидеть здесь (http://partner.alawar.ru/showrooms.php).
Игры распространяются по условно-бесплатной (shareware) лицензии. Пользователь имеет право бесплатно поиграть в любую скачанную игру, после чего ему будет предложено приобрести ключ и активировать полную версию. Приобрести ключ можно через SMS, банковский перевод, электронную карту, электронные деньги и пр.
Правила участия в Партнерской программе находятся здесь:
http://partner.alawar.ru/partners_gs.php
Ответы на часто задаваемые вопросы по Партнерской программе можно найти здесь:
http://partner.alawar.ru/faq.php
Партнерская программа предоставляет ряд возможностей по интеграции контента, такие как xml-витрина, javascript-витрина, распространение флеш-игр и др. Более подробная информация представлена на официальном сайте Партнерской программы:
http://partner.alawar.ru/vitr/vconfig/
Интеграция шаблона витрины
Интеграция шаблона витрины – это добавление набора файлов шаблона витрины для изменения ее внешнего вида.
Вы можете воспользоваться одним из двух предложенных вариантов интеграции шаблона – использовать готовый шаблон из Партнерской зоны или создать собственный шаблон.
Начало работы
Перед началом работы витрины необходимо сделать следующее:
- Следует переименовать файл “config.inc.php.templates” на “config.inc.php” в корне витрины.
- Указать свой PID (идентификатор партнера), для этого нужно изменить файл config.inc.php в корне витрины:
define( 'PARTNER_ID', XXXX );
где XXXX - идентификатор партнера в Партнерской программе. - Выставить кодировку, в которой будет отображаться витрина:
define('SA_CODEPAGE', XXXX);
где XXXX – любое из значений 'windows-1251' или ' utf-8'.
Файлы шаблона витрин должны быть в выбранной кодировке.
Использование готового шаблона
Для внедрения на сайт готового шаблона вам необходимо сделать следующее:
- Распаковать архив в папку «…/alawar-vitrina-example/var/ru/_templates/».
- Скопировать архив шаблона из Партнерской зоны (ссылка).
- Включить использование выбранного шаблона в административной зоне витрины. На главной странице административной зоны в выпадающем списке «Название шаблона» нужно выбрать необходимый шаблон и сохранить изменения, нажав кнопку «Submit».
Создание нового шаблона
Для создания нового шаблона вам необходимо сделать следующее:
Необходимо преобразовать эскиз витрины (набор html-файлов, графических материалов, стилей) в набор шаблонов для отображения каталога игр с помощью программных скриптов витрины.
Файлы шаблонов составляют следующую структуру:
Пути указываются относительно папки, в которой находятся файлы шаблонов: …/alawar-vitrina-example/var/ru/_templates/default_tpl/
- /default/base.php – точка входа на витрину. В этом файле могут быть размещены «хедер» и «футер» Партнерского сайта, должен быть включен файл шаблона «main.php» (см. ниже), интерфейс отображения скриншотов к играм.
- /default/main.php – содержит меню жанров игр, выносные блоки с «хитовыми» и «новыми» играми, включение файлов-шаблонов со списками «хитовых», «новых» игр, по жанрам, со страницей игры. Также может содержать подключение страницы поиска, отправки сообщений в техподдержку и др.
- /casualpcgames/game_list.php – содержит списки игр.
- /casualpcgames/game.php – содержит страницу игры.
- /casualpcgames/404.php – содержит сообщение, что данная страница не может быть отображена.
- /casualpcgames/notexist.php – содержит сообщение о том, что по такому адресу страницы не существует.
- /onlinegames/game_list.php – может содержать список онлайновых флеш-игр.
- /default/search.php – в этом файле может находиться список игр, найденный в результате поиска.
- /default/support.php – здесь может находиться код формы техподдержки.
- /default/advert_block.php – может содержать рекламные блоки с «хитовыми», «новыми» и другими играми.
- - минимальный набор шаблонов, присутствие которых необходимо для работы витрины.
По шагам:
- Берем архив ядра базовой витрины и распаковываем в отдельную папку.
- Из архива с эскизом витрины копируем файлы картинок и стилей в папку шаблона (Пример: …/alawar-vitrina-example/var/ru/_templates/default_tpl/).
- Установки в основном файле конфигурации. В корне дистрибутива витрины открываем файл config.inc.php.templates:
Меняем значение константы "PARTNER_ID" на значение идентификатора партнера этой витрины. Здесь также можно изменить и другие параметры витрины.
При разработке нового шаблона витрины рекомендуется отключать кеширование страниц витрины. Для этого выставляем значение свойства «SA_HTML_CACHE_LIFETIME» в 0.
- Создаем папки и пустые php-файлы шаблонов. В эти файлы копируем фрагменты html-кода, предоставленного в эскизе витрины. Разбиение html-кода можно делать, следуя рекомендациям, указанным в описании структуры файлов шаблона витрины.
- Далее необходимо заменить названия игр, ссылки на страницу с игрой, ссылки на скачиваемый дистрибутив, пути и размеры графических материалов и др. на соответствующие переменные, константы и методы, с помощью которых можно отобразить необходимые данные. Подробнее о переменных и методах можно узнать в таблице основных операций и таблице формата данных.
- При создании нового шаблона следует обратить внимание на следующие моменты:
- Пункты меню жанров могут быть активными и неактивными, в зависимости от параметров «cat», «act» и «code», передаваемых на витрину. Поэтому необходимо на каждый пункт меню навешивать соответствующие условия на активность.
- На странице с игрой внизу также можно отображать список игр того же жанра, к которому относится сама игра.
Формат данных указан в Приложении 1.
Документация кода витрины предоставлена по данной ссылке.
Для быстрой интеграции шаблона предлагаем вам ознакомиться с основными операциями.
Основные операции, которые могут вам потребоваться при разработке нового шаблона:
Таблица 1. Основные операции при создании шаблона витрины
Название операции |
Код и результат реализации |
Создание модели |
|
Получение списка жанров |
$genres= $model->createGenreMenu();
Результат:Массив с информацией по жанрам. Каждый элемент имеет следующие поля:
array( 'name' => 'имя-жанра', 'code' => 'код-жанра', 'action' => 'genre', // служебная информация для формированияuriк странице жанра ); |
Получение списка хитовых игр |
$iTopGames = $model->getTopGames(); $_temp = $iTopGames->getItems(); $topGames = $_temp->getArray();
Результат: Массив объектов игра, содержащий название игры, ее описание, ссылки на графические материалы и скачиваемый дистрибутив игры. Объекты отсортированы по убыванию рейтинга.
Пример объекта: object(SA_PCGame)#11 (9) { ["id"]=> int(6363) ["code"]=> bool(false) ["name"]=> string(15) "Веселая ферма 3" ["dictionaries"]=> array(3) { ["all-games"]=> array(1) { ["all-games"]=> bool(false) } ["Genre"]=> array(1) { ["arcade"]=> string(3) "684" } ["Rating"]=> array(1) { ["rating-hit"]=> string(3) "684" } } ["Properties"]=> array(8) { ["SymbolCode"]=> string(13) "farm-frenzy-3" ["ReleaseDate"]=> string(19) "2009-07-21 10:00:00" ["Description45"]=> string(41) "Бизнес-симулятор крестьянского хозяйства." … ["RelatedItems"]=> array(1) { [105566]=> array(4) { ["id"]=> string(6) "105566" ["Source"]=> string(11) "onlinegames" ["Name"]=> string(15) "Веселая ферма 3" ["Properties"]=> array(2) { ["Width"]=> string(3) "640" ["Height"]=> string(3) "585" } } } ["Files"]=> array(1) { ["distrib"]=> array(5) { ["Type"]=> string(7) "distrib" ["Timestamp"]=> string(10) "1255584196" ["Name"]=> string(22) "FarmFrenzy3Rus_758.exe" ["Size"]=> string(7) "91.02Mb" ["Url"]=> string(52) "http://www.alawar.ru/download/FarmFrenzy3Rus_758.exe" } } } |
Получение списка новых игр |
$iNewGames = $model->getNewGames(); $_temp = $iNewGames->getItems(); $newGames = $_temp->getArray();
Результат: Массив объектов игра, содержащий название игры, ее описание, ссылки на графические материалы и скачиваемый дистрибутив игры. Объекты отсортированы по убыванию даты выхода игры.
Объект имеет такую же структуру, как и в описанном выше пункте получения списка хитовых игр |
Получение списка игр определенного жанра |
$iGames = $model->getGamesByGenre($game->getGenreCode()); $_temp = $iGames->getItems(); $games = $_temp->getArray();
Результат: Массив объектов игра, содержащий название игры, ее описание, ссылки на графические материалы и скачиваемый дистрибутив игры. В массив входят лишь объекты игр указанного жанра, отсортированные по убыванию рейтинга в указанном жанре.
Объект имеет такую же структуру, как и в описанном выше пункте получения списка хитовых игр. |
Вывод информации по игре |
$game->getProperty('Description45'); или $game->getProperty('Description80'); или $game->getProperty('Description450'); или $game->getProperty('Description2000');
Результат: Строка с описанием игры размером до указанной величины. Подробнее формат данных игры можете посмотреть в Приложении 2. |
Подготовка раздела с флеш-играми |
Раздел с онлайновыми флеш-играми располагается на отдельной странице. В адресной строке должен присутствовать параметр «cat», равный «onlinegames». В этом случае автоматически инициализируется массив $games с объектами онлайн-игр. Иначе нужно создавать отдельную модель с онлайновыми флеш-играми. Пример: $onlineModel = $showroom->CreateModel('ru','onlinegames'); $iTopGames = $onlineModel->getTopGames(); $_temp = $iTopGames->getItems(); $oGames = $_temp->getArray();
Результат: Массив $oGames объектов онлайновые флеш-игры, содержащий название игры, ее описание, ссылки на графические материалы и скачиваемый дистрибутив игры. Объекты отсортированы по убыванию рейтинга. |
В разделе простых игр получение онлайн-аналога простой игры |
$onlineGames = $game->getRelatedItems('onlinegames'); $keys = array_keys( $onlineGames ); $key = $keys[0]; $onlineModel = $showroom->CreateModel('ru', 'onlinegames'); $iGames = $onlineModel->getAllGames(); $oGame = $iGames->getItem( $key ); Результат: Объект – онлайновая флеш-игра, аналог исходной PC-игре. |
В разделе онлайн-игр получение простой игры - аналога онлайн-игры |
$pcGames = $game->getRelatedItems('casualpcgames'); $keys = array_keys( $pcGames ); $key = $keys[0]; $casualpcModel = $showroom->CreateModel('ru', 'casualpcgames'); $iGames = $casualpcModel->getAllGames(); $pcGame = $iGames->getItem( $key ); Результат: Объект – PC-игра, аналог исходной онлайновой флеш-игры. |
Создание рекламных блоков с играми
Чтобы сделать рекламный блок, нужно получить соответствующий набор игр «хитовые», «новые» или игры определенного жанра, см. таблицу с операциями для разработки нового шаблона. После чего вывести в блок название, иконки игр, ссылки на страницы с подробной информацией о них; возможно, описание игр.
Развертывание готовой XML-витрины на сервере партнера
Для развертывания витрины необходимо иметь скрипт витрины и сервер, удовлетворяющий требованиям (Подробнее в Приложении 3).
Необходимые действия:
- Файлы витрины выкладываются на сервер в нужную папку.
- Права доступа на папки var и все содержащиеся в ней подпапки должны быть выставлены в 775 или в 777 в зависимости от настроек сервера (желательно 777).
- Нужно проверить значения параметров «PARTNER_ID», «SA_CODEPAGE», «SA_USE_LOCAL_IMG_STORAGE» и «SA_USE_LOCAL_DISTRIB_STORAGE», содержащихся в конфигурационном файле “config.inc.php”, он находится в корневой папке витрины. Описание данного файла смотрите ниже.
- Нужно зайти в административную зону витрины (Пример: http://alawar-vitrina-example/admin/index.php). Для этого нужно ввести логин и пароль (по умолчанию login:vitr; password:pass), эти значения задаются в конфигурационном файле, мы настоятельно рекомендуем сменить стандартный логин и пароль на более сложные значения, чтобы обезопасить работу административной зоны витрины. В административной зоне витрины необходимо произвести первоначальную загрузку данных об играх (на вкладке “Cache” нужно нажать кнопку “Reload Now”).
- Витрина готова к эксплуатации.
Опциональные действия:
- Чтобы сменить кодировку витрины, необходимо:
- В файле “config.inc.php” изменить значение константы “SA_CODEPAGE” на название необходимой кодировки; значение по умолчанию – “windows-1251”.
- Необходимо перекодировать в соответствующую кодировку файлы шаблонов, они находятся в папках “var/ru/_templates/*/”; * - любая папка в этом каталоге.
- Код витрины задокументирован, поэтому смена кодировки затронет эти комментарии, в связи с этим необходимо аналогично пункту (b) перекодировать все файлы витрины в соответствующую кодировку.
- Чтобы загрузить локальную графику или дистрибутивы на сервер, нужно, чтобы соответствующие параметры “SA_USE_LOCAL_IMG_STORAGE” и “SA_USE_LOCAL_DISTRIB_STORAGE” конфигурационного файла имели значение “true”. После этого нужно зайти на администраторскую страницу витрины, перейти на вкладки “Images” и “Distrib Storage” соответственно, затем нажать на кнопку “Reload Now”.
Кроме этого, обновлять графику, дистрибутивы и данные об игрых соответственно можно также используя кронтаб. Для этого в его конфигурации нужно прописать следующие строки:
25 2,9 * * * .../alawar-vitrina-example/admin/reload-images.php
35 4,8 * * * .../alawar-vitrina-example/admin/reload-distribs.php
45 5,7 * * * .../alawar-vitrina-example/admin/reload-xml.php
Также сервер витрины должен удовлетворять определенным требованиям, если производится кеширование дистрибутивов и графики.
Приложение 1.
Описание форматов данных
Описание формата данных игр.
Тег в xml дан относительно ALAWAR_EXPORT/Languages/Language/Catalogs/Catalog@”casualpcgames”/Items/Item
Таблица 2. Форматы данных
Название элемента описания игры |
Тег в xml |
Метод выборки из объекта игры |
Имя |
Name |
$game->name |
Символьный код |
Properties/Property@SymbolCode |
$game->getProperty('SymbolCode') |
Дата выхода игры |
Properties/Property@ReleaseDate |
$game->getProperty(' ReleaseDate') |
Описание игры длиной 45 символов |
Properties/Property@Description45 |
$game->getProperty(' Description45') |
Описание игры длиной 80 символов |
Properties/Property@Description80 |
$game->getProperty(' Description80') |
Описание игры длиной 450 символов |
Properties/Property@Description450 |
$game->getProperty(' Description450') |
Описание игры длиной 2000 символов |
Properties/Property@Description2000 |
$game->getProperty(' Description2000') |
Ссылка на покупку игры |
Properties/Property@OrderUrl |
$game->getProperty(' OrderUrl') |
Images (иконки для игр) | ||
Иконка размера 44x44 на белом фоне (icon44x44) |
Images/Image@icon44x44 |
$game->getImage('icon44x44') |
Иконка размером 44x44 с фоном игры (icon44x44bg) |
Images/Image@icon44x44bg |
$game->getImage('icon44x44bg') |
Иконка размером 100x100 на белом фоне (icon100x100) |
Images/Image@icon100x100 |
$game->getImage('icon100x100') |
Иконка размером 100x100 с фоном игры (icon100x100bg) |
Images/Image@icon100x100bg |
$game->getImage('icon100x100bg') |
Логотип игры размером 190x140 игры (logo190x140) |
Images/Image@logo190x140 |
$game->getImage('logo190x140') |
Рисунок размером 586x152 (banner586x152) |
Images/Image@banner586x152 |
$game->getImage('banner586x152') |
Screenshot (Скриншоты) | ||
URL иконки скриншота (small) |
|
$Screenshots[$i]['small']['Url'] |
Ширина иконки скриншота (small) |
|
$Screenshots[$i]['small']['Width'] |
Высота иконки скриншота (small) |
|
$Screenshots[$i]['small']['Height'] |
URL скриншота (big) |
|
$Screenshots[$i]['big']['Url'] |
Ширина скриншота (big) |
|
$Screenshots[$i]['big']['Width'] |
Высота скриншота (big) |
|
$Screenshots[$i]['big']['Height'] |
Files (Дистрибутив игры) | ||
Ссылка на скачиваемый дистрибутив (distrib) |
Files/File@distrib |
$game->getDownloadFileUrl() |
RelatedItem (Элементы связанные с данным) | ||
Массив объектов игр, связанных с данным |
RelatedItems/RelatedItemCatalog@onlinegames/RelatedItem |
$game->getRelatedItems('onlinegames') |
Onlinegames (онлайновые флеш-игры) Тег в xml дан относительно ALAWAR_EXPORT/Languages/Language/Catalogs/Catalog@”onlinegames”/Items/Item
| ||
URL онлайн-игры |
Properties/Property@PageUrl |
$oGame->getProperty('PageUrl ') |
Рекомендуемая ширина окна с онлайн-игрой |
Properties/Property@Width |
$oGame->getProperty(' Width') |
Рекомендуемая высота окна с онлайн-игрой |
Properties/Property@Height |
$oGame->getProperty('Height ') |
Ширина swf-файла с игрой |
Properties/Property@swfWidth |
$oGgame->getProperty('SwfWidth ') |
Высота swf-файла с игрой |
Properties/Property@swfHeight |
$oGame->getProperty(' SwfHeight') |
HTML-код тега embed для вставки игры на страницу |
Properties/Property@Embed |
$oGame->getProperty('Embed ') |
Описание формата данных жанров
Данные жанров игр имеют следующий формат:
array(
'name' => 'имя-жанра',
'code' => 'код-жанра',
'action' => 'genre', // служебная информация для формирования URI к странице жанра
);
Приложение 2. Дополнительная информация по эксплуатации витрины
Описание основных значений конфигурации витрины
Таблица 3. Описание основных значений конфигурации витрины.
Константа SA_CODEPAGE |
Кодировка витрины (Пример: “windows-1251”, “urf-8”, “koi8-r”); Рекомендуемое значение – windows1251. |
Константа SA_CACHE_LIFETIME |
Задает время жизни данных об играх, значение указывается в секундах; по умолчанию – 86400 .Данная константа задает период обновления данных об играх с сервера Alawar Entertainment, Inc. |
Константа SA_USE_LOCAL_IMG_STORAGE |
Если на витрине используется локальная графика для игр, то значение параметра должно быть “true”; значение по умолчанию – “false”. |
Константа SA_USE_LOCAL_DISTRIB_STORAGE |
Если на витрине используются локальные дистрибутивы игр, то значение параметра должно быть “true”; значение по умолчанию – “false”. |
Константа SA_HTML_CACHE_LIFETIME |
Время жизни кеша страниц витрины, значение указывается в секундах; по умолчанию – 86400 секунд. Данная константа задает период обновления html-кода страниц витрины на сервере партнера. |
Константа SA_DEFAULT_LANGUAGE |
Должна соответствовать рынку: Русский рынок: (ru). |
Константа SA_DEFAULT_CATALOG |
Коды основного каталога игр витрины могут быть следующими: Простые казуальные игры - (casualpcgames). Онлайновые флеш-игры - (onlinegames). Данная константа задает раздел витрины по умолчанию.
|
Константа SA_ADMIN_LOGIN |
Задается логин для входа в административную зону витрины |
Константа SA_ADMIN_PASSWORD |
Задается пароль для входа в административную зону витрины |
Параметры кеширования данных на витрине
При эксплуатации витрины необходимо помнить следующие моменты:
- Витрина в соответствии с конфигурационным файлом (константа SA_CACHE_LIFETIME) обновляет данные по играм с сервера Alawar. Рекомендуемый интервал обновления 86400секунд.
- Витрина в процессе работы создает html-кеш страниц витрины для повышения производительности работы (константа SA_HTML_CACHE_LIFETIME конфигурационного файла). Это позволяет ускорить загрузку страниц витрины.
- Очистку кеша витрины (отображения актуального контента) необходимо проводить следующим образом:
Вариант 1 (более осторожный и долгий):
Выставить в файле config.inc.php значение константы «SA_HTML_CACHE_LIFETIME» в 0. После этого перегрузить необходимые страницы витрины.
Вариант 2 (Радикальный):
Необходимо удалить все файлы из папки «…/alawar-vitrina-example/var/cache/pages/».
Приложение 3. Системные требования
Базовая витрина - это веб-приложение, написанное на PHP, которое устанавливается на сервер. Непосредственная работа с ним производится через веб-браузер - Internet Explorer, Mozilla или др. Для успешной работы нужно, чтобы и сервер, и клиент удовлетворяли определенным требованиям.
Требования для сервера:
- Операционная система: Unix (Linux), Windows
- Веб-сервер: Apache
- Версия PHP может быть и как модуль Apache и в режиме CGI.
PHP: PHP4 >= 4.3.0 or PHP5.
- Опция Safe mode должна быть выставлена в "Off".
Рекомендуется (не обязательно) для веб-сервера также установить:
- Apache с модулями mod_rewrite (для формирования SEF-путей); gd module (для корректной работы captcha).
Требования для клиента:
- Рекомендуемые: браузер Mozilla Firefox для любой операционной системы, Internet Explorer 7+ для Windows
- Required: любой графический браузер для любой ОС (Netscape, IE, Opera, Konqueror для Windows, Unix, Mac)
- Hardware: достаточно современный компьютер
Замечание по поводу использования памяти:
Сейчас в Базовой витрине есть части, которые требуют больше 128 Мб памяти, сконфигурированные в php.ini по умолчанию. Во многих случаях это не является проблемой, так как ограничение используется далеко не всегда.