Синхронизация комментариев

Синхронизация комментариев позволяет сохранять комментарии Cackle в базу данных вашего локального сервера для хранения и индексации поисковыми системами. При синхронизации нужно получать список каналов, а затем для каждой страницы(канала) вашего сайта получать комментарии используя нижеприведенное API.

API получения списка каналов

HTTP метод	Endpoint	Ограничение	Комментарий
GET	http://cackle.me/api/3.0/comment/chan/list.json	1 раз в 5 секунд	Получить список каналов. Максимум 100 каналов за 1 запрос. Кодировка данных запроса UTF-8.

Параметры запроса:

Параметр	Обязательный	Описание	Комментарий
id	Да	Идентификатор вашего виджета	Можно получить в панели администрирования: меню "Установить", вкладка "CMS Платформа", выбрать WordPress.
siteApiKey	Да	Секретный ключ виджета	Можно получить в панели администрирования: меню "Установить", вкладка "CMS Платформа", выбрать WordPress.
accountApiKey	Да	Секретный ключ аккаунта	Можно получить в панели администрирования: меню "Установить", вкладка "CMS Платформа", выбрать WordPress.
gtModify	Нет	Дата в миллисекундах	Передавая данный параметр, API вернет все следующие каналы, время модификации которых больше modified. Если параметр не передавать, то будет получен весь список каналов.

API получения комментариев для канала

HTTP метод	Endpoint	Ограничение	Комментарий
GET	http://cackle.me/api/3.0/comment/list.json	1 раз в 5 секунд	Получить комментарии на определенной странице сайта. Максимум 100 комментариев за 1 запрос. Кодировка данных запроса UTF-8.

Параметры запроса:

Параметр	Обязательный	Описание	Комментарий
id	Да	Идентификатор вашего виджета	Можно получить в панели администрирования: меню "Установить", вкладка "CMS Платформа", выбрать WordPress.
siteApiKey	Да	Секретный ключ виджета	Можно получить в панели администрирования: меню "Установить", вкладка "CMS Платформа", выбрать WordPress.
accountApiKey	Да	Секретный ключ аккаунта	Можно получить в панели администрирования: меню "Установить", вкладка "CMS Платформа", выбрать WordPress.
chan	Да	Идентификатор страницы (channel)	Подробнее о канале.
commentId	Нет	Идентификатор комментария Cackle	Передавая данный параметр, API вернет все следующие комментарии, id которых больше commentId. Не может быть передан одновременно с modified параметром.
modified	Нет	Дата в миллисекундах	Передавая данный параметр, API вернет все следующие комментарии, время модификации которых больше modified. Не может быть передан одновременно с commentId параметром.

Как использовать это API

Для успешной настройки синхронизации через данное API мы рекомендуем выполнить два действия:

I. Сохранить все Cackle каналы
II. Сохранить все Cackle комментарии в локальную БД
III. Отлавливать добавления/изменения Cackle комментариев
IV. Библиотека синхронизации на php

I. Сохранить все Cackle каналы

Для сохранения всех комментариев, необходимо иметь список всех каналов на вашем сайте.

Алгоритм работы

1. Вызываем API для получения всех каналов без параметра gtModify:
http://cackle.me/api/3.0/comment/chan/list.json?id={siteId}&siteApiKey={siteApiKey}&accountApiKey={accountApiKey}
2. В JSON ответе API, приходит массив каналов:
{"chans":[ {"id":101, "channel": '101', modified: ...}, {"id":102, "channel": '102', modified: ...}, ... {"id":216, "channel": '216'. modified ...} ]}
3. Если каналов меньше 100, то это все каналы на данном сайте сохраняем в локальную БД(в виде отдельных записей или массива объектов) с целью последующего прохода по ним для синхронизации, а также сохраняем максимальный modified из всех каналов, который в дальнейшем будет использоваться для получения модифицированных каналов(параметр gtModify);
4. Если их 100, то подождем 5 секунд и можно вызывать API снова для получения следующей пачки с каналами, то есть переходим на пункт 1 с указанием page;

II. Сохранение всех Cackle комментариев в локальную БД

Для сохранения всех комментариев, необходимо иметь список всех каналов (параметр chan) на вашем сайте.

Алгоритм работы

1. Вызываем API для выбранного канала (параметр chan) с параметром commentId=0:
http://cackle.me/api/3.0/comment/list.json?id={siteId}&siteApiKey={siteApiKey}&accountApiKey={accountApiKey}&chan={chan}&commentId=0
2. В JSON ответе API, приходит массив комментариев сортированных по id от ранних к новым:
{"comments":[ {"id":101, "siteId": ...}, {"id":102, "siteId": ...}, ... {"id":216, "siteId": ...} ]}
3. Если комментариев меньше 100, то это все комментарии на данном канале, сохраняем комментарии в локальную БД;
4. Подождем 5 секунд и можно вызывать API снова для следующего канала, то есть переходим на пункт 1;
5. Если комментариев 100, то на данном канале есть ещё комментарии. Сохраним все 100 комментариев в локальную БД и запомним id последнего комментария из массива "comments" (он будет максимальным, в примере выше это 216);
6. Подождем 5 секунд и вызовем API снова для текущего канала с параметром commentId равным сохраненному id последнего комментария из пункта 5 (commentId=216);
7. В ответе придут следующие комментарии для данного канала id которых > параметра commentId;
8. Переходим на пункт 3 (если комментариев < 100) или пункт 5 (если комментариев 100).

Пример

Пускай ваш сайте http://mysite.ru зарегистрирован в Cackle с id 1, siteApiKey 123, accountApiKey 321.
Согласно алгоритму получения списка всех каналов с комментариями мы должны сделать следующее:

1. Вызываем API:
http://cackle.me/api/3.0/comment/chan/list.json?id=1&siteApiKey=123&accountApiKey=321
2. Приходит ответ:
{"chans":[ {"id":1, "channel": '1', url: 'http://mysite.ru/page1',...}, {"id":2, "channel": '2', url: 'http://mysite.ru/page2',...}, {"id":3, "channel": '3', url: 'http://mysite.ru/page3',...} {"id":4, "channel": '4', url: 'http://mysite.ru/page4',...} ]}
3. Каналов меньше 100, сохраняем каналы в локальную БД, а также сохраняем максимальный modify;

На предполагаемом сайте есть 4 страницы и на каждой установлен виджет комментариев Cackle:

http://mysite.ru/page1 - 3 комментария
http://mysite.ru/page2 - 230 комментариев
http://mysite.ru/page3 - 125 комментариев
http://mysite.ru/page4 - 99 комментариев

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

1. Вызываем API:
http://cackle.me/api/3.0/comment/list.json?id=1&siteApiKey=123&accountApiKey=321&chan=/page1&commentId=0
2. Приходит ответ:
{"comments":[ {"id":1, "siteId": ...}, {"id":2, "siteId": ...}, {"id":3, "siteId": ...} ]}
3. Комментариев меньше 100 и это все комментарии на данном канале, сохраняем комментарии в локальную БД;
Для страницы /page1 были сохранены все 3 комментария.

1. Вызываем API:
http://cackle.me/api/3.0/comment/list.json?id=1&siteApiKey=123&accountApiKey=321&chan=/page2&commentId=0
2. Приходит ответ:
{"comments":[ {"id":4, "siteId": ...}, {"id":5, "siteId": ...}, ... {"id":104, "siteId": ...} ]}
5. Комментариев 100 значит на странице есть ещё комментарии. Сохраняем полученные 100 комментариев в локальную БД и запоминаем id последнего комментария 104;
6. Вызываем API:
http://cackle.me/api/3.0/comment/list.json?id=1&siteApiKey=123&accountApiKey=321&chan=/page2&commentId=104
7. Приходит ответ:
{"comments":[ {"id":105, "siteId": ...}, {"id":106, "siteId": ...}, ... {"id":205, "siteId": ...} ]}
5. Комментариев 100 значит на странице есть ещё комментарии. Сохраняем полученные 100 комментариев в локальную БД и запоминаем id последнего комментария 205;
6. Вызываем API:
http://cackle.me/api/3.0/comment/list.json?id=1&siteApiKey=123&accountApiKey=321&chan=/page2&commentId=205
7. Приходит ответ:
{"comments":[ {"id":206, "siteId": ...}, {"id":207, "siteId": ...}, {"id":236, "siteId": ...} ]}
5. Комментариев меньше 100 и это все комментарии на данном канале, сохраняем комментарии в локальную БД;
Для страницы /page2 были сохранены все 230 комментариев.

1. Вызываем API:
http://cackle.me/api/3.0/comment/list.json?id=1&siteApiKey=123&accountApiKey=321&chan=/page3&commentId=0
2. Приходит ответ:
{"comments":[ {"id":237, "siteId": ...}, {"id":238, "siteId": ...}, ... {"id":337, "siteId": ...} ]}
5. Комментариев 100 значит на странице есть ещё комментарии. Сохраняем полученные 100 комментариев в локальную БД и запоминаем id последнего комментария 337;
6. Вызываем API:
http://cackle.me/api/3.0/comment/list.json?id=1&siteApiKey=123&accountApiKey=321&chan=/page3&commentId=337
7. Приходит ответ:
{"comments":[ {"id":338, "siteId": ...}, {"id":339, "siteId": ...}, ... {"id":363, "siteId": ...} ]}
5. Комментариев меньше 100 и это все комментарии на данном канале, сохраняем комментарии в локальную БД;
Для страницы /page3 были сохранены все 125 комментариев.

1. Вызываем API:
http://cackle.me/api/3.0/comment/list.json?id=1&siteApiKey=123&accountApiKey=321&chan=/page4&commentId=0
2. Приходит ответ:
{"comments":[ {"id":364, "siteId": ...}, {"id":365, "siteId": ...}, ... {"id":463, "siteId": ...} ]}
3. Комментариев меньше 100 и это все комментарии на данном канале, сохраняем комментарии в локальную БД;
Для страницы /page4 были сохранены все 99 комментариев.

II. Отлавливание добавления/изменения Cackle комментариев

Для отслеживания добавления или изменения (редактирование, удаление, модерация, голосование) Cackle комментариев, необходимо иметь список всех каналов (параметр chan) на вашем сайте и сохранять для каждого канала время последней модификации (параметр modified). Так как запросы на получения измененных комментариев происходят по-канально, то для начала необходимо получить список всех измененных каналов и уже только для них получать измененные комментарии. Поэтому сначала: запрашиваются изменные каналы, затем только для измененных каналов получаем список добавлений/изменений Cackle комментариев.

Алгоритм получения измененных каналов

1. Вызываем API для получения всех каналов с параметром gtModify сохраненным при первичном получении списка каналов:
http://cackle.me/api/3.0/comment/chan/list.json?id={siteId}&siteApiKey={siteApiKey}&accountApiKey={accountApiKey}
2. В JSON ответе API, приходит массив каналов:
{"chans":[ {"id":101, "channel": ...}, {"id":102, "channel": ...}, ... {"id":216, "channel": ...} ]}
3. Если каналов меньше 100, то это все каналы на данном сайте сохраняем в локальную БД(в виде отдельных записей или массива объектов) с целью последующего прохода по ним для синхронизации, а также сохраняем максимальный modified из всех каналов, который в дальнейшем будет использоваться для получения модифицированных каналов(параметр gtModify);
4. Если их 100, то подождем 5 секунд и можно вызывать API снова для получения следующей пачки с каналами, то есть переходим на пункт 1 с указанием page;

Алгоритм получения добавления/изменения комментариев для канала

1. Вызываем API для выбранного канала (параметр chan) с параметром modified=<время в миллисекундах> (обычно modified берется из последнего комментария сохраненного при синхронизации всех Cackle комментариев или просто текущее время):
http://cackle.me/api/3.0/comment/list.json?id={siteId}&siteApiKey={siteApiKey}&accountApiKey={accountApiKey}&chan={chan}&modified=1714113994810
2. В JSON ответе API, приходит массив комментариев с временем модификации больше чем в параметре modified:
{"comments":[ {... "modified":"1432421378073"}, {... "modified":"1432447569166"}, ... {... "modified":"1432467294131"} ]}
3. Сохраняем для данного канала (параметр chan) время модификации последнего комментария (в примере выше 1432467294131);
4. Подождем 5 секунд и можно вызывать API снова для следующего канала с начальным modified, то есть переходим на пункт 1;
5. Если мы прошли по всем каналам, то переходим к самому первому каналу и вызываем API с modified сохраненным именно для этого канала (из примера 1432467294131);
6. Далее переходим к следующему каналу и вызываем API с ранее сохраненным modified именно для данного канала.

На практике, для реализации алгоритма, обычно создается отдельная таблица, которая хранит значение [chan, modified]. Когда кто-то заходит на страницу вашего сайта, вы определяете канал страницы (chan) и по нему берете modified, далее можно делать запрос к API. Так же обязательно проверяйте таймер между запросами, он должен быть не меньше 5 секунд.

Пример

Пускай ваш сайт http://mysite.ru зарегистрирован в Cackle с id 1, siteApiKey 123, accountApiKey 321 и gtModify 1455652041007 сохраненный на предыдущих шагах получения списков каналов.

1. Вызываем API:
http://cackle.me/api/3.0/comment/chan/list.json?id=1&siteApiKey=123&accountApiKey=321&gtModify=1455652041007
2. Приходит ответ:
{"chans":[ {"id":1, "channel": '1', url: 'http://mysite.ru/page1',...}, {"id":2, "channel": '2', url: 'http://mysite.ru/page2',...},
3. Каналов меньше 100, сохраняем каналы в локальную БД для получения модифицированных комментариев, а также максимальный modify для следующих запросов;

Т.е на сайте есть 2 страницы с модифицированными коммментариями и на каждой установлен виджет комментариев Cackle:

http://mysite.ru/page1
http://mysite.ru/page2

Для реализации алгоритма необходимо создать в БД таблицу с каналом и временем последней модификации [chan, modified]:

CREATE TABLE chan_modified (chan character varying(1000), modified bigint, CONSTRAINT chan_modified_pkey PRIMARY KEY (chan));

Записать начальные значения (modified выберем как текущее время):

INSERT INTO chan_modified VALUES ('/page1', 1432421378073); INSERT INTO chan_modified VALUES ('/page2', 1432421378073);

1. Вызываем API для первого канала /page1:
http://cackle.me/api/3.0/comment/list.json?id=1&siteApiKey=123&accountApiKey=321&chan=/page1&modified=1432421378073
2. В JSON ответе API скорее всего придет пустой массив {"comments":[]} так как вряд ли кто-то успеет опубликовать или изменить комментарии;
3. Подождем 5 секунд и можно вызывать API снова для следующего канала /page2 с его modified;
4. Пускай прошло какое-то время и на /page1 появилось два комментария, вызываем API с chan=/page1&modified=1432421378073:
{"comments":[ {"id":1, "siteId": ... "modified":"1432422582935"}, {"id":2, "siteId": ... "modified":"1432422739512"} ]}
5. Сохраним оба комментария в БД вместе с их Cackle id (1, 2);
6. Обновим в таблице chan_modified поле modified взятое из последнего комментария для текущего канала /page1:
UPDATE chan_modified SET modified = 1432422739512 WHERE chan = '/page1';
7. Подождем 5 секунд и можно вызывать API для следующего канала /page2;
8. Допустим через некоторое время комментарий с id 1, был отредактирован автором, на странице /page1;
9. Делая запрос к API с chan=/page1&modified=1432422739512 получим данный комментарий:
{"comments":[{"id":1, "siteId": ... "modified":"1432423183461"}}]}
10. Так как Cackle id мы тоже сохраняем в БД, то легко найти комментарий с id 1, и обновить его;
11. Обновим в таблице chan_modified поле modified для текущего канала /page1:
UPDATE chan_modified SET modified = 1432423183461 WHERE chan = '/page1';
12. Подождем 5 секунд и можно вызывать API для следующего канала.

IV. Библиотека синхронизации на php

Библиотека синхронизации на php - Cackle comments sync