Посібник Cluefolk

Створіть компанію та проєкт

1. Увійдіть через Google або поштою й підтвердьте адресу. Без компанії ви потрапляєте на сторінку компаній (Companies & invitations у меню облікового запису); натисніть там create your own company.
2. Пройдіть два кроки: Company (уведіть Company name і натисніть Create company) та Project (на екрані Your first project уведіть Project name і натисніть Create project). Робоче місце відкривається в новому проєкті.
3. Для наступного проєкту натисніть change поруч із назвою проєкту вгорі бічної панелі, потім New project; уведіть Name і натисніть Create project. Новий проєкт одразу відкриється. У Settings → General показано його назву, Project ID і Game icon: завантажте те саме зображення, що й іконка застосунку гри. Команда бачить його в меню проєктів і в попередньому перегляді віджета, а гравці — іконку, яку SDK бере із самої гри. Створювати й перейменовувати проєкти та задавати іконку може лише власник компанії.
4. Надайте доступ команді в Settings → Team кожного проєкту: натисніть круглу кнопку + і вкажіть пошту та роль. Іншого власника компанії запрошують у Settings → Members. Працівник приєднується за запрошенням і не створює окремої компанії.

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

Вхід і запрошення до компанії

1. Відкрийте cluefolk.com, натисніть Sign in і виберіть Google або Continue with email; під час входу поштою нові користувачі реєструються на наступній сторінці. Підтвердьте адресу за посиланням із листа та за потреби ввійдіть повторно.
2. Щоб приєднатися до команди, увійдіть саме з тією адресою, на яку надійшло запрошення. Відкрийте посилання з листа й натисніть Accept invitation або прийміть запрошення в Companies & invitations.
3. Запрошення перевіряються під час входу й оновлення сторінки. Якщо власник або адміністратор щойно запросив вас, оновіть сторінку.
4. Без компанії ви потрапляєте на сторінку компаній — її ж відкриває Companies & invitations у меню облікового запису. Напис You haven’t joined a company yet означає, що ви ще не приєдналися до компанії. Дочекайтеся запрошення або натисніть create your own company, щоб створити власну компанію та стати її власником.

Обліковий запис Google або підтверджена пошта самі по собі не дають доступу до чужої компанії.

Особистий обліковий запис, компанія та проєкт

1. Особистий обліковий запис існує окремо від вашої ролі в проєктах компанії. Ви можете належати до кількох компаній і мати різні ролі в різних проєктах.
2. Перед діями перевірте назву проєкту вгорі бічної панелі, під логотипом Cluefolk. Щоб перейти до іншого проєкту, натисніть change поруч із нею: у невеликому меню перелічено проєкти компанії з вашою роллю, поточний позначено галочкою; власники компанії бачать там також New project. Проєкт — це простір підтримки однієї гри: його гравці, звернення, налаштування, підключення сервера й ключі належать лише йому й ніколи не діляться з іншими проєктами.
3. Під перемикачем розташовані розділ Support desk з пунктами Inbox, Incidents, Players і Reports та розділ Views, який відкриває Inbox із готовим фільтром. Адміністратори проєкту й власники компанії бачать також посилання Settings унизу бічної панелі: Members компанії та налаштування вибраного проєкту.
4. Щоб збірки для розробки та QA не змішувалися зі справжніми гравцями, створіть для них окремий проєкт, наприклад «Space Farm» і «Space Farm QA». Кожен проєкт має власний ID, гравців і звернення.
5. Щоб перейти до іншої компанії, відкрийте меню облікового запису праворуч угорі (ваше ім’я). У ньому перелічено ваші компанії з вашою роллю, поточну позначено галочкою; виберіть іншу компанію, щоб відкрити її. У цьому ж меню є Account settings, Companies & invitations і Sign out. Значок книги поруч відкриває цей посібник.
6. У Account settings зібрано особисті налаштування: Profile (ім’я та пошта), Appearance — системна, світла або темна тема — і Privacy з кнопкою Cookie settings та посиланням на політику cookies.
7. У Profile введіть ім’я та прізвище й натисніть Save. Команда бачить ім’я та прізвище, гравець — лише ім’я на ваших відповідях, наприклад Anna · Support team. Поки ім’я не збережено, гравець бачить Support team.

Доступ надається до кожного проєкту окремо. Якщо доступ відкликали, попросіть власника компанії або адміністратора проєкту знову додати вас у Settings → Team.

Учасники й власники компанії

1. Власникові компанії: відкрийте Settings унизу бічної панелі й виберіть Members у розділі з назвою вашої компанії. На сторінці перелічено учасників компанії та запрошення власників (Invitations); учасники, які не є власниками, її не бачать.
2. Роль у компанії — Owner або Member. Власник має повний доступ до всіх проєктів. Власників може бути кілька; останнього власника не можна понизити чи видалити.
3. Доступ кожного учасника до проєктів показано лише для перегляду. Щоб надати доступ до проєкту або змінити роль у ньому, відкрийте Settings → Team цього проєкту.
4. У Settings → Members укажіть email і явно виберіть Owner, Admin або Operator. Для Admin і Operator також виберіть доступні проєкти. Роль автоматично не вибирається.
5. Remove і Confirm removal виключають людину з компанії та всіх її проєктів. Її обліковий запис і доступ до інших компаній зберігаються.

Зняття доступу до проєкту також виключає людину з черг цього проєкту й знімає призначені їй звернення.

Кому доступні дії

Support desk — робоче місце підтримки. У Settings розташовані Members компанії (лише для власників) і налаштування вибраного проєкту; цей розділ бачать лише власники компанії й адміністратори проєкту, в оператора його немає. Особисті налаштування — в Account settings у меню облікового запису. Власникові компанії доступно все в усіх проєктах; учасник отримує Admin або Operator у конкретному проєкті в Settings → Team.

Гравці та вхід

1. Виберіть потрібний проєкт у перемикачі бічної панелі й відкрийте Settings → Server connection. У блоці Players and sign-in виберіть Who can contact support.
2. Типово вибрано Everyone. Players signed in through the game are verified; others write anonymously. SDK розпізнає анонімного гравця за встановленням застосунку, тож історія зберігається між запусками навіть без ігрового backend.
3. Щоб підтверджувати гравців, ігровий backend після входу гравця підписує короткочасний identity-токен ES256. Вставте публічний ключ backend (PEM або JWK) у Identity signing keys і натисніть Add key. Issuer (iss) та audience (aud) токена показано над ключами.
4. Коли гравець входить через гру на тому самому встановленні, його анонімні звернення переходять до підтвердженого облікового запису.
5. Варіант Only players signed in through the game. потребує щонайменше одного identity-ключа. Гравець без чинного identity-токена тоді не зможе відкрити підтримку.

Cluefolk зберігає лише публічні ключі. Для ротації додайте новий ключ, переключіть на нього сервер, потім видаліть старий. Останній identity-ключ не можна видалити, доки вхід обов’язковий.

Підключіть ігровий сервер за потреби

1. Відкрийте Settings → Server connection. Звернення, анонімні гравці, identity-токени й ручні бейджі працюють без адреси ігрового сервера.
2. Щоб синхронізувати атрибути для автоматичних бейджів, доставляти подарунки, отримувати ігрові події й запитувати сповіщення, укажіть Game server URL: HTTPS-адресу, наприклад https://api.yourgame.com, без шляху й параметрів.
3. У Profile signing keys додайте публічний ключ, яким сервер підписує знімки атрибутів і відповідь на підключення. Для підключення потрібен щонайменше один ключ профілів.
4. Cluefolk command keys показує JWKS URL, issuer і audience. Cluefolk підписує кожен запит до вашого сервера (подарунки, профілі, події, push) ключем ES256, а сервер перевіряє його за JWKS URL, який кешується до 5 хвилин. Rotate command key і Rotate now одразу переводять нові запити на новий ключ; попередній ключ залишається опублікованим.
5. Download server config зберігає cluefolk-server.json з ідентифікаторами, issuer, audience, JWKS URL і публічними командними ключами Cluefolk. Секретів у ньому немає; передайте файл розробнику backend разом із посібником з інтеграції.
6. Розробник реалізує /cluefolk/connect, /cluefolk/profile, /cluefolk/gifts, /cluefolk/events і /cluefolk/push за потреби. Натисніть Check connection, щоб перевірити сервер і завантажити підписаний каталог атрибутів; після цього кнопка називається Refresh catalog.

Закриті ключі залишаються на ігровому backend: вони не повинні потрапляти до застосунку, WebView, публічного репозиторію чи параметрів SDK. Після зміни адреси потрібна нова перевірка.

Контракт ігрового сервера й підписаний каталог ↗

Оновлення каталогу атрибутів

1. Відкрийте Settings → Attributes. Таблиця Player attributes показує назву, ключ і тип кожного атрибута.
2. Після змін на ігровому сервері натисніть Refresh catalog. Прийнятий каталог одразу з’явиться в таблиці. Він також відображається в Server connection.
3. Визначення атрибутів і значення гравців надходять з ігрового сервера. На їх основі Cluefolk будує картки гравців і автоматичні бейджі; вручну атрибути не створюються.
4. Підтримуються типи string, integer, decimal, boolean, datetime та enum. Якщо потрібно змінити тип наявного атрибута, розробник має створити новий ключ.

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

Автоматичні та ручні бейджі

1. Адміністраторові: відкрийте Settings → Badges і натисніть + над списком. Задайте назву, іконку й колір; ключ і те, хто в команді бачить бейдж, — у More options.
2. У How players get it виберіть Automatically, from game data й опишіть Who gets it за атрибутами ігрового сервера — або An operator sets it on the player card. Check players показує, скільки гравців підходить. Save зберігає чернетку, Publish вмикає бейдж.
3. Для бейджа, який призначає підтримка, виберіть An operator sets it on the player card і залиште Everyone on the project у More options, потім збережіть і опублікуйте. Оператори фільтрують Inbox за бейджами у Filters → Players.

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

Подарунки та їхні ліміти

1. Подарункам потрібен підключений ігровий сервер: без нього Settings → Gifts лише пояснює, як його підключити. Адміністраторові: на вкладці Catalog натисніть + Create a gift, задайте назву й опис для гравця, команду ігрового сервера та що видати (JSON), потім Create gift. Команду й вміст погодьте з розробником ігрового сервера.
2. Щоб змінити подарунок, натисніть Change → і збережіть нову версію; уже надіслані подарунки лишаються з версією, з якою їх надіслали.
3. Натисніть Limits & approval →. Operators can send this gift визначає, чи бачать подарунок оператори. Gifts per player (0 = no limit) за Within, days діє для всіх, зокрема адміністраторів.
4. Для операторів задайте Gifts per operator per day (0 = no limit) — жорсткий ліміт — і за потреби Ask an administrator to approve larger volumes: коли оператор за 24 години надіслав вибрану кількість таких подарунків, наступні запити чекають підтвердження (0 — підтверджується кожен запит). Другий подарунок у тому самому зверненні завжди чекає адміністратора. Натисніть Save limits.

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

Підтвердження подарунків і звіт

1. Адміністраторові: відкрийте Settings → Gifts → Approvals. Вкладка показує кількість запитів, що чекають, подарунок, гравця, автора запиту й причину.
2. Натисніть Approve and send, щоб поставити доставку в чергу, або заповніть Decision note і натисніть Decline; для відмови нотатка обов’язкова. Open conversation ↗ показує контекст.
3. Власний запит вирішує інший адміністратор. Під час підтвердження ліміти на гравця перевіряються повторно.
4. Відкрийте Report і виберіть період: для кожного оператора й подарунка видно, скільки нараховано, очікує, відхилено чи завершилося помилкою та для скількох гравців.

Оператор бачить рішення в історії подарунків гравця. Відхилений запит ніколи не доставляється.

Додавання й керування командою проєкту

1. Виберіть потрібний проєкт у перемикачі бічної панелі й відкрийте Settings → Team — доступ до проєкту надається тут або під час запрошення через Members. На сторінці перелічено власників компанії (лише перегляд, усі проєкти), учасників з їхніми ролями та запрошення цього проєкту (Invitations).
2. Щоб додати людину, натисніть круглу кнопку + (Add to the project), у вікні вкажіть Email address, виберіть Role і натисніть Add to project. Той, хто вже є в компанії, одразу отримує доступ без листа («… now has access.»); решті надходить запрошення поштою, воно діє 7 днів («Invitation sent to …»). Адміністратор додає операторів; додати admin може лише власник компанії.
3. Запрошена людина входить із цією поштою й приймає запрошення; вона стає учасником компанії з доступом до цього проєкту.
4. Власник може змінювати тут роль учасника. Revoke access і Confirm revoke знімають доступ лише до цього проєкту; Revoke invitation скасовує запрошення, що очікує.

Admin налаштовує проєкт і може працювати зі зверненнями. Operator використовує робоче місце підтримки. Склад компанії та її власників власник компанії веде в Settings → Members.

Черги, категорії та параметри підтримки

1. Відкрийте Settings → Queues & workflow. У Queues створіть New queue, виберіть Members, задайте Open conversations per operator, за потреби ввімкніть Assign automatically і натисніть Save queue. Нові звернення отримують учасники, у яких відкритий Cluefolk, — спершу найменш завантажені.
2. У Conversation fields додайте поля для команди або, з Ask the player, для форми гравця. Ключ і тип поля після створення не змінюються.
3. У Support settings налаштуйте запит оцінки, Reopen window, days, Retention, days, Reply SLA, business minutes, Time zone і Business hours (без інтервалів — цілодобово).
4. Player messages обмежує кількість повідомлень гравця Per minute і Per hour (типово 6 і 60). Повідомлення понад ліміт відхиляються, а віджет показує, коли гравець зможе написати знову.
5. Conversation categories гравець вибирає за бажанням. Змінюйте назви, порядок кнопками ↑/↓, додавайте категорію з ключем і назвою через + Category або зніміть позначку, щоб вимкнути її. Збережені ключі не змінюються; вимкнені категорії залишаються в наявних зверненнях. Натисніть Save settings.

Гравець має одночасно одне активне звернення: нові повідомлення потрапляють до нього, а вирішене звернення знову відкривається в межах строку повторного відкриття. Збережене представлення Inbox — це фільтр, а не правило автоматичного розподілу.

Оформлення віджета для гравців

1. Відкрийте Settings → Widget. Задайте п’ять базових кольорів для кожної теми: Accent (шапка й повідомлення гравця), Action (кнопки та посилання), Background, Surface (картки й повідомлення команди) і Text. Приглушений текст, рамки й текст на кольорових кнопках обчислюються за контрастом і показані в рядку Derived. У файлі лише кольори та вміст. Логотип — іконка застосунку гри, її бере SDK (див. Logo); щоб побачити її в попередньому перегляді, завантажте Game icon у Settings → General. Потім налаштуйте блоки — привітання, теми, контакт.
2. Кожна тема відкриває чат з однією з категорій звернень цього проєкту. Виберіть її в Category; список береться з Queues & workflow.
3. Перевірте живий попередній перегляд у світлій і темній темі й натисніть Save, щоб зберегти цю версію для команди.
4. Download for build зберігає <ID>_widget.json, де <ID> — перші 16 символів ID проєкту. Розробники додають його до білда гри й передають його текст SDK; гравці побачать зміни лише в наступному білді з новим файлом. Import file завантажує такий файл до редактора.

Мова поруч із Light/Dark перемикає лише попередній перегляд адміністратора. Покупки й Нагороди розділені; у Покупок золота рамка. Show “Talk to the team” button типово вимкнено; кнопку можна ввімкнути перед експортом теми.

Швидкі відповіді

1. У Settings → Quick replies зберігаються швидкі відповіді команди: кожна має назву, мову й текст. Адміністратор додає відповідь кнопкою + над списком, а вибравши відповідь у списку, редагує чи видаляє її; оператор вставляє їх під час підготовки відповіді в Inbox.

{{player.id}}, {{conversation.id}} і {{agent.name}} у тексті підставляються під час вставлення відповіді; {{agent.name}} — ваше ім’я.

Перевірка перед запуском підтримки

1. Вирішіть, хто може звертатися до підтримки, у Players and sign-in. Якщо використовується ігровий сервер, переконайтеся, що підключення підтверджено, а каталог містить потрібні ключі й типи атрибутів.
2. Опублікуйте потрібні подарунки й бейджі, задайте ліміти подарунків, запросіть операторів і перевірте їхню участь у чергах.
3. На тестовому гравці надішліть повідомлення, отримайте публічну відповідь і запитайте подарунок. Перевірте фактичне нарахування в грі, а не лише статус черги.
4. У Server connection перевірте Game events і Notifications. У Test push кнопка Send test запитує push через ігровий сервер для гравця, який увійшов через гру й отримав публічну відповідь підтримки.
5. У Reports робочого місця переглядайте роботу підтримки, зокрема Countries — карту й список країн, у яких Cloudflare побачив гравців на початку звернень. У Settings → Audit — записані зміни. Якщо підтримку готували в окремому проєкті для збірок розробки, так само налаштуйте й перевірте релізний проєкт: налаштування між проєктами не копіюються.

Cluefolk передає запити сповіщень ігровому серверу. Ключі FCM/APNs і робота з токенами пристроїв належать до інтеграції гри, а не до браузера оператора.

Початок зміни

1. Увійдіть на cluefolk.com. Угорі лівої панелі написано, з якою грою ви працюєте. Якщо гра не та, натисніть change поруч із назвою й виберіть потрібну.
2. Відкрийте Inbox. Ліворуч — список звернень, посередині — відкрите звернення, праворуч — картка гравця.
3. Не закривайте вкладку Cluefolk під час роботи. Якщо адміністратор увімкнув автоматичний розподіл, нові звернення отримують ті, у кого Cluefolk відкритий, — спочатку найменш завантажені.

Фільтр статусів дозволяє кілька варіантів. All active виключає Resolved; увімкніть Resolved для перегляду історії. Початкова черга — New unanswered, без автоматично відкритого діалогу. × закриває лише перегляд і зберігає чернетку.

Як знайти звернення

1. Статуси: New — публічної відповіді оператора ще немає; In progress — перша відповідь закріпила діалог за оператором; Needs a reply і Waiting for player встановлюються вручну; Awaiting confirmation — чекаємо рішення гравця; Resolved — історія лише для читання.
2. Фільтр статусів дозволяє кілька варіантів. All active виключає Resolved; увімкніть Resolved для перегляду історії. Початкова черга — New unanswered, без автоматично відкритого діалогу. × закриває лише перегляд і зберігає чернетку.
3. Для пошуку введіть ID гравця, слово з листування, версію гри чи системи телефона, наприклад 2.4 або iOS 17. ⌘K (Mac) або Ctrl K (Windows) одразу переводить курсор у пошук.
4. Filters змінює порядок (наприклад, Newest first — спочатку нові) і звужує список за оператором, категорією, пріоритетом чи тегом. У розділі Players — за тим, хто гравець: натисніть + Condition і виберіть бейдж або ігрові дані, наприклад Level At least 10 чи ★ VIP Has. Активні фільтри видно плашками під пошуком, × прибирає фільтр. Щоб зберегти набір фільтрів, введіть назву в Save as a view… — вигляд з’явиться в лівій панелі в розділі Views.

Ім’я з іконкою людини на зверненні — це його оператор. Немає імені — звернення вільне.

Відповідь гравцеві

1. Відкрийте звернення без оператора й прочитайте його. Картка гравця праворуч показує, хто це (див. «Перевірка гравця»).
2. Перевірте, що над полем введення вибрано вкладку Reply, і напишіть відповідь. Щоб вставити готову відповідь, відкрийте Quick reply і виберіть шаблон.
3. Натисніть Enter або Send reply. Shift+Enter — новий рядок.
4. Перша публічна відповідь закріплює звернення за вами й встановлює In progress. Наступні відповіді зберігають вибраний вручну робочий статус.

Оператор бачить свої звернення та нові непризначені звернення без відповіді. Чужий діалог може переглядати лише admin або owner. Для відповіді та приватної нотатки потрібно забрати діалог собі; також можна передати його іншому оператору.

Передати звернення колезі

1. Відкрийте своє звернення.
2. Угорі відкрийте Operator і виберіть колегу. Люди з позначкою Owner або Admin теж можуть відповідати гравцям.
3. Тепер гравцеві відповідає лише колега. Ви й далі можете писати особисті нотатки.
4. Щоб повернути звернення всій команді, виберіть Unassigned.

Власники й адміністратори можуть забрати будь-яке звернення, вибравши You в Operator. Оператор не може забрати чуже звернення: попросіть колегу або адміністратора передати його вам.

Написати команді (особиста нотатка)

1. Над полем введення виберіть Private note. Поле стане жовтим: гравець цього тексту не побачить.
2. Щоб покликати колегу, виберіть його в Mention. Він знайде нотатку в розділі Mentioned me.
3. Натисніть Enter або Add note.

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

Перевірка гравця

1. Картка гравця — праворуч. На вузькому екрані натисніть іконку людини вгорі звернення.
2. ✓ Verified player — гра підтвердила акаунт. Anonymous — гравець написав, не входячи в акаунт, і показаний як Guest з коротким кодом. Player ID (not verified) — гравець ввів ID сам; не покладайтеся на нього в питаннях акаунта.
3. У блоці Player — платформа, версія системи, пристрій, версія та білд гри, мова й країна.
4. Conversations — усі звернення гравця, нові згори. Натисніть на звернення, щоб відкрити його.
5. Game attributes — дані з гри, наприклад рівень або покупки. Порожнє чи старе значення не означає нуль.
6. Натисніть на будь-яке значення в картці, наприклад на ID гравця, щоб скопіювати його — скажімо, для пошуку гравця в інших системах. З’явиться Copied.

Позначити гравця бейджем

1. У картці гравця натисніть + Badge і виберіть бейдж. Він з’явиться одразу.
2. Щоб прибрати бейдж, натисніть хрестик на ньому.

Бейджі без хрестика ставляться автоматично за даними гри, вручну їх не змінити. Якщо потрібного бейджа немає в списку, зверніться до адміністратора.

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

1. Подарунки доступні лише гравцям, які увійшли через гру (✓ Verified player). У зверненні натисніть Send a gift під полем введення.
2. Виберіть подарунок, напишіть причину для команди (наприклад, «зникла покупка, замовлення 123») і натисніть Confirm and send gift.
3. Якщо з’явилося Sent for approval, подарунок спершу схвалює адміністратор. Рішення з’явиться на вкладці Gifts у картці гравця.
4. На вкладці Gifts видно, чи прийняв ігровий сервер подарунок. Після цього гравець побачить подарунок у чаті; коли він з’явиться в самій грі, вирішує гра.

Не надсилайте подарунок повторно, якщо він іде довго: це буде другий подарунок. Якщо статус Unknown, натисніть Check delivery again; якщо не допомогло, повідомте адміністратора.

Багато гравців з однією проблемою

1. Коли багато гравців пишуть про одну проблему (наприклад, не відкривається магазин), зберіть їхні звернення в інцидент. Відкрийте Incidents, натисніть + Create an incident, введіть Incident title і Automatic acknowledgement — повідомлення, яке гравці отримають одразу, — і натисніть Create incident.
2. Щоб додати звернення, відкрийте його, натисніть + Add to incident, виберіть інцидент і натисніть Add. Для нової проблеми виберіть New incident…, опишіть її й натисніть Create and add. Щоб додати кілька одразу, позначте їх у списку звернень і виберіть інцидент в Add to incident….
3. Гравці, яким ще не відповідали, одразу отримують автоматичне повідомлення.
4. Щоб написати їм усім, відкрийте інцидент і скористайтеся Message affected players.
5. Адміністратор надсилає розсилку лише в активні звернення. Завершення інциденту запитує підтвердження кожного гравця. Відмова залишає його діалог активним. Якщо активних звернень немає, форми розсилки немає. Delete incident потребує підтвердження та зберігає історію розмов.

Адміністратор надсилає розсилку лише в активні звернення. Завершення інциденту запитує підтвердження кожного гравця. Відмова залишає його діалог активним. Якщо активних звернень немає, форми розсилки немає. Delete incident потребує підтвердження та зберігає історію розмов.

Завершити звернення

1. Коли питання вирішено, натисніть окрему кнопку Resolved. Гравець отримає запит підтвердження рішення.
2. За згоди гравець ставить оцінку або пропускає її. Діалог зберігається в історії лише для читання; наступне повідомлення починає нову розмову.
3. Відмова продовжує той самий діалог зі статусом Needs a reply та фіксує невдалу спробу за оператором, який запропонував завершення. Без відповіді через 24 години діалог завершується з окремим результатом timeout. Нове повідомлення до підтвердження скасовує запит.

Фільтр статусів дозволяє кілька варіантів. All active виключає Resolved; увімкніть Resolved для перегляду історії. Початкова черга — New unanswered, без автоматично відкритого діалогу. × закриває лише перегляд і зберігає чернетку.

Заблокувати гравця-порушника

1. У картці гравця натисніть Ban player, за бажання вкажіть причину й підтвердьте кнопкою Ban player.
2. Гравець більше не зможе писати в підтримку цієї гри. Його звернення збережуться.
3. Щоб розблокувати, натисніть Unban player.

Вивантажити або видалити дані гравця

1. Власники й адміністратори: відкрийте Players, виберіть гравця й розгорніть Privacy.
2. Export player data готує файл. Коли в запиту з’явиться completed, натисніть Download JSON.
3. Щоб видалити дані, введіть ID, який просить сторінка (ID гравця в грі або Cluefolk ID для анонімного гравця), і натисніть Erase player data.

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

Проєкт, авторизація та життєвий цикл SDK

1. Використовуйте точний ID проєкту — його показано в Settings → General (Copy копіює його; ID постачається в грі й не є секретом) і в конфігурації сервера. Якщо у вас окремий проєкт для збірок розробки, ці збірки використовують його ID, а релізні — ID релізного проєкту. Віджет вбудовано в SDK, тому обов’язковий лише ID проєкту; API за замовчуванням — https://cluefolk.com. У шапці віджета показано іконку застосунку гри; щоб узяти інше зображення, передайте ім’я ресурсу (logoResource на Android, logoImageName на iOS, LogoResource в Unity).
2. Ініціалізуйте SDK один раз і дочекайтеся готовності. Після цього підтримка працює без входу: гравець анонімний, його розпізнають за секретом встановлення в захищеному сховищі пристрою.
3. Додайте файл <ID>_widget.json із Settings → Widget → Download for build до білда, завантажте його конструктором теми (Appearance.Builder(json).build()) і передайте в setAppearance (Unity: SetAppearance) після готовності SDK і до першого відкриття. Той самий конструктор без файлу задає кольори, тексти й поворот екрана кодом. Без цього віджет показує оформлення за замовчуванням: сервер його не надсилає.
4. Вхід необов’язковий. Після входу гравця в гру backend підписує короткочасний (не довше 5 хвилин) одноразовий ES256 cluefolk-identity+jwt: sub — ігровий ID, iss і aud збігаються з Players and sign-in. Передайте його в loginWithIdentity; анонімна історія цього встановлення перейде до облікового запису.
5. Provider identity-токенів необов’язковий: якщо його задано, SDK запитує свіжий токен в уже авторизованого backend щоразу, коли потрібна нова сесія (сесія діє 30 днів і подовжується під час використання). Якщо токен не отримано, підтримка залишається доступною анонімно, а callback помилок отримує IDENTITY_UNAVAILABLE. Якщо проєкт вимагає вхід, анонімна сесія завершується помилкою IDENTITY_REQUIRED.
6. open відкриває головний екран підтримки. openConversation з порожнім ID відкриває поточний чат гравця; перше повідомлення в ньому починає звернення. Оновлюйте ігровий індикатор через callback непрочитаних.
7. Під час виходу або зміни ігрового облікового запису викликайте logout; close лише закриває вікно підтримки.

gameApi, identityToken, recentLogText, supportListener, Activity та view controller у прикладах надає сама гра; це не додаткові методи Cluefolk. SDK відкриті за ліцензією MIT: Android — у Maven Central, iOS — через Swift Package Manager або XCFramework, Unity — за Git URL (github.com/cluefolk).

Android · Kotlin та Java

1. Мінімум — Android 7.0 (API 24), compileSdk 34 або новіший, Android Gradle Plugin 7.4 або новіший і AndroidX. Додайте com.cluefolk:android-sdk з Maven Central (нижче): він підключить AndroidX Activity, Core і WebKit та свої правила R8.
2. Реалізуйте Cluefolk.EventListener і призначте його до ініціалізації. Серед callback: onCluefolkReady, onCluefolkUnreadChanged(count), onCluefolkIdentityTokenRequired(requestId) і onCluefolkError(code). Ініціалізуйте SDK на UI thread з Application context.
3. Після onCluefolkReady або коли isReady() поверне true, кнопка підтримки може викликати open(activity) для анонімного гравця. Якщо гравець увійшов у гру, передайте токен із відповіді ігрового входу в loginWithIdentity; помилка підтримки не має ламати вхід у гру.
4. Ініціалізація асинхронно завантажує локальні credentials. Інші публічні методи можна викликати з будь-якого потоку; callbacks надходять у main looper. Підключіть отримання push і обробку натискання за інструкцією нижче.

dependencies {
    implementation("com.cluefolk:android-sdk:0.3.2")
}

import com.cluefolk.sdk.Cluefolk

Cluefolk.setEventListener(supportListener)
Cluefolk.initialize(application, Cluefolk.Options(projectId = "YOUR_PROJECT_ID"))
// Optional: only if your game issues Cluefolk identity tokens.
Cluefolk.setIdentityTokenProvider { callback ->
    gameApi.fetchCluefolkIdentity { token, error ->
        callback.complete(token, error)
    }
}

// After onCluefolkReady(); works without sign-in (anonymous player):
Cluefolk.open(activity)
Cluefolk.openConversation(activity, "") // the player's current chat

// Optional, after successful game login:
Cluefolk.loginWithIdentity(identityToken) { error ->
    // Do not fail game login because of support.
}
Cluefolk.setConversationContext("""{"screen":"settings"}""")

// Game account sign-out:
Cluefolk.logout()

Вихідний код, список змін і релізи: github.com/cluefolk/android-sdk (ліцензія MIT).

iOS · Swift та Objective-C

1. Мінімум — iOS 15. У Xcode виберіть File → Add Package Dependencies…, введіть https://github.com/cluefolk/ios-sdk і додайте бібліотеку Cluefolk до target застосунку. Без Swift Package Manager додайте Cluefolk.xcframework з релізів репозиторію з Embed & Sign.
2. Зберігайте сильне посилання на об’єкт CluefolkEventListener: властивість listener у SDK — weak. Призначте listener і викличте initialize; provider identity-токенів необов’язковий.
3. Усі публічні виклики виконуйте на MainActor. Ініціалізація повертає керування, поки credentials читаються у фоні; перед відкриттям підтримки або входом дочекайтеся onCluefolkReady() або isReady.
4. Потім кнопка підтримки може викликати open(from:) з актуальним view controller; гравець залишається анонімним, доки не виконано loginWithIdentity. Callback onCluefolkUnreadChanged оновлює індикатор непрочитаних.
5. Для Objective-C/Objective-C++ імпортуйте Cluefolk/Cluefolk-Swift.h; доступні імена CLFCluefolk, CLFOptions і CLFEventListener. Події сповіщень передавайте на MainActor.

.package(url: "https://github.com/cluefolk/ios-sdk", from: "0.3.2")

import Cluefolk

// MainActor; retain supportListener in your app.
let sdk = Cluefolk.shared
sdk.eventListener = supportListener
try sdk.initialize(CluefolkOptions(projectId: "YOUR_PROJECT_ID"))
// Optional: only if your game issues Cluefolk identity tokens.
sdk.setIdentityTokenProvider { completion in
    gameApi.fetchCluefolkIdentity { token, error in
        completion(token, error)
    }
}

// After onCluefolkReady(); works without sign-in (anonymous player):
sdk.open(from: presentingViewController)
sdk.openConversation("", from: presentingViewController) // current chat

// Optional, after successful game login:
sdk.loginWithIdentity(identityToken) { error in
    // Do not fail game login because of support.
}
do {
    try sdk.setConversationContext(["screen": "settings"])
} catch {
    // Report a support configuration error to the app.
}

// Game account sign-out:
sdk.logout()

У релізних збірках використовуються довірені HTTPS-адреси. Вихідний код, список змін і релізи: github.com/cluefolk/ios-sdk (ліцензія MIT).

Unity 2022.3 LTS і новіші

1. У Window → Package Manager виберіть + → Add package from git URL… і введіть https://github.com/cluefolk/unity-sdk.git#0.3.2 або додайте рядок нижче до Packages/manifest.json.
2. У Player Settings задайте для Android Minimum API Level 24 і Target API Level 34 або вище, для iOS Target minimum iOS Version 15.0 або вище. Якщо значення нижчі, збірка зупиниться з повідомленням.
3. Налаштовувати Gradle і Xcode не потрібно: Android-збірка підключає com.cluefolk:android-sdk тієї ж версії з Maven Central і вмикає AndroidX, iOS-збірка підключає та вбудовує Cluefolk.xcframework з пакета.
4. Викликайте фасад із Unity main thread. Підпишіться на Cluefolk.Event, потім ініціалізуйте SDK. Подія ready встановлює Cluefolk.IsReady; після цього Open() працює для анонімного гравця, а LoginWithIdentityAsync за потреби прив’язує ігровий обліковий запис.
5. SetIdentityTokenProvider необов’язковий. Якщо provider кидає виняток або повертає порожній токен, гравець залишається анонімним, а Event повідомляє error з кодом IDENTITY_UNAVAILABLE. Для індикатора використовуйте поле count події unreadChanged; під час знищення власника зніміть обробник.
6. Методи фасаду одразу перевіряють аргументи й кидають ArgumentException. Перевіряйте збірки Android/iOS Player: в Editor і на desktop WebView підтримки не відкривається, а компіляція C# не перевіряє пристрій або IL2CPP.

"com.cluefolk.sdk": "https://github.com/cluefolk/unity-sdk.git#0.3.2"

using CluefolkSDK;

Cluefolk.Event += OnCluefolkEvent;
Cluefolk.Initialize(new CluefolkOptions { ProjectId = "YOUR_PROJECT_ID" });
// Optional: only if your game issues Cluefolk identity tokens.
Cluefolk.SetIdentityTokenProvider(
    () => GameApi.GetFreshCluefolkIdentityAsync());

// After Event("ready", ...); works without sign-in:
Cluefolk.Open();
Cluefolk.OpenConversation(); // the player's current chat

// Optional, after successful game login:
try {
    await Cluefolk.LoginWithIdentityAsync(identityToken);
} catch (Exception error) {
    // Surface support failure without failing game login.
    Debug.LogWarning(error.GetType().Name);
}
Cluefolk.SetConversationContext(
    new Dictionary<string, object> { ["screen"] = "settings" });

// Game account sign-out:
Cluefolk.Logout();

Пакет Unity викликає нативні SDK; власної реалізації WebView, HTTP чи сесій у ньому немає. Вихідний код і релізи: github.com/cluefolk/unity-sdk (ліцензія MIT).

Push через ігровий сервер

1. Єдиний маршрут: публічна відповідь підтримки → черга Cluefolk → /cluefolk/push ігрового backend → наявний push-провайдер гри → пристрій. Device tokens, дозволи ОС і ключі Firebase/APNs залишаються у гри.
2. Налаштуйте й перевірте Settings → Server connection. Обробник гри перевіряє командний JWT ES256 за JWKS URL, його призначення, проєкт, строк і action: push.notify, усуває дублікати за eventId і зберігає push job до підтвердження.
3. Передайте підписані поля push.data до мобільного сповіщення без змін. Android отримує їх у data, iOS — в userInfo на верхньому рівні поряд з aps. playerId — внутрішній UUID Cluefolk, а не ігровий ID.
4. Сповіщення запитуються лише для гравців, які ввійшли через гру: гра знаходить пристрої за власним ID гравця. Передавайте отримання й натискання у виклики платформ нижче; натискання відкриває потрібне звернення лише для налаштованого проєкту й авторизованого гравця.
5. У Server connection → Test push укажіть ігровий Player ID гравця з публічною відповіддю підтримки й натисніть Send test. Перевірте Notifications, потім сам пристрій. Приймається не більше п’яти тестів за хвилину.

{
  "origin": "cluefolk",
  "projectId": "YOUR_PROJECT_ID",
  "playerId": "CLUEFOLK_PLAYER_UUID",
  "conversationId": "CONVERSATION_UUID",
  "messageId": "MESSAGE_UUID",
  "status": "open",
  "count": "1"
}

// Android: receive / notification tap
Cluefolk.handlePush(data)
Cluefolk.openFromPush(activity, data)

// iOS: receive / notification tap, on MainActor
Cluefolk.shared.handlePush(userInfo)
Cluefolk.shared.openFromPush(userInfo, from: controller)

// Unity: receive / notification tap
Cluefolk.HandlePush(data);
Cluefolk.HandlePush(data, opened: true);

Accepted підтверджує, що ігровий backend зберіг подію. Це не підтвердження показу банера ОС чи прочитання відповіді.

Перевірка всієї інтеграції

1. Відкрийте підтримку без входу, надішліть повідомлення й перевірте, що оператор бачить анонімного гравця з даними пристрою та застосунку. Потім увійдіть через гру на тому самому встановленні й переконайтеся, що звернення перейшло до підтвердженого ігрового ID.
2. Надішліть публічну відповідь оператора, потім перезапустіть гру: історія та непрочитані вже мають бути в стані SDK. Відкрийте відповідь і перевірте зміни непрочитаних і Read; приватні нотатки гравцеві не показуються.
3. Підключіть backend, оновіть типізований каталог і перевірте автоматичний бейдж на відомих даних. Окремо перевірте ручний бейдж оператора, опублікований подарунок, прийнятий ігровим сервером, і подарунок, що потребує підтвердження.
4. Перевірте push в активній грі, у фоні та під час холодного запуску. Перевірте розділення проєктів (сповіщення з іншого проєкту, наприклад для збірок розробки, не відкриває звернення) і змініть гравця перед відкриттям старого сповіщення.
5. Перевірте offline/retry, вихід і повторний вхід, вкладення-зображення, помилки завеликих зображень, ліміт повідомлень за хвилину та, якщо ввімкнено, обов’язковий вхід. Перевіряйте реальні Android/iOS Player, зокрема Unity toolchain, які використовуєте.

Успішна збірка чи підтвердження сервера — лише частина перевірки. Зафіксуйте пристрій, ОС, версії SDK/адаптера та результат повного сценарію.