Руководство 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/адаптера и результат полного сценария.