Руководство по интеграции

Установите без ошибок — вы или ваш ИИ-агент.

Всё, что делает AppKit, где что появляется, и готовый prompt, который можно вставить в вашего ассистента по коду. Что не умеете сами — агент сделает за вас.

Prompt для ИИ Установка Где появляется Пустые экраны Завершение шагов Гарантии Частые ошибки

01Prompt для вашего ИИ-агента

Вставьте текст ниже в вашего ассистента по коду, замените MINHA_CHAVE_PK_LIVE на ключ из панели — и он сделает всю интеграцию: установку, пустые экраны и завершение шагов, не сломав ваш продукт.

Claude Code Antigravity OpenAI / Codex Cursor, Copilot…

prompt-appkit.txt

Ты мой ассистент по коду. Интегрируй AppKit (appkit.com.br) в мой веб-продукт, НИЧЕГО не сломав. AppKit внедряет онбординговый checklist, пустые экраны и объявления, управляемые из внешней панели. Сделай ровно следующее:

1) УСТАНОВКА
- Если проект использует бандлер (React/Vue/Next/Svelte и т.п.): установи пакет
  @tecaless/appkit-sdk
  и в точке входа, ПОСЛЕ логина пользователя (когда его id уже у меня есть), вызови:
  import { init } from '@tecaless/appkit-sdk'
  init({ apiKey: 'MINHA_CHAVE_PK_LIVE', userId: <стабильный id залогиненного пользователя> })
- Если это статический сайт / no-code: добавь ПЕРЕД :
  
- userId/data-user ДОЛЖЕН быть стабильным идентификатором залогиненного пользователя. AppKit хеширует его на сервере — НИКОГДА не отправляй email или имя. Если залогиненного пользователя нет, оставь без userId.

2) ПУСТЫЕ ЭКРАНЫ
Для каждого экрана, который появляется без данных и где мне нужен призыв к действию (например, счета, контакты, календарь), оберни текущее пустое состояние в ОДИН помеченный контейнер, оставив текущее содержимое внутри как fallback:
   ...текущее «записей нет»... 
Используй короткое стабильное имя для каждого экрана (например, faturas-vazio, contatos-vazio). НЕ используй CSS-селектор, сгенерированный сборкой. Верни мне список созданных имён.

3) ЗАВЕРШЕНИЕ ШАГОВ (важно для настоящих метрик)
Для каждого шага онбординга, который означает НАСТОЯЩЕЕ ДЕЙСТВИЕ пользователя (например, «выставить первый счёт»), вызывай ровно в тот момент, когда действие действительно свершилось — после сохранения на сервере, а не по клику на кнопку:
  window.AppKit && window.AppKit.track('fatura_emitida')
Используй одно имя события на действие, в snake_case. Верни мне список созданных событий.

4) НИЧЕГО НЕ СЛОМАТЬ
- Загружай SDK асинхронно; он fail-open (если упадёт, сам исчезнет и не затронет мой продукт).
- Ключ pk_live публичный по своей природе (может находиться на клиенте). Не раскрывай никакие секретные ключи.
- Не блокируй рендеринг в ожидании AppKit.

В конце перечисли: (а) изменённые файлы, (б) созданные имена data-appkit, (в) созданные имена событий — чтобы я настроил их в панели AppKit.

Когда агент закончит, используйте возвращённые им имена data-appkit и имена событий, чтобы настроить пустые экраны и завершение шагов в панели.

02Установка

Два способа. Если вы используете фреймворк, начните с npm.

С бандлером (React, Vue, Next, Svelte…) — рекомендуется

terminal

npm i @tecaless/appkit-sdk

app.js — после логина

import { init, track } from '@tecaless/appkit-sdk'

init({ apiKey: 'MINHA_CHAVE_PK_LIVE', userId: usuario.id })
// когда происходит настоящее действие:
track('fatura_emitida')

No-code / статический сайт — одна строка

перед </body>

<script src="https://appkit.com.br/sdk/appkit@3.0.7.js"
        data-key="MINHA_CHAVE_PK_LIVE"
        data-user="ID_DO_USUARIO" async></script>

Ваш ключ pk_live_… находится в панели, в разделе Установка. Он публичный по природе (позволяет только читать вашу конфигурацию и отправлять события).

03Где что появляется

Все три сценария работают на любой странице вашего продукта, в пределах домена, где вы его установили. Вы управляете всем из панели, без нового деплоя.

Checklist

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

Объявление

Полоса сверху, которая сдвигает контент вниз (не перекрывает его). Может содержать ссылку. Вы публикуете и снимаете её когда угодно.

Пустой экран

Там, где ваш продукт пишет «записей нет» — без вашего участия в коде (агент всё сделает). Превращается в призыв к действию.

04Пустые экраны: вам не нужно трогать код

Магия пустого экрана в том, что ничего объявлять не нужно. Нажмите Скопировать prompt — и ваш ИИ-агент возьмёт на себя техническую часть: укажет на элемент, который уже есть в вашей системе (через селектор, не трогая HTML), или при необходимости добавит стабильную метку — AppKit принимает оба варианта. Дальше вы просто редактируете текст из панели, навсегда, без деплоя.

Пользователь нажал «Скопировать prompt» в функции ПУСТЫЕ ЭКРАНЫ AppKit (appkit.com.br). Он хочет, чтобы экран его продукта, который появляется без данных, стал призывом к действию — БЕЗ ручной правки кода. Сделай:

ПРЕДУСЛОВИЕ — AppKit должен быть установлен. Если ещё нет, сначала установи:
  npm i @tecaless/appkit-sdk
  import { init } from '@tecaless/appkit-sdk'; init({ apiKey: 'MINHA_CHAVE_PK_LIVE', userId:  })
  (или, no-code:  перед )

ПУСТОЙ ЭКРАН — найди в коде экран, который появляется пустым (например, список счетов/контактов), и выбери, КАК AppKit там закрепится (принимаются оба способа):
  (а) укажи на УЖЕ СУЩЕСТВУЮЩИЙ элемент через стабильный CSS-селектор (id или семантический класс) — не трогая HTML; или
  (б) если есть только сгенерированный сборкой класс, оберни пустое состояние в …текущее содержимое….
Верни мне селектор/имя каждого пустого экрана (например, "#faturas-vazio" или "faturas-vazio"), чтобы я вставил его в панель → Пустые экраны.

ДОСТУПНЫЕ ФУНКЦИИ AppKit (включай каждую в панели https://appkit.com.br/painel): checklist первых шагов, пустые экраны, объявления сверху и завершение шагов по событию (вызывай window.AppKit.track('acao_real') в момент настоящего действия). Полное руководство: https://appkit.com.br/guia

НИЧЕГО не ломай: загружай async, SDK — fail-open, а ключ pk_live публичный (не раскрывай секретные ключи). В конце перечисли изменённые файлы и созданные селекторы/имена.

Если якорь однажды исчезнет, AppKit предупредит вас (событие appkit_anchor_missing) и ничего не отрисует — ваш экран останется прежним.

05Как завершается шаг

Три режима, выбираются для каждого шага в панели. Это решает, измеряет ли ваша воронка активации настоящее действие или просто клики.

правда

По событию

Ваш код вызывает AppKit.track('acao') в момент настоящего действия. Это нельзя подделать — именно это годится как метрика трекшена.

proxy

По маршруту

Пользователь попадает на маршрут (например, /faturas/nova). Настоящий сигнал, но «дойти» — не значит «сделать».

необязательный

Вручную

Пользователь кликает по пункту, чтобы отметить его. Подходит для информационных шагов («прочитайте это»). Подделывается — намеренно.

Чтобы ваша аналитика трекшена чего-то стоила, важные шаги должны быть по событию. Если они ручные, вы измеряете «пользователь нажал завершить», а не «пользователь сделал».

06Гарантии

Fail-open: если AppKit упадёт, виджет исчезнет, а ваш продукт останется прежним. Ни одна наша ошибка не попадёт в вашу консоль.
Лёгкий и изолированный: ~10 KB, в Shadow DOM. Не трогает ваш CSS и не соперничает с загрузкой вашей страницы.
Кнопка выключения: один клик в панели убирает AppKit у всех ваших пользователей за 30 секунд, без деплоя.
LGPD по построению: id вашего пользователя превращается в необратимый hash (SHA-256 + salt на аккаунт) до записи в базу. Никогда не отправляйте email или имя.
Проверяемый: SDK отдаётся с фиксированного URL, и есть публичный npm-пакет.

07Частые ошибки (и как их избежать)

Виджет не появляется

Проверьте ключ data-key и что сценарий опубликован (а не в черновике) в панели.

Пустой экран не появляется

В HTML нет data-appkit="…", или имя в панели не совпадает с именем в коде.

Шаг не завершается сам

Правило «по маршруту» с пустым маршрутом, или «по событию» без вызова track() в вашем коде в нужный момент.

Показывается имя пользователя

Не помещайте имя/email в заголовки сценариев или в data-user — используйте стабильный id.

Остались вопросы? contato@appkit.com.br.