رفتن به محتوای اصلی
آلفاناDocs

راهنمای فریم‌ورک‌ها

انتخاب integration مناسب آلفانا برای React، Next.js، JavaScript ساده و WordPress.

SDK اصلی آلفانا به Framework خاصی وابسته نیست. هسته alphana-sdk را می‌توانید مستقیماً در پروژه‌های JavaScript و TypeScript استفاده کنید و در کنار آن، integrationهای آماده‌تری برای React، Next.js و WordPress در اختیار دارید.

اگر پروژه شما React است، ورودی alphana-sdk/react یک UserTrackerProvider و مجموعه‌ای از Hookهای React ارائه می‌کند تا lifecycle Tracker و دسترسی به APIهای SDK داخل Component Tree ساده‌تر شود.

برای سایت‌هایی که bundler یا Package Manager ندارند نیز build مستقل IIFE در دسترس است. این نسخه از طریق <script> بارگذاری می‌شود و برای سایت‌های HTML معمولی، CMSها، Google Tag Manager و WordPress مناسب است.

انتخاب integration مناسب بیشتر به ساختار پروژه و نحوه Navigation آن بستگی دارد، نه به تفاوت در داده‌هایی که آلفانا دریافت می‌کند.

کدام integration را انتخاب کنیم؟#

محیطمسیر پیشنهادی
React / Viteقرار دادن UserTrackerProvider در ریشه یا سطح پایدار App و استفاده از Hookهای alphana-sdk/react
Next.js App Routerقرار دادن Provider داخل Client Component و ثبت Navigation با usePageView(usePathname())
JavaScript / TypeScriptساخت مستقیم instance از UserTracker و اجرای init() در lifecycle مناسب
WordPressاستفاده از افزونه Alphana Tracker و دریافت build نسخه‌دار از manifest رسمی CDN

در همه این روش‌ها، هدف یکسان است: Tracker باید یک‌بار initialize شود، App درست را با appId و secretKey بشناسد و تغییر مسیرهای واقعی کاربر به‌درستی ثبت شوند.

React و Vite#

در پروژه‌های React، پیشنهاد می‌شود از integration مخصوص React استفاده کنید:

tsx
import {
  UserTrackerProvider,
  useTracker,
  useTrackGoal,
} from "alphana-sdk/react";

UserTrackerProvider باید در سطحی از Component Tree قرار بگیرد که با هر Render دوباره ساخته نشود و تمام بخش‌هایی که به Tracker نیاز دارند زیر آن قرار داشته باشند.

بعد از آن می‌توانید به‌جای دسترسی مستقیم به instance اصلی Tracker، از Hookهایی مثل useTrackGoal()، useTrackRevenue()، useFeatureFlag() یا usePageView() استفاده کنید.

این روش برای پروژه‌های Vite و سایر setupهای معمول React مناسب است.

راهنمای کامل:

Next.js App Router#

در Next.js App Router باید بین کد Server و Client تفاوت قائل شوید.

SDK آلفانا برای اجرا در مرورگر طراحی شده است؛ بنابراین Provider و Hookهای Tracker باید داخل Client Component استفاده شوند.

یک الگوی معمول این است که Provider را در یک Client Component پایدار قرار دهید و آن Component را از Layout اصلی فراخوانی کنید.

برای ثبت تغییر Route نیز می‌توانید مسیر فعلی را از usePathname() دریافت کنید و آن را به usePageView() بدهید:

tsx
const pathname = usePathname();

usePageView(pathname);

این بخش در Next.js اهمیت بیشتری دارد، چون تغییر Route در App Router معمولاً بدون reload کامل صفحه انجام می‌شود. اگر Navigation به‌درستی ثبت نشود، Pageviewها و بخشی از context مربوط به Journey و Attribution ناقص خواهند بود.

راهنمای کامل:

* [Next.js App Router](/docs/frameworks/nextjs)
id: frameworks
## JavaScript و TypeScript

اگر پروژه شما از React یا Framework مشابه استفاده نمی‌کند، می‌توانید مستقیماً از `UserTracker` استفاده کنید:

```typescript
import { UserTracker } from "alphana-sdk";

const tracker = new UserTracker({
  appId: "YOUR_APP_ID",
  secretKey: "YOUR_APP_SECRET",
}).init();

در این روش lifecycle Tracker مستقیماً در اختیار خودتان است.

می‌توانید متدهایی مثل trackPageView()، trackGoal()، trackRevenue()، identify() و flush() را مستقیماً روی همان instance فراخوانی کنید.

اگر Navigation در پروژه شما بدون reload صفحه انجام می‌شود، مطمئن شوید Pageviewهای جدید را در زمان تغییر مسیر به‌صورت دستی ثبت می‌کنید.

راهنمای کامل:

WordPress#

برای WordPress پیشنهاد می‌شود از افزونه Alphana Tracker استفاده کنید.

افزونه اطلاعات App را دریافت می‌کند و build مرورگر SDK را از CDN رسمی آلفانا بارگذاری می‌کند. برای مدیریت قابل‌پیش‌بینی نسخه نیز افزونه manifest رسمی CDN را می‌خواند و URL نسخه‌دار مناسب را cache می‌کند.

به این شکل لازم نیست Script SDK را به‌صورت دستی داخل Theme یا فایل‌های WordPress قرار دهید.

استفاده از افزونه همچنین کمک می‌کند installation آلفانا از کد Theme جدا بماند و تغییر یا به‌روزرسانی Theme باعث حذف Tracker نشود.

راهنمای کامل:

سایت‌های بدون Bundler#

اگر پروژه شما Package Manager یا bundler ندارد، لازم نیست برای استفاده از آلفانا ساختار پروژه را تغییر دهید.

Build IIFE رسمی SDK را می‌توانید مستقیماً با <script> بارگذاری کنید:

html
<script
  async
  src="https://storage.alphana.ir/cdn/alphana-sdk/latest/alphana-sdk.js"
  data-app-id="YOUR_APP_ID"
  data-secret-key="YOUR_APP_SECRET"
></script>

در این حالت SDK تنظیمات را از Data Attributeهای Script می‌خواند و به‌صورت خودکار initialize می‌شود.

این روش برای مواردی مثل HTML ساده، CMSهای سفارشی یا Google Tag Manager نیز مناسب است.

جزئیات بیشتر را در نصب با Script و CDN ببینید.

تفاوت integrationها#

تفاوت این روش‌ها بیشتر در نحوه راه‌اندازی و lifecycle Tracker است.

هسته collection در همه آن‌ها همان SDK آلفاناست:

  • React یک Provider و Hookهای آماده در اختیار شما قرار می‌دهد.
  • Next.js نیاز دارد مرز Server و Client و Navigation داخلی را در نظر بگیرید.
  • Vanilla JavaScript کنترل مستقیم Tracker را در اختیار شما می‌گذارد.
  • WordPress installation را از طریق افزونه و CDN رسمی مدیریت می‌کند.
  • Script/CDN برای محیط‌هایی مناسب است که package یا bundler در اختیار ندارند.

بنابراین لازم نیست integration پیچیده‌تری را فقط به دلیل امکانات بیشتر انتخاب کنید. روشی را استفاده کنید که با معماری فعلی پروژه شما هماهنگ‌تر است.

نکات مشترک در همه Frameworkها#

صرف‌نظر از Framework، چند اصل در تمام integrationها یکسان است:

  • Tracker را فقط یک‌بار initialize کنید.
  • از appId و secretKey مربوط به App درست استفاده کنید.
  • دامنه واقعی سایت را در تنظیمات App ثبت کنید.
  • در SPAها تغییر Navigation را به‌درستی ثبت کنید.
  • Account API Key با پیشوند alphana_api_ را داخل Client قرار ندهید.
  • بعد از نصب، درخواست‌های POST /api/collect را در Network مرورگر بررسی کنید.
  • ابتدا مطمئن شوید collection پایه کار می‌کند و سپس قابلیت‌های اضافی مثل Goal، Revenue، Journey یا Feature Flag را اضافه کنید.

راهنماهای هر Framework#

برای ادامه، راهنمای مربوط به محیط پروژه خود را انتخاب کنید: