راهنمای برنامه‌نویسان

ردیابی رویدادها

رویدادهای سیستمی و سفارشی در زبلاین

پس از یکپارچه‌سازی Web SDK، زبلاین به‌صورت خودکار رهگیری تعدادی از رویدادهای پیش‌فرض را آغاز می‌کند. این رویدادها با عنوان رویدادهای سیستمی یا System Events شناخته می‌شوند و تعاملات عمومی کاربران با وب‌سایت و کمپین‌های شما را ثبت می‌کنند.

برای رهگیری رفتارهایی که به‌صورت پیش‌فرض ثبت نمی‌شوند، می‌توانید رویدادهای سفارشی تعریف کنید. این رویدادها متناسب با نوع کسب‌وکار و رفتارهایی که برای شما اهمیت دارند ایجاد می‌شوند.

ایجاد رویدادهای سفارشی

برای رهگیری تعاملاتی که برای کسب‌وکار شما اهمیت دارند، می‌توانید از رویدادهای سفارشی یا Custom Events استفاده کنید.

هر رویداد سفارشی می‌تواند شامل اطلاعات تکمیلی با عنوان ویژگی‌های رویداد یا Event Attributes باشد. این اطلاعات ممکن است شامل قیمت، تعداد، دسته‌بندی محصول، روش پرداخت، تاریخ انجام رویداد و اطلاعات مشابه باشند.

ردیابی رویدادهای سفارشی در زبلاین

برای رهگیری یک رویداد سفارشی در Web SDK زبلاین، از متد zebline.event.track استفاده کنید. در کنار نام رویداد می‌توانید اطلاعات و ویژگی‌های مرتبط با آن رویداد را نیز ارسال کنید.

zebline.event.track(eventName, [eventData]);

نکات مهم

• نام هر رویداد سفارشی باید کمتر از ۵۰ کاراکتر باشد.
• نام ویژگی‌های رویداد به حروف بزرگ و کوچک حساس است.
• نام هر ویژگی نباید بیشتر از ۵۰ کاراکتر باشد.
• مقدار ویژگی‌هایی با نوع String نباید بیشتر از ۱۰۰۰ کاراکتر باشد.
• برای نام‌گذاری رویدادها و ویژگی‌ها از یک ساختار ثابت و مشخص استفاده کنید.

انواع داده‌های مجاز برای ویژگی‌های رویداد

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

• String: مقدار متنی
• Number: مقدار عددی
• Boolean: مقدار درست یا نادرست
• Date: تاریخ
• JSON Array: آرایه JSON
• JSON Object: شیء JSON

قراردادهای نام‌گذاری

• تمام کلیدها را با حروف کوچک انگلیسی بنویسید.
• برای نام‌هایی که از چند کلمه تشکیل شده‌اند، از زیرخط یا Underscore استفاده کنید.
• از فاصله، علائم نامتعارف و ساختارهای متفاوت برای ویژگی‌های مشابه خودداری کنید.

نمونه نام‌گذاری مناسب:

first_name
membership_level
favorite_color
product_category
payment_method

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

برای هر رویداد سفارشی می‌توانید حداکثر ۲۵ ویژگی از هر نوع داده تعریف کنید. بهتر است فقط اطلاعاتی را ارسال کنید که واقعاً در تحلیل، سگمنت‌بندی یا شخصی‌سازی کمپین‌ها مورد استفاده قرار می‌گیرند.

ردیابی ویژگی‌های رویداد سفارشی

در ادامه چند نمونه از ثبت رویدادهای سفارشی همراه با ویژگی‌های مربوط به هر رویداد را مشاهده می‌کنید.

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

در این نمونه، اطلاعات محصولی که به سبد خرید اضافه شده است همراه با رویداد ارسال می‌شود.

zebline.event.track("added_to_cart", {
"Product ID": 1337,
"Price": 39.80,
"Quantity": 1,
"Product": "Givenchy Pour Homme Cologne",
"Category": "Fragrance",
"Currency": "USD",
"Discounted": true
});

ثبت سفارش

در رویداد ثبت سفارش می‌توانید اطلاعاتی مانند مبلغ سفارش، محصولات، زمان تحویل، شهر، کد پستی و کد تخفیف را ارسال کنید.

zebline.event.track("order_placed", {
"Amount": 808.48,
"Product 1 SKU Code": "UHUH799",
"Product 1 Name": "Armani Jeans",
"Product 1 Price": 300.49,
"Product 1 Size": "L",
"Product 2 SKU Code": "FBHG746",
"Product 2 Name": "Hugo Boss Jacket",
"Product 2 Price": 507.99,
"Product 2 Size": "L",
"Delivery Date": new Date("2017-01-09T00:00:00.000Z"),
"Delivery City": "San Francisco",
"Delivery ZIP": "94121",
"Coupon Applied": "BOGO17"
});

ثبت بازدید صفحه

این رویداد می‌تواند برای ثبت اطلاعات بازدید از یک صفحه مشخص، عنوان صفحه، آدرس ارجاع‌دهنده و زمان بازدید استفاده شود.

zebline.event.track("page_viewed", {
"Page URL": "https://example.com/home",
"Page Title": "Homepage",
"Referrer": "https://google.com",
"Timestamp": new Date()
});

ثبت عضویت کاربر

هنگام ثبت‌نام کاربر می‌توانید اطلاعاتی مانند روش ثبت‌نام، نوع پلن و زمان عضویت را همراه رویداد ارسال کنید.

zebline.event.track("user_signed_up", {
"User ID": "user_12345",
"Signup Method": "Google",
"Plan Type": "Premium",
"Signup Date": new Date("2024-02-15T12:00:00.000Z")
});

ثبت خروج از سیستم

برای ثبت رفتار خروج کاربر از حساب می‌توانید رویدادی مانند نمونه زیر ارسال کنید.

zebline.event.track("user_logged_out", {
"User ID": "user_12345",
"Logout Reason": "User clicked logout",
"Timestamp": new Date()
});

ثبت پرداخت انجام‌شده

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

zebline.event.track("payment_completed", {
"User ID": "user_56789",
"Amount": 150.75,
"Payment Method": "Credit Card",
"Transaction ID": "TXN_789456",
"Payment Date": new Date("2024-02-15T14:30:00.000Z")
});

ردیابی رویدادهای پیچیده

در Web SDK زبلاین می‌توانید ویژگی‌های پیچیده‌تر را نیز در قالب Array و Object همراه رویداد ارسال کنید. این قابلیت برای رویدادهایی مناسب است که شامل چند محصول، چند ویژگی یا اطلاعات تو در تو هستند.

Web SDK تعدادی از رویدادهای سیستمی را به‌صورت خودکار رهگیری می‌کند. در کنار این رویدادها، می‌توانید هر تعامل اختصاصی کاربر با وب‌سایت را نیز به‌عنوان رویداد سفارشی ثبت کنید.

ارسال ویژگی‌های پیچیده همراه با رویدادهای سفارشی

ویژگی‌های پیچیده می‌توانند شامل آرایه‌ها، اشیا و داده‌های تو در تو باشند. برای مثال، یک سفارش ممکن است چند محصول، یک آدرس تحویل و چند کد تخفیف داشته باشد.

ثبت سفارش با ویژگی‌های پیچیده

zebline.event.track("order_placed", {
"Amount": 2300,
```
/* مقدار تاریخی */
"Delivery Date": new Date("2017-01-09T00:00:00.000Z"),
/* داده‌های پیچیده */
"Products": [
{
"SKU Code": "UHUH799",
"Product Name": "Armani Jeans",
"Price": 300.49,
"Details": {
"Size": "L"
}
},
{
"SKU Code": "FBHG746",
"Product Name": "Hugo Boss Jacket",
"Price": 507.99,
"Details": {
"Size": "L"
}
}
],
/* اشیا */
"Delivery Address": {
"City": "San Francisco",
"ZIP": "94121"
},
/* آرایه‌ها */
"Coupons Applied": [
"BOGO17"
]
```
});

سایر نمونه‌ها

ثبت اطلاعات محصولات سبد خرید

در این نمونه، اطلاعات چند محصول همراه با ویژگی‌های اختصاصی هر محصول در قالب یک آرایه ارسال می‌شود.

zebline.event.track("cart_updated", {
"User ID": "user_78901",
"Cart Items": [
{
"Product ID": "12345",
"Name": "iPhone 13",
"Price": 999.99,
"Attributes": {
"Color": "Blue",
"Storage": "128GB"
}
},
{
"Product ID": "67890",
"Name": "MacBook Air",
"Price": 1299.99,
"Attributes": {
"Color": "Silver",
"RAM": "16GB"
}
}
]
});

ثبت تراکنش بانکی

برای ثبت تراکنش‌های مالی می‌توانید اطلاعاتی مانند شناسه تراکنش، مبلغ، ارز، نوع تراکنش و زمان انجام آن را ارسال کنید.

zebline.event.track("bank_transaction", {
"Transaction ID": "TXN_987654",
"User ID": "user_56789",
"Amount": 2500,
"Currency": "USD",
"Transaction Type": "Deposit",
"Timestamp": new Date("2024-03-01T10:00:00.000Z")
});

ثبت تعامل کاربر با صفحه

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

zebline.event.track("user_interaction", {
"User ID": "user_11223",
"Page Name": "Dashboard",
"Click Elements": [
"Settings Button",
"Profile Picture",
"Logout Button"
],
"Timestamp": new Date()
});

استفاده از ویژگی‌های ساده و پیچیده به شما کمک می‌کند اطلاعات کامل‌تری از تعامل کاربران جمع‌آوری کنید و از این اطلاعات برای تحلیل رفتار، سگمنت‌بندی و شخصی‌سازی کمپین‌ها استفاده کنید.

نکات مهم در ارسال دیتای رویدادها