Skip to Content
مستندات متریکس همواره در حال بهبود است! 🚀 آخرین به‌روزرسانی‌ها را از اینجا دنبال کنید.

ارسال ایونت (سرویس اتریبیوشن و اتومیشن)

هر تعامل کاربر با وب‌سایت شما می‌تواند به عنوان یک ایونت (Event) در داشبورد متریکس ثبت شود. متریکس این ایونت ها را جمع‌آوری کرده و تحلیل‌های آماری آن‌ها را در اختیار شما قرار می‌دهد.

پیش از ارسال هر ایونت ی، SDK را مقداردهی اولیه کنید. اگر ایونت باید به یک کاربر مشخص نسبت داده شود، ابتدا authorizeUser را فراخوانی کنید.


۱. ارسال ایونت با Slug

این متد برای ارسال ایونت های سفارشی بر اساس اسلاگ (Slug) ایونت که در داشبورد تعریف شده، استفاده می‌شود.

newEvent(slug: string, customAttributes?: { [key: string]: string }, onSuccess?: () => void): void
پارامترنوعتوضیحالزامی
slugstringاسلاگ (slug) ایونت که در داشبورد متریکس تعریف شده است.بله
customAttributes{ [key: string]: string }یک آبجکت از ویژگی‌های سفارشی مرتبط با ایونت .خیر
onSuccess() => voidیک تابع callback که پس از ارسال موفق ایونت اجرا می‌شود.خیر

برای مثال، برای ردیابی کلیک روی یک دکمه، ابتدا ایونت مربوطه را در داشبورد متریکس تعریف کنید (Settings > Manage Events > Create event). سپس متد newEvent را با اسلاگ آن ایونت فراخوانی کنید:

import { newEvent } from '@metrixorg/websdk'; // ارسال یک ایونت ساده newEvent('BUTTON_CLICKED'); // ارسال ایونت همراه با ویژگی‌های سفارشی const attributes = { first_name: 'Ali', last_name: 'Bagheri', product_name: 'shirt', size: 'large', purchase_date: '2024-11-20T11:24:03Z', // برای شناسایی تاریخ، از فرمت ISO 8601 استفاده کنید }; newEvent('PURCHASE_COMPLETED', attributes, () => { console.log('Purchase event sent successfully!'); });

اگر slug خالی ارسال شود، با خطای زیر مواجه خواهید شد: Error: newEvent: slug is required and cannot be empty.


۲. ارسال ایونت با نام (Name)

این متد عملکردی مشابه newEvent دارد، با این تفاوت که به جای slug، از نام ایونت (Event Name) برای شناسایی آن استفاده می‌کند.

newEventByName(name: string, customAttributes?: { [key: string]: string }, onSuccess?: () => void): void
پارامترنوعتوضیحالزامی
namestringنام ایونت (Event Name) که در داشبورد متریکس تعریف شده است.بله
customAttributes{ [key: string]: string }یک آبجکت از ویژگی‌های سفارشی مرتبط با ایونت .خیر
onSuccess() => voidیک تابع callback که پس از ارسال موفق ایونت اجرا می‌شود.خیر
import { newEventByName } from '@metrixorg/websdk'; newEventByName('Purchase Completed', { product_name: 'shirt', size: 'large', });

اگر name خالی ارسال شود، با خطای زیر مواجه خواهید شد: Error: newEventByName: name is required and cannot be empty.


۳. ردیابی درآمد (Revenue Events)

برای ثبت یک ایونت درآمدی، ابتدا آن را در داشبورد متریکس تعریف کرده و سپس از متد newRevenue استفاده کنید.

newRevenue(slug: string, revenue: number, currency?: 'IRR' | 'USD' | 'EUR', onSuccess?: () => void): void
پارامترنوعتوضیحالزامی
slugstringاسلاگ ایونت درآمدی که در داشبورد تعریف شده است.بله
revenuenumberمقدار درآمد کسب‌شده.بله
currency'IRR' | 'USD' | 'EUR'واحد پول. مقدار پیش‌فرض IRR است.خیر
onSuccess() => voidیک تابع callback که پس از ارسال موفق ایونت اجرا می‌شود.خیر
import { newRevenue } from '@metrixorg/websdk'; newRevenue('ORDER_COMPLETED', 12000, 'IRR');

ارزهای پشتیبانی‌شده:

  • IRR (ریال ایران)
  • USD (دلار آمریکا)
  • EUR (یورو)

مثال‌های کاربردی

ایونت های پایه

import { init, newEvent } from '@metrixorg/websdk'; // مقداردهی اولیه SDK init('APP_ID', 'API_KEY'); // ردیابی کلیک روی یک دکمه document.getElementById('purchaseButton').addEventListener('click', () => { newEvent('BUTTON_CLICKED', { button_id: 'purchaseButton', button_label: 'Buy Now', }); });

ایونت های تجارت الکترونیک (E-commerce)

مشاهده محصول

import { newEvent } from '@metrixorg/websdk'; const attributes = { product_id: 'SKU-12345', product_name: 'Premium Running Shoes', category: 'footwear', price: '129.99', brand: 'Nike', in_stock: 'true', }; newEvent('PRODUCT_VIEWED', attributes);

افزودن به سبد خرید

import { newEvent } from '@metrixorg/websdk'; const attributes = { product_id: 'SKU-12345', product_name: 'Premium Running Shoes', price: '129.99', quantity: '1', cart_total: '129.99', }; newEvent('ITEM_ADDED_TO_CART', attributes);

شروع فرآیند پرداخت

import { newEvent } from '@metrixorg/websdk'; const attributes = { cart_item_count: '3', cart_total: '399.97', currency: 'USD', }; newEvent('CHECKOUT_STARTED', attributes);

تکمیل خرید

import { newEvent } from '@metrixorg/websdk'; const attributes = { transaction_id: 'txn_12345678', transaction_total: '399.97', currency: 'USD', item_count: '3', payment_method: 'credit_card', shipping_cost: '10.00', tax_amount: '35.00', }; newEvent('PURCHASE_COMPLETED', attributes, () => { console.log('Purchase tracked successfully'); });

ایونت درآمدی

import { newRevenue } from '@metrixorg/websdk'; newRevenue('ORDER_COMPLETED', 399.97, 'USD', () => { console.log('Revenue tracked successfully'); });

ایونت های تعامل کاربر

ارسال فرم

import { newEvent } from '@metrixorg/websdk'; document.getElementById('contactForm').addEventListener('submit', e => { e.preventDefault(); const formData = new FormData(e.target); newEvent('FORM_SUBMITTED', { form_id: 'contactForm', form_name: 'Contact Us', field_count: String(formData.size), }); e.target.submit(); });

انجام جستجو

import { newEvent } from '@metrixorg/websdk'; function performSearch(query: string) { const results = search(query); newEvent('SEARCH_PERFORMED', { search_query: query, result_count: String(results.length), category_filtered: 'all', }); return results; }

مشاهده صفحه

import { newEvent } from '@metrixorg/websdk'; newEvent('PAGE_VIEWED', { page_url: window.location.pathname, page_title: document.title, referrer: document.referrer || 'direct', });

ایونت های حساب کاربری

ساخت حساب کاربری

import { newEvent } from '@metrixorg/websdk'; const attributes = { signup_method: 'email', account_type: 'free', referral_source: 'google', }; newEvent('ACCOUNT_CREATED', attributes);

ورود موفق

import { newEvent } from '@metrixorg/websdk'; const attributes = { login_method: 'email', account_type: 'premium', }; newEvent('LOGIN_SUCCESSFUL', attributes);

بازنشانی رمز عبور

import { newEvent } from '@metrixorg/websdk'; newEvent('PASSWORD_RESET_REQUESTED', { reset_method: 'email', });

بهترین شیوه‌ها (Best Practices)

نام‌گذاری ویژگی‌ها (Attributes)

  • از snake_case برای نام‌گذاری کلیدها استفاده کنید: product_name، order_id، category_type
  • نام‌ها را توصیفی و با حروف کوچک انتخاب کنید.
  • از فاصله یا کاراکترهای خاص در نام کلیدها خودداری کنید.
// درست const goodAttributes = { product_name: 'Winter Jacket', payment_method: 'credit_card', order_total: '150.00', }; // نادرست const badAttributes = { 'Product Name': 'Winter Jacket', // فاصله در نام کلید paymentMethod: 'credit_card', // camelCase 'order-total': '150.00', // خط تیره در نام کلید }; newEvent('PURCHASE_COMPLETED', goodAttributes);

محدودیت ویژگی‌ها

  • ویژگی‌های سفارشی را کوتاه و مرتبط با ایونت نگه دارید.
  • برای هر ایونت حداکثر از ۱۰ تا ۱۵ جفت کلید-مقدار استفاده کنید.
  • از ارسال ویژگی‌های تکراری یا محاسبه‌شدنی در سمت سرور خودداری کنید.

مدیریت نوع داده‌ها

  • تمام مقادیر ویژگی‌ها باید به صورت رشته (string) ارسال شوند.
  • عدد، تاریخ و مقادیر بولین را به رشته تبدیل کنید:
const attributes = { quantity: '5', // عدد به صورت رشته price: '99.99', // اعشار به صورت رشته is_premium: 'true', // بولین به صورت رشته signup_date: '2024-01-15T10:30:00Z', // تاریخ با فرمت ISO 8601 timestamp: String(Date.now()), // Unix timestamp }; newEvent('PURCHASE_COMPLETED', attributes);

داده‌های حساس

  • هرگز اطلاعات حساسی مانند رمز عبور، شماره کارت بانکی یا اطلاعات شناسایی شخصی را در ویژگی‌های ایونت ارسال نکنید.
  • در صورت نیاز، مقادیر PII را به صورت hash‌شده ارسال کنید.
  • سیاست‌های نگهداری داده و حریم خصوصی خود را در نظر بگیرید.

ترتیب ارسال ایونت ها

  • ایونت ها را به همان ترتیبی که رخ می‌دهند ثبت کنید تا تحلیل قیف (funnel) دقیق باشد.
  • ایونت ها را قبل از ریدایرکت یا ارسال فرم فراخوانی کنید تا از ارسال موفقیت‌آمیز آن‌ها اطمینان حاصل شود.

عیب‌یابی (Troubleshooting)

ایونت ها در داشبورد نمایش داده نمی‌شوند

  1. مطمئن شوید init() قبل از هر فراخوانی newEvent اجرا شده است.
  2. بررسی کنید APP_ID و API_KEY صحیح باشند.
  3. مطمئن شوید slug یا name ایونت با آنچه در داشبورد تعریف کرده‌اید، دقیقاً مطابقت دارد.
  4. در تب Network مرورگر، درخواست ارسالی به سرورهای متریکس را بررسی کنید و از موفقیت‌آمیز بودن آن مطمئن شوید.
  5. کنسول مرورگر را برای هرگونه خطا بررسی کنید.

ویژگی‌های سفارشی (Custom Attributes) نمایش داده نمی‌شوند

  1. مطمئن شوید تمام مقادیر ویژگی‌ها به صورت رشته (string) ارسال شده‌اند.
  2. بررسی کنید نام کلیدها با قاعده snake_case نوشته شده باشند.
  3. بررسی کنید آیا محدودیتی برای ویژگی‌های سفارشی در تنظیمات ایونت در داشبورد فعال شده است.
  4. ابتدا با یک ویژگی ساده تست کنید: { test: 'value' }

کالبک اجرا نمی‌شود

  1. کالبک onSuccess پس از رسیدن ایونت به سرورهای متریکس اجرا می‌شود.
  2. تأخیر شبکه می‌تواند باعث دیرتر اجرا شدن آن شود.
  3. کنسول مرورگر را برای هرگونه پیام خطا بررسی کنید.

خلاصه API

متدتوضیح
newEvent(slug, customAttributes?, onSuccess?)ارسال ایونت بر اساس slug تعریف‌شده در داشبورد.
newEventByName(name, customAttributes?, onSuccess?)ارسال ایونت بر اساس name تعریف‌شده در داشبورد.
newRevenue(slug, revenue, currency?, onSuccess?)ارسال ایونت درآمدی بر اساس slug تعریف‌شده در داشبورد.