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

API رشد

دریافت عملکرد کمپین‌های UTM از Public API آلفانا.

API رشد برای دریافت داده‌های UTM از Public API آلفانا استفاده می‌شود و کمک می‌کند عملکرد ترکیب‌های مختلف Campaign، Source و Medium را خارج از داشبورد نیز تحلیل کنید.

در نسخه فعلی، endpoint زیر داده‌های UTM را برای یک App و بازه زمانی مشخص برمی‌گرداند:

text
GET /api/v1/growth/utm

این endpoint حداکثر ۱۰۰ ترکیب دقیق UTM را همراه تعداد Sessionها و Visitorهای یکتا برمی‌گرداند.

هر ردیف نماینده یک ترکیب مشخص از پارامترهای UTM است؛ بنابراین اگر فقط یکی از مقادیر Source، Medium، Campaign، Term یا Content متفاوت باشد، آن ترکیب می‌تواند به‌عنوان یک ردیف جدا در نتیجه دیده شود.

نمونه درخواست#

برای دریافت عملکرد UTM یک App در یک بازه زمانی مشخص:

curl
curl --get https://api.alphana.ir/api/v1/growth/utm \
  -H "Authorization: Bearer $ALPHANA_API_KEY" \
  --data-urlencode "appId=11111111-1111-4111-8111-111111111111" \
  --data-urlencode "from=2026-07-01T00:00:00.000Z" \
  --data-urlencode "to=2026-07-31T23:59:59.999Z"

در این درخواست:

  • appId مشخص می‌کند داده‌های کدام App باید بررسی شوند.
  • from ابتدای بازه زمانی گزارش را تعیین می‌کند.
  • to انتهای بازه زمانی گزارش را مشخص می‌کند.
  • Account API Key از طریق Header Authorization ارسال می‌شود.

برای درخواست‌های Public API باید از Account API Key معتبر با پیشوند alphana_api_ استفاده کنید.

پارامتر appId#

مقدار appId باید شناسه Appی باشد که حساب فعلی به آن دسترسی دارد.

اگر شناسه App را در اختیار ندارید، ابتدا فهرست Appهای قابل‌دسترسی را دریافت کنید:

text
GET /api/v1/apps

سپس مقدار id App موردنظر را به‌عنوان appId در درخواست Growth استفاده کنید.

برای مثال:

text
appId=11111111-1111-4111-8111-111111111111

Account API Key باید به App موردنظر دسترسی داشته باشد؛ در غیر این صورت درخواست تحلیلی نباید به داده‌های آن App دسترسی پیدا کند.

بازه زمانی#

مقادیر from و to بازه زمانی گزارش را مشخص می‌کنند.

برای مثال:

text
from=2026-07-01T00:00:00.000Z
to=2026-07-31T23:59:59.999Z

بهتر است بازه زمانی را صریح و با timestamp کامل ارسال کنید تا مرز گزارش قابل‌پیش‌بینی باشد.

انتخاب بازه به نوع تحلیلی که انجام می‌دهید بستگی دارد. برای مثال می‌توانید عملکرد یک Campaign را در طول یک ماه بررسی کنید یا دو بازه مشابه را در سیستم خودتان با یکدیگر مقایسه کنید.

ساختار ترکیب UTM#

هر ردیف نتیجه بر اساس ترکیب دقیق فیلدهای UTM ساخته می‌شود.

فیلدهای اصلی عبارت‌اند از:

فیلدمعنی
sourceمنبع ورودی، معادل utm_source
mediumکانال یا Medium، معادل utm_medium
campaignنام Campaign، معادل utm_campaign
termKeyword یا Audience، معادل utm_term
contentCreative، Placement یا CTA، معادل utm_content

برای مثال، این دو URL:

text
/pricing?utm_source=google&utm_medium=cpc&utm_campaign=spring

و:

text
/pricing?utm_source=google&utm_medium=cpc&utm_campaign=summer

به دلیل تفاوت در Campaign، دو ترکیب UTM جدا در گزارش ایجاد می‌کنند.

Sessionها و Visitorها#

در کنار هر ترکیب UTM، API تعداد Sessionها و Visitorهای یکتا را برمی‌گرداند.

Sessions نشان می‌دهد چند Session با همان ترکیب UTM ثبت شده‌اند.

Visitors تعداد Visitorهای یکتایی را نشان می‌دهد که در همان ترکیب دیده شده‌اند.

این دو Metric الزاماً برابر نیستند؛ چون یک Visitor می‌تواند بیش از یک Session داشته باشد.

برای مثال، ممکن است یک ترکیب این وضعیت را داشته باشد:

text
sessions: 180
visitors: 125

این یعنی ۱۲۵ Visitor یکتا در مجموع ۱۸۰ Session برای همان ترکیب UTM ثبت کرده‌اند.

حذف ردیف‌های بدون Source#

ردیف‌هایی که مقدار utm_source ندارند از نتیجه این endpoint حذف می‌شوند.

یعنی اگر یک Session هیچ Source UTM ثبت‌شده‌ای نداشته باشد، در خروجی GET /api/v1/growth/utm قرار نمی‌گیرد.

این رفتار کمک می‌کند خروجی این endpoint روی Trafficی متمرکز بماند که واقعاً با UTM Source قابل دسته‌بندی است.

اگر هدف شما تحلیل کل Traffic، Referrer یا ورودی‌های بدون UTM است، باید از گزارش یا endpoint متناسب با همان نوع داده استفاده کنید.

ترتیب نتایج#

نتیجه ابتدا بر اساس تعداد Sessionها به‌صورت نزولی مرتب می‌شود.

اگر دو ردیف تعداد Session برابر داشته باشند، تعداد Visitorها معیار بعدی مرتب‌سازی خواهد بود و آن نیز به‌صورت نزولی اعمال می‌شود.

به‌صورت مفهومی:

text
sessions DESC
visitors DESC

در نتیجه، ترکیب‌هایی که بیشترین حجم Session را داشته‌اند در ابتدای پاسخ قرار می‌گیرند.

این ترتیب برای نمایش سریع Campaignها و Sourceهای پرترافیک مناسب است.

محدودیت ۱۰۰ ترکیب#

این endpoint حداکثر ۱۰۰ ترکیب UTM را در پاسخ برمی‌گرداند.

اگر در بازه زمانی انتخاب‌شده بیش از ۱۰۰ ترکیب مختلف وجود داشته باشد، فقط ۱۰۰ مورد اول بر اساس ترتیب فعلی گزارش در پاسخ دیده می‌شوند.

از آنجا که مرتب‌سازی ابتدا بر اساس sessions و سپس visitors انجام می‌شود، ترکیب‌های پرترافیک‌تر در اولویت قرار می‌گیرند.

اگر سیستم شما تعداد زیادی ترکیب UTM تولید می‌کند، بهتر است Naming کمپین‌ها را کنترل کنید تا داده به دلیل تفاوت‌های کوچک و ناخواسته بیش از حد پراکنده نشود.

مقدارهای Nullable#

همه Campaignها الزاماً تمام پارامترهای UTM را ندارند.

برای مثال ممکن است URL فقط شامل این موارد باشد:

text
utm_source=google
utm_medium=cpc
utm_campaign=spring_sale

و utm_term یا utm_content در آن وجود نداشته باشند.

در چنین شرایطی، فیلدهای term یا content می‌توانند در داده واقعی مقدار nullable داشته باشند.

بنابراین در integration خود فرض نکنید تمام پنج فیلد UTM همیشه string غیرخالی هستند.

برای مثال، در TypeScript بهتر است ساختار داده شما امکان null را برای فیلدهای اختیاری در نظر بگیرد.

نمونه مدل داده#

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

typescript
type UtmPerformanceRow = {
  source: string;
  medium: string | null;
  campaign: string | null;
  term: string | null;
  content: string | null;
  sessions: number;
  visitors: number;
};

این مثال فقط برای نشان دادن نحوه برخورد با فیلدهای nullable است؛ هنگام پیاده‌سازی نهایی، قرارداد واقعی پاسخ endpoint را مبنا قرار دهید.

اهمیت Naming Convention#

چون گزارش بر اساس ترکیب دقیق UTMها ساخته می‌شود، تفاوت‌های کوچک در Naming می‌توانند داده را بین چند ردیف جدا کنند.

برای مثال، این مقادیر ممکن است به‌عنوان Sourceهای جدا دیده شوند:

text
google
Google
google_ads

حتی اگر از نگاه تیم بازاریابی همه آن‌ها به یک منبع اشاره کنند، Naming نامنظم می‌تواند تحلیل را سخت‌تر کند.

بهتر است قبل از اجرای Campaignها یک Convention ثابت برای موارد زیر داشته باشید:

text
utm_source
utm_medium
utm_campaign
utm_term
utm_content

این موضوع به‌خصوص زمانی مهم است که داده Public API وارد Dashboard داخلی، BI Tool یا گزارش‌های سفارشی شما می‌شود.

نمونه استفاده در Backend#

می‌توانید این endpoint را از Backend خود فراخوانی کنید و داده را برای گزارش داخلی پردازش کنید.

برای مثال:

typescript
const url = new URL("https://api.alphana.ir/api/v1/growth/utm");

url.searchParams.set("appId", "11111111-1111-4111-8111-111111111111");

url.searchParams.set("from", "2026-07-01T00:00:00.000Z");

url.searchParams.set("to", "2026-07-31T23:59:59.999Z");

const response = await fetch(url, {
  headers: {
    Authorization: `Bearer ${process.env.ALPHANA_API_KEY}`,
    Accept: "application/json",
  },
});

const data = await response.json();

Account API Key در این مثال فقط از Environment سمت Server خوانده می‌شود و نباید به Client منتقل شود.

تحلیل Source و Campaign#

یکی از استفاده‌های معمول این endpoint مقایسه عملکرد Campaignهاست.

برای مثال می‌توانید بررسی کنید:

  • کدام utm_source بیشترین Session را ایجاد کرده است
  • کدام Campaign Visitorهای بیشتری آورده است
  • آیا یک Source تعداد Session بالا اما Visitor یکتای کمتری دارد
  • کدام ترکیب Source و Medium در یک بازه زمانی فعال‌تر بوده است
  • کدام Campaignها به دلیل Naming نامنظم در چند ردیف شکسته شده‌اند

این endpoint حجم ورود را نشان می‌دهد؛ برای تفسیر کامل‌تر نتیجه Campaign بهتر است این داده را در کنار Revenue، Goal یا رفتار بعد از ورود کاربران بررسی کنید.

UTM در SDK#

داده‌ای که در این endpoint دیده می‌شود از UTMهایی می‌آید که SDK هنگام ورود Visitor ثبت می‌کند.

SDK پارامترهای Campaign را از URL می‌خواند و آن‌ها را در context مربوط به Traffic و Attribution نگه می‌دارد.

برای جزئیات بیشتر درباره capture شدن UTMها، first-touch، last-touch و Click IDها، صفحه UTM و Attribution را ببینید.

احراز هویت#

این endpoint بخشی از Public API است و باید با Account API Key فراخوانی شود.

برای مثال:

text
Authorization: Bearer alphana_api_...

App secretKey مورد استفاده SDK برای این درخواست مناسب نیست.

اگر درباره تفاوت Credentialها مطمئن نیستید، صفحه احراز هویت Public API را ببینید.

مسیر پیشنهادی برای استفاده#

یک جریان معمول برای دریافت داده UTM می‌تواند به این شکل باشد:

  1. Account API Key را در Backend نگهداری کنید.
  2. با GET /api/v1/apps شناسه App موردنظر را پیدا کنید.
  3. بازه زمانی گزارش را مشخص کنید.
  4. GET /api/v1/growth/utm را با appId، from و to فراخوانی کنید.
  5. مقدارهای nullable مثل term و content را در مدل داده در نظر بگیرید.
  6. نتیجه را بر اساس Source، Medium یا Campaign در ابزار داخلی خود نمایش یا تحلیل کنید.
  7. برای تحلیل عمیق‌تر، UTM را در کنار رفتار و نتیجه واقعی کاربر بررسی کنید.