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

نصب با Script و CDN

استفاده از IIFE رسمی آلفانا، data attributeها و Google Tag Manager بدون نیاز به bundler.

اگر پروژه شما از bundler یا Package Manager استفاده نمی‌کند، می‌توانید SDK آلفانا را مستقیماً با یک <script> به صفحه اضافه کنید.

نسخه مرورگر SDK به‌صورت یک IIFE مستقل منتشر می‌شود و پس از بارگذاری، API اصلی را از طریق window.AlphanaSDK در اختیار صفحه قرار می‌دهد. در کنار آن، command API سراسری window.alphana نیز ایجاد می‌شود تا بتوانید بدون import کردن package با SDK تعامل داشته باشید.

برای هر انتشار، فایل مسیر latest با نسخه جدید جایگزین می‌شود. اگر به URL ثابت و قابل بازتولید نیاز دارید، بهتر است به‌جای latest از مسیر نسخه‌دار استفاده کنید؛ فایل‌های نسخه‌دار برای cache بلندمدت طراحی شده‌اند و immutable باقی می‌مانند.

نصب پایه#

برای نصب SDK، snippet زیر را داخل HTML سایت قرار دهید:

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>

مقادیر `YOUR_APP_ID` و `YOUR_APP_SECRET` را با `appId` و `secretKey` مربوط به App خودتان در داشبورد آلفانا جایگزین کنید.

بعد از بارگذاری فایل، SDK تنظیمات موردنیاز را مستقیماً از همان `<script>` می‌خواند و نیازی نیست برای راه‌اندازی پایه، `UserTracker` را به‌صورت دستی ایجاد کنید.

## Data Attributeها چگونه خوانده می‌شوند؟
id: getting-started-script-cdn
هنگام اجرای Script، SDK به `document.currentScript.dataset` دسترسی پیدا می‌کند و مقادیر تعریف‌شده روی همان Tag را می‌خواند.

در نمونه بالا:

```html
data-app-id="YOUR_APP_ID" data-secret-key="YOUR_APP_SECRET"

به تنظیمات App فعلی تبدیل می‌شوند.

SDK علاوه بر data-app-id و data-secret-key می‌تواند تنظیمات پشتیبانی‌شده مربوط به build مرورگر را نیز از dataset همان Script دریافت کند.

بعد از خواندن تنظیمات، Tracker به‌صورت خودکار initialize می‌شود و init() لازم نیست جداگانه فراخوانی شود.

این رفتار برای integrationهایی مناسب است که می‌خواهید آلفانا را بدون اضافه کردن dependency به build پروژه راه‌اندازی کنید.

دسترسی از طریق window.AlphanaSDK#

بعد از بارگذاری موفق Script، build مرورگر SDK API خود را روی object زیر قرار می‌دهد:

javascript
window.AlphanaSDK;

بنابراین در صورت نیاز می‌توانید از JavaScript معمولی صفحه به exportهای build مرورگر دسترسی داشته باشید.

وجود این object همچنین می‌تواند برای بررسی اولیه این موضوع مفید باشد که فایل SDK با موفقیت بارگذاری شده است.

برای مثال:

javascript
console.log(window.AlphanaSDK);

اگر Script به‌درستی load شده باشد، API منتشرشده SDK در این object در دسترس خواهد بود.

Command API سراسری#

Build مرورگر علاوه بر window.AlphanaSDK، command API زیر را نیز ایجاد می‌کند:

javascript
window.alphana;

این API برای interaction با Tracker از محیط‌هایی طراحی شده است که import مستقیم package در آن‌ها در دسترس نیست؛ برای مثال سایت‌هایی که SDK را با Script Tag، CMS یا Tag Manager نصب کرده‌اند.

به این ترتیب، استفاده از نسخه CDN فقط به collection خودکار محدود نمی‌شود و integrationهای بدون bundler نیز می‌توانند از command API منتشرشده توسط SDK استفاده کنند.

مسیر latest#

ساده‌ترین روش نصب استفاده از مسیر زیر است:

text
https://storage.alphana.ir/cdn/alphana-sdk/latest/alphana-sdk.js

مسیر latest همیشه به build فعلی منتشرشده SDK اشاره می‌کند و در زمان انتشار نسخه جدید جایگزین می‌شود.

این گزینه زمانی مناسب است که می‌خواهید بدون تغییر URL، نسخه منتشرشده فعلی SDK را دریافت کنید.

با این حال، چون محتوای latest در انتشارهای بعدی تغییر می‌کند، برای محیط‌هایی که reproducibility اهمیت دارد بهتر است نسخه SDK را pin کنید.

استفاده از مسیر نسخه‌دار#

برای deploymentهایی که باید دقیقاً یک build مشخص را در طول زمان استفاده کنند، URL نسخه‌دار انتخاب مناسب‌تری است.

مسیرهای نسخه‌دار immutable هستند و می‌توان آن‌ها را با cache بلندمدت نگهداری کرد. در نتیجه، انتشار یک نسخه جدید SDK محتوای URL قبلی را تغییر نمی‌دهد.

این رفتار برای محیط Production، سیستم‌های cacheشده یا integrationهایی که تغییر نسخه باید به‌صورت کنترل‌شده انجام شود مفید است.

به‌جای استفاده دائمی از:

text
/latest/alphana-sdk.js

می‌توانید URL نسخه‌ای را که از manifest رسمی دریافت کرده‌اید pin کنید.

نصب با Google Tag Manager#

اگر Google Tag Manager روی سایت شما فعال است، می‌توانید SDK آلفانا را بدون تغییر مستقیم کد پروژه از طریق یک Custom HTML Tag نصب کنید.

در Google Tag Manager یک Tag جدید از نوع Custom HTML بسازید و snippet نصب آلفانا را داخل آن قرار دهید:

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>

سپس Trigger آن را روی All Pages قرار دهید تا SDK در تمام صفحاتی که GTM بارگذاری می‌شود اجرا شود.

قبل از Publish می‌توانید از Preview Mode خود GTM استفاده کنید و مطمئن شوید Tag فقط یک‌بار و در زمان موردنظر اجرا می‌شود.

پس از Publish، سایت را باز کنید و از طریق DevTools مرورگر، بخش Network را بررسی کنید.

باید درخواست collection به مسیر زیر قابل مشاهده باشد:

text
POST /api/collect

وجود این درخواست نشان می‌دهد SDK initialize شده و telemetry در حال ارسال به backend آلفاناست.

جلوگیری از نصب چندباره#

اگر SDK را از طریق Google Tag Manager نصب می‌کنید، مطمئن شوید همان Script به‌صورت مستقیم در کد سایت یا از طریق integration دیگری دوباره اضافه نشده باشد.

اجرای چندباره SDK می‌تواند باعث ایجاد Trackerهای تکراری، listenerهای اضافه یا ثبت چندباره بعضی Eventها شود.

برای هر صفحه فقط یک روش اصلی برای load کردن SDK انتخاب کنید؛ برای مثال یا Script مستقیم، یا GTM، یا integration مخصوص Framework.

بررسی نصب#

بعد از اضافه کردن Script، چند مورد را بررسی کنید:

  1. فایل alphana-sdk.js بدون خطای Network بارگذاری شود.
  2. window.AlphanaSDK بعد از load شدن Script در دسترس باشد.
  3. SDK با appId و secretKey صحیح initialize شده باشد.
  4. در Network درخواست‌های collection مشاهده شوند.
  5. دامنه فعلی با دامنه ثبت‌شده App در آلفانا هماهنگ باشد.

برای بررسی جریان اصلی ingestion، درخواست زیر را پیدا کنید:

text
POST https://api.alphana.ir/api/collect

اگر request ارسال نمی‌شود، ابتدا بارگذاری Script، مقدار Data Attributeها، دامنه App و خطاهای Console مرورگر را بررسی کنید.

Script یا Package؟#

نصب با Script و CDN برای سایت‌هایی مناسب است که نمی‌خواهند SDK را وارد build JavaScript خود کنند یا دسترسی مستقیمی به source code پروژه ندارند.

برای مثال:

  • سایت‌های HTML معمولی
  • CMSها
  • Google Tag Manager
  • integrationهای سریع بدون build مجدد
  • محیط‌هایی که نصب Package Manager ممکن نیست

اگر پروژه شما React، Next.js یا یک application مدرن با bundler است، نصب package معمولاً کنترل بیشتری روی lifecycle، Hookها و APIهای SDK در اختیارتان قرار می‌دهد.

در آن حالت، راهنمای نصب SDK یا integration مربوط به Framework را ببینید.

نسخه SDK و Cache#

مسیر latest برای دریافت خودکار نسخه فعلی مناسب است، اما cache کردن آن برای مدت بسیار طولانی می‌تواند باعث شود نسخه جدید SDK با تأخیر به کاربران برسد.

در مقابل، URLهای نسخه‌دار برای cache بلندمدت طراحی شده‌اند، چون محتوای آن‌ها بعد از انتشار تغییر نمی‌کند.

بنابراین اگر مدیریت دقیق نسخه برای شما مهم است، URL نسخه‌دار را pin کنید و ارتقای SDK را به‌صورت کنترل‌شده انجام دهید.