> ## Documentation Index
> Fetch the complete documentation index at: https://www.mellowtel.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Інтеграція Mellowtel у ваш розширення для Chrome/Edge

Тут ви дізнаєтеся, як реалізувати бібліотеку Mellowtel у вашому проекті розширення для Chrome/Edge.

Орієнтовний час виконання: 5-7 хвилин.

# Відповідність політикам браузера

Mellowtel відповідає політикам браузера, якщо інтеграція поважає вибір і налаштування користувачів.

Офіційні плагіни Mellowtel доступні в Chrome і Edge. Незабаром ми подамо їх також в інші основні браузери.

Chrome: [https://chromewebstore.google.com/detail/support-with-mellowtel/jngbedjpioeongcicaomeideeompcbcc](https://chromewebstore.google.com/detail/support-with-mellowtel/jngbedjpioeongcicaomeideeompcbcc)

Edge: [https://microsoftedge.microsoft.com/addons/detail/support-with-mellowtel/chpomjnojnimgcaomhmcmfgjinfoekhi](https://microsoftedge.microsoft.com/addons/detail/support-with-mellowtel/chpomjnojnimgcaomhmcmfgjinfoekhi)

У Chrome деякі розробники можуть зіткнутися з проблемами під час перевірки з політикою єдиної мети, яка стверджує, що плагін може мати лише одну чітко визначену функціональність (але часто інтерпретується непослідовно в багатофункціональних розширеннях).
У таких випадках ми рекомендуємо розробникам поділитися своїм особистим посиланням і попросити користувачів встановити офіційний плагін Mellowtel для Chrome, який має єдину мету дозволити розробникам заробляти завдяки користувачам, які хочуть підтримати їх, ділячись своїми невикористаними ресурсами.
Розробники можуть створити своє посилання з [панелі керування Mellowtel](https://www.mellowtel.com/dashboard/support-with-mellowtel) і перенаправити користувачів на офіційний [плагін Mellowtel для Chrome](https://chromewebstore.google.com/detail/support-with-mellowtel/jngbedjpioeongcicaomeideeompcbcc).

Якщо ж у вас є плагін для Chrome, який працює в просторі обміну пропускною здатністю AI і це єдина мета плагіна, ви можете інтегрувати Mellowtel безпосередньо у ваш плагін.

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

# Рекомендовані браузери

На даний момент ми рекомендуємо інтегрувати Mellowtel у плагіни для Edge, оскільки ми все ще працюємо над оптимізацією версій бібліотеки для Firefox і Safari.

# Вимоги

Перед початком переконайтеся, що:

1. Ваш плагін використовує [Manifest V3](https://developer.chrome.com/docs/extensions/develop/migrate/what-is-mv3).
2. Ваш код організований у скомпільований спосіб, використовуючи Webpack, Rollup або інші збирачі.
   Якщо у вас немає налаштованого збирача, спочатку дотримуйтесь інструкцій [тут](/browser-plugins/static-to-webpack)

# Встановлення пакету npm

Щоб встановити пакет npm, ви можете виконати наступну команду у вашому терміналі:

```npm theme={null}
npm install mellowtel
```

<Accordion title="Yarn">
  Якщо ви використовуєте yarn як менеджер пакетів, ви можете виконати наступну команду:

  ```yarn theme={null}
  yarn add mellowtel
  ```
</Accordion>

# Вибір реалізації

Є два способи, як ви можете реалізувати бібліотеку у вашому розширенні.

Якщо ви збираєтеся вперше випустити розширення у Веб-магазині, дотримуйтесь Опції 1.
Якщо у вас вже є розширення, опубліковане у Веб-магазині, прочитайте "Як вирішити?"

### Як вирішити?

Коли ви встановлюєте своє розширення з Веб-магазину, чи з'являється вікно попередження з проханням дозволити "Читати і змінювати всі ваші дані на всіх веб-сайтах"?

Це виглядає так:

<Frame caption="Вікно попередження з проханням дозволити читати і змінювати всі ваші дані на всіх веб-сайтах">
  <img src="https://mintcdn.com/mellowtel/-NaMUO-H7VMwBlS7/images/alert_web_store.png?fit=max&auto=format&n=-NaMUO-H7VMwBlS7&q=85&s=c26c3ab1b347d62e376b28ec4c0766a7" width="898" height="282" data-path="images/alert_web_store.png" />
</Frame>

Якщо так, ви можете дотримуватися Опції 1. Якщо ні, вам потрібно дотримуватися Опції 2.

# Опція 1

Якщо ви вперше випускаєте розширення у Веб-магазині або імпортуєте бібліотеку в розширення, яке запитує дозвіл на роботу на всіх веб-сайтах, ви можете дотримуватися Опції 1.

### Налаштуйте ваш маніфест

У вашому файлі [manifest.json](https://developer.chrome.com/docs/extensions/reference/manifest) змініть секції `permissions` і `host_permissions` таким чином:

```json theme={null}
{

  "permissions": [
    "storage",
    "declarativeNetRequest"
  ],
  "host_permissions": [
    "\u003Call_urls\u003E"
  ]

}
```

### Налаштуйте вашого службового працівника (фоновий скрипт)

У вашому файлі [службового працівника](https://developer.chrome.com/docs/extensions/develop/concepts/service-workers) вам потрібно імпортувати пакет `mellowtel`.
Примітка: Службовий працівник також відомий як `фоновий скрипт`.

Ви можете скопіювати та вставити наступний код у файл службового працівника, змінивши `configuration_key` на ваш власний ключ.

```javascript theme={null}
import Mellowtel from "mellowtel";

let mellowtel;

(async () => {
    mellowtel = new Mellowtel("<configuration_key>"); // Замініть на ваш ключ конфігурації
    await mellowtel.initBackground();
})();
```

<Accordion title="Розбір коду службового працівника">
  Імпортуйте пакет mellowtel

  ```javascript theme={null}
      import Mellowtel from "mellowtel";
  ```

  Потім ви можете використовувати `Mellowtel(configuration_key, options?)` для створення нового екземпляра об'єкта Mellowtel. Об'єкт Mellowtel є вашим точкою входу до решти SDK Mellowtel. Ваш `configuration_key` є обов'язковим при виклику цієї функції, оскільки він ідентифікує ваше розширення для Mellowtel. Ви можете знайти свій `configuration_key` на [панелі керування](https://www.mellowtel.com/mellowtel-dashboard/#home)

  ```javascript theme={null}
  mellowtel = new Mellowtel("<configuration_key>");
  ```

  Ініціалізуйте Mellowtel, викликавши метод `initBackground`. Цей метод ініціалізує об'єкт Mellowtel і налаштує необхідні слухачі.

  ```javascript theme={null}
  await mellowtel.initBackground();
  ```
</Accordion>

### Налаштуйте ваш скрипт вмісту

Вам потрібно імпортувати пакет mellowtel також у [скрипти вмісту](https://developer.chrome.com/docs/extensions/develop/concepts/content-scripts).

Цей скрипт вмісту повинен виконуватися у `all_frames` і `<all_urls>` на `document_start`.

Ми пропонуємо створити новий скрипт вмісту (наприклад, content\_start\_mellowtel.js), де ви можете скопіювати та вставити наступний код.
Змініть `configuration_key` на ваш власний ключ.

```javascript theme={null}
import Mellowtel from "mellowtel";

(async () => {
    const mellowtel = new Mellowtel("<configuration_key>"); // Замініть на ваш ключ конфігурації
    await mellowtel.initContentScript();
})();
```

Потім не забудьте також додати цей скрипт вмісту у ваш файл `manifest.json` у секцію content\_scripts разом з будь-яким іншим скриптом вмісту, який у вас вже є.
Ви можете скопіювати та вставити наступний код, змінивши `name_of_your_content_script.js` на вибрану вами назву.

```json theme={null}
{
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["<name_of_your_content_script.js>"], // <-- Змініть тут на назву вашого скрипта вмісту
      "run_at": "document_start",
      "all_frames": true
    }
  ]
}
```

### Налаштуйте логіку підключення/відключення

Щоб активувати Mellowtel, користувачі повинні явно підключитися до сервісу.

Ви можете реалізувати логіку підключення/відключення двома способами:

1. Використовуючи рекомендовану реалізацію з попередньо створеною сторінкою, наданою Mellowtel.

2. Створюючи власні елементи підключення/відключення і використовуючи методи, показані [тут](https://docs.mellowtel.com/concepts/opt-in-out#2-custom-elements)

<Info>
  Якщо ви вирішите створити власні елементи підключення/відключення, розгляньте можливість використання <a href="/mellowtel-elements/quickstart" target="_blank">**Mellowtel Elements**</a> - попередньо створених компонентів інтерфейсу користувача, які обробляють згоду користувача та налаштування з мінімальними зусиллями інтеграції.
</Info>

Якщо ви використовуєте рекомендовану реалізацію, відкрийте ваш файл `службового працівника` (також відомий як фоновий скрипт) і додайте наступний код:

```javascript theme={null}
chrome.runtime.onInstalled.addListener(async function(details) {
    console.log("Розширення встановлено або оновлено");
    // Якщо ви хочете обробляти перше встановлення та оновлення по-різному
    /**
    if(details.reason === "install"){
        // викликати функцію для обробки першого встановлення
    } else if(details.reason === "update") {
        // викликати функцію для обробки оновлення
    }
    **/
    await mellowtel.generateAndOpenOptInLink();
});
```

### Генерація посилання на налаштування

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

Ви можете згенерувати посилання, використовуючи метод `generateSettingsLink()`.
Цей метод поверне посилання, яке відкриє сторінку налаштувань Mellowtel, де користувачі можуть у будь-який момент вирішити, чи хочуть вони підключитися чи відключитися.

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

Наприклад, ви можете помістити його у функцію `openSettings()` таким чином. Ви можете викликати `openSettings()` при натисканні кнопки або будь-якій іншій відповідній події:

```javascript theme={null}
async function openSettings() {
    try {
        // Генерація та управління посиланням на налаштування
        const settingsLink = await mellowtel.generateSettingsLink();
        // Логування згенерованого посилання для налагодження
        console.log("Згенероване посилання на налаштування:", settingsLink);
        // Тепер ви можете використовувати це посилання в спливаючому вікні, на сторінці параметрів або в будь-якому елементі інтерфейсу
    } catch (error) {
        console.error("Помилка при генерації посилання на налаштування:", error);
    }
}
```

Чудово! Тепер ви готові відправити своє розширення до Веб-магазину. Дотримуйтесь інструкцій тут, щоб дізнатися, як [подати своє розширення](/browser-plugins/submit-to-chrome-store)

# Опція 2

<Warning>Опція 2 може потенційно вимкнути ваше розширення, якщо не реалізована правильно. Тому вона недоступна для всіх користувачів </Warning>

Якщо ви не можете реалізувати Опцію 1, будь ласка, зв'яжіться з нами на [Discord](https://discord.com/invite/txAZp4MSDe)