WordPress

رفتار افزونه Alphana Tracker، تنظیم credential، استفاده از CDN manifest و شناسایی کاربران واردشده.

افزونه Alphana Tracker راه‌اندازی SDK آلفانا در WordPress را بدون نیاز به اضافه کردن دستی Script به Theme انجام می‌دهد.

این افزونه build مرورگر SDK را از CDN رسمی آلفانا دریافت می‌کند و به‌جای استفاده مستقیم از مسیر latest، URL نسخه‌دار موجود در manifest رسمی را می‌خواند:

text

https://storage.alphana.ir/cdn/alphana-sdk/manifest.json

نتیجه این manifest برای شش ساعت در transient وردپرس cache می‌شود. به این شکل، افزونه لازم نیست در هر بار بارگذاری سایت دوباره manifest را دریافت کند و در عین حال می‌تواند نسخه منتشرشده SDK را به‌صورت کنترل‌شده دنبال کند.

## پیکربندی

بعد از نصب افزونه، تنظیمات اتصال به آلفانا از داخل پنل WordPress انجام می‌شود.
id: frameworks-wordpress
برای راه‌اندازی:

1. افزونه `Alphana Tracker` را نصب و فعال کنید.

2. وارد صفحه «ردیاب آلفانا» شوید و مقدارهای `App ID`، `Secret Key` و `API Endpoint` را وارد کنید.

3. گزینه `Enable Tracking` را فعال کنید و تنظیمات را ذخیره کنید.

`App ID` و `Secret Key` باید متعلق به همان Appی باشند که در داشبورد آلفانا برای این وب‌سایت ساخته‌اید.

بعد از ذخیره تنظیمات، افزونه manifest رسمی CDN را دریافت می‌کند و URL نسخه‌دار SDK را برای بارگذاری در سایت استفاده می‌کند.

## بارگذاری SDK

افزونه فقط زمانی Script آلفانا را enqueue می‌کند که تنظیمات لازم برای Tracker در دسترس باشند.

اگر یکی از credentialهای اصلی خالی باشد، SDK به صفحه اضافه نمی‌شود.

همچنین اگر manifest رسمی CDN در دسترس نباشد و افزونه نتواند URL معتبر build مرورگر را دریافت کند، Script را enqueue نمی‌کند.

این رفتار کمک می‌کند به‌جای بارگذاری ناقص یا نامعتبر SDK، Tracker فقط زمانی روی سایت اجرا شود که فایل و تنظیمات لازم در دسترس باشند.

URL نسخه SDK از manifest زیر دریافت می‌شود:

```text
https://storage.alphana.ir/cdn/alphana-sdk/manifest.json

نتیجه manifest برای شش ساعت cache می‌شود و در درخواست‌های بعدی از transient ذخیره‌شده WordPress استفاده خواهد شد.

شناسایی کاربران واردشده#

اگر Visitor در WordPress وارد حساب خود شده باشد، افزونه می‌تواند اطلاعات شناخته‌شده او را از طریق identify() به Tracker اضافه کند.

ویژگی‌های ارسال‌شده می‌توانند شامل موارد زیر باشند:

userId
email
name
نخستین Role موجود برای کاربر

به این شکل، رفتار کاربر واردشده فقط به یک Session ناشناس محدود نمی‌ماند و می‌تواند با context بیشتری در تحلیل‌های آلفانا بررسی شود.

این اطلاعات از داده‌هایی گرفته می‌شوند که WordPress برای همان کاربر در اختیار دارد و از طریق API شناسایی SDK ارسال می‌شوند.

Role کاربر#

یک کاربر WordPress ممکن است بیش از یک Role داشته باشد.

در رفتار فعلی افزونه، نخستین Role موجود برای کاربر به‌عنوان ویژگی شناسایی‌شده ارسال می‌شود.

برای مثال، اگر Role کاربر:

text

subscriber

باشد، این مقدار می‌تواند همراه سایر propertyهای identify() به آلفانا ارسال شود.

اگر تحلیل شما به ساختار پیچیده‌تری از Roleها نیاز دارد، این رفتار را هنگام طراحی Segmentها و Audienceهای خود در نظر بگیرید.

وضعیت اشتراک#

افزونه علاوه بر راه‌اندازی Tracker، برای نمایش کارت وضعیت اشتراک نیز از API آلفانا استفاده می‌کند.

برای دریافت وضعیت فعلی، درخواست زیر ارسال می‌شود:

text

GET /api/subscriptions/status

این درخواست با Bearer مربوط به App Secret انجام می‌شود.

نتیجه وضعیت اشتراک نیز مانند manifest برای شش ساعت در WordPress cache می‌شود تا برای هر بار نمایش صفحه تنظیمات، درخواست جدیدی به backend ارسال نشود.

به این ترتیب، کارت اشتراک داخل افزونه می‌تواند وضعیت فعلی App را نمایش دهد، بدون اینکه در هر بار باز کردن صفحه تنظیمات به API درخواست مستقیم ارسال کند.

Cache در WordPress#

دو نوع داده اصلی در افزونه cache می‌شوند:

داده	مدت Cache
CDN Manifest	۶ ساعت
Subscription Status	۶ ساعت

این cache با transientهای WordPress انجام می‌شود.

پس از پایان مدت cache، افزونه در اولین درخواست موردنیاز داده جدید را دریافت می‌کند و transient را دوباره به‌روزرسانی می‌کند.

App Secret و Account API Key#

Credential مورد استفاده افزونه برای Tracker با Account API Key یکسان نیست.

در تنظیمات افزونه از credentialهای خود App استفاده کنید:

text

App ID
Secret Key
API Endpoint

و Account API Key را از این integration جدا نگه دارید.

رفتار در صورت خطا#

اگر افزونه نتواند manifest رسمی CDN را دریافت کند، SDK را با URL حدسی یا نسخه نامشخص بارگذاری نمی‌کند.

همچنین اگر App ID یا Secret Key تنظیم نشده باشند، Tracker روی سایت enqueue نخواهد شد.

بنابراین اگر بعد از فعال کردن افزونه درخواست‌های آلفانا را در Network نمی‌بینید، ابتدا این موارد را بررسی کنید:

افزونه فعال باشد.
Enable Tracking روشن باشد.
App ID وارد شده باشد.
Secret Key وارد شده باشد.
API Endpoint مقدار صحیح داشته باشد.
manifest رسمی CDN از Server قابل دسترسی باشد.
transient یا cache قدیمی باعث استفاده از مقدار نامعتبر نشده باشد.

بررسی نصب#

بعد از ذخیره تنظیمات، یکی از صفحات عمومی سایت را باز کنید و DevTools مرورگر را بررسی کنید.

ابتدا مطمئن شوید فایل SDK از CDN آلفانا بارگذاری شده است.

سپس در Network باید درخواست‌های collection آلفانا دیده شوند:

text

POST /api/collect

اگر کاربر وارد WordPress باشد، می‌توانید در کنار collection اصلی بررسی کنید که جریان شناسایی Visitor نیز بدون خطا انجام می‌شود.

برای تست بهتر، یک صفحه را در حالت Guest و یک‌بار در حالت Logged-in باز کنید تا تفاوت رفتار شناسایی کاربر مشخص باشد.

چرا manifest نسخه‌دار؟#

استفاده از manifest کمک می‌کند افزونه به یک URL واقعی و نسخه‌دار SDK برسد.

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

افزونه manifest را می‌خواند، URL فعلی را دریافت می‌کند و همان مقدار را برای مدت مشخص cache می‌کند.

در نتیجه، سایت لازم نیست در هر request دوباره وضعیت آخرین نسخه SDK را بررسی کند و در عین حال installation به فایل رسمی منتشرشده آلفانا متصل باقی می‌ماند.

قدم بعدی#

بعد از اینکه Tracker روی WordPress فعال شد، می‌توانید داده‌های Session، Pageview و سایر telemetryهای فعال را در داشبورد آلفانا بررسی کنید.

برای درک بیشتر رفتار SDK و تنظیمات آن، صفحات زیر را ببینید: