Интеграция SDK: Construct 3 — документация SpyMagic

Описание

Интеграция SDK

Unity Defold Construct 3 JS

доступ через API

События

a/b тесты Платежи Реклама Игроки Ресурсы Прогресс игрока

Внешние данные

Construct 3 плагин

Официальный плагин SpyMagic для Construct 3 (Addon SDK v2). Ставится через Addon manager как обычный .c3addon, настраивается в свойствах объекта, все события отправляются действиями из event sheet — без кода. Внутри та же механика, что и у остальных SDK: офлайн-очередь, батчи, повторы при обрывах связи.

Требования Установка Настройка Как это работает Идентификация игрока Действия, условия, выражения Пример event sheet Веб-порталы Диагностика FAQ

Требования

параметр	значение
Construct 3	r400 и новее (Addon SDK v2)
Режим рантайма	Worker (по умолчанию) и DOM. В worker-режиме недоступны только `focus_lost` / `focus_gain` и адрес страницы
Экспорт	Web (HTML5), Cordova / Android / iOS, NW.js, WebView2
Зависимости	нет

Установка

spymagic-construct-1.0.0.c3addon

Скачайте файл аддона.

В Construct 3: Menu → View → Addon manager → Install new addon..., выберите файл и перезапустите редактор.

Добавьте объект SpyMagic Analytics в любой layout (объект глобальный, один на проект). Он появится в разделе Web окна Insert new object.

Для разработки самого плагина: включите Developer mode в настройках Construct и подключите папку аддона через Addon manager → Add dev addon с локального веб-сервера. Исходники лежат в zip-архиве.

Настройка

Выделите объект SpyMagic Analytics и заполните свойства в Properties Bar:

свойство	по умолчанию	описание
Token	—	ключ проекта. Виден администратору компании в Настройки → Игры, кнопка «показать»
Endpoint	https://spymagic.pro/track/	адрес трекера
Platform	Auto	platform_id из таблицы платформ. Auto: Cordova на Android → Google Play (2), на iOS → Apple Store (5), иначе www (1). Для веб-порталов используйте действие Set platform
Game version	1.0.0	версия сборки, уходит в init / auth
Batch interval	30	раз в сколько секунд отправлять очередь. 0 — каждое событие отдельно
Max batch size	30	отправить сразу при накоплении стольких событий (10, пока сессия молодая)
Max queue size	200	предел офлайн-очереди
Auto init	вкл	инициализация при создании объекта. Выключите, чтобы вызывать действие Initialize самим
Auto send init	вкл	слать `init` при инициализации
Track focus	вкл	`focus_lost` / `focus_gain` по `visibilitychange` (только DOM-режим)
Debug log	выкл	диагностика в консоль браузера

Как это работает

uuid. Определяется один раз и хранится в Construct storage (IndexedDB, работает и в worker). Если страница уже содержит наш JS-сниппет с window.spymagic.uuid или localStorage.uuid, берётся он.

Очередь и батчи. Каждое действие кладёт событие в очередь с порядковым sid и unix-временем. Очередь уходит одним POST каждые Batch interval секунд, при достижении Max batch size, при действиях Flush, Purchase, Logout и при скрытии вкладки.

Повторы. 2xx — доставлено, срабатывает On send success. Статус 0 (нет сети, adblock) или 5xx — события возвращаются в голову очереди, срабатывает On send error. 4xx — батч выбрасывается.

Персист. Неотправленное сохраняется раз в 2 секунды и переживает перезапуск игры.

Идентификация игрока

действие	когда вызывать
Register (User ID, User name)	один раз в жизни игрока — аккаунт только что создан. Считается установкой
Auth (User ID)	каждый последующий запуск. Плагин добавит платформу, версию, язык, устройство, install_id
Logout	выход из аккаунта, очередь отправляется сразу
Set user property (Key, Value)	`name`, `mail`, `password`, `gender`, `sound`, `music` — см. Игроки
Set user ID	если id известен без Register/Auth

User ID — целое число. Если аккаунты в игре без числового id, заведите его на своём сервере или используйте int(...) от числовой части.

Действия, условия, выражения

действие	событие	параметры
Session & player
Initialize / Send init	init	вручную, если выключены Auto init / Auto send init
Register / Auth / Logout / Set user ID / Set user property	register, auth, logout, user_set	см. выше
Flush	—	отправить очередь сейчас
Events
Set event parameter (Key, Value) → Track event (Name)	любое	параметры накапливаются и уходят со следующим Track event
Track event (JSON) (Name, JSON)	любое	detail строкой JSON, например `"{""boss_id"": 7}"`
Track event now	любое	немедленно, минуя очередь
Loading step (Step)	loading	этап загрузки 1..N
Hit (Scene)	hit	смена layout / экрана, уникальное имя
Click (X, Y, Scene)	click	тепловые карты
Error (Text)	error	клиентская ошибка
Progress & A/B — описание
Level up (Level)	levelup
Tutorial step (Step), Tutorial complete	tutorial, tutorial_complete
Story point (Step)	story_point
Level result / Battle result	level_result, battle_result	Result (Defeat/Draw/Victory), Level, Time s, Location, Power, Auto, Surrender
Experiment (Experiment ID, Group ID)	experiment	эксперимент заранее заведён в разделе
Economy — платежи, ресурсы
Set resource (Key, Amount) → Send resources	resource	срез ресурсов на руках
Purchase init / Purchase	purchase_init, purchase	Offer code, Currency (RUB, USD, VK, YAN), Price. Purchase — только после подтверждения стора
Purchase method (Method, Offer code)	purchase_method	свой эквайринг
Purchase error (Error, Transaction)	purchase_error
Virtual purchase	virtual_purchase	Offer ID, Rewards JSON, Currency name, Currency code, Amount
Ads — описание
Rewarded requested / received / error (Placement)	rewarded_init, rewarded_received, rewarded_error
Settings
Set platform (Platform ID)	—	смена platform_id в рантайме
Set enabled (Enabled/Disabled)	—	жёсткий выключатель для тестовых сборок
Set batch interval (Seconds)	—

условие	описание
Is initialized	SDK готов (uuid и очередь загружены)
Is enabled	отправка не выключена
On send success	триггер: батч доставлен
On send error	триггер: батч не доставлен, см. LastStatus / LastError

выражение	описание
`SpyMagic.UUID`	uuid устройства/игрока
`SpyMagic.UserID`	текущий user_id (0 — аноним)
`SpyMagic.Platform`	platform_id
`SpyMagic.QueueLength`	событий в очереди
`SpyMagic.SID`	счётчик действий сессии
`SpyMagic.LastStatus`, `SpyMagic.LastError`	результат последнего батча
`SpyMagic.SDKVersion`	версия плагина

Пример event sheet

System: On start of layout
    → SpyMagic: Loading step 1
    → SpyMagic: Hit scene "lobby"

AJAX: On "login" completed
    LocalStorage: Key "registered" not exists
        → SpyMagic: Register player int(AJAX.LastData) named "Player"
        → LocalStorage: Set item "registered" to 1
    Else
        → SpyMagic: Auth player int(AJAX.LastData)

System: On level finished
    → SpyMagic: Level result: Victory, level LevelNumber, time round(LevelTime) s
    → SpyMagic: Set resource "gold" = Gold
    → SpyMagic: Send resources snapshot

Touch: On any touch end
    → SpyMagic: Click at (Touch.X, Touch.Y) on LayoutName

Button "Buy": On clicked          → SpyMagic: Purchase init "BATTLE_PASS_1" for 899 RUB
Store: On purchase success         → SpyMagic: Purchase "BATTLE_PASS_1" for 899 RUB

Boss: On unlocked
    → SpyMagic: Set event parameter "boss_id" = Boss.ID
    → SpyMagic: Set event parameter "attempts" = Attempts
    → SpyMagic: Track event "boss_unlocked"

SpyMagic: On send error
    → Browser: Log SpyMagic.LastStatus & " " & SpyMagic.LastError

Веб-порталы

Платформа. Один веб-экспорт может стоять на Яндекс.Играх, VK, CrazyGames, Poki. Определите портал (по домену через Browser.URL или по SDK площадки) и вызовите Set platform с нужным id в On start of layout первого layout.

init со страницы. Если хотите измерять честную скорость загрузки, в экспортированный index.html перед загрузчиком Construct можно вставить наш JS-сниппет (тот же, что для Unity): он отправит init до старта рантайма и передаст uuid плагину. Плагин увидит флаг window.spymagic.init_sent и второй init не пошлёт.

Adblock режет запросы к трекерам. События лягут в очередь и уйдут при следующем удачном флаше; после превышения Max queue size старые отбрасываются.

Диагностика

Включите Debug log — в консоли браузера (F12) появятся отправленные батчи, ошибки HTTP и выброшенные события.

Триггер On send error плюс выражения LastStatus / LastError позволяют показать проблему прямо в игре при отладке.

Доехавшие события смотрите в разделе События проекта — батч уходит не позже чем через Batch interval секунд, либо вызовите Flush.

FAQ

Нужно ли добавлять объект на каждый layout?	Нет, объект глобальный: один раз на любом layout, дальше доступен во всех event sheet.
Как передать вложенные параметры?	Действием Track event (JSON): строкой JSON, кавычки внутри выражения Construct удваиваются — `"{""items"": [1, 2, 3]}"`. Либо соберите строку объектом JSON и передайте `JSON.ToCompactString`.
Не вижу focus_lost / focus_gain	Рантайм работает в worker-режиме, там документ недоступен. Переключите Project properties → Advanced → Use worker = No, либо считайте эти события необязательными.
Как не слать данные из превью?	В On start of layout: если `Browser.URL` содержит `preview.construct.net` — действие Set enabled: Disabled. Либо отдельный проект в аналитике с другим токеном.
Сервер ответил 401	Неверный токен или проект удалён. Проверьте свойство Token — ключ целиком, с префиксом до точки.