Маркетплейс игр на своем сайте

Виджет игр-шаблонов — подключение и настройка

Виджет «Маркетплейс» позволяет разместить на сайте каталог игр QQ для авторов. Такую игру можно приобрести и проводить самому. Вы можете настроить, какие игры показывать, сколько карточек выводить, какие фильтры доступны посетителям, а также выбрать светлую или тёмную тему и собственный акцентный цвет.

1. Быстрое подключение

Добавьте следующий код в нужное место внутри <body> вашей страницы:

<script type="module" src="https://qq.land/widget-mp/index.js"></script>
<qq-template-games></qq-template-games>

Готово! Если сайт разрешает выполнять JavaScript и использовать пользовательские HTML-элементы, каталог появится на странице.

2. Подключение с настройками

Чтобы изменить виджет, найдите его элемент в JavaScript и установите нужные свойства.

Пример: шесть игр, фильтры для посетителей и тёмное оформление:

<!-- Подключение скрипта и место отображения -->
<script type="module" src="https://qq.land/widget-mp/index.js"></script>
<qq-template-games></qq-template-games>

<!-- Настройка -->
<script type="module">
  const widgetComponent = document.querySelector('qq-template-games');

  widgetComponent.filter = JSON.stringify({
    records: 6
  });

  widgetComponent.userFilters = 'format,transport,franchise,author';
  widgetComponent.showUserFilters = 'true';
  widgetComponent.accentColor = '#ffeb3b';
  widgetComponent.theme = 'dark';
</script>

В этом примере посетители видят до 6 игр, могут фильтровать их по формату, транспорту, франшизе и автору, а сам виджет оформлен в тёмной теме с жёлтым акцентом.

Принцип настройки:

filter — какие игры отбирать изначально; объект условий передаётся через JSON.stringify(...).
userFilters — какие переключаемые фильтры будут доступны посетителю сайта.
showUserFilters — включает панель с фильтрами, поиском и сортировкой.
accentColor и theme — внешний вид.

3. Основные параметры виджета

Свойство	Назначение	Пример
`filter`	Начальные условия отбора и количество игр	`JSON.stringify({ records: 6 })`
`userFilters`	Список доступных посетителям фильтров	`'format,transport,franchise,author'`
`showUserFilters`	Показать фильтры, поиск и сортировку	`'true'`
`accentColor`	Акцентный цвет интерфейса в формате HEX	`'#ffeb3b'`
`theme`	Цветовая тема	`'light'` или `'dark'`

Обратите внимание: filter получает строку с JSON, а showUserFilters в примере разработчика включается строкой 'true' (в кавычках).

4. Начальная фильтрация игр: `filter`

Через filter можно заранее задать условия отбора. Например, показывать только игры из определённого города, от конкретного автора или с определённой последовательностью заданий.

widgetComponent.filter = JSON.stringify({
  'cities.name': 'Владимир',
  transport: 'FOOT',
  records: 6
});

Значение filter — JavaScript-объект, преобразованный в JSON-строку. Все условия записываются внутри фигурных скобок и разделяются запятыми.

4.1. Полный перечень известных полей фильтрации

Поле внутри `filter`	Что отбирает	Пример значения
`records`	Количество выводимых игр	`6`
`'games.name'`	Название игры	`{ ilike: 'достать ножи' }`
`'cities.name'`	Город или несколько городов	`'Владимир'` либо `['Владимир', 'Дмитров']`
`tags`	Форматы/теги игры	`{ inArray: ['PHOTO', 'BRAIN'] }`
`transport`	Транспорт	`'CAR'` либо `['CAR', 'FOOT']`
`schema`	Последовательность заданий	`'LINEAR'` либо `['LINEAR', 'RANDOM']`
`'games.id'`	ID конкретных игр	`'1'` либо `['1', '2', '3']`
`start_type`	Способ запуска игры	`{ eq: ['team'] }`
`franchise_id`	ID франшизы или нескольких франшиз	`'1'` либо `['1', '2', '3']`
`owner`	ID автора игры	`{ eq: '1' }`
`'-or'`	Условие ИЛИ для перечисленных внутри него полей	`{ 'cities.name': 'Владимир', transport: 'NONE' }`

Количество игр по умолчанию — 3. Чтобы вывести другое количество, задайте records.

4.2. Название игры: `games.name`

Для поиска по названию используется оператор ilike. По сообщению разработчика, такой поиск не зависит от регистра букв.

widgetComponent.filter = JSON.stringify({
  'games.name': {
    ilike: 'достать ножи'
  },
  records: 6
});

Например, запрос достать ножи не требует точно повторять заглавные и строчные буквы в названии игры.

4.3. Город: `cities.name`

Один город:

widgetComponent.filter = JSON.stringify({
  'cities.name': 'Владимир',
  records: 6
});

Несколько городов:

widgetComponent.filter = JSON.stringify({
  'cities.name': ['Владимир', 'Дмитров'],
  records: 6
});

Совет: указывайте названия городов соблюдая регистр, в каком они заведены на QQ.

4.4. Форматы игр: `tags`

Форматы задаются массивом значений через оператор inArray.

Значение	Формат игры
`STREET`	Лёгкие уличные квесты
`URBAN`	Сложные квесты по заброшенным местам
`BRAIN`	Виртуальные игры
`SNOOP`	Детективные квесты
`MAZE`	Квесты-лабиринты
`TOUR`	Экскурсии
`COMBAT`	Межкомандные сражения
`PHOTO`	Фото-игры

Пример: фото-игры и детективные квесты:

widgetComponent.filter = JSON.stringify({
  tags: {
    inArray: ['PHOTO', 'SNOOP']
  },
  records: 6
});

Пример со всеми перечисленными форматами:

widgetComponent.filter = JSON.stringify({
  tags: {
    inArray: [
      'PHOTO', 'BRAIN', 'COMBAT', 'SNOOP',
      'TOUR', 'MAZE', 'STREET', 'URBAN'
    ]
  }
});

Важно: значения тегов в этом виджете записываются заглавными буквами: PHOTO, BRAIN и т. д. Не путайте их со строчными значениями атрибута format из другого виджета <qq-list-games>.

4.5. Транспорт: `transport`

Значение	Описание
`NONE`	Без транспорта (например, виртуальные игры)
`ANY`	Любой транспорт
`CAR`	Автомобиль
`FOOT`	Пешком
`BIKE`	Велосипед

Только пешие игры:

widgetComponent.filter = JSON.stringify({
  transport: 'FOOT'
});

Автомобильные и пешие игры:

widgetComponent.filter = JSON.stringify({
  transport: ['CAR', 'FOOT']
});

4.6. Последовательность заданий: `schema`

Значение	Описание
`LINEAR`	Линейная последовательность
`RANDOM`	Случайная последовательность
`ALL`	Все задания доступны сразу
`CUSTOM`	Сложная, настраиваемая последовательность

Только линейные игры:

widgetComponent.filter = JSON.stringify({
  schema: 'LINEAR'
});

Линейные и случайные:

widgetComponent.filter = JSON.stringify({
  schema: ['LINEAR', 'RANDOM']
});

4.7. Конкретные игры по ID: `games.id`

Если нужно показывать заранее выбранные игры, используйте их ID.

Одна игра:

widgetComponent.filter = JSON.stringify({
  'games.id': '118'
});

Несколько игр:

widgetComponent.filter = JSON.stringify({
  'games.id': ['118', '119', '120']
});

ID в примере приведены для иллюстрации синтаксиса, а не как подтверждённые ID доступных шаблонов.

4.8. Способ запуска: `start_type`

Для этого поля применяется оператор eq с массивом значений.

Значение	Как указано разработчиком
`team`	Игры типа `fun`
`auto`	Игры типа `run`
`manual`	Игры типа `run`

Для fun:

widgetComponent.filter = JSON.stringify({
  start_type: {
    eq: ['team']
  }
});

Для run:

widgetComponent.filter = JSON.stringify({
  start_type: {
    eq: ['auto', 'manual']
  }
});

Обратите внимание: здесь используется поле start_type, а не атрибут type виджета списка игр. Значения team, auto, manual и связь с fun/run приведены по примеру разработчика.

4.9. Франшиза: `franchise_id`

Одна франшиза:

widgetComponent.filter = JSON.stringify({
  franchise_id: '1'
});

Несколько франшиз:

widgetComponent.filter = JSON.stringify({
  franchise_id: ['1', '2', '3']
});

Замените значения на нужные ID франшиз.

4.10. Автор игры: `owner`

Для отбора по автору используется поле owner с оператором eq.

widgetComponent.filter = JSON.stringify({
  owner: {
    eq: '1'
  },
  records: 6
});

Замените '1' на ID нужного автора.

4.11. Условие «ИЛИ»: `-or`

По умолчанию отдельные условия в объекте filter задают совместный отбор. Если нужно объединить несколько условий по принципу «ИЛИ», поместите их внутрь поля '-or'.

Пример: показать игры из Владимира ИЛИ игры без транспорта (в том числе из других городов):

widgetComponent.filter = JSON.stringify({
  '-or': {
    'cities.name': 'Владимир',
    transport: 'NONE'
  },
  records: 6
});

Подойдут игры, удовлетворяющие хотя бы одному из этих двух условий.

Важно: поле записывается строго как '-or', с дефисом и в кавычках, внутри объекта filter. Это не отдельное JavaScript-свойство виджета и не HTML-атрибут or из виджета <qq-list-games>.

5. Фильтры для посетителей: `userFilters`

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

Поддерживаемые элементы панели:

Значение в `userFilters`	Что сможет выбирать посетитель
`format`	Формат игры
`transport`	Транспорт
`franchise`	Франшизу
`author`	Автора

Значения перечисляются через запятую в одной строке.

Показать все четыре фильтра:

widgetComponent.userFilters = 'format,transport,franchise,author';
widgetComponent.showUserFilters = 'true';

Показать только франшизу и автора:

widgetComponent.userFilters = 'franchise,author';
widgetComponent.showUserFilters = 'true';

Важно: userFilters управляет фильтрами для посетителя, а filter ограничивает исходный набор игр. Для отображения панели необходимо showUserFilters = 'true'; вместе с фильтрами разработчик указывает отображение поиска и сортировки.

6. Оформление: цвет и тема

6.1. Акцентный цвет: `accentColor`

Укажите собственный цвет в формате HEX:

widgetComponent.accentColor = '#ffeb3b';

Примеры цветов:

Цвет	Код
Жёлтый	`#ffeb3b`
Зелёный	`#4caf50`
Синий	`#2196f3`
Оранжевый	`#ff9800`
Красный	`#f44336`

Это примеры HEX-цветов, а не встроенные цветовые схемы.

6.2. Светлая и тёмная темы: `theme`

Значение	Результат
`'light'`	Светлая тема (по умолчанию)
`'dark'`	Тёмная тема

widgetComponent.theme = 'dark';

Тему и акцентный цвет можно настраивать независимо. Разработчик указывает, что цвет по умолчанию — зеленовато-жёлтый; точный HEX по умолчанию не предоставлен.

Демонстрация двух тем: qq.land/widget-mp/.

7. Готовые примеры для копирования

Во всех примерах ниже приводится полный код одного виджета. Выберите подходящий вариант и вставьте его в разрешающий JavaScript HTML-блок на странице.

Пример 1. Обычный каталог без настроек

<script type="module" src="https://qq.land/widget-mp/index.js"></script>
<qq-template-games></qq-template-games>

Пример 2. Шесть игр из Владимира, светлая тема

<script type="module" src="https://qq.land/widget-mp/index.js"></script>
<qq-template-games></qq-template-games>

<script type="module">
  const widgetComponent = document.querySelector('qq-template-games');

  widgetComponent.filter = JSON.stringify({
    'cities.name': 'Владимир',
    records: 6
  });
  widgetComponent.theme = 'light';
  widgetComponent.accentColor = '#4caf50';
</script>

Пример 3. Пешие и автомобильные игры с выбором формата

<script type="module" src="https://qq.land/widget-mp/index.js"></script>
<qq-template-games></qq-template-games>

<script type="module">
  const widgetComponent = document.querySelector('qq-template-games');

  widgetComponent.filter = JSON.stringify({
    transport: ['FOOT', 'CAR'],
    records: 6
  });
  widgetComponent.userFilters = 'format,transport';
  widgetComponent.showUserFilters = 'true';
</script>

Пример 4. Виртуальные и детективные игры, тёмная тема

<script type="module" src="https://qq.land/widget-mp/index.js"></script>
<qq-template-games></qq-template-games>

<script type="module">
  const widgetComponent = document.querySelector('qq-template-games');

  widgetComponent.filter = JSON.stringify({
    tags: {
      inArray: ['BRAIN', 'SNOOP']
    },
    records: 6
  });
  widgetComponent.theme = 'dark';
  widgetComponent.accentColor = '#ffeb3b';
</script>

Пример 5. Игры выбранного автора и франшизы

<script type="module" src="https://qq.land/widget-mp/index.js"></script>
<qq-template-games></qq-template-games>

<script type="module">
  const widgetComponent = document.querySelector('qq-template-games');

  widgetComponent.filter = JSON.stringify({
    franchise_id: '1',
    owner: {
      eq: '1'
    },
    records: 6
  });
</script>

Здесь '1' — пример ID, подставьте реальные идентификаторы.

Пример 6. Вывод только выбранных игр по ID

<script type="module" src="https://qq.land/widget-mp/index.js"></script>
<qq-template-games></qq-template-games>

<script type="module">
  const widgetComponent = document.querySelector('qq-template-games');

  widgetComponent.filter = JSON.stringify({
    'games.id': ['118', '119', '120'],
    records: 3
  });
</script>

Указанные ID условные: замените их на нужные ID игр-шаблонов.

Пример 7. Игры из Владимира ИЛИ игры без транспорта

<script type="module" src="https://qq.land/widget-mp/index.js"></script>
<qq-template-games></qq-template-games>

<script type="module">
  const widgetComponent = document.querySelector('qq-template-games');

  widgetComponent.filter = JSON.stringify({
    '-or': {
      'cities.name': 'Владимир',
      transport: 'NONE'
    },
    records: 6
  });
  widgetComponent.userFilters = 'format,transport,franchise,author';
  widgetComponent.showUserFilters = 'true';
</script>

Пример 8. Полная настройка со всеми основными возможностями

В примере отбираются линейные или случайные игры заданных форматов, доступные в двух городах, с запуском auto или manual. Посетителям доступны фильтры, поиск и сортировка.

<script type="module" src="https://qq.land/widget-mp/index.js"></script>
<qq-template-games></qq-template-games>

<script type="module">
  const widgetComponent = document.querySelector('qq-template-games');

  widgetComponent.filter = JSON.stringify({
    'cities.name': ['Владимир', 'Дмитров'],
    tags: {
      inArray: ['STREET', 'URBAN', 'PHOTO']
    },
    transport: ['CAR', 'FOOT'],
    schema: ['LINEAR', 'RANDOM'],
    start_type: {
      eq: ['auto', 'manual']
    },
    records: 6
  });

  widgetComponent.userFilters = 'format,transport,franchise,author';
  widgetComponent.showUserFilters = 'true';
  widgetComponent.accentColor = '#ffeb3b';
  widgetComponent.theme = 'dark';
</script>

Важно: условия отбора в этом примере применяются совместно. Если игр, соответствующих сразу всем условиям, нет, каталог может оказаться пустым. Уберите лишние ограничения, если результат слишком узкий.

Пример 9. Два каталога на одной странице с разными настройками

Если на странице несколько экземпляров виджета, используйте уникальные id вместо общего querySelector('qq-template-games'), который находит только первый элемент.

<script type="module" src="https://qq.land/widget-mp/index.js"></script>

<h2>Игры во Владимире</h2>
<qq-template-games id="qq-local"></qq-template-games>

<h2>Виртуальные игры</h2>
<qq-template-games id="qq-online"></qq-template-games>

<script type="module">
  const localWidget = document.querySelector('#qq-local');
  const onlineWidget = document.querySelector('#qq-online');

  localWidget.filter = JSON.stringify({
    'cities.name': 'Владимир',
    records: 6
  });
  localWidget.theme = 'light';

  onlineWidget.filter = JSON.stringify({
    transport: 'NONE',
    records: 6
  });
  onlineWidget.theme = 'dark';
  onlineWidget.accentColor = '#ffeb3b';
</script>

Примечание: здесь показан способ независимо назначать настройки двум HTML-элементам. Одновременная работа нескольких экземпляров зависит от реализации установленной версии скрипта; в предоставленной информации она отдельно не подтверждена.

8. Типичные ошибки и решения

Проблема	Что проверить
Виджет не отображается	Добавлены ли `<qq-template-games>` и скрипт `https://qq.land/widget-mp/index.js`
На сайте виден код, а не каталог	HTML-редактор экранирует пользовательский HTML или запрещает JavaScript
Настройки фильтрации не применяются	Используется ли `JSON.stringify({...})`, верно ли записаны имена полей
Поиск по названию не работает как ожидается	Указаны ли `'games.name'` и оператор `ilike`
Не фильтруются теги	Указан ли `tags: { inArray: [...] }` и значения в верхнем регистре
Не работает объединение «ИЛИ»	Используется ли поле `'-or'` внутри `filter`
Показано только три игры	Задайте `records: 6` или другое нужное число; по умолчанию — 3
Не появляется панель фильтров	Указано ли `widgetComponent.showUserFilters = 'true'`
Не те фильтры в панели	Проверить строку `userFilters`, например `'franchise,author'`
Не меняется тема или цвет	Проверьте `theme`, HEX-значение `accentColor` и имя переменной виджета
Настраивается не тот виджет	Используйте индивидуальные `id` и точный селектор элемента

Маркетплейс игр на своем сайте

Виджет игр-шаблонов — подключение и настройка

1. Быстрое подключение

2. Подключение с настройками

3. Основные параметры виджета

4. Начальная фильтрация игр: filter

4.1. Полный перечень известных полей фильтрации

4.2. Название игры: games.name

4.3. Город: cities.name

4.4. Форматы игр: tags

4.5. Транспорт: transport

4.6. Последовательность заданий: schema

4.7. Конкретные игры по ID: games.id

4.8. Способ запуска: start_type

4.9. Франшиза: franchise_id

4.10. Автор игры: owner

4.11. Условие «ИЛИ»: -or

5. Фильтры для посетителей: userFilters