Встановлення Looma на OpenCart

Для OpenCart є офіційне розширення Looma. Воно саме вставляє віджет на вітрину й віддає Looma каталог, розділи та інформаційні сторінки — без фіду й без правок теми. Працює на OpenCart 3.0.x, 4.0.x і 4.1.x та на ocStore 3.0.3.x.

Якщо ставити розширення не хочеться, лишається ручна вставка коду: тоді працює тільки віджет, а товари доведеться віддавати фідом.

Що дає розширення

	З розширенням	Ручна вставка
Віджет на вітрині	вставляється сам	копіювати код у шаблон теми
Товари	беруться з магазину напряму	потрібен Google Merchant фід
Розділи каталогу	приїжджають разом з адресами	Looma обходить сайт сама
Сторінки «Доставка», «Оплата»	потрапляють у базу знань асистента	—
Оновлення теми	нічого не ламає	код доводиться вставляти заново

Передумови

• OpenCart 3.0.x, 4.0.x, 4.1.x або ocStore 3.0.3.x і доступ до адмінки магазину;
• HTTPS на магазині — Looma приймає лише https://-адресу;
• у Looma — роль Власник або Адміністратор і тариф із доступом до API (розділ «Інтеграції» видно тільки їм).

Крок 1. Поставте розширення

Спосіб A: файлом

Де взяти файл

Завантажте архів для своєї версії магазину:

• OpenCart 4.0.x і 4.1.x — looma.ocmod.zip
• OpenCart 3.0.x і ocStore 3.0.3.x — looma-oc3.ocmod.zip

Ті самі кнопки є в Looma: Інтеграції → OpenCart.

Не знаєте свою версію? Вона внизу будь-якої сторінки адмінки магазину.

1. Збережіть архів, не змінюючи імені файлу.

   Не перейменовуйте архів

   В OpenCart 4 ім'я файлу задає теку розширення й простір імен усередині магазину. Перейменований архів встановиться, але ендпоінт віддаватиме 404, і Looma не побачить магазин.

2. Extensions → Installer → Upload і оберіть архів.

3. Extensions → Extensions → Modules, знайдіть у списку Looma і натисніть + (Install).

   На OpenCart 4 цей крок обов'язковий

   До нього маршрут розширення не існує взагалі: екран налаштувань уже відкривається, а перевірка з'єднання в Looma повертає помилку. На 3.0.x такої залежності немає, але кнопку однаково треба натиснути, щоб з'явився екран налаштувань.

4. Натисніть Edit біля Looma — відкриється екран налаштувань.

Спосіб B: зі сторінки на opencart.com

Розширення опубліковане в офіційному каталозі: Looma на opencart.com.

1. Відкрийте сторінку розширення й натисніть Download.
2. Оберіть архів під свою версію — на сторінці їх два, з тими самими іменами, що й вище.
3. Далі — усе те саме, що в способі A, з першого кроку.

«Extensions → Marketplace» усередині магазину — не той шлях

У магазині є вкладка Extensions → Marketplace, і здається, що розширення можна поставити просто звідти. На практиці вона працює лише тоді, коли ваш магазин прив'язаний до акаунта opencart.com: OpenCart 4 одразу відповідає «You must enter your OpenCart API information … before you can download extensions», а на 3.0.x пошук повертає порожній список.

Тому беріть файл — зі сторінки розширення або прямо з Looma. Це швидше й не вимагає жодного стороннього акаунта.

Спосіб C: з вихідного коду

Розширення відкрите (GPL-3.0), і зібрати пакет можна самому: github.com/looma-chat/looma-opencart.

git clone https://github.com/looma-chat/looma-opencart.git
cd looma-opencart
./build.sh          # два архіви в dist/

Спосіб для тих, хто хоче спершу прочитати код або тримати власну збірку. Для звичайного встановлення він не потрібен — архіви в способах A і B зібрані з цих самих джерел.

Крок 2. Налаштуйте розширення в магазині

На екрані розширення чотири речі, які знадобляться. Підписи там англійською — власних перекладів у пакеті поки немає, тож нижче вони наведені так, як ви їх побачите.

Address for Looma (адреса для Looma) — готова адреса ендпоінта, скопіюйте її цілком. Вона відрізняється між версіями платформи, тому її показує саме розширення:

3.0.x / ocStore   https://ваш-магазин.com/index.php?route=extension/module/looma
4.0.x / 4.1.x     https://ваш-магазин.com/index.php?route=extension/looma/api

Адреса має бути https

Якщо магазин працює по http, розширення попередить про це прямо на екрані. Looma таку адресу не прийме — спершу підключіть сертифікат.

Connection key (ключ підключення) — придумайте довгий випадковий рядок (наприклад, 32 символи з менеджера паролів) і вставте той самий ключ і сюди, і в Looma. Магазин зберігає лише його хеш, тож прочитати ключ звідси назад не можна. Якщо загубили — просто задайте новий у двох місцях.

Мінімум 24 символи

Коротший ключ форма не прийме. Найпростіше — згенерувати його в менеджері паролів: саме цим ключем ви закриваєте свій каталог від сторонніх.

Last request from Looma (останній запит від Looma) — час останнього успішного звернення. Це головний факт для діагностики: він розрізняє «запит не дійшов узагалі» і «дійшов, шукати треба на боці Looma».

Перемикачі — Share products, Share categories, Share information pages і Add the widget to the storefront. Знятий перемикач означає, що магазин перестає віддавати саме ці дані; решта працює.

Крок 3. Підключіть магазин у Looma

1. Інтеграції → Готові інтеграції → OpenCart.
2. Знайдіть потрібний сайт і натисніть Підключити.
3. Вставте адресу (Address for Looma) і ключ (Connection key) з екрана розширення, натисніть Зберегти.
4. Натисніть Перевірити з'єднання.

Після успішної перевірки статус зміниться на Підключено, і поруч буде видно, які операції підтримує ваш магазин.

Крок 4. Увімкніть товари з магазину

Крок опційний: якщо вас влаштовує наявний фід, пропустіть його.

1. Налаштування сайту → Товари.
2. У «Джерелі даних» оберіть Пряме підключення до магазину.
3. Оберіть мову, якою імпортувати товари, збережіть і натисніть Оновити дані.

Зміна джерела перестворює каталог

Товари імпортуються наново, тому лічильники переглядів по картках обнуляються. Дашборд попередить про це перед перемиканням.

Далі каталог оновлюється раз на добу автоматично, а кнопка «Оновити дані» запускає імпорт позачергово. Докладніше — у розділі Пряме підключення магазину.

Віджет: нічого копіювати не треба

Розширення додає код віджета само — подією на виході готової сторінки, тож тема тут ні до чого.

• Одразу після встановлення тега на вітрині ще немає — і це нормально. Магазин дізнається адресу вашого сайту в Looma з першого ж запиту, тож тег з'явиться після першої вдалої перевірки з'єднання.
• Якщо ви вже вставили код Looma в тему руками, розширення свій тег не додає — чужу вставку воно не перезаписує. Looma показує це на екрані підключення, щоб ви знали, що працює саме ручна вставка.
• Вимкнути віджет можна перемикачем Add the widget to the storefront — наприклад, якщо ви керуєте вставкою через GTM.

Сторінки магазину в базі знань

Інформаційні сторінки («Доставка», «Оплата», «Про нас», контакти) стають джерелами знань асистента — саме вони відповідають на питання «як доставляєте?» і «до котрої працюєте?».

Інтеграції → OpenCart → Сторінки магазину в базі знань: там перелік сторінок і позначка навпроти кожної. Знята позначка — асистент перестає використовувати цю сторінку; повернути можна будь-коли, повторно завантажувати нічого не треба. Кнопка Оновити зі магазину забирає свіжий текст, якщо ви щойно правили сторінку в магазині.

Сторінка, яку видалили в магазині, не зникає мовчки: вона лишається в списку з позначкою Немає в магазині, бо збережений текст асистент усе ще використовує.

Усунення несправностей

«Магазин не відповідає» на перевірці з'єднання. Найчастіше на OpenCart 4 не натиснута кнопка + у Extensions → Extensions → Modules — без неї маршрут розширення не існує. Перевірте також, що адреса скопійована цілком і починається з https://.

«Магазин відхилив дані для доступу». Ключ у Looma й у магазині різні. Задайте новий ключ у двох місцях — прочитати збережений із магазину не можна.

У полі Last request from Looma порожньо. Жоден запит не дійшов до магазину: шукайте причину між Looma й магазином — маршрут, HTTPS, файрвол чи захист від ботів на хостингу.

Віджет не з'явився на вітрині. Перевірте, що перевірка з'єднання проходила хоч раз (до неї магазин не знає токена сайту), що перемикач віджета увімкнений, і очистіть кеш: Dashboard → іконка шестерні → Refresh для Theme і SASS.

Товари не оновились після зміни в магазині. Каталог оновлюється раз на добу — натисніть Оновити дані в налаштуваннях сайту, щоб не чекати.

Якщо розширення не підходить

Віджет можна вставити руками — тоді працює тільки він, а товари доведеться віддавати Google Merchant фідом.

Редактор теми (OpenCart 4.x)

1. Design → Theme Editor, оберіть активну тему.

2. Відкрийте common/header і знайдіть закриваючий тег </head>.

3. Вставте перед ним код встановлення з Дашборда → Налаштування сайту → Встановлення:

   <script>
   (function(d) {
       var s = d.createElement('script');
       s.defer = true;
       s.src = 'https://widget.looma.chat/loader.js?token=YOUR_SITE_TOKEN';
       if (d.head) d.head.appendChild(s);
   })(document);
   </script>

4. Збережіть і перевірте вітрину — бульбашка чату має з'явитися внизу праворуч.

Файли теми через FTP

• OpenCart 4.x: catalog/view/template/common/header.twig
• OpenCart 3.x: catalog/view/theme/ВАША_ТЕМА/template/common/header.twig (для стандартної теми — catalog/view/theme/default/…)

Вставте той самий код перед </head> і збережіть файл.

Оновлення теми зітре вставку

Після кожного оновлення теми код доведеться додавати заново. Саме цю проблему й вирішує розширення — воно нічого в темі не змінює.

Наступні кроки

• Пряме підключення магазину — товари й дані з магазину
• Налаштування AI-асистента — поведінка й вигляд чату
• Швидкий пошук — заміна стандартного пошуку OpenCart