Skip to Content
مستندات متریکس همواره در حال بهبود است! 🚀 آخرین به‌روزرسانی‌ها را از اینجا دنبال کنید.
مستندات فنیAndroidTracking Users

ردیابی کاربران

SDK متریکس قابلیت‌های جامع شناسایی کاربر و مدیریت ویژگی‌ها (attributes) را فراهم می‌کند. کاربران را می‌توان از طریق شناسه‌های سفارشی (custom IDs) شناسایی کرد و با انواع ویژگی‌های جمعیت‌شناختی (demographic) و سفارشی غنی‌سازی نمود.

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

برای شناسایی یک کاربر در سیستم Metrix و ایجاد یا به‌روزرسانی پروفایل کاربری او، متدهای زیر را فراخوانی کنید. این کار یک User را در پایگاه داده Metrix ایجاد یا به‌روزرسانی می‌کند که می‌توان از طریق بخش User Lookup در پنل Metrix به آن دسترسی پیدا کرد.

تنظیم یک شناسه کاربری سفارشی (Custom User ID)

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

// زمانی که یک کاربر وارد سیستم شما می‌شود، فراخوانی کنید
MetrixAnalytics.User.setUserCustomId("userId");
 
// زمانی که یک کاربر از سیستم شما خارج می‌شود، فراخوانی کنید
MetrixAnalytics.User.deleteUserCustomId();

توجه: شناسه کاربری سفارشی به صورت محلی ذخیره می‌شود و با هر ایونت (event) ارسال می‌گردد، که به Metrix امکان می‌دهد رفتار کاربر را در طول جلسات (sessions) مختلف ردیابی کند.

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

اطلاعات کاربر به‌طور خودکار با یک تأخیر 300 میلی‌ثانیه (debounce) به‌روزرسانی می‌شود، که امکان به‌روزرسانی‌های دسته‌ای را قبل از ارسال به Metrix فراهم می‌کند.

تنظیم ویژگی‌های سفارشی (Custom Attributes)

ویژگی‌های سفارشی دلخواه را با استفاده از جفت‌های کلید-مقدار تنظیم کنید. ویژگی‌های سفارشی می‌توانند از هر نوعی باشند (String, Number, Boolean و غیره):

Map<String, Object> attributes = new HashMap<>();
attributes.put("type", "Loyal");
attributes.put("signup_date", "2024-11-20T11:24:03.000Z"); // use ISO 8601 to consider this attribute as s a date
 
MetrixAnalytics.User.setCustomAttribute(attributes);

نکته: برای ویژگی‌های تاریخ از فرمت ISO 8601 (مانند 2024-11-20T11:24:03.000Z) استفاده کنید تا Metrix آنها را به درستی به عنوان تاریخ در پلتفرم شناسایی کند.

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

SDK متدهای اختصاصی برای ویژگی‌های کاربری متداول ارائه می‌دهد:

MetrixAnalytics.User.setFirstName("userFirstName");
MetrixAnalytics.User.setLastName("userLastName");
MetrixAnalytics.User.setEmail("email");
MetrixAnalytics.User.setHashedEmail("hashedEmail");   // SHA256 hash
MetrixAnalytics.User.setPhoneNumber("phoneNumber");
MetrixAnalytics.User.setHashedPhoneNumber("hashedPhoneNumber");   // SHA256 hash
MetrixAnalytics.User.setCountry("country");
MetrixAnalytics.User.setRegion("region");
MetrixAnalytics.User.setCity("city");
MetrixAnalytics.User.setLocality("locality");
MetrixAnalytics.User.setGender(UserGender.MALE);  // گزینه‌ها: MALE, FEMALE, OTHER
MetrixAnalytics.User.setBirthday(birthday);  // Birthday value type should be 'Long' (timestamp in milliseconds)
// پوش نوتیفیکیشن
MetrixAnalytics.User.setFcmToken("fcm_token_value");
 
// کانال‌های پیام‌رسانی
MetrixAnalytics.User.channelEnabled(MessageChannel.SMS);
MetrixAnalytics.User.channelEnabled(MessageChannel.EMAIL);
MetrixAnalytics.User.channelDisabled(MessageChannel.SMS);

مرجع ویژگی‌های کاربر

ویژگینوعتوضیحاتمتد
customIdStringشناسه منحصربه‌فرد برای کاربر (ایمیل، نام کاربری و غیره)setUserCustomId() / deleteUserCustomId()
firstNameStringنام کاربرsetFirstName()
lastNameStringنام خانوادگی کاربرsetLastName()
emailStringآدرس ایمیل کاربر (متن ساده)setEmail()
hashedEmailStringآدرس ایمیل کاربر (هش شده با SHA256)setHashedEmail()
phoneNumberStringشماره تلفن کاربر (متن ساده)setPhoneNumber()
hashedPhoneNumberStringشماره تلفن کاربر (هش شده با SHA256)setHashedPhoneNumber()
countryStringکشور کاربرsetCountry()
regionStringمنطقه/استان/ایالت کاربرsetRegion()
cityStringشهر کاربرsetCity()
localityStringمحله/مکان کاربرsetLocality()
genderUserGenderجنسیت کاربر (MALE, FEMALE, OTHER)setGender()
birthdayLongتاریخ تولد کاربر (مهر زمانی بر حسب میلی‌ثانیه)setBirthday()
fcmTokenStringتوکن ثبت FCM برای پوش نوتیفیکیشن‌هاsetFcmToken()
customAttributesMapجفت‌های کلید-مقدار سفارشی برای داده‌های کاربرsetCustomAttribute() / setUserAttributes()
channelsSetکانال‌های پیام‌رسانی فعال (SMS, PUSH, EMAIL)channelEnabled() / channelDisabled()

کانال‌های پیام‌رسانی (Messaging Channels)

کانال‌های ارتباطی فعال برای کاربر را مدیریت کنید:

// کانال‌های موجود: SMS, PUSH, EMAIL
 
// فعال کردن یک کانال
MetrixAnalytics.User.channelEnabled(MessageChannel.SMS);
MetrixAnalytics.User.channelEnabled(MessageChannel.PUSH);
MetrixAnalytics.User.channelEnabled(MessageChannel.EMAIL);
 
// غیرفعال کردن یک کانال
MetrixAnalytics.User.channelDisabled(MessageChannel.SMS);

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

فراخوانی پس از احراز هویت

همیشه پس از احراز هویت موفق کاربر یا ورود به سیستم، شناسه کاربری را تنظیم کنید:

// پس از ورود موفقیت‌آمیز
User user = authenticateUser(username, password);
if (user != null) {
    MetrixAnalytics.User.setUserCustomId(user.getId());
    MetrixAnalytics.User.setEmail(user.getEmail());
    MetrixAnalytics.User.setFirstName(user.getFirstName());
}

استفاده از شناسه‌های ثابت

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

// خوب: استفاده ثابت از ایمیل
MetrixAnalytics.User.setUserCustomId(user.getEmail());
 
// بد: تغییر بین شناسه کاربری و ایمیل
MetrixAnalytics.User.setUserCustomId(user.getId());  // Session 1
MetrixAnalytics.User.setUserCustomId(user.getEmail());  // Session 2

hash کردن داده‌های حساس

ایمیل و شماره تلفن‌ها را قبل از ارسال با استفاده از SHA256 hash کنید:

import java.security.MessageDigest;
 
public static String sha256Hash(String input) {
    try {
        MessageDigest digest = MessageDigest.getInstance("SHA-256");
        byte[] hash = digest.digest(input.getBytes());
        StringBuilder hexString = new StringBuilder();
        for (byte b : hash) {
            String hex = Integer.toHexString(0xff & b);
            if (hex.length() == 1) hexString.append('0');
            hexString.append(hex);
        }
        return hexString.toString();
    } catch (Exception e) {
        throw new RuntimeException(e);
    }
}
 
// مثال استفاده
MetrixAnalytics.User.setHashedEmail(sha256Hash("user@example.com"));
MetrixAnalytics.User.setHashedPhoneNumber(sha256Hash("989123456789"));

به‌روزرسانی‌های دسته‌ای (Batch Updates)

به‌روزرسانی‌ها به‌طور خودکار با تأخیر 300 میلی‌ثانیه (debounced) انجام می‌شوند، بنابراین می‌توانید چندین به‌روزرسانی ویژگی را بدون نگرانی در مورد عملکرد به‌صورت دسته‌ای انجام دهید:

// تمام این فراخوانی‌ها در یک به‌روزرسانی واحد دسته‌بندی می‌شوند
MetrixAnalytics.User.setFirstName("John");
MetrixAnalytics.User.setLastName("Doe");
MetrixAnalytics.User.setEmail("john@example.com");
MetrixAnalytics.User.setPhoneNumber("989123456789");
MetrixAnalytics.User.setCountry("Iran");

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

  • حداکثر ویژگی‌های سفارشی: تا 50 ویژگی برای هر ایونت
  • حداکثر طول کلید: 512 بایت
  • حداکثر طول مقدار: 512 بایت

پاکسازی هنگام خروج از سیستم

همیشه هنگام خروج کاربر از سیستم، شناسه کاربری را پاک کنید:

// زمانی که کاربر از سیستم خارج می‌شود
MetrixAnalytics.User.deleteUserCustomId();

User ID Listeners

تغییرات شناسه کاربری از منابع خارجی (مانند دریافت شناسه در سطح دستگاه) :

MetrixAnalytics.setUserIdListener(userId -> {
    Log.d("Analytics", "User ID received: " + userId);
    // رابط کاربری خود را به‌روزرسانی کنید یا اقدامات دیگری انجام دهید
});
Getting StartedTracking Events