Найважливіші функції та переваги
- Офіційне API Instagram: модуль використовує Instagram API with Instagram Login і дозвіл
instagram_business_basic. Він не використовує вимкнені Meta інтерфейси Instagram Legacy API та Instagram Basic Display API. - Без запитів до Instagram під час відображення сторінки: блок формується з постів, збережених у базі даних магазину. Відображення сторінки не запускає запитів до Instagram, а синхронізація відбувається в окремих запитах.
- Зображення з домену магазину: зображення зберігаються в каталозі
img/pdblockinstagram/. Блок не завантажує скрипти, фрейми чи cookie Instagram, а під час його відображення браузер клієнта не підключається до серверів Meta. - Автоматичне оновлення токена: модуль оновлює токен приблизно кожні 7 днів під час синхронізації, тож за наявності працюючого CRON або трафіку в магазині не потрібно генерувати його повторно.
- Стійкість до збоїв: якщо Instagram недоступний, відхиляє токен або обмежує кількість запитів, клієнти й надалі бачать останні збережені пости. Невдала синхронізація ніколи не видаляє працюючий фід.
- Налаштовуваний вигляд: сітка або карусель, кількість колонок для комп’ютера й телефону, відступи, квадратні плитки, опис при наведенні, попередній перегляд поста та кнопка «Показати більше».
- Панель із діагностикою: заголовок з індикаторами стану, п’ять вкладок, попередній перегляд збережених постів, перевірка сервера та журнал подій полегшують налаштування й пошук причин проблем.
Як працює модуль?
- Підключення облікового запису: на вкладці Підключення ви вставляєте токен, згенерований у Meta for Developers. Модуль перевіряє його, зчитує назву облікового запису й одразу завантажує пости.
- Синхронізація на стороні сервера: модуль завантажує профіль і список постів, а зображення завантажує лише для тих постів, яких ще немає в магазині. Він зберігає 48 найновіших постів облікового запису.
- Локальні копії зображень: кожне зображення декодується й повторно зберігається як JPEG у двох ширинах: 640 px і 320 px. Файли постів поза 48 найновішими видаляються.
- Відображення в магазині: сторінка показує збережені пости. Якщо фід неактуальний, після завантаження сторінки браузер у фоновому режимі надсилає один запит до магазину, який запускає синхронізацію.
Якщо обліковий запис ще не має збережених постів, блок не відображається. Головний перемикач Показувати фід вмикає та вимикає всі місця відображення одночасно.
Налаштування вигляду та вмісту блоку
| Налаштування | Можливості | За замовчуванням |
|---|---|---|
| Макет | Сітка або карусель в одному ряду, що прокручується пальцем або стрілками. | Сітка |
| Кількість постів | Від 1 до 48. | 8 |
| Колонки на комп’ютері | Від 2 до 8 (екрани від 992 px). На планшетах (768–991 px) модуль показує стільки ж колонок, максимум 4. | 4 |
| Колонки на телефоні | 1, 2 або 3 (екрани менше 768 px). | 2 |
| Відступ між зображеннями | 0, 2, 4, 8, 12, 16 або 24 px. | 8 px |
| Квадратні плитки | Обрізання зображень до квадрата, як у сітці профілю в Instagram, або оригінальні пропорції. | Увімкнено |
| Опис при наведенні | Початок опису поста (до 90 символів) на зображенні при наведенні курсора або без опису. На сенсорних екранах накладка не показується. | Початок опису |
| Клік по посту | Відкриття попереднього перегляду в магазині або поста в Instagram у новій вкладці. | Попередній перегляд у магазині |
| Кнопка «Показати більше» | Лише в макеті сітки: відкриває наступні порції постів, загалом до чотирьох разів більше за встановлену кількість, максимум 48. | Вимкнено |
| Заголовок блоку | Окремий для кожної мови, до 128 символів. Порожній заголовок не відображається. | «Слідкуйте за нами в Instagram» |
| Посилання на профіль | Фото профілю, назва @акаунта та кнопка «Підписатися», що веде до профілю в Instagram. | Увімкнено |
| Відео та рілси | Враховувати або пропускати відеопости та рілси. | Враховуються |
| Лише пости, що містять | Текст до 64 символів, наприклад хештег. Відображаються лише пости, опис яких містить цей текст, незалежно від регістру. | Порожньо (усі пости) |
Плитки відео та рілсів мають іконку відтворення, а пости з кількома зображеннями — іконку каруселі. Налаштування вигляду зберігаються окремо для кожного магазину, групи магазинів або всіх магазинів.
Де відображати зображення з Instagram?
- Головна сторінка: у вмісті головної сторінки (hook
displayHome). - Сторінка товару: під деталями товару (hook
displayFooterProduct). - Над футером на кожній сторінці: hook
displayFooterBefore. - Будь-яке місце теми: код
{widget name='pdblockinstagram'}, вставлений у шаблон. Необов’язкові параметриlimitіlayoutдають змогу встановити іншу кількість постів і макет, наприклад{widget name='pdblockinstagram' limit=6 layout='carousel'}. Код для копіювання доступний на Панелі.
Таблиця стилів і скрипт модуля підключаються лише на сторінках, де увімкнене місце відображення показує фід; блок, вставлений віджетом, підключає їх самостійно. У темі Hummingbird, стандартній для PrestaShop 9, ширина блоку на головній сторінці та над футером підлаштовується під контейнер теми.
Вікно попереднього перегляду поста в магазині
Після кліку на зображення відкривається вікно зі збільшеним зображенням, датою публікації, повним описом поста та кнопкою Переглянути в Instagram. Між постами можна переходити стрілками у вікні або клавішами зі стрілками на клавіатурі. Вікно закривається кнопкою Закрити, клавішею Esc або кліком по фону, а фокус повертається до натиснутого зображення.
Без JavaScript або в браузері без підтримки діалогових вікон кожна плитка залишається звичайним посиланням на пост в Instagram. Для відео та рілсів попередній перегляд показує обкладинку, а для каруселі — перше зображення; відео можна переглянути в Instagram.
Синхронізація: CRON, фонове оновлення та кнопка в панелі
- Частота: нові пости завантажуються кожні 15 хв, 30 хв, 1 год, 3 год, 6 год, 12 год або 24 год. За замовчуванням — щогодини.
- CRON: вкладка CRON і діагностика містить адресу з секретним ключем і приклад рядка для crontab. Рекомендується викликати адресу кожні 15–60 хвилин методом GET або POST. Модуль виконує роботу лише тоді, коли настав час синхронізації або оновлення токена; параметр
&force=1примусово запускає синхронізацію. - Фонове оновлення без CRON: коли клієнт відкриває сторінку з неактуальним фідом, браузер надсилає один POST-запит до магазину через півтори секунди після завантаження сторінки, не частіше ніж раз на хвилину в одній вкладці браузера. Сторінка завжди показує збережені пости, тож клієнт нічого не чекає.
- Кнопка в панелі: Синхронізувати зараз завантажує пости негайно, незалежно від розкладу.
- Лише одна синхронізація одночасно: блокування в базі MySQL запобігає паралельним синхронізаціям одного й того самого облікового запису.
- Ліміт часу: завантаження зображень за один прохід триває максимум 25 секунд. Решта зображень завантажуються під час наступного виклику CRON або фонового оновлення, можливого вже приблизно за хвилину.
Токен доступу оновлюється автоматично
Токен, згенерований у панелі Meta, дійсний 60 днів. Модуль оновлює його під час синхронізації приблизно кожні 7 днів, а раніше — коли до завершення строку дії залишається менше 14 днів. Згідно з документацією Meta, автоматичне оновлення відбувається не раніше ніж через 24 години після підключення або попереднього оновлення; після невдалої спроби модуль повторює її через добу. На Панелі і на вкладці Підключення також доступна кнопка Оновити токен зараз, а заголовок панелі показує кількість днів дії.
Токен зберігається в базі даних магазину й використовується виключно сервером. Він ніколи не потрапляє до браузерів клієнтів, у панелі відображається лише в скороченому вигляді (перші й останні чотири символи), а в повідомленнях і журналі подій маскується.
Якщо Instagram відхилить токен (він закінчився, доступ застосунку було відкликано, змінено пароль облікового запису або протягом 60 днів не виконувалася жодна синхронізація), модуль припиняє надсилати запити, показує повідомлення в панелі й надалі відображає збережені пости. Достатньо згенерувати новий токен і вставити його кнопкою Перевірити та замінити токен.
Зображення зберігаються на сервері магазину
- Два розміри: кожне зображення зберігається як прогресивний JPEG шириною 640 px і 320 px; менші оригінали не збільшуються. Фото профілю має ширину 150 px.
- Безпечне завантаження: зображення завантажуються через HTTPS виключно із серверів Instagram (
cdninstagram.com,fbcdn.net), а потім декодуються й заново зберігаються через PHP GD. На диск потрапляють лише пікселі зображення. Модуль запитує у серверів Instagram формат JPEG; файли PNG і WebP конвертуються, якщо їх підтримує бібліотека GD на сервері. - Надійність зберігання: каталог
img/pdblockinstagram/розташований поза каталогом модуля, тому оновлення модуля не видаляє зображення. - Атрибути зображень:
srcsetз обома ширинами іsizes, підібрані до кількості колонок, розміриwidthіheight, ліниве завантаження та альтернативний текст із початку опису поста (до 125 символів) або у вигляді «Пост @назва в Instagram». - Емодзі в описах: описи постів зберігаються способом, стійким до кодування з’єднання з базою даних, тому емодзі коректно відображаються також у PrestaShop 1.7.0–1.7.6.
Стійкість до помилок і обмежень Instagram
- Повторні спроби зі зростаючою паузою: після помилки наступна спроба відбувається через 5 хвилин, а пауза подвоюється до 6 годин. Після перевищення ліміту запитів модуль чекає щонайменше годину.
- Захист працюючого фіду: зображення, які не вдалося завантажити, повторно завантажуються під час наступної синхронізації. Якщо не вдається зберегти жодного зображення, попередній фід залишається без змін.
- Безпечні посилання: адреса кожного поста будується заново у вигляді
https://www.instagram.com/p/…/(такожreelіtv). Нетипова адреса замінюється посиланням на профіль. - Стабільність сторінки: помилка під час побудови блоку не перериває відображення сторінки магазину. Підключення до Instagram мають ліміти часу, перевірку TLS-сертифіката й не переходять за перенаправленнями.
Панель налаштування
Заголовок панелі показує стан модуля у вигляді тексту та кольору: видимість фіду, підключений обліковий запис, кількість днів дії токена, час останньої синхронізації, кількість збережених постів і останній виклик CRON. Налаштування поділено на п’ять вкладок.
| Вкладка | Вміст |
|---|---|
| Панель | Перші кроки (доки обліковий запис не підключено), картка облікового запису (тип облікового запису, пости, збережені та доступні в Instagram, строк дії токена, остання й наступна синхронізація), кнопки синхронізації та оновлення токена, попередній перегляд 12 найновіших збережених постів із затемненням постів, прихованих фільтрами, список місць відображення та код віджета. |
| Підключення | Вставлення та перевірка токена, заміна токена, відключення облікового запису та список магазинів, у яких обліковий запис відображається. |
| Вигляд | Місця відображення, вигляд блоку та вибір постів (відео й рілси, текстовий фільтр). |
| Як отримати токен | Покрокова інструкція для Meta for Developers: вимоги, створення застосунку, додавання облікового запису Instagram, генерування токена, інформація після підключення та рішення типових проблем. |
| CRON і діагностика | Адреса CRON і приклад рядка crontab, час останнього виклику, генерування нової адреси, частота завантаження постів, перевірка сервера (cURL, GD, каталог зображень із правом запису), видалення збережених постів і журнал подій. |
Журнал подій реєструє підключення та відключення облікових записів, синхронізації з кількістю постів, завантажених і невдалих зображень, оновлення токена та помилки, а також джерело події: CRON, сторінку магазину (у фоновому режимі) або панель. Модуль зберігає 200 останніх записів, а журнал можна очистити.
Multistore, мови та дозволи
- Окремий обліковий запис і налаштування: кожен магазин, група магазинів або всі магазини можуть мати власний обліковий запис Instagram і власний вигляд блоку. Магазин без власних значень успадковує їх від групи або налаштувань усіх магазинів.
- Спільний фід: магазини, що показують той самий обліковий запис, використовують один набір постів, зображень і токен.
- Права працівників: працівник із доступом лише до частини магазинів змінює тільки те, що показують його магазини. Спільні для всіх магазинів налаштування (адреса CRON, частота, журнал) вимагають доступу до кожного магазину, а відключення успадкованого облікового запису в одному магазині лише приховує його там.
- Мови: заголовок блоку налаштовується окремо для кожної мови магазину. Інтерфейс модуля й тексти в магазині доступні польською та англійською.
Оновлення з версії 1.x
Версія 1.x використовувала Instagram Legacy API, яке Meta вимкнула в червні 2020 р., тому відтоді не відображала зображення. Версію 2.0.0 було написано заново. Оновлення зберігає кількість зображень, налаштування описів, кнопку «Показати більше» та відображення на головній сторінці й сторінці товару. Старі дані доступу, фід за хештегом, старі скрипти та опція зображення заголовка видаляються, а обліковий запис потрібно підключити повторно новим токеном.
Вимоги та сфера роботи
Заявлений діапазон сумісності охоплює PrestaShop 1.7.0–9.x та PHP 7.0–8.5. Модуль тестували на PrestaShop 1.7.2.4, 1.7.4.4, 1.7.5.2, 1.7.6.7, 1.7.7.8, 1.7.8.11, 8.0.1, 8.1.5, 8.2.3, 9.0.2 і 9.1.5, з темами Classic і Hummingbird. Front працює без jQuery; скрипт має близько 12 KB, а таблиця стилів — близько 11 KB до стиснення.
- Сервер: розширення PHP cURL і GD, каталог
img/pdblockinstagram/із правом запису та можливість вихідних HTTPS-з’єднань доgraph.instagram.comі серверів зображень Instagram. - Instagram: професійний обліковий запис (бізнес або автора); перехід із приватного облікового запису безкоштовний. Для створення застосунку в Meta for Developers потрібен обліковий запис Facebook, сторінка Facebook не потрібна. Згідно з інструкцією в панелі, для читання власного облікового запису застосунок може залишатися в режимі розробника, без перевірки Meta.
Модуль лише зчитує пости підключеного облікового запису й нічого не публікує в Instagram. Кожен магазин відображає пости одного підключеного облікового запису. Використовуване API не надає пошуку за хештегами, тому модуль не показує пости інших облікових записів; фільтр «Лише пости, що містять» працює на описах власних постів. Історії (Stories) недоступні в API, а для частини рілсів із ліцензованою музикою Instagram не надає зображення, тому такі пости пропускаються. Відео та рілси не відтворюються в магазині, а пости з кількома зображеннями представлені першим зображенням.