ارسال ایونت (سرویس اتریبیوشن و اتومیشن)
هر تعامل کاربر با وبسایت شما میتواند به عنوان یک ایونت (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 تعریفشده در داشبورد. |