ثبّت بلا أخطاء — أنت أو وكيل الذكاء الاصطناعي لديك.

01الـ prompt لوكيل الذكاء الاصطناعي لديك

الصق النص أدناه في مساعد البرمجة لديك، واستبدل MINHA_CHAVE_PK_LIVE بالمفتاح من لوحة التحكم، وسيقوم بالتكامل كاملًا — التثبيت والشاشات الفارغة وإكمال الخطوات — من دون كسر منتجك.

أنت مساعد البرمجة الخاص بي. ادمج AppKit ‏(appkit.com.br) في منتجي على الويب من دون كسر أي شيء. يقوم AppKit بحقن checklist للـ onboarding وشاشات فارغة وإعلانات، تُدار من لوحة تحكم خارجية. نفّذ بالضبط ما يلي:

1) التثبيت
- إذا كان المشروع يستخدم bundler ‏(React/Vue/Next/Svelte/إلخ): ثبّت الحزمة
  @tecaless/appkit-sdk
  وفي نقطة الدخول، بعد أن يسجّل المستخدم الدخول (عندما يكون معرّفه متاحًا لديّ)، استدعِ:
  import { init } from '@tecaless/appkit-sdk'
  init({ apiKey: 'MINHA_CHAVE_PK_LIVE', userId: <المعرف الثابت للمستخدم المسجل دخوله> })
- إذا كان موقعًا ثابتًا / no-code: أضف قبل :
  
- يجب أن يكون userId/data-user هو المعرّف الثابت للمستخدم المسجل دخوله. يحوّله AppKit إلى hash على الخادم — لا ترسل أبدًا بريدًا إلكترونيًا أو اسمًا. إن لم يكن هناك مستخدم مسجل دخوله، فاتركه بلا userId.

2) الشاشات الفارغة
لكل شاشة تبدأ من دون بيانات وأريد فيها دعوة إلى الفعل (مثل الفواتير أو جهات الاتصال أو التقويم)، لفّ حالة الفراغ الحالية داخل حاوية واحدة موسومة، مع إبقاء المحتوى الحالي بداخلها كخيار احتياطي:
  
 ...محتوى «لا توجد سجلات» الحالي... 
استخدم اسمًا قصيرًا وثابتًا لكل شاشة (مثل faturas-vazio وcontatos-vazio). لا تستخدم مُحدِّد CSS مولَّدًا من الـ build. أعد إليّ قائمة الأسماء التي أنشأتها.

3) إكمال الخطوات (مهم للقياس الحقيقي)
لكل خطوة onboarding تمثل فعلًا حقيقيًا من المستخدم (مثل «إصدار أول فاتورة»)، استدعِ في اللحظة الدقيقة التي يتحقق فيها الفعل فعلًا — بعد الحفظ على الخادم، لا عند نقر الزر:
  window.AppKit && window.AppKit.track('fatura_emitida')
استخدم اسم حدث واحدًا لكل فعل، بصيغة snake_case. أعد إليّ قائمة الأحداث التي أنشأتها.

4) لا تكسر شيئًا
- حمّل الـ SDK بشكل غير متزامن؛ فهو fail-open (إذا تعطل، يختفي من تلقاء نفسه ولا يؤثر على منتجي).
- مفتاح pk_live عام بطبيعته (يمكن أن يبقى على العميل). لا تكشف أي مفتاح سري.
- لا تُوقف عملية العرض بانتظار AppKit.

في النهاية، اذكر: (أ) الملفات المعدّلة، (ب) أسماء data-appkit المنشأة، (ج) أسماء الأحداث المنشأة — كي أضبطها في لوحة تحكم AppKit.

02التثبيت

طريقتان. إذا كنت تستخدم إطار عمل، فابدأ بـ 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 / موقع ثابت — سطر واحد

<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أين يظهر كل شيء

تعمل التجارب الثلاث في أي صفحة من منتجك، ضمن النطاق الذي ثبّته فيه. تتحكم في كل شيء من لوحة التحكم، من دون deploy جديد.

04الشاشات الفارغة: لست بحاجة إلى لمس الكود

سحر الشاشة الفارغة أنك لا تعلن أي شيء. انقر نسخ الـ prompt وسيتولى وكيل الذكاء الاصطناعي الجانب التقني: يشير إلى عنصر موجود أصلًا في نظامك (عبر مُحدِّد، من دون لمس HTML) أو يضيف عند الحاجة وسمًا ثابتًا — AppKit يقبل الاثنين. بعد ذلك تعدّل النص من لوحة التحكم فقط، إلى الأبد، من دون deploy.

نسخ الـ prompt لوكيل الذكاء الاصطناعي لديّ

نقر المستخدم «نسخ الـ 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؛ أو
  (ب) إذا لم يوجد سوى فئة مولَّدة من الـ build، فلفّ حالة الفراغ داخل 
…المحتوى الحالي…
.
أعد إليّ مُحدِّد/اسم كل شاشة فارغة (مثل "‎#faturas-vazio" أو "faturas-vazio") كي ألصقه في لوحة التحكم ← الشاشات الفارغة.

ميزات AppKit المتاحة (فعّل كلًا منها في لوحة التحكم https://appkit.com.br/painel): checklist للخطوات الأولى، وشاشات فارغة، وإعلانات في الأعلى، وإكمال الخطوات بالأحداث (استدعِ window.AppKit.track('acao_real') لحظة وقوع الفعل الحقيقي). الدليل الكامل: https://appkit.com.br/guia

لا تكسر شيئًا: حمّل بشكل غير متزامن، فالـ SDK هو fail-open، ومفتاح pk_live عام (لا تكشف أي مفتاح سري). في النهاية، اذكر الملفات المعدّلة والمُحدِّدات/الأسماء المنشأة.

إذا اختفى المرساة يومًا ما، ينبهك AppKit (حدث appkit_anchor_missing) ولا يعرض شيئًا — تبقى شاشتك طبيعية.

05كيف تكتمل الخطوة

ثلاثة أوضاع، تُختار لكل خطوة في لوحة التحكم. هذا يحدد ما إذا كان قمع التفعيل لديك يقيس فعلًا حقيقيًا أم مجرد نقرات.

06الضمانات

• فشل آمن: إذا تعطل AppKit، يختفي الـ widget ويبقى منتجك كما هو تمامًا. لا يصل أي خطأ منا إلى الـ console لديك.
• خفيف ومعزول: نحو 10 KB، داخل Shadow DOM. لا يلمس CSS الخاص بك ولا ينافس تحميل صفحتك.
• زر الإيقاف: نقرة واحدة في لوحة التحكم تزيل AppKit من جميع مستخدميك خلال 30 ثانية، من دون deploy.
• LGPD بحكم التصميم: معرّف مستخدمك يتحول إلى hash لا يمكن عكسه (SHA-256 + salt لكل حساب) قبل أن يلمس قاعدة البيانات. لا ترسل أبدًا بريدًا إلكترونيًا أو اسمًا.
• قابل للتدقيق: يُقدَّم الـ SDK من عنوان URL ثابت وهناك حزمة npm عامة.

07الأخطاء الشائعة (وكيف تتجنبها)

ما زال لديك سؤال؟ contato@appkit.com.br.