README.txt in Yandex.Metrics 6.2

------------------------------------------------------------------------------
                            YANDEX.METRICS PROJECT
------------------------------------------------------------------------------
Note: See Russian documentation below.

The Yandex.Metrica [1] service is European alternative of Google Analytics.

The Yandex.Metrics project helps to integrate a website with the Yandex.Metrica [1].

Since versions 6.x-2.x and 7.x-2.x project consists of two modules.

* Yandex.Metrics Counter module
    Features:
        * Installing Yandex.Metrica counter code on site
        * Configuring visibility of the counter
    Dependencies
        * NO DEPENDENCIES! Just enable and use.

* Yandex.Metrics Reports module
    Note:
        The Yandex.Metrics API [2] is used for communication with Yandex.Metrica service.
    Features:
        * Authorizing of your site on Yandex services (through oAuth 2.0)
        * Reports and charts:
            * Page Views, Visitors, New Visitors
            * Traffic Sources
            * Popular Search Phrases
            * Popular Content
            * Geography of Visits
        * Block with popular content links (updating through Cron)
    Dependencies
        * Yandex.Metrics Counter module
        * Google chart API [3]
        * [Optional] For support of internationalized domain names
          download idna_convert class [4] of Matthias Sommerfeld and copy it
          into the 'sites/all/libraries/idna_convert/' or 'sites/name_of_your_site/libraries/idna_convert/'
          folder of your Drupal setup.

Interface translations
* Russian (Русский)



INSTALLING
------------------------------------------------------------------------------
1. Backup your database.

2. Make sure you resolved dependencies of modules. If you are going to use Yandex.Metrics Reports module
   please install Google chart API [3] module first.

3. If you use internationalized domain name you should download PHP file idna_convert.class.php
   of Matthias Sommerfeld from [4] and copy it into the 'sites/all/libraries/idna_convert/' or
   'sites/name_of_your_site/libraries/idna_convert/' folder of your Drupal setup.

4. Copy the complete 'yandex_metrics/' directory into the 'sites/all/modules/',
   'sites/default/modules' or 'sites/name_of_your_site/modules' folder of 
   your Drupal setup. 
   More information about installing contributed modules could be found at 
   "Install contributed modules" (http://drupal.org/node/70151)

5. Enable necessary modules in "Yandex.Metrics" section of module administration page
   (Administer >> Site building >> Modules).

6. Configure modules (see "CONFIGURATION" below).



UPDATING
------------------------------------------------------------------------------
1. Verify that the version you are going to upgrade contains all the features
   you are using in your Drupal setup. Some features could have been removed
   or replaced by others.

2. Read carefully in the project issue tracking about upgrade paths problems
   before you start the upgrade process. 

3. Backup your database.

4. Update current module code with latest recommended version. Previous versions 
	could have bugs already reported and fixed in the last version.

5. Complete the update process, set maintenance mode, call the update.php script 
	and finish the update operation. 
	For more information please go to: http://groups.drupal.org/node/19513

6. Verify your module configuration and check that the features you are using
   work as expected. Also verify that all required modules are enabled, and
   permissions are set as desired.

Note: whenever you have the chance, try an update in a local or development
      copy of your site.


CONFIGURATION
------------------------------------------------------------------------------
* Yandex.Metrics Counter module
    1. On the access control administration page ("Administer >> User management >> Access control")
       you need to assign:

        *	"administer Yandex.Metrics settings" permission to the roles that are allowed
            to administer the Yandex.Metrics settings.

    2. Create Yandex.Metrica [1] account.

       Please skip this step if you have already had it.

    3. Create Yandex.Metrica counter for your site at Yandex.Metrica admin interface.
       And generate counter Javascript code there.
       Note: We recommend to create simple counter without any widget
             but counter code with widget is acceptable.

       Save this Javascript code for later usage.

       Please skip this step if you have already created a counter.

    4. Go to the module settings page ("Administer >> Site configuration >> Yandex.Metrics")
       Users need the "administer Yandex.Metrics settings" permission to access to this page.

       Paste Javascript code of counter from Yandex.Metrics to the Counter Code text field
       on the module settings page ("Administer >> Site configuration >> Yandex.Metrics").
       You can also define counter code visibility settings.
       Then submit form.
       By this step you add counter code to the footer of permitted pages of your site.

       Please skip this step if you have already added Yandex.Metrics counter code on your site pages
       through another way.

       Please skip next steps if you need nothing except installation of counter code.


* Yandex.Metrics Reports module
    1. On the access control administration page ("Administer >> User management >> Access control")
       you need to assign:

        *   "access Yandex.Metrics report" permission to the roles that are allowed
            to view Yandex.Metrics Summary Report

    2. Register your Yandex application. Use Yandex step-by-step guide [5]
       to perform this step.

       Enter Callback URI for your Yandex application.
       Callback URI: http://YOUR_SITE_HOST_NAME/yandex_metrics/oauth

       Save your application Client ID and Client Secret for later usage.

    3. Application authorization.
       Go to Authorization tab and paste application Client ID and Client Secret into the corresponding fields.
       Then press Authorise Application button to submit form.

       You will be redirected to the special Yandex page.
       You should confirm your application authorization on that page.
       Enter your Yandex login and password if it will be necessary.

       Then your will be redirected back to the settings page of the Yandex.Metrics module on your site
       and get success message.

    4. Reports settings
       Go to Reports tab.
       Here you can to turn on AJAX for reports.
       It can reduce loading time of Summary Report page.

       Also you can enable/disable displaying of reports.

    5. Check Yandex.Metrics Summary Report content
       ("Administer >> Reports >> Yandex.Metrics Summary Report").
       To access this page users need the "access Yandex.Metrics report" permission.
       Note:
         Your report can be empty if you have just created Yandex.Metrics counter
         and placed it to your site. Probably statistic information have not been collected yet.
         Please try again later.

    6. After module installing and configuration, there's gonna be accessible "Popular content" block.
       This block shows popular content pulled from Yandex as a list of links.

       The block has two configuration options: the Filter date period and the Count of links.
       These options are accessible at block configuration page("Administer >> Blocks >> Popular content").
       The Filter date period option configures the period of time that you want to filter popular
       content(Today, Yesterday, Week or Month).
       The Count of links option allows you to select how many links to show in the
       block(5, 10 or 15 links).

       Note:
         Block caches the popular content data, that's done to prevent excessive requests to Yandex.
         In order to clear the cache you should change the Filter date period and after that save the
         block. Also, it tries to pull and save popular content in cache when the block is showing
         for the first time.

       Attention:
         To maintain data in the block up-to-date, you should configure CRON [6].



BUGS AND SHORTCOMINGS
------------------------------------------------------------------------------
* See the list of project issues [7].


CREDITS
------------------------------------------------------------------------------
Maintainer: Konstantin Komelin [8]
List of committers: [9]


LINKS
------------------------------------------------------------------------------
[1] http://metrica.yandex.com/
[2] http://api.yandex.ru/metrika/
[3] http://drupal.org/project/chart
[4] http://www.phpclasses.org/browse/file/5845.html
[5] http://api.yandex.ru/oauth/doc/dg/tasks/register-client.xml
[6] http://drupal.org/cron
[7] http://drupal.org/project/issues/yandex_metrics
[8] http://drupal.org/user/1195752
[9] http://drupal.org/node/1180284/committers




------------------------------------------------------------------------------
                            ПРОЕКТ YANDEX.METRICS
------------------------------------------------------------------------------

Сервис Яндекс.Метрика [1] - это Европейская альтернатива Google Analytics.

Проект Yandex.Metrics помогает интегрировать вебсайт с Яндекс.Метрикой [1].

Начиная с версий 6.x-2.x и 7.x-2.x проект состоит из двух модулей.

* Модуль Yandex.Metrics Counter (Счетчик)
    Возможности:
        * Установка счетчика Яндекс.Метрики на сайт
        * Настройка видимости счетчика
    Зависимости:
        * НЕТ ЗАВИСИМОСТЕЙ! Включаем и используем.

* Модуль Yandex.Metrics Reports (Отчеты)
    Информация:
        Для взаимодействия с сервисом Яндекс.Метрика используется API Яндекс.Метрики [2].
    Возможности:
        * Авторизация сайта на сервисах Яндекса (используя oAuth 2.0)
        * Отчеты и графики:
            * Просмотры страниц, посетители, новые посетители
            * Источники переходов
            * Популярные поисковые фразы
            * Популярное содержимое
            * География посещений
        * Блок со ссылками на популярный контент (обновление по Cron)
    Зависимости:
        * Модуль Yandex.Metrics Counter
        * Google chart API [3]
        * [Необязательно] Для поддержки интернационализированных доменных имен
          скачайте класс idna_convert [4], разработанный Matthias Sommerfeld, и скопируйте его
          в 'sites/all/libraries/idna_convert/' или 'sites/name_of_your_site/libraries/idna_convert/'
          директорию установленного Drupal.

Переводы интерфейса
* Русский



УСТАНОВКА
------------------------------------------------------------------------------
1. Создайте резервную копию вашей базы данных.

2. Убедитесь, что зависимости модулей разрешены. Если вы собираетесь использовать модуль Yandex.Metrics Reports,
   пожалуйста, сначала установите модуль Google chart API [3].

3. Если вы используете интернационализированное доменное имя, вам следует скачать PHP файл
   idna_convert.class.php, созданный Matthias Sommerfeld, со страницы [4] и скопировать его
   в 'sites/all/libraries/idna_convert/' или 'sites/name_of_your_site/libraries/idna_convert/'
   директорию вашей Drupal установки.

4. Скопируйте директорию 'yandex_metrics/' целиком в 'sites/all/modules/' или
   'sites/default/modules' или 'sites/имя_вашего_сайта/modules' директорию
   вашей Drupal установки.
   Больше информации об установке модулей вы можете найти в 
   "Install contributed modules" (http://drupal.org/node/70151)

5. Включите необходимые модули в разделе "Yandex.Metrics" страницы администрирования модулей
   (Управление >> Конструкция сайта >> Модули).

6. Натройте модуль (смотрите раздел "НАСТРОЙКА" ниже).



ОБНОВЛЕНИЕ
------------------------------------------------------------------------------
1. Убедитесь в том, что версия, до которой вы хотите обновиться, содержит все
   возможности, которые вы используете в вашей Drupal установке. 
   Некоторые возможности могли быть удалены или заменены другими.

2. Внимательно изучите очередь задач проекта на наличие возможных проблем при
   обновлении до начала процесса обновления.

3. Создайте резервную копию вашей базы данных.

4. Обновите текущий код модуля на последнюю рекомендуемую версию. Предыдущая
   версия могла иметь ошибки уже известные и исправленные в последней версии.

5. Завершите процесс обновления. Для этого установите режим обслуживания на сайте,
   вызовите скрипт update.php и завершите операцию обновления.
   Для получения дополнительной информации, пожалуйста, следуйте в 
   http://groups.drupal.org/node/19513.

6. Проверьте настройки вашего модуля и то, что модуль работает корректно.
   Также убедитесь, что все требуемые модули включены и разрешения ролей назначены. 

Замечание: если вы имеете такую возможность, постарайтесь обновить модуль сначала
           на локальной или тестовой копии вашего сайта.


НАСТРОЙКА
------------------------------------------------------------------------------
* Модуль Yandex.Metrics Counter

    1. На странице управления разрешениями ролей ("Управление >> Управление пользователями
       >> Разрешения ролей") вам нужно назначить:

        *	"управлять Yandex.Metrics настройками" разрешение ролям, которым вы хотите позволить
            управлять настройками Yandex.Metrics модуля.

    2. Создайте учетную запись на Яндекс.Метрике [1].

       Пропустите этот шаг, если вы уже ее имеете.

    3. Создайте счетчик Яндекс.Метрики для вашего сайта в личном кабинете Яндекс.Метрики.
       Там же создайте Javascript код счетчика.
       Замечание: Мы рекомендуем создать простой счетчик без информера,
                  но счетчик с информером так же допускается.

       Сохраните сформированный Javascript код для того, чтобы использовать его далее.

       Пропустите этот шаг, если вы уже создали счетчик для вашего сайта.

    4. Перейдите на страницу настройки модуля ("Управление >> Настройка сайта >> Yandex.Metrics")
       Для доступа к этой странице пользователи нуждаются в разрешении "управлять Yandex.Metrics настройками".

       Вставьте Javascript код счетчика из Яндекс.Метрики в текстовое поле Код счетчика на странице
       настройки модуля ("Управление >> Настройка сайта >> Yandex.Metrics").
       Вы также можете произвести настройку отображения кода счетчика.
       Затем отправьте форму.
       Этим шагом вы добавите код счетчика в подвал разрешенных страниц вашего сайта.

       Пропустите этот шаг, если вы уже добавили код счетчика Яндекс.Метрики на страницы вашего сайта
       любым другим способом.

       Пропустите следующие шаги, если вас не интересует ничего, кроме установки счетчика.

    5. Зарегистрируйте Яндекс приложение. Используйте пошаговую инструкцию от Яндекс [5]
       для выполнения этого шага.

       Введите Callback URI для вашего Яндекс приложения.
       Callback URI: http://ИМЯ_ВАШЕГО_САЙТА/yandex_metrics/oauth

       Сохраните Id приложения и Пароль приложения для того, чтобы использовать его далее.

* Модуль Yandex.Metrics Reports

    1. На странице управления разрешениями ролей ("Управление >> Управление пользователями
       >> Разрешения ролей") вам нужно назначить:

        *   "доступ к Yandex.Metrics отчету" разрешение ролям, которым вы хотите разрешить
            просматривать Сводный отчет Yandex.Metrics

    2. Авторизация приложения.
       Перейдите на вкладку Авторизация и вставьте Id приложения и Пароль приложения в соответствующие поля.
       Затем нажмите кнопку Авторизовать приложение для того чтобы отправить форму.

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

       После этого вы будете перенаправлены обратно на страницу настройки модуля Yandex.Metrics
       на вашем сайте и увидите уведомление об успешной авторизации.

    3. Настройка отчетов
       Перейдите на вкладку Отчеты.
       Здесь вы можете включить AJAX для отчетов.
       Это может уменьшить время загрузки Сводного отчета Yandex.Metrics.

       Кроме того здесь можно включить или выключить отображение того или иного отчета.

    4. Проверьте содержимое Сводного отчета Yandex.Metrics
       ("Управление >> Отчеты >> Сводный отчет Yandex.Metrics").
       Для доступа к этой странице пользователи нуждаются в разрешении "доступ к Yandex.Metrics отчету".
       Замечание:
         Ваш отчет может быть пуст, если вы только что создали счетчик Яндекс.Метрики и разместили
         его на ваш сайт. Вероятно статистическая информация еще не была собрана.
         Пожалуйста, попробуйте позже.

    5. После установки и настройки модуля вам будет доступен блок "Популярное содержимое".
       Этот блок показывает список ссылок популярного контента предоставляемого Яндексом.

       Для настройки блока доступны две опции: Фильтр по дате и Количество ссылок для показа.
       Эти опции находятся на странице настройки блока("Управление >> Блоки >> Популярное содержимое").
       Опция "Фильтр по дате" позволяет выбрать промежуток времени по которому будет выбираться
       популярный контент(Сегодня, Вчера, Текущая неделя или Текущий месяц).
       Опция "Количество ссылок" предоставляет возможность указать количество ссылок, которое
       будет показываться в блоке(5, 10 или 15 ссылок).

       Замечание:
         Для того чтобы не посылать лишнее количество запросов к Яндексу, блок использует
         механизм кеширования результатов. Очистить кеш можно при изменении текущего значения опции
         "Фильтр по дате" и затем сохранив новые настройки блока. Кроме этого, блок попытается
         выполнить запрос популярного контента и сохранить результаты в кеш при первом показе блока.

       Внимание:
         Для поддержания данных в блоке в актуальном состоянии вам следует настроить CRON [6].



ОШИБКИ И НЕДОСТАТКИ
------------------------------------------------------------------------------
* Смотрите полный список задач проекта [7].


УЧАСТНИКИ
------------------------------------------------------------------------------
Разработчик: Константин Комелин [8]
Коммиттеры: [9]


ССЫЛКИ
------------------------------------------------------------------------------
[1] http://metrika.yandex.ru/
[2] http://api.yandex.ru/metrika/
[3] http://drupal.org/project/chart
[4] http://www.phpclasses.org/browse/file/5845.html
[5] http://api.yandex.ru/oauth/doc/dg/tasks/register-client.xml
[6] http://drupal.org/cron
[7] http://drupal.org/project/issues/yandex_metrics
[8] http://drupal.org/user/1195752
[9] http://drupal.org/node/1180284/committers