Модуль для SimplaCMS

1. Введение

Этот документ описывает процесс установки модуля REES46 на ваш магазин на платформе SimplaCMS.

2. Краткий план установки

1. Зарегистрировать магазин в системе REES46.
2. Подключить основные скрипты модуля.
3. Установить скрипты сбора данных.
4. Настроить блоки рекомендаций.
5. Проверить работоспособность.

3. Видео-инструкция по установке и настройке модуля

IN PROGRESS

4. Пошаговая инструкция по установке

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

4.1. Регистрация магазина

1. Перейдите на сайт http://rees46.com.
2. Зарегистрируйтесь и создайте новый магазин
3. Запишите код магазина и секретный ключ (длинная бесмысленная последовательность букв и цифр, которую вы получите после создания магазина на сайте REES46). И то и другое можно получить в разделе "Настройка магазина".

4.2. Подключите основные скрипты модуля

4.2.1. Скачайте архив со скриптами

1. Скачайте по ссылке https://bitbucket.org/mkechinov/rees46_simplacms_sdk/get/1.0.6.zip архив с модулем.
2. Распакуйте его.
3. Каталог REES46, который содержится в архиве, перенесите в корневую директорию вашего сайта.
4. Файл REES46/rees46_recommended.tpl перенесите в каталог, где лежат файлы вашего текущего шаблона.

4.2.2. Установите код магазина

Откройте файл REES46/init.php и в коде

DEFINE('REES46_SHOP_ID', 'УКАЖИТЕ_ID_МАГАЗИНА');

замените строку "УКАЖИТЕ_ID_МАГАЗИНА" на код магазина, полученный в пункте 4.1.

4.2.3. Измените файл index.php

Откройте в редакторе файл ./index.php, лежайщий в корневой директории и добавьте в него код

// @rees46
if(file_exists('REES46/index.inc.php')) {
    require_once('REES46/index.inc.php');
}

сразу после строки:

$view = new IndexView();

Аккуратно выполняйте эту операцию, потому что любая опечатка может привести к ошибке на вашем сайте.

4.2.4. JS-код REES46

Перейдите в редактирование текущего шаблона, откройте файл index.tpl и перед закрывающим тегом </body> установите код:

{* @rees46 *}
<script src="//cdn.rees46.com/rees46_script2.js"></script>
<script type="text/javascript">
    $(function () {
        REES46.init('{$rees46_shop_id}', {if $user}{literal}{{/literal}id: {$user->id}, email: "{$user->email}"{literal}}{/literal}{else}null{/if});
        REES46.addReadyListener(function() {
            REES46.addStyleToPage();
            $('.rees46.rees46-recommend').each(function(){
                var block = $(this);
                var block_type = $(this).data('type');
                var current_category_id = $(this).data('category');
                var current_item_id = $(this).data('item');
                var current_cart = [{$rees46_cart_elements}];
                {literal}
                var request_data = {
                    recommender_type: block_type,
                    limit: 5
                };
                if(typeof(current_category_id) != 'undefined') {
                    request_data.category = current_category_id;
                }
                if(typeof(current_item_id) != 'undefined') {
                    request_data.item = current_item_id;
                }
                if(typeof(current_cart) != 'undefined') {
                    request_data.cart = current_cart;
                }
                REES46.recommend(request_data, function (recommended_ids) {
                    REES46.renderSimplaRecommendations(recommended_ids, block);
                });
                {/literal}
            });

            // Track cart events
            $('form.variants').live('submit', function(e) {
                if($(this).find('input[name=variant]:checked').size()>0)
                    var variant = $(this).find('input[name=variant]:checked').val();
                if($(this).find('select[name=variant]').size()>0)
                    var variant = $(this).find('select').val();
                var recommended_by = $(this).find('input[name=recommended_by]').val();
                $.getJSON( "/REES46/get_item_info.php?variant_id=" + variant, function( data ) {
                    REES46.pushData('cart', data, null, recommended_by);
                });
            });
        });

        REES46.renderSimplaRecommendations = function(recommended_ids, block) {
            if(recommended_ids && Object.prototype.toString.call(recommended_ids) === '[object Array]' && recommended_ids.length > 0) {
                var block_limit = block.data('limit') || 4;
                var block_title = block.data('title');
                var block_type = block.data('type');
                $.get(
                        '/REES46/render.php',
                        {
                            ids: recommended_ids,
                            limit: block_limit,
                            title: block_title,
                            type: block_type
                        },
                        function(rendered_block){
                            if(rendered_block.length > 0) {
                                block.html(rendered_block);
                            }
                        }
                );
            }
        }
    });
</script>

4.3. Подключите скрипты сбора данных

Для полноценных рекомендаций необходимо собирать следующие события:

• просмотр товара пользователем;
• добавление товара в корзину;
• удаление товара из корзины;
• оформление заказа.

4.3.1. Просмотр товара

Откройте шаблон просмотра товара product.tpl и вставьте в конец файла этот код:

{* @rees46 *}
<script type="text/javascript">
    $(function () {
        REES46.addReadyListener(function(){
            {if $product->variant->stock}
                REES46.pushData('view', {
                    "item_id": {$product->id},
                    "price":{$product->variant->price},
                    "is_available":true,
                    "category":{$category->id},
                    {if $product->name}"name": "{$product->name|escape}",{/if}
                    {if $product->image}"image_url": "{$product->image->filename|resize:800:600:w}",{/if}
                    "url": "{$config->root_url}/products/{$product->url}"
                });
            {else}
                REES46.pushData('view', {
                    "item_id": {$product->id},
                    "price":null,
                    "is_available":false,
                    "categories": {product_categories product=$product},
                    {if $product->name}"name": "{$product->name|escape}",{/if}
                    {if $product->image}"image_url": "{$product->image->filename|resize:800:600:w}",{/if}
                    "url": "{$config->root_url}/products/{$product->url}"
                });
            {/if}
        });
    });
</script>

4.3.2. Добавление товара в корзину

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

4.3.3. Удаление товара из корзины

Скопируйте этот код:

 // Отправляем событие в REES46
 // @rees46
include('REES46/track_remove_from_cart.php');

Вставить его нужно в файл ./view/CartView.php, перед строкой

$this->cart->delete_item($delete_variant_id);

Эта строка находится примерно под номером 37.

4.3.4. Оформление заказа

Скопируйте код 

// Отправляем событие в REES46
// @rees46
include('REES46/track_purchase.php');

Вставить его нужно в файл ./view/CartView.php, перед строкой:

// Перенаправляем на страницу заказа
header('Location: '.$this->config->root_url.'/order/'.$order->url);

4.4. Подключите блоки рекомендованных товаров

4.4.1. Куда какие блоки ставить

Важно установить максимальное количество блоков из предложенных. Может возникнуть соблазн поставить только 1-2 блока, потому что "не хочется портить дизайн". В этом случае помните: 1-2 блока не могут работать эффективно. Для достижения максимального эффекта блоки должны быть расположены по рекомендованной схеме:

• Главная страница:
  • популярные товары (без категории).
• Страница категории:
  • популярные товары (сверху);
  • вы недавно смотрели (снизу);
  • возможно, вам это понравится (снизу).
• Детальный просмотр товара (все снизу):
  • с этим товаром покупают;
  • похожие товары;
  • возможно, вам это понравится.
• Страница корзины:
  • не забудьте посмотреть.

4.4.2. Коды установки блоков

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

<div class="rees46 rees46-recommend" data-type="recently_viewed"></div>

REES46 автоматически сканирует содержимое страницы на наличие этих тегов и вместо них выводит рекомендованные товары (если есть что рекомендовать).

Вы можете (и в некоторых случаях должны) добавлять дополнительные атрибуты к тегу рекомендованных товаров в зависимости от целей:

4.4.2.1. Блок "Популярные товары"

Показывает популярные товары в просматриваемой категории или на главной странице.

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

<div class="rees46 rees46-recommend" data-type="popular" data-limit="3"></div>

На странице категории (products.tpl) используйте этот код (рекомендуется указывать его вверху страницы):

 <div class="rees46 rees46-recommend" data-type="popular" data-title="Популярные товары в этой категории" data-limit="3" data-category="{$category->id}"></div>

4.4.2.2. Блок "Не забудьте посмотреть"

Анализирует содержимое корзины покупателя и дает персонализированные предложения сопутствующих товаров.

Как правило размещается на странице просмотра корзины. Не включает в себя те товары, которые уже добавлены в корзину.

{* @rees46 *}
<div class="rees46 rees46-recommend" data-type="see_also" data-limit="3"></div>

Разместите его в файле cart.tpl вашего шаблона над строкой:

{if $deliveries}

4.4.2.3. Блок "Вы недавно смотрели"

Показывает товары, которые пользователь недавно просматривал, но которые еще не добавлены в корзину.

Желательно отображать на всех страницах сайта. Минимум в просмотре списка товаров категории и на главной странице сайта.

<div class="rees46 rees46-recommend" data-type="recently_viewed" data-limit="3"></div>

4.4.2.4. Блок "С этим товаром также покупают"

Показывает сопутствующие товары к тому, который покупатель просматривает прямо сейчас. Похож на see_also, но относится только к одному товару.

Рекомендуется отображать на странице просмотра товара.

Требует указания текущего просматриваемого товара, поэтому указанный пример работает только в шаблоне product.tpl.

{if $product->variant}
    <div class="rees46 rees46-recommend" data-type="also_bought" data-limit="3" data-item="{$product->id}"></div>
{/if}

4.4.2.5. Блок "Похожие товары"

Выводит товары, которые похожи на просматриваемый. Выводить нужно на странице просмотра товара.

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

Рекомендуется отображать на странице просмотра товара.

Требует указания текущего просматриваемого товара, поэтому указанный пример работает только в шаблоне product.tpl.

{if $product->variant}
    <div class="rees46 rees46-recommend" data-type="similar" data-limit="3" data-item="{$product->id}"></div>
{/if}

4.4.2.6. Блок "Возможно, вас это заинтересует"

Выводит товары, которые просто будут интересны покупателю. Имеет смысл выводить на главной странице и на странице просмотра товара.

Не требует параметров.

<div class="rees46 rees46-recommend" data-type="interesting" data-limit="3"></div>

На странице просматриваемого товара имеет смысл исключить рекомендацию его же, поэтому данный блок рекомендаций в шаблоне product.tpl должен выглядеть так:

<div class="rees46 rees46-recommend" data-type="interesting" data-limit="3" data-item="{$product->id}"></div>

5. Проверка работоспособности

Проверка выполняется так:

1. Включаете консоль разработчика в вашем браузере.
2. Находите вкладку Network (или "Сеть"), в которой при обновлении страницы отображаются происходящие запросы.
3. Включаете режим фильтрации только XHR-запросов.
4. Проверяете, есть ли запросы, которые уходят на api.rees46.com.

5.1. Проверка отправки событий

1. Перейдите на страницу просмотра товара.
2. Убедитесь, что уходит запрос на адрес api.rees46.com/push

5.2. Проверка запроса рекомендаций

1. Перейдите на главную страницу и убедитесь, что уходит один запрос на api.rees46.com/recommend.
2. Перейдите на страницу категории и убедитесь, что уходят три запроса на api.rees46.com/recommend.
3. Перейдите на страницу товара и убедитесь, что уходят три запроса на api.rees46.com/recommend.
4. Перейдите на страницу корзины и убедитесь, что уходит один запрос на api.rees46.com/recommend.

6. Управление внешним видом рекомендаций

Все рекомендации выполнены в основном дизайне и структуре шаблонов SimplaCMS.

Шаблон рекомендованных товаров лежит в файле ./design/имя_вашего_шаблона/html/rees46_recommended.tpl. Вы можете менять внешний вид шаблона так, как вам захочется. Но всегда проверяйте работоспособность оформленного блока рекомендованных товаров: кнопка "Добавить в корзину" должна работать. Если перестала работать, значит ваши изменения что-то сломали. Стоит вернуть их обратно и проверить, что могло сломать работу добавления товаров в корзину.

7. Если рекомендации еще не появились

Рекомендации могут появиться не сразу – все зависит от посещаемости вашего сайта. Если на вашем сайте оформляются заказы, значит статистика собирается и скоро рекомендации начнут появляться. Но обязательно проверьте правильность установки по пунктам 5.1 и 5.2.

8. Участие в разработке модуля

REES46 является бесплатной профессиональной рекомендательной системой, цель которой – дать возможность персонализированного подхода к клиенту любому интернет-магазину. Если вы специалист в разработке модулей под SimplaCMS и желаете улучшить модуль, отправляйте pull request в репозиторий https://bitbucket.org/mkechinov/rees46_simplacms_sdk