شناسایی و ردیابی کاربران در Metrix

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

ردیابی خودکار کاربران

پلاگین وردپرس Metrix به طور خودکار کاربران وارد شده را شناسایی می‌کند و اطلاعات آن‌ها را بدون نیاز به هیچ کد اضافی به Metrix ارسال می‌کند.

چه اطلاعاتی به طور خودکار ردیابی می‌شود

هنگامی که یک کاربر وارد (logged in) می‌شود، پلاگین به طور خودکار اطلاعات زیر را جمع‌آوری و ارسال می‌کند:

توجه: کاربران ناشناس (کاربرانی که وارد نشده‌اند) نیز ردیابی می‌شوند، اما بدون اطلاعات شناسایی شخصی.

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

اگر نیاز به شناسایی دستی یک کاربر دارید، می‌توانید از متد authorize_user() استفاده کنید:

Metrix_SDK::authorize_user($customUserId);

مثال: شناسایی بر اساس شناسه کاربر وردپرس

<?php
$current_user = wp_get_current_user();
if ($current_user->ID) {
    Metrix_SDK::authorize_user($current_user->ID);
}
?>

مثال: شناسایی بر اساس نام کاربری

<?php
$current_user = wp_get_current_user();
if ($current_user->ID) {
    Metrix_SDK::authorize_user($current_user->user_login);
}
?>

مثال: شناسایی بر اساس ایمیل

<?php
$current_user = wp_get_current_user();
if ($current_user->ID) {
    Metrix_SDK::authorize_user($current_user->user_email);
}
?>

عدم احراز هویت کاربران (خروج از حساب کاربری)

هنگامی که یک کاربر از حساب کاربری خود خارج می‌شود (logs out)، به طور خودکار او را از حالت احراز هویت خارج کنید تا به وضعیت ناشناس بازگردد:

Metrix_SDK::deauthorize_user();

پلاگین این متد را به طور خودکار هنگام خروج از وردپرس از طریق هوک wp_logout فراخوانی می‌کند. برای خروج استاندارد از وردپرس، نیازی به پیاده‌سازی اضافی نیست.

مثال: عدم احراز هویت دستی

<?php
// این را زمانی که کاربر از سیستم خارج می‌شود یا جلسه او به پایان می‌رسد فراخوانی کنید
Metrix_SDK::deauthorize_user();
?>

به‌روزرسانی اطلاعات کاربر

پس از شناسایی یک کاربر با authorize_user()، می‌توانید اطلاعات پروفایل او را با استفاده از متدهای زیر به‌روزرسانی کنید:

اطلاعات پایه

Metrix_SDK::set_first_name($first_name);
Metrix_SDK::set_last_name($last_name);
Metrix_SDK::set_email($email);
Metrix_SDK::set_phone_number($phone_number);

داده‌های هش شده (برای حفظ حریم خصوصی)

در صورت لزوم، از نسخه‌های هش شده داده‌های حساس استفاده کنید:

Metrix_SDK::set_hashed_email($hashedEmail);
Metrix_SDK::set_hashed_phone_number($hashed_phone_number);

اطلاعات موقعیت مکانی

Metrix_SDK::set_country($country);
Metrix_SDK::set_city($city);
Metrix_SDK::set_region($region);
Metrix_SDK::set_locality($locality);

اطلاعات جمعیتی

Metrix_SDK::set_gender($gender);
Metrix_SDK::set_birthday($birthday);  // فرمت: YYYY-MM-DD

شناسه‌های سفارشی

Metrix_SDK::set_custom_user_id($id);

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

Metrix_SDK::set_custom_attribute($key, $value);

مثال کامل: به‌روزرسانی پروفایل کاربر

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

<?php
$current_user = wp_get_current_user();
 
if ($current_user->ID) {
    // مرحله 1: شناسایی کاربر
    Metrix_SDK::authorize_user($current_user->user_login);
 
    // مرحله 2: به‌روزرسانی اطلاعات پایه
    Metrix_SDK::set_first_name($current_user->user_firstname);
    Metrix_SDK::set_last_name($current_user->user_lastname);
    Metrix_SDK::set_email($current_user->user_email);
 
    // مرحله 3: افزودن اطلاعات موقعیت مکانی
    Metrix_SDK::set_country('Iran');
    Metrix_SDK::set_city('Tehran');
    Metrix_SDK::set_region('Tehran Province');
 
    // مرحله 4: افزودن ویژگی‌های سفارشی
    Metrix_SDK::set_custom_attribute('membership_level', 'VIP');
    Metrix_SDK::set_custom_attribute('account_type', 'premium');
    Metrix_SDK::set_custom_attribute('join_date', '2024-01-15');
    
    // مرحله 5: تنظیم شناسه کاربر سفارشی برای سیستم‌های خارجی
    Metrix_SDK::set_custom_user_id('EXT_USER_12345');
}
?>

ردیابی خودکار داده‌های کاربر (بهترین روش)

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

در functions.php قالب شما

<?php
add_action('wp_footer', function() {
    $current_user = wp_get_current_user();
    
    if ($current_user->ID) {
        // دریافت فراداده (meta data) کاربر
        $user_company = get_user_meta($current_user->ID, 'company', true);
        $user_phone = get_user_meta($current_user->ID, 'phone', true);
        
        if ($user_company) {
            Metrix_SDK::set_custom_attribute('company', $user_company);
        }
        
        if ($user_phone) {
            Metrix_SDK::set_phone_number($user_phone);
        }
    }
});
?>

جستجوی کاربر در داشبورد Metrix

هنگامی که داده‌های کاربر به Metrix ارسال شد، می‌توانید آن‌ها را در داشبورد Metrix خود مشاهده کنید:

1. به داشبورد Metrix خود وارد شوید
2. به بخش جستجوی کاربر (User Lookup) بروید
3. کاربران را بر اساس موارد زیر جستجو کنید:
   • نام کاربری
   • آدرس ایمیل
   • شناسه کاربر سفارشی
   • سایر ویژگی‌های ردیابی شده

آنچه در جستجوی کاربر خواهید دید

• جزئیات شناسایی کاربر
• تمام ویژگی‌های ردیابی شده
• ویژگی‌های سفارشی که شما تنظیم کرده‌اید
• جدول زمانی فعالیت کاربر
• تاریخچه رویدادها

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

1. authorize_user() را زودتر فراخوانی کنید

کاربران را در اسرع وقت در بارگذاری صفحه خود شناسایی کنید، معمولاً در هوک‌های header یا هوک‌های اولیه footer.

add_action('wp_head', function() {
    $current_user = wp_get_current_user();
    if ($current_user->ID) {
        Metrix_SDK::authorize_user($current_user->ID);
    }
}, 5);

2. از شناسه‌های سازگار استفاده کنید

همیشه برای یک کاربر از یک شناسه یکسان استفاده کنید (مثلاً همیشه از شناسه کاربر یا همیشه از ایمیل استفاده کنید، نه ترکیبی از آنها).

// خوب: شناسه سازگار
Metrix_SDK::authorize_user($current_user->ID);
 
// اجتناب شود: ترکیب شناسه‌ها
Metrix_SDK::authorize_user($current_user->user_login);  // این را بعداً تغییر ندهید

3. داده‌های کاربر را پاک‌سازی کنید (Sanitize)

همیشه داده‌ها را قبل از ارسال به Metrix، به خصوص ویژگی‌های سفارشی، پاک‌سازی (sanitize) کنید:

<?php
$custom_value = isset($_POST['value']) ? sanitize_text_field($_POST['value']) : '';
Metrix_SDK::set_custom_attribute('user_input', $custom_value);
?>

4. داده‌های حساس هش شده را مدیریت کنید

برای اطلاعات حساس مانند ایمیل یا شماره تلفن، از نسخه‌های هش شده استفاده کنید:

<?php
$email = $current_user->user_email;
$hashed_email = md5(strtolower(trim($email)));
Metrix_SDK::set_hashed_email($hashed_email);
?>

5. داده‌ها را در هر بارگذاری صفحه تنظیم کنید

اطلاعات کاربر باید در هر بارگذاری صفحه به‌روزرسانی شود تا Metrix آخرین داده‌ها را داشته باشد:

<?php
// این به طور خودکار از طریق هوک wp_footer در پلاگین اتفاق می‌افتد
// اما در صورت نیاز می‌توانید داده‌های اضافی را اضافه کنید
add_action('wp_footer', function() {
    $current_user = wp_get_current_user();
    if ($current_user->ID) {
        // به‌روزرسانی هر ویژگی سفارشی اضافی
        Metrix_SDK::set_custom_attribute('last_visit', date('Y-m-d H:i:s'));
    }
});
?>

عیب‌یابی

اطلاعات کاربر در جستجوی کاربر ظاهر نمی‌شود

دلایل احتمالی:

• کاربر وارد نشده است (کاربران ناشناس به روش متفاوتی ردیابی می‌شوند)
• App ID یا API Key به درستی پیکربندی نشده است
• داده‌های کاربر قبل از اتمام راه‌اندازی ارسال شده است

راه‌حل:

1. بررسی کنید که کاربر وارد شده باشد
2. بررسی کنید که App ID و API Key در تنظیمات Metrix صحیح باشند
3. کش مرورگر را پاک کرده و صفحه را دوباره بارگذاری کنید
4. چند دقیقه صبر کنید تا داده‌ها با داشبورد Metrix همگام‌سازی شوند

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

دلایل احتمالی:

• داده‌ها حاوی کاراکترهای خاصی هستند که نیاز به گریز (escaping) دارند
• تنظیم ویژگی سفارشی قبل از احراز هویت کاربر فراخوانی می‌شود

راه‌حل:

1. همیشه قبل از تنظیم ویژگی‌ها، authorize_user() را فراخوانی کنید:

   Metrix_SDK::authorize_user($user_id);
   Metrix_SDK::set_custom_attribute('key', 'value');

2. قبل از ارسال، داده‌ها را پاک‌سازی کنید:

   $value = sanitize_text_field($value);
   Metrix_SDK::set_custom_attribute('key', $value);

صفحه “جستجوی کاربر” خالی است

دلایل احتمالی:

• هیچ کاربری از زمان فعال‌سازی پلاگین از وب‌سایت شما بازدید نکرده است
• کاربران به عنوان ناشناس/وارد نشده بازدید می‌کنند

راه‌حل:

• با یک کاربر تستی وارد سایت وردپرس خود شوید
• هنگامی که وارد شده‌اید، از چند صفحه بازدید کنید
• پس از چند دقیقه دوباره بخش جستجوی کاربر را بررسی کنید

امنیت و حریم خصوصی

محافظت از داده‌های کاربر

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

چه چیزی ذخیره می‌شود

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