ارسال ایونت (سرویس اتریبیوشن و اتومیشن)
هر تعامل کاربر با وبسایت شما میتواند به عنوان یک رویداد (Event) در داشبورد متریکس ثبت شود. متریکس این رویدادها را جمعآوری کرده و تحلیلهای آماری آنها را در اختیار شما قرار میدهد.
پیش از ارسال هر رویدادی، SDK را مقداردهی اولیه کنید. اگر رویداد باید به یک کاربر مشخص نسبت داده شود، ابتدا authorizeUser را فراخوانی کنید.
۱. ارسال رویداد با Slug
این متد برای ارسال رویدادهای سفارشی بر اساس اسلاگ (Slug) رویداد که در داشبورد تعریف شده، استفاده میشود.
newEvent(slug: string, customAttributes?: { [key: string]: string }, onSuccess?: () => void): void| پارامتر | نوع | توضیح | الزامی |
|---|---|---|---|
slug | string | اسلاگ (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| پارامتر | نوع | توضیح | الزامی |
|---|---|---|---|
name | string | نام رویداد (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| پارامتر | نوع | توضیح | الزامی |
|---|---|---|---|
slug | string | اسلاگ رویداد درآمدی که در داشبورد تعریف شده است. | بله |
revenue | number | مقدار درآمد کسبشده. | بله |
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)
رویدادها در داشبورد نمایش داده نمیشوند
- مطمئن شوید
init()قبل از هر فراخوانیnewEventاجرا شده است. - بررسی کنید
APP_IDوAPI_KEYصحیح باشند. - مطمئن شوید
slugیاnameرویداد با آنچه در داشبورد تعریف کردهاید، دقیقاً مطابقت دارد. - در تب Network مرورگر، درخواست ارسالی به سرورهای متریکس را بررسی کنید و از موفقیتآمیز بودن آن مطمئن شوید.
- کنسول مرورگر را برای هرگونه خطا بررسی کنید.
ویژگیهای سفارشی (Custom Attributes) نمایش داده نمیشوند
- مطمئن شوید تمام مقادیر ویژگیها به صورت رشته (string) ارسال شدهاند.
- بررسی کنید نام کلیدها با قاعده snake_case نوشته شده باشند.
- بررسی کنید آیا محدودیتی برای ویژگیهای سفارشی در تنظیمات رویداد در داشبورد فعال شده است.
- ابتدا با یک ویژگی ساده تست کنید:
{ test: 'value' }
کالبک اجرا نمیشود
- کالبک
onSuccessپس از رسیدن رویداد به سرورهای متریکس اجرا میشود. - تأخیر شبکه میتواند باعث دیرتر اجرا شدن آن شود.
- کنسول مرورگر را برای هرگونه پیام خطا بررسی کنید.
خلاصه API
| متد | توضیح |
|---|---|
newEvent(slug, customAttributes?, onSuccess?) | ارسال رویداد بر اساس slug تعریفشده در داشبورد. |
newEventByName(name, customAttributes?, onSuccess?) | ارسال رویداد بر اساس name تعریفشده در داشبورد. |
newRevenue(slug, revenue, currency?, onSuccess?) | ارسال رویداد درآمدی بر اساس slug تعریفشده در داشبورد. |