ミスなく導入 — あなた自身でも、AI エージェントでも。

01AI エージェント向けの prompt

下のテキストをコーディングアシスタントに貼り付け、MINHA_CHAVE_PK_LIVE をダッシュボードのキーに置き換えてください。インストール、空状態、ステップ完了まで、プロダクトを壊さずに連携全体をやってくれます。

あなたは私のコーディングアシスタントです。AppKit（appkit.com.br）を私の Web プロダクトに、何も壊さずに組み込んでください。AppKit は外部ダッシュボードから制御される onboarding チェックリスト・空状態・お知らせを注入します。正確に次を実行してください：

1) インストール
- プロジェクトが bundler（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 はサーバー側でそれを hash 化する — メールアドレスや氏名は絶対に送らない。ログイン中ユーザーがいなければ userId は付けない。

2) 空状態
データなしで始まり、行動への誘導を出したい画面（例：請求書、連絡先、カレンダー）ごとに、現在の空状態をマーク付きコンテナ 1 つで包み、既存の内容は fallback として中に残す：
  
 ...既存の「レコードなし」の内容... 
画面ごとに短く安定した名前を使う（例：faturas-vazio、contatos-vazio）。ビルド生成の CSS セレクターは使わない。作成した名前の一覧を私に返すこと。

3) ステップ完了（実メトリクスのために重要）
ユーザーの実際の行動を表す onboarding ステップ（例：「最初の請求書を発行」）ごとに、行動が本当に確定したまさにその瞬間に呼び出す — ボタンクリック時ではなく、サーバーへの保存後に：
  window.AppKit && window.AppKit.track('fatura_emitida')
アクションごとに snake_case のイベント名を 1 つ使う。作成したイベントの一覧を私に返すこと。

4) 何も壊さない
- SDK は非同期で読み込む。フェイルオープンなので（落ちても勝手に消えるだけで、私のプロダクトには影響しない）。
- pk_live キーは本来パブリックなもの（クライアントに置いてよい）。秘密キーは一切公開しない。
- AppKit を待ってレンダリングをブロックしない。

最後に一覧を出す：(a) 変更したファイル、(b) 作成した data-appkit 名、(c) 作成したイベント名 — 私が AppKit ダッシュボードで設定できるように。

02インストール

方法は 2 つ。フレームワークを使っているなら npm から始めてください。

bundler を使う場合（React、Vue、Next、Svelte…）— 推奨

npm i @tecaless/appkit-sdk

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

init({ apiKey: 'MINHA_CHAVE_PK_LIVE', userId: usuario.id })
// 実際のアクションが起きたとき：
track('fatura_emitida')

No-code / 静的サイト — 1 行だけ

<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それぞれの表示場所

3 つのエクスペリエンスは、インストールしたドメイン内であればプロダクトのどのページでも動きます。すべてダッシュボードから制御でき、再 deploy は不要です。

04空状態：コードに触れる必要はありません

空状態のマジックは、何も宣言しなくていいことです。Prompt をコピーをクリックすれば、AI エージェントが技術的な部分を引き受けます。システムに既にある要素をセレクター経由で指すか（HTML には触れません）、必要なら安定したマーカーを追加します — AppKit はどちらも受け付けます。あとはダッシュボードから文言を編集するだけ。ずっと、deploy なしで。

AI エージェント向けの prompt をコピー

ユーザーは AppKit（appkit.com.br）の「空状態」機能で「Prompt をコピー」をクリックしました。プロダクト内のデータなしで始まる画面を、手作業でコードを触らずに行動への誘導へ変えたいと考えています。次を実行して：

前提 — AppKit がインストールされていること。まだなら先にインストールする：
  npm i @tecaless/appkit-sdk
  import { init } from '@tecaless/appkit-sdk'; init({ apiKey: 'MINHA_CHAVE_PK_LIVE', userId: <ログイン中ユーザーの id> })
  （または no-code： を  の前に）

空状態 — コード内で空のまま始まる画面（例：請求書/連絡先の一覧）を見つけ、AppKit をそこにどうアンカーするかを選ぶ（どちらの方法でも可）：
  (a) 安定した CSS セレクター（id またはセマンティックなクラス）で既存の要素を指す — HTML には触れない。または
  (b) ビルド生成のクラスしかない場合は、空状態を次で包む：
…既存の内容…
.
各空状態のセレクター/名前（例："#faturas-vazio" または "faturas-vazio"）を私に返すこと。ダッシュボード → 空状態に貼り付けるため。

AppKit の利用可能な機能（それぞれダッシュボード https://appkit.com.br/painel で有効化）：はじめの一歩チェックリスト、空状態、上部お知らせ、イベントによるステップ完了（実際のアクションの瞬間に window.AppKit.track('acao_real') を呼ぶ）。完全ガイド：https://appkit.com.br/guia

何も壊さないこと：async で読み込む。SDK はフェイルオープン、pk_live キーはパブリック（秘密キーは公開しない）。最後に、変更したファイルと作成したセレクター/名前を一覧にすること。

アンカーがいつか消えても、AppKit が通知し（appkit_anchor_missing イベント）、何もレンダリングしません — 画面は通常のままです。

05ステップはどう完了するか

3 つのモードを、ダッシュボードでステップごとに選べます。これで、アクティベーションファネルが実際の行動を測るのか、単なるクリックを測るのかが決まります。

06保証

• フェイルオープン：AppKit が落ちても widget が消えるだけで、プロダクトはそのままです。私たちのエラーがあなたの console に届くことはありません。
• 軽量で隔離：約 10 KB、Shadow DOM 内。あなたの CSS に触れず、ページの読み込みを妨げません。
• オフスイッチ：ダッシュボードのワンクリックで、30 秒以内に全ユーザーから AppKit を取り除けます。deploy 不要。
• 設計段階からの LGPD 対応：ユーザーの id は、データベースに触れる前に不可逆な hash（SHA-256 + アカウントごとの salt）になります。メールアドレスや氏名は決して送らないでください。
• 監査可能：SDK は固定 URL で配信され、公開 npm パッケージがあります。

07よくあるミス（と回避方法）

まだ疑問がありますか？ contato@appkit.com.br まで。