---
name: audience-help
description: Анализируй аудиторию сайтов и поисковых фраз через Audience Help API. Создавай портреты аудитории, сравнивай конкурентов, находи значимые особенности и предлагай идеи для маркетинга на основе географии, демографии, интересов и поведения.
metadata:
  version: "0.2.3"
---

# Audience Help

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

## Быстрый вызов

Вызови скилл по имени и добавь задачу. Примеры:

```text
$audience-help Проанализируй аудиторию example.com за 30 дней.
$audience-help Сравни example.com и example.org: портреты, отличия, идеи для маркетинга.
$audience-help Проанализируй аудиторию запросов «купить смартфон» и «купить планшет».
```

Домены в примерах замени объектами пользователя. Для сохранённого задания передай `job_id` и продолжи получение его результата. Поручение пользователя определяет объект, глубину и формат ответа.

## Как общаться с пользователем

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

Проверки качества выполняй внутри рабочего процесса. В ответ выноси конкретную проблему только тогда, когда она меняет вывод, охват сравнения или следующее действие пользователя. Достаточно одной короткой фразы рядом с соответствующим результатом. Обычный анализ начинай с содержательного вывода; общие оговорки о возможностях аналитики оставляй за рамками ответа.

Факты формулируй прямо. Предложения для маркетинга подавай как действия и идеи для проверки: «стоит протестировать», «можно усилить», «для этого сегмента подойдёт такой акцент». Подробность ответа подбирай под задачу. Источник и период укажи короткой подписью; технические идентификаторы и журнал проверок сохрани в рабочих данных.

Источник аналитики в клиентском отчёте — Audience Help. В ответы и выгрузки включай выбранные показатели, расчёты и выводы по задаче. Названия поставщиков, служебные поля происхождения данных, внутренние адреса, пути, заголовки авторизации, технические журналы и исходные ответы API сохраняй вне клиентских материалов. Ключи используй только для авторизации. Идентификатор задания выдавай по запросу для продолжения или поддержки.

Перед построением портрета или сравнения прочитай [методику анализа](references/analysis-method.md). При чтении по URL разрешай относительные ссылки от адреса этого файла.

## Документация и доступ

- [Описание API](https://audience.help/apidocs) — сценарии, определения и правила исполнения.
- [OpenAPI](https://audience.help/api/v2/openapi.json) — схемы запросов и ответов.
- Базовый адрес: `https://audience.help/api/v2`.

Перед первым вызовом в сессии прочитай актуальные разделы документации и схему выбранного сценария. Существенное противоречие разбери до зависимого запроса.

Используй инструмент HTTPS с поддержкой методов, заголовков и JSON. Авторизация: `Authorization: Bearer …`; секрет получай из защищённого окружения, например `AUDIENCE_HELP_KEY`. Если доступа не хватает, кратко назови, что нужно настроить. Передавай ключ только на `https://audience.help`, исключи его из URL, файлов, журналов и ответов, отключи перенос авторизации при перенаправлениях.

## Выбор анализа

1. Для продолжения используй сохранённый `job_id`. Для нового анализа выбери домен или набор поисковых фраз.
2. Определи объект, период и блоки по вопросу пользователя. Стандартный период возьми из актуальной документации, если пользователь его не задал. Существенную неоднозначность или изменение охвата согласуй; обычные параметры выбери самостоятельно.
3. Для базового портрета используй стандартные блоки. Добавляй интересы и поведение для содержательного портрета, сравнения и маркетинговых рекомендаций. Состав поисковых фраз сохраняй в рамках поручения; значимые расширения согласуй.
4. Поручение выполнить анализ и настроенный доступ достаточны для запуска. Используй существующую авторизацию, без повторного подтверждения каждого задания. Запрос о возможностях сервиса обслужи объяснением этих возможностей.
5. Для сравнения задай сопоставимые периоды и блоки. Используй сохранённые результаты, когда они подходят по актуальности и охвату, и соблюдай лимит параллельных заданий.

## Запросы и продолжение

Отправляй JSON с `Content-Type: application/json`.

| Действие | Сайт | Поисковые фразы |
| --- | --- | --- |
| Создать | `POST /domain-jobs/` | `POST /keyword-jobs/` |
| Проверить | `GET /domain-jobs/{job_id}/` | `GET /keyword-jobs/{job_id}/` |
| Получить результат | `GET /domain-jobs/{job_id}/result/` | `GET /keyword-jobs/{job_id}/result/` |

Перед POST создай уникальный `Idempotency-Key` и сохрани его вместе с точным телом запроса. При неясном сетевом исходе повтори то же тело с тем же ключом. Новый ключ используй для нового самостоятельного анализа; конфликт идемпотентности сначала разбери.

После принятия запроса сохрани `job_id`, вид, параметры и время следующей проверки отдельно от секрета. Сообщи пользователю, что анализ выполняется. Проверяй домены с интервалом от 15 секунд, фразы — от минуты, учитывая более длинные серверные интервалы, `Retry-After` и `retry_at`. Пользуйся ожиданием среды между запросами.

- `succeeded`: получи JSON, выполни внутренние проверки по методике и подготовь ответ.
- `queued`, `processing`: дождись готовности.
- `retrying`: продолжай то же задание по `retry_at`.
- `failed`, `cancelled`, `expired`: кратко объясни причину и предложи следующий шаг. Новое задание с расходом квоты запускай в пределах поручения пользователя; автоматическую замену завершившегося ошибкой задания согласуй.

При временном сбое выполни до трёх повторов с увеличением интервала и учётом серверных указаний. Для POST сохраняй исходный ключ и тело. Ошибки параметров и доступа требуют исправления причины.

При `JOB_LIMIT_REACHED` или `ANALYSIS_LIMIT_REACHED` приостанови создание оставшихся заданий до обновления лимита, сохрани принятые задания и готовые результаты. При ограничении скорости или параллельности продолжи по серверному расписанию с теми же идентификаторами.

Если среда завершает выполнение раньше готовности, сохрани состояние и способ продолжения. Для последующего уведомления используй настроенный механизм возобновления. `callback_url` подходит для настроенного получателя пользователя с проверкой подписи и обработкой дублей по документации.

## Подготовка ответа

Примени [методику](references/analysis-method.md) к фактическому JSON. Для пакетной проверки при наличии Python 3 используй [scripts/check_result.py](scripts/check_result.py):

```sh
python3 scripts/check_result.py /path/to/first-result.json /path/to/second-result.json
```

Путь команды указан относительно папки скилла. Помощник читает JSON результата API или обёртку `{ "http_status": 200, "data": ... }`; `-` означает stdin. Работает локально, сохраняет исходные файлы и выдаёт найденные расхождения. Коды завершения: `0` — механические проверки пройдены, `1` — замечания к данным, `2` — ошибка чтения или структуры. Смысл сегментов и сопоставимость оценивай по методике. При другой программной среде выполни те же проверки доступными средствами.

Собери ответ вокруг задачи пользователя: вывод → подтверждающие цифры → практический смысл. В сравнении покажи главные различия и краткие портреты. Для действий предложи подходящее сообщение, предложение или тест, опираясь на найденные особенности. Сохрани исходные ответы, параметры, расчёты и `job_id` для проверки и продолжения.