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

رهگیری کاربران

شناسایی کاربران

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

این شناسه برای ایجاد یک پروفایل ناشناس در زبلاین استفاده می‌شود. رویدادهای سیستمی، رویدادهای سفارشی، نشست‌ها و ویژگی‌های ثبت‌شده کاربر تا پیش از شناسایی هویت او، در همین پروفایل ناشناس ذخیره خواهند شد.

شناسایی کاربران با شناسه منحصربه‌فرد

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

پیشنهاد می‌شود UserId را در یکی از موقعیت‌های زیر به کاربر اختصاص دهید:

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

تأثیر اختصاص UserId به کاربر

پس از اختصاص UserId، اقدامات زیر در زبلاین انجام می‌شود:

1. کاربر به‌عنوان یک کاربر شناخته‌شده در داشبورد ثبت می‌شود.
2. یک پروفایل مشخص برای نگهداری داده‌های کاربر ایجاد می‌شود.
3. پروفایل‌های ناشناس قبلی کاربر با پروفایل شناخته‌شده او ادغام می‌شوند.

فرایند ادغام پروفایل‌ها

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

دستورالعمل‌های UserId

هنگام تعریف UserId نکات زیر را در نظر داشته باشید:

• APIهای مربوط به کاربران، زیرمجموعه شیء کاربر در SDK زبلاین هستند.
• UserId می‌تواند حداکثر ۱۰۰ کاراکتر داشته باشد.
• شناسه انتخاب‌شده باید هر کاربر را به‌صورت منحصربه‌فرد مشخص کند.
• بهتر است از شناسه ثابت پایگاه داده استفاده شود و اطلاعاتی مانند ایمیل، نام کاربری یا شماره موبایل به‌عنوان UserId انتخاب نشوند؛ زیرا ممکن است در آینده تغییر کنند.

ورود کاربر (Login)

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

نمونه کد JavaScript

zebline.user.login('9SBOkLVMWvPX');

خروج کاربر (Logout)

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

نمونه کد JavaScript

zebline.user.logout();

خروج کامل با ریست شناسه ناشناس

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

امضای متد:

zebline.user.logout(options?)

پارامتر
options
اختیاری است و می‌تواند مقدار زیر را دریافت کند:

• clearAnonymousId: true
  برای حذف اطلاعات هویتی ناشناس، پاک‌کردن داده‌های نشست و ساخت یک شناسه ناشناس جدید استفاده می‌شود.

جزئیات رفتار Clear Anonymous ID

اگر مقدار clearAnonymousId برابر با true باشد:

• اطلاعات نشست کاربر از Storage پاک می‌شود.
• کوکی‌ها و اطلاعات هویتی مرتبط حذف یا منقضی می‌شوند.
• SDK دوباره مقداردهی اولیه می‌شود.
• یک AnonymousId جدید برای کاربر ایجاد خواهد شد.

کوکی‌های مرتبط می‌توانند شامل موارد زیر باشند:

zbl_anonymous_id
zbl_user
zbl_utm
zbl_cache_integration
zbl_cache_insite

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

مثال‌ها

خروج معمولی و حفظ شناسه ناشناس:

zebline.user.logout();

خروج کامل و ساخت شناسه ناشناس جدید:

zebline.user.logout({ clearAnonymousId: true });

zebline.user.login('USERID');

zebline.user.logout();

ویژگی‌های کاربر (User Attributes)

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

ویژگی‌های کاربر به دو دسته تقسیم می‌شوند:

1. ویژگی‌های سیستمی کاربر (System User Attributes)
2. ویژگی‌های سفارشی کاربر (Custom User Attributes)

ویژگی‌های کاربر را می‌توان هم برای کاربران ناشناس و هم برای کاربران شناخته‌شده ثبت کرد.

کاربرد ویژگی‌های کاربر

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

• سگمنت‌بندی و دسته‌بندی کاربران
• هدف‌گذاری دقیق کمپین‌ها
• شخصی‌سازی پیام‌ها در کانال‌های ارتباطی مختلف
• ساخت Journeyهای متناسب با مشخصات کاربران

تفاوت ویژگی‌های کاربر با پارامترهای رویداد

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

تنظیم ویژگی‌های سیستمی کاربر

ایمیل

zebline.user.setAttribute('email', 'john@doe.com');

تاریخ تولد

zebline.user.setAttribute('birth_date', '1999-08-19');

شماره موبایل

zebline.user.setAttribute('mobile', '09121234567');

وضعیت اشتراک کاربران (Opt-In Status)

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

نمونه کد JavaScript

zebline.user.setAttribute('email_opt_in', true);
zebline.user.setAttribute('sms_opt_in', true);

نکات مهم وضعیت اشتراک

• کاربرانی که ایمیل یا شماره موبایل خود را ارائه کرده‌اند، ممکن است به‌صورت پیش‌فرض در وضعیت مجاز دریافت پیام قرار بگیرند.
• مجوز دریافت Web Push از طریق فرایند دریافت اجازه مرورگر مدیریت می‌شود.
• کاربران Opted-out نباید از کانالی که از آن انصراف داده‌اند، پیام دریافت کنند.

تنظیم ویژگی‌های سفارشی کاربران

برای ثبت اطلاعات اختصاصی کسب‌وکار خود می‌توانید از متد
zebline.user.setAttribute
استفاده کنید.

دستورالعمل‌های رهگیری ویژگی‌های سفارشی

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

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

ویژگی‌هایی با نوع داده String، Number، Boolean و Date در دسته ویژگی‌های سفارشی ساده قرار می‌گیرند.

۱. ویژگی رشته‌ای (String)

zebline.user.setAttribute("Category", "GOLD");

۲. ویژگی عددی (Number)

zebline.user.setAttribute("Value Index", 5.06);

۳. ویژگی بولی (Boolean)

zebline.user.setAttribute("Inactive", false);

۴. ویژگی تاریخ (Date)

zebline.user.setAttribute(
  "Registered On",
  new Date("2015-11-09T10:01:11.000Z")
);

تنظیم چندین ویژگی به‌طور هم‌زمان

به‌جای اجرای چندباره متد
setAttribute،
می‌توانید با استفاده از
setAttributes
چند ویژگی را در یک درخواست ثبت کنید.

نمونه کد JavaScript

zebline.user.setAttributes({
  email: 'john@doe.com',
  inactive: false,
  registered_on: new Date("2015-11-09T10:01:11.000Z"),
  city: 'Tehran',
  locale: 'Iran'
});

ارسال دسته‌ای اطلاعات کاربر

ویژگی‌های سیستمی

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

zebline.user.setAttributes({
  email: 'john@doe.com',
  mobile: '09120000000',
  birth_date: '1986-08-19',
  email_opt_in: true
});

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

برای ارسال اطلاعات اختصاصی کاربران نیز می‌توانید ویژگی‌های موردنیاز را به‌صورت یک Object ارسال کنید.

zebline.user.setAttributes({
  membership_level: 'Gold',
  purchase_count: 15,
  last_purchase_date: new Date("2024-02-10T14:30:00.000Z"),
  prefers_notifications: true
});

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

در صورت وجود سؤال می‌توانید از طریق ایمیل
support@zebline.com
با پشتیبانی زبلاین در ارتباط باشید.