Скрипт базовой витрины — различия между версиями

Материал из Alawar
Перейти к: навигация, поиск
м (Защищена страница «Скрипт базовой витрины» ([edit=sysop] (бессрочно) [move=sysop] (бессрочно)))
 
Строка 182: Строка 182:
  
 
<br>
 
<br>
 +
 +
  
 
Пример объекта:  
 
Пример объекта:  

Текущая версия на 13:15, 3 апреля 2019

Работа с экземпляром партнерских витрин

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

Содержание

  1. Определения, используемые в данном документе
  2. Введение: что это такое, для чего нужно, как это работает, примеры готовых витрин, FAQ
  3. Интеграция шаблона витрины
  4. Развертывание готовой XML-витрины на сервере партнера
  5. Приложение 1. Описание форматов данных
    1. Описание формата данных игр
    2. Описание формата данных жанров
  6. Приложение 2. Дополнительная информация по эксплуатации витрины
    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/


Интеграция шаблона витрины

Интеграция шаблона витрины – это добавление набора файлов шаблона витрины для изменения ее внешнего вида.

Вы можете воспользоваться одним из двух предложенных вариантов интеграции шаблона – использовать готовый шаблон из Партнерской зоны или создать собственный шаблон.

Начало работы

Перед началом работы витрины необходимо сделать следующее:

  1. Следует переименовать файл “config.inc.php.templates” на “config.inc.php” в корне витрины.
  2. Указать свой PID (идентификатор партнера), для этого нужно изменить файл config.inc.php в корне витрины:
    define( 'PARTNER_ID', XXXX );
    где XXXX - идентификатор партнера в Партнерской программе.
  3. Выставить кодировку, в которой будет отображаться витрина:
    define('SA_CODEPAGE', XXXX);
    где XXXX – любое из значений 'windows-1251' или ' utf-8'.
    Файлы шаблона витрин должны быть в выбранной кодировке.


Использование готового шаблона

Для внедрения на сайт готового шаблона вам необходимо сделать следующее:

  1. Распаковать архив в папку «…/alawar-vitrina-example/var/ru/_templates/».
  2. Скопировать архив шаблона из Партнерской зоны (ссылка).
  3. Включить использование выбранного шаблона в административной зоне витрины. На главной странице административной зоны в выпадающем списке «Название шаблона» нужно выбрать необходимый шаблон и сохранить изменения, нажав кнопку «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 – может содержать рекламные блоки с «хитовыми», «новыми» и другими играми.
  • - минимальный набор шаблонов, присутствие которых необходимо для работы витрины.

По шагам:

  1. Берем архив ядра базовой витрины и распаковываем в отдельную папку.
  2. Из архива с эскизом витрины копируем файлы картинок и стилей в папку шаблона (Пример: …/alawar-vitrina-example/var/ru/_templates/default_tpl/).
  3. Установки в основном файле конфигурации. В корне дистрибутива витрины открываем файл config.inc.php.templates:


Меняем значение константы "PARTNER_ID" на значение идентификатора партнера этой витрины. Здесь также можно изменить и другие параметры витрины.

При разработке нового шаблона витрины рекомендуется отключать кеширование страниц витрины. Для этого выставляем значение свойства «SA_HTML_CACHE_LIFETIME» в 0.

  1. Создаем папки и пустые php-файлы шаблонов. В эти файлы копируем фрагменты html-кода, предоставленного в эскизе витрины. Разбиение html-кода можно делать, следуя рекомендациям, указанным в описании структуры файлов шаблона витрины.
  2. Далее необходимо заменить названия игр, ссылки на страницу с игрой, ссылки на скачиваемый дистрибутив, пути и размеры графических материалов и др. на соответствующие переменные, константы и методы, с помощью которых можно отобразить необходимые данные. Подробнее о переменных и методах можно узнать в таблице основных операций и таблице формата данных.
  3. При создании нового шаблона следует обратить внимание на следующие моменты:
  • Пункты меню жанров могут быть активными и неактивными, в зависимости от параметров «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).

Необходимые действия:

  1. Файлы витрины выкладываются на сервер в нужную папку.
  2. Права доступа на папки var и все содержащиеся в ней подпапки должны быть выставлены в 775 или в 777 в зависимости от настроек сервера (желательно 777).
  3. Нужно проверить значения параметров «PARTNER_ID», «SA_CODEPAGE», «SA_USE_LOCAL_IMG_STORAGE» и «SA_USE_LOCAL_DISTRIB_STORAGE», содержащихся в конфигурационном файле “config.inc.php”, он находится в корневой папке витрины. Описание данного файла смотрите ниже.
  4. Нужно зайти в административную зону витрины (Пример: http://alawar-vitrina-example/admin/index.php). Для этого нужно ввести логин и пароль (по умолчанию login:vitr; password:pass), эти значения задаются в конфигурационном файле, мы настоятельно рекомендуем сменить стандартный логин и пароль на более сложные значения, чтобы обезопасить работу административной зоны витрины. В административной зоне витрины необходимо произвести первоначальную загрузку данных об играх (на вкладке “Cache” нужно нажать кнопку “Reload Now”).
  5. Витрина готова к эксплуатации.


Опциональные действия:

  1. Чтобы сменить кодировку витрины, необходимо:
  2. В файле “config.inc.php” изменить значение константы “SA_CODEPAGE” на название необходимой кодировки; значение по умолчанию – “windows-1251”.
  3. Необходимо перекодировать в соответствующую кодировку файлы шаблонов, они находятся в папках “var/ru/_templates/*/”; * - любая папка в этом каталоге.
  4. Код витрины задокументирован, поэтому смена кодировки затронет эти комментарии, в связи с этим необходимо аналогично пункту (b) перекодировать все файлы витрины в соответствующую кодировку.
  5. Чтобы загрузить локальную графику или дистрибутивы на сервер, нужно, чтобы соответствующие параметры “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

Задается пароль для входа в административную зону витрины


Параметры кеширования данных на витрине

При эксплуатации витрины необходимо помнить следующие моменты:

  1. Витрина в соответствии с конфигурационным файлом (константа SA_CACHE_LIFETIME) обновляет данные по играм с сервера Alawar. Рекомендуемый интервал обновления 86400секунд.
  2. Витрина в процессе работы создает html-кеш страниц витрины для повышения производительности работы (константа SA_HTML_CACHE_LIFETIME конфигурационного файла). Это позволяет ускорить загрузку страниц витрины.
  3. Очистку кеша витрины (отображения актуального контента) необходимо проводить следующим образом:


Вариант 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 по умолчанию. Во многих случаях это не является проблемой, так как ограничение используется далеко не всегда.


Источник — «http://wiki.partner.alawar.ru/index.php?title=Скрипт_базовой_витрины&oldid=34383»